Étendre une définition OpenAPI pour un connecteur personnalisé

Pour créer des connecteurs personnalisés pour Azure Logic Apps, Microsoft Power Automate ou Microsoft Power Apps, vous pouvez fournir un fichier de définition OpenAPI, c’est-à-dire un document lisible par l’ordinateur et indépendant du langage décrivant les opérations et les paramètres de votre API. En plus des fonctionnalités prêtes à l’emploi d’OpenAPI, lorsque vous créez des connecteurs personnalisés pour Logic Apps et OpenAPI, vous pouvez inclure les extensions Power Automate suivantes :

• summary
• x-ms-summary
• description
• x-ms-visibility
• x-ms-api-annotation
• x-ms-operation-context
• x-ms-capabilities
• x-ms-trigger
• x-ms-trigger-hint
• x-ms-notification-content
• x-ms-notification-url
• x-ms-url-encoding
• x-ms-dynamic-values and x-ms-dynamic-list
• x-ms-dynamic-schema and x-ms-dynamic-properties

Les sections suivantes décrivent ces extensions.

summary

Spécifie le titre de l’action (opération).

S’applique à : Opérations
Recommandé : utiliser une majuscule en début de phrase pour summary.
Exemple : « Lors de l’ajout d’un événement au calendrier » ou « Envoyer un courrier »

"actions" {
  "Send_an_email": {
    /// Other action properties here...
    "summary": "Send an email",
    /// Other action properties here...
  }
},

x-ms-summary

Spécifie le titre d’une entité.

S’applique à : Paramètres, Schéma de réponse
Recommandé : utiliser une majuscule en début de phrase pour x-ms-summary.
Exemple : « ID De Calendrier », « Objet », « Description D’Événement »

"actions" {
    "Send_an_email": {
        /// Other action properties here...
        "parameters": [{
            /// Other parameters here...
            "x-ms-summary": "Subject",
            /// Other parameters here...
        }]
    }
},

description

Explication détaillée de la fonctionnalité de l’opération ou du format et de la fonction d’une entité.

S’applique à : Opérations, Paramètres, Schéma de réponse
Recommandé : utiliser une majuscule en début de phrase pour description.
Exemple : « Cette opération est déclenchée lors de l’ajout d’un événement au calendrier », « Spécifiez l’objet du message »

"actions" {
    "Send_an_email": {
        "description": "Specify the subject of the mail",
        /// Other action properties here...
    }
},

x-ms-visibility

Spécifie la visibilité d’une entité pour l’utilisateur.

Valeurs possibles : important, advanced et internal
S’applique à : Opérations, Paramètres, Schémas

• Les opérations et paramètres important sont toujours affichés en premier à l’utilisateur.
• Les opérations et paramètres advanced sont masqués sous un menu supplémentaire.
• Les opérations et paramètres internal sont masqués à l’utilisateur.

Notes

Pour les paramètres internal et required, vous devez fournir des valeurs par défaut.

Exemple : les menus Afficher plus et Afficher les options avancées masquent les opérations et paramètres advanced.

"actions" {
    "Send_an_email": {
        /// Other action properties here...
        "parameters": [{
            "name": "Subject",
            "type": "string",
            "description": "Specify the subject of the mail",
            "x-ms-summary": "Subject",
            "x-ms-visibility": "important",
            /// Other parameter properties here...
        }]
        /// Other action properties here...
    }
},

x-ms-api-annotation

Utilisé pour la gestion des versions et du cycle de vie d’une opération.

S’applique à : Opérations

• family—Chaîne dénotant le dossier de la famille d’opérations.
• revision—Entier dénotant le numéro de révision.
• replacement—Objet contenant les informations et les opérations de l’API de remplacement.

"x-ms-api-annotation": {
        "family": "ListFolder",
        "revision": 1,
        "replacement": {
          "api": "SftpWithSsh",
          "operationId": "ListFolder"
        }
      }

x-ms-operation-context

Utilisé pour simuler l’activation d’un déclencheur et ainsi tester un workflow dépendant d’un déclencheur.

S’applique à : Opérations

"x-ms-operation-context": {
        "simulate": {
          "operationId": "GetItems_V2",
          "parameters": {
            "$top": 1
          }
        }

x-ms-capabilities

Utilisé au niveau du connecteur, il s’agit d’une vue d’ensemble des fonctionnalités qu’il offre, opérations spécifiques comprises.

S’applique à : Connecteurs

"x-ms-capabilities": {
  "testConnection": {
    "operationId": "GetCurrentUser"
  },
}

Utilisé au niveau de l’opération, il est utilisé pour identifier que l’opération prend en charge le chargement des blocs et/ou la taille de bloc statique, et peut être fournie par l’utilisateur.

S’applique à : Opérations

• chunkTransfer—Valeur booléenne indiquant si le transfert de blocs est pris en charge.

"x-ms-capabilities": {
  "chunkTransfer": true
}

x-ms-trigger

Identifie si l’opération en cours est un déclencheur qui produit un événement unique. Si ce champ est absent, cela signifie qu’il s’agit d’une opération action.

S’applique à : Opérations

• single—Réponse de type objet
• batch—Réponse de type tableau

"x-ms-trigger": "batch"

x-ms-trigger-hint

Description des conditions d’activation d’un événement dans le cas d’une opération de déclenchement.

S’applique à : Opérations

"x-ms-trigger-hint": "To see it work, add a task in Outlook."

x-ms-notification-content

Contient une définition de schéma d’une demande de notification de webhook. Il s’agit du schéma d’une charge utile de webhook publiée par des services externes sur l’URL de notification.

S’applique à : Ressources

"x-ms-notification-content": {
      "schema": {
        "$ref": "#/definitions/WebhookPayload"
      }
    },

x-ms-notification-url

Identifie dans une valeur booléenne s’il faut placer une URL de notification de webhook dans ce paramètre/champ pour une opération d’inscription de webhook.

S’applique à : Paramètres/Champs d’entrée

"x-ms-notification-url": true

x-ms-url-encoding

Identifie si le paramètre de chemin actuel doit être codé en double URL double ou en simple URL single. Si ce champ est absent, cela signifie qu’il s’agit du codage single.

S’applique à : Paramètres du chemin d’accès

"x-ms-url-encoding": "double"

Utiliser des valeurs dynamiques

Les valeurs dynamiques sont une liste d’options permettant à l’utilisateur de sélectionner les paramètres d’entrée pour une opération. 

S’applique à : Paramètres 

Utilisation des valeurs dynamiques

Notes

Une chaîne de chemin d’accès est un pointeur JSON qui ne contient pas la barre oblique avant. Voici donc un pointeur JSON : /property/childProperty, et ceci est une chaîne de chemin d’accès : property/childProperty.

Il existe deux manières de définir les valeurs dynamiques :

1. Utiliser x-ms-dynamic-values

   Nom	Nécessaire	Description
   operationId	Oui	Opération retournant les valeurs.
   parameters	Oui	Objet fournissant les paramètres d’entrée requis pour appeler une opération avec valeurs dynamiques.
   value-collection	Non	Chaîne de chemin d’accès qui donne un tableau d’objets dans la charge utile de réponse. Si la collection de valeurs n’est pas spécifiée, la réponse est évaluée en tant que tableau.
   value-title	Non	Chaîne de chemin d’accès dans l’objet à l’intérieur de la collection de valeurs qui renvoie à une description de la valeur.
   value-path	Non	Chaîne de chemin d’accès dans l’objet à l’intérieur de la collection de valeurs qui renvoie à la valeur du paramètre.

   "x-ms-dynamic-values": {
       "operationId": "PopulateDropdown",
       "value-path": "name",
       "value-title": "properties/displayName",
       "value-collection": "value",
       "parameters": {
           "staticParameter": "<value>",
           "dynamicParameter": {
               "parameter": "<name of the parameter to be referenced>"
           }
       }
   }  
   

   Notes

   Il est possible d’avoir des références de paramètres ambiguës lors de l’utilisation de valeurs dynamiques. Par exemple, dans la définition suivante d’une opération, les valeurs dynamiques font référence au champ id, ce qui est ambigu d’après la définition, car il n’est pas clair s’il fait référence au paramètre id ou à la propriété requestCorps/id.

   {
       "summary": "Tests dynamic values with ambiguous references",
       "description": "Tests dynamic values with ambiguous references.",
       "operationId": "TestDynamicValuesWithAmbiguousReferences",
       "parameters": [{
           "name": "id",
           "in": "path",
           "description": "The request id.",
           "required": true
       }, {
           "name": "requestBody",
           "in": "body",
           "description": "query text.",
           "required": true,
           "schema": {
               "description": "Input body to execute the request",
               "type": "object",
               "properties": {
                   "id": {
                       "description": "The request Id",
                       "type": "string"
                   },
                   "model": {
                       "description": "The model",
                       "type": "string",
                       "x-ms-dynamic-values": {
                           "operationId": "GetSupportedModels",
                           "value-path": "name",
                           "value-title": "properties/displayName",
                           "value-collection": "value",
                           "parameters": {
                               "requestId": {
                                   "parameter": "id"
                               }
                           }
                       }
                   }
               }
           }
       }],
       "responses": {
           "200": {
               "description": "OK",
               "schema": {
                   "type": "object"
               }
           },
           "default": {
               "description": "Operation Failed."
           }
       }
   }
   

2. x-ms-dynamic-list

   Il n’y a aucun moyen de référencer les paramètres sans ambiguïté. Cette fonctionnalité pourrait être fournie à l’avenir. Si vous souhaitez que votre opération tire parti de toutes les nouvelles mises à jour, ajoutez la nouvelle extension x-ms-dynamic-list avec x-ms-dynamic-values. De même, si votre extension dynamique fait référence à des propriétés dans des paramètres, vous devez ajouter la nouvelle extension x-ms-dynamic-list avec x-ms-dynamic-values. Les références des paramètres pointant vers les propriétés doivent être exprimées sous forme de chaînes de chemin d’accès.

   • parameters—Cette propriété est un objet pour lequel chaque propriété d’entrée de l’opération dynamique appelée est définie avec un champ de valeur statique ou une référence dynamique à la propriété de l’opération source. Ces deux options sont définies dans ce qui suit.

   • value—valeur littérale à utiliser pour le paramètre d’entrée. Dans l’exemple suivant, le paramètre d’entrée de l’opération GetDynamicList nommé version est défini à l’aide de la valeur statique 2.0.

     {
         "operationId": "GetDynamicList",
         "parameters": {
           "version": {
             "value": "2.0"
           }
         }
     }
     

   • parameterReference—Chemin de référence complet du paramètre, qui commence par le nom du paramètre, suivi de la chaîne de chemin d’accès de la propriété à laquelle il sera fait référence. Par exemple, la propriété d’entrée de l’opération GetDynamicList nommée property1, qui est sous le paramètre destinationInputParam1, est définie comme une référence dynamique à une propriété nommée proprerty1 sous le paramètre sourceInputParam1 de l’opération source.

     {
         "operationId": "GetDynamicList",
           "parameters": {
               "destinationInputParam1/property1": {
                 "parameterReference": "sourceInputParam1/property1"
         }
       }
     }
     

     Notes

     Si vous souhaitez faire référence à une propriété marquée comme étant interne avec une valeur par défaut, vous devez utiliser la valeur par défaut comme valeur statique dans cette définition, à la place de parameterReference. La valeur par défaut issue de la liste n’est pas utilisée si elle est définie à l’aide de parameterReference.

     Nom	Obligatoire	Description
     operationId	Oui	Opération retournant la liste.
     parameters	Oui	Objet fournissant les paramètres d’entrée requis pour appeler une opération avec liste dynamique.
     itemsPath	Non	Chaîne de chemin d’accès qui donne un tableau d’objets dans la charge utile de réponse. Si  itemsPath  n’est pas indiquée, la réponse est évaluée comme un tableau.
     itemTitlePath	Non	Chaîne de chemin dans l’objet, à l’intérieur de  itemsPath , qui fait référence à la description de la valeur.
     itemValuePath	Non	Chaîne de chemin d’accès dans l’objet, à l’intérieur de  itemsPath , qui fait référence à la valeur de l’élément.

     Avec x-ms-dynamic-list, utilisez des références de paramètre avec la chaîne de chemin d’accès de la propriété à laquelle vous faites référence. Utilisez ces références de paramètre pour la clé et la valeur de la référence de paramètre d’opération dynamique.

     {
       "summary": "Tests dynamic values with ambiguous references",
       "description": "Tests dynamic values with ambiguous references.",
       "operationId": "TestDynamicListWithAmbiguousReferences",
       "parameters": [
         {
           "name": "id",
           "in": "path",
           "description": "The request id.",
           "required": true
         },
         {
           "name": "requestBody",
           "in": "body",
           "description": "query text.",
           "required": true,
           "schema": {
             "description": "Input body to execute the request",
             "type": "object",
             "properties": {
               "id": {
                 "description": "The request id",
                 "type": "string"
               },
               "model": {
                 "description": "The model",
                 "type": "string",
                 "x-ms-dynamic-values": {
                   "operationId": "GetSupportedModels",
                   "value-path": "name",
                   "value-title": "properties/displayName",
                   "value-collection": "cardTypes",
                   "parameters": {
                     "requestId": {
                       "parameter": "id"
                     }
                   }
                 },
                 "x-ms-dynamic-list": {
                   "operationId": "GetSupportedModels",
                   "itemsPath": "cardTypes",
                   "itemValuePath": "name",
                   "itemTitlePath": "properties/displayName",
                   "parameters": {
                     "requestId": {
                       "parameterReference": "requestBody/id"
                     }
                   }
                 }
               }
             }
           }
         }
       ],
       "responses": {
         "200": {
           "description": "OK",
           "schema": {
             "type": "object"
           }
         },
         "default": {
           "description": "Operation Failed."
         }
       }
     } 
     

Utiliser le schéma dynamique

Le schéma dynamique indique que le schéma pour la réponse ou le paramètre actuels est dynamique. Cet objet appelle une opération définie par la valeur dans ce champ, découvre le schéma de façon dynamique et affiche l’interface utilisateur appropriée pour la collecte des entrées d’utilisateur ou les champs disponibles.

S’applique à : Paramètres, Réponses

Cette image montre comment le formulaire d’entrée change en fonction de l’élément que l’utilisateur sélectionne dans la liste :

Cette image montre comment les sorties changent en fonction de l’élément que l’utilisateur sélectionne dans la liste déroulante. Dans cette version, l’utilisateur sélectionne Voitures :

Dans cette version, l’utilisateur sélectionne Alimentation :

Utilisation du schéma dynamique

Notes

Une chaîne de chemin d’accès est un pointeur JSON qui ne contient pas la barre oblique avant. Voici donc un pointeur JSON : /property/childProperty, et ceci est une chaîne de chemin d’accès : property/childProperty.

Il existe deux manières de définir le schéma dynamique :

1. x-ms-dynamic-schema :

   Nom	Nécessaire	Description
   operationId	Oui	Opération retournant le schéma.
   parameters	Oui	Objet fournissant les paramètres d’entrée requis pour appeler une opération avec un schéma dynamique.
   value-path	Non	Chaîne de chemin d’accès faisant référence à la propriété possédant le schéma. À défaut de spécification, la réponse est supposée contenir le schéma dans les propriétés de l’objet racine. Si elle est spécifiée, la réponse correcte doit contenir la propriété. Pour un schéma vide ou non défini, cette valeur doit être null.

     {
     "name": "dynamicListSchema",
     "in": "body",
     "description": "Dynamic schema for items in the selected list",
     "schema": {
         "type": "object",
         "x-ms-dynamic-schema": {
             "operationId": "GetListSchema",
             "parameters": {
                 "listID": {
                     "parameter": "listID-dynamic"
                 }
             },
             "value-path": "items"
         }
       }
     }
   

   Notes

   Il peut y avoir des références ambiguës dans les paramètres. Par exemple, dans la définition suivante d’une opération, le schéma dynamique fait référence à un champ nommé query, qui ne peut pas être interprété de manière déterministe à partir de la définition, qu’il fasse référence à l’objet de paramètre query ou à la propriété de chaîne query/query.

   {
   
       "summary": "Tests dynamic schema with ambiguous references",
       "description": "Tests dynamic schema with ambiguous references.",
       "operationId": "TestDynamicSchemaWithAmbiguousReferences",
       "parameters": [{
           "name": "query",
           "in": "body",
           "description": "query text.",
           "required": true,
           "schema": {
               "description": "Input body to execute the request",
               "type": "object",
               "properties": {
                   "query": {
                       "description": "Query Text",
                       "type": "string"
                   }
               }
           },
           "x-ms-summary": "query text"
       }],
       "responses": {
           "200": {
               "description": "OK",
               "schema": {
                   "x-ms-dynamic-schema": {
                       "operationId": "GetDynamicSchema",
                       "parameters": {
                           "query": {
                               "parameter": "query"
                           }
                       },
                       "value-path": "schema/valuePath"
                   }
               }
           },
           "default": {
               "description": "Operation Failed."
           }
       }
   }
   

   Exemples de connecteurs open source

   Connecteur	Scénario	Lien
   Gestion des tickets	Obtenir le schéma pour les détails d’un événement sélectionné	Gestion des tickets

2. x-ms-dynamic-properties :

   Il n’y a aucun moyen de référencer les paramètres sans ambiguïté. Cette fonctionnalité pourrait être fournie à l’avenir. Si vous souhaitez que votre opération tire parti de toutes les nouvelles mises à jour, ajoutez la nouvelle extension x-ms-dynamic-properties avec x-ms-dynamic-schema. De même, si votre extension dynamique fait référence à des propriétés dans des paramètres, vous devez ajouter la nouvelle extension x-ms-dynamic-properties avec x-ms-dynamic-schema. Les références des paramètres pointant vers les propriétés doivent être exprimées sous forme de chaînes de chemin d’accès.

   • parameters—Cette propriété est un objet pour lequel chaque propriété d’entrée de l’opération dynamique appelée est définie avec un champ de valeur statique ou une référence dynamique à la propriété de l’opération source. Ces deux options sont définies dans ce qui suit.

   • value—valeur littérale à utiliser pour le paramètre d’entrée. Dans l’exemple suivant, le paramètre d’entrée de l’opération GetDynamicSchema nommé version est défini avec la valeur statique 2.0.

     {
         "operationId": "GetDynamicSchema",
         "parameters": {
           "version": {
             "value": "2.0"
           }
         }
     }
     

   • parameterReference—Chemin de référence complet du paramètre, qui commence par le nom du paramètre, suivi de la chaîne de chemin d’accès de la propriété à laquelle il sera fait référence. Par exemple, la propriété d’entrée de l’opération GetDynamicSchema nommée property1, qui est sous le paramètre destinationInputParam1, est définie comme une référence dynamique à une propriété nommée proprerty1 sous le paramètre sourceInputParam1 de l’opération source.

     {
         "operationId": "GetDynamicSchema",
           "parameters": {
               "destinationInputParam1/property1": {
                 "parameterReference": "sourceInputParam1/property1"
         }
       }
     }
     

     Notes

     Si vous souhaitez faire référence à une propriété marquée comme étant interne avec une valeur par défaut, vous devez utiliser la valeur par défaut comme valeur statique dans cette définition, à la place de parameterReference. La valeur par défaut issue du schéma n’est pas utilisée si elle est définie à l’aide de parameterReference.

     Nom	Obligatoire	Description
     operationId	Oui	Opération retournant le schéma.
     parameters	Oui	Objet fournissant les paramètres d’entrée requis pour appeler une opération avec un schéma dynamique.
     itemValuePath	Non	Chaîne de chemin d’accès faisant référence à la propriété possédant le schéma. À défaut de spécification, la réponse est supposée contenir le schéma dans l’objet racine. Si elle est spécifiée, la réponse correcte doit contenir la propriété. Pour un schéma vide ou non défini, cette valeur doit être null.

     Avec x-ms-dynamic-properties, les références de paramètres peuvent être utilisées avec la chaîne de chemin d’accès de la propriété à laquelle il sera fait référence, à la fois pour la clé et la valeur de la référence du paramètre d’opération dynamique.

         {
         "summary": "Tests dynamic schema with ambiguous references",
         "description": "Tests dynamic schema with ambiguous references.",
         "operationId": "TestDynamicSchemaWithAmbiguousReferences",
         "parameters": [{
             "name": "query",
             "in": "body",
             "description": "query text.",
             "required": true,
             "schema": {
                 "description": "Input body to execute the request",
                 "type": "object",
                 "properties": {
                     "query": {
                         "description": "Query Text",
                         "type": "string"
                     }
                 }
             },
             "x-ms-summary": "query text"
         }],
         "responses": {
             "200": {
                 "description": "OK",
                 "schema": {
                     "x-ms-dynamic-schema": {
                         "operationId": "GetDynamicSchema",
                         "parameters": {
                             "version": "2.0",
                             "query": {
                                 "parameter": "query"
                             }
                         },
                         "value-path": "schema/valuePath"
                     },
                     "x-ms-dynamic-properties": {
                         "operationId": "GetDynamicSchema",
                         "parameters": {
                             "version": {
                                 "value": "2.0"
                             },
                             "query/query": {
                                 "parameterReference": "query/query"
                             }
                         },
                         "itemValuePath": "schema/valuePath"
                     }
                 }
             },
             "default": {
                 "description": "Operation Failed."
             }
           }
         }
     

Étape suivante

Créer un connecteur personnalisé à partir d’une définition OpenAPI

Voir aussi

Vue d’ensemble des connecteurs personnalisés

Fournir des commentaires

Nous apprécions grandement les commentaires sur les problèmes liés à notre plateforme de connecteurs ou les idées de nouvelles fonctionnalités. Pour fournir des commentaires, accédez à Soumettre des problèmes ou obtenir de l’aide avec les connecteurs et sélectionnez votre type de commentaire.