Créer un connecteur personnalisé avec une extension OpenAPI

Une façon de créer des connecteurs personnalisés pour Microsoft Copilot Studio, Azure Logic Apps, Microsoft Power Automate ou Microsoft Power Apps consiste à fournir un fichier de définition OpenAPI. Un fichier de définition OpenAPI est un document indépendant du langage, lisible par l’ordinateur qui décrit les opérations et les paramètres de votre API. Outre les fonctionnalités prêtes à l'emploi d'OpenAPI, vous pouvez également inclure les extensions OpenAPI suivantes lorsque vous créez des connecteurs personnalisés pour Logic Apps et Power Automate :

• 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.

résumé

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 : « Quand un événement est ajouté au calendrier » ou « Envoyer un courrier électronique »

"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 à la première lettre des mots pour x-ms-summary.
Exemple : ID de calendrier, Objet, Description de l’événement

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

description

Fournit une explication détaillée des fonctionnalités 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 lorsqu’un nouvel événement est ajouté au calendrier », « Spécifiez l’objet du courrier ».

"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

• L’utilisateur voit toujours d'abord les opérations et les paramètres important.
• L’utilisateur voit les opérations et les advanced paramètres uniquement lorsqu’il utilise un menu supplémentaire.
• L’utilisateur ne voit internal pas les opérations et les paramètres.

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

"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

Permet de gérer le contrôle de version et le cycle de vie d’une opération.

S’applique à : Opérations

• family : chaîne de caractères 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

Utilisez cette propriété pour simuler le déclenchement d’un déclencheur afin de pouvoir tester un flux dépendant du déclencheur.

S’applique à : Opérations

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

x-ms-capabilities

Lorsque vous utilisez cette propriété au niveau du connecteur, elle fournit une vue d’ensemble des fonctionnalités proposées par le connecteur, notamment des opérations spécifiques.

S’applique à : Connecteurs

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

Lorsque vous utilisez cette propriété au niveau de l’opération, elle identifie que l’opération prend en charge le chargement de bloc et la taille de segment statique, que l’utilisateur peut fournir.

S’applique à : Opérations

• chunkTransfer— Valeur booléenne qui indique si le transfert de bloc est pris en charge.

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

x-ms-trigger

Indique si l’opération actuelle est un déclencheur qui produit un événement unique. Si ce champ est absent, l’opération est un 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

Décrit comment déclencher un événement lors 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. Ce schéma définit la charge utile du webhook que les services externes publient sur l’URL de notification.

S’applique à : Ressources

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

x-ms-notification-url

Utilisez une valeur booléenne pour spécifier s’il faut inclure une URL de notification webhook dans ce paramètre ou ce champ pour une opération d’inscription de webhook.

S’applique à : Paramètres et champs d’entrée

"x-ms-notification-url": true

x-ms-url-encoding

Spécifiez si le paramètre de chemin actuel doit utiliser l’encodage d’URL double (double) ou l’encodage d’URL unique (single). Si ce champ est manquant, il est utilisé par défaut pour l’encodage single .

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

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

x-ms-dynamic-values

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

Vous pouvez définir des valeurs dynamiques de deux façons :

• Utilisez 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	Une chaîne de chemin dans l’objet de la collection de valeurs qui fait référence à la 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>"
          }
      }
  }  
  

{
    "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."
        }
    }
}

• Utilisez x-ms-dynamic-list.

  Vous ne pouvez pas référencer sans ambiguïté les paramètres. 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. En outre, 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 dans lequel vous définissez chaque propriété d’entrée de l’opération dynamique appelée 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 la section suivante.

  • value— Il s’agit de la 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— Il s’agit du chemin d’accès de référence de paramètre complet, en commençant par le nom du paramètre suivi de la chaîne de chemin d’accès de la propriété à référencer. 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"
        }
      }
    }
    

Avec x-ms-dynamic-list, utilisez des références de paramètre avec la chaîne de chemin de la propriété que vous référencez. 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."
    }
  }
} 

x-ms-dynamic-schema

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

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

L’image suivante 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

Vous pouvez définir un schéma dynamique de deux façons :

• 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. Si vous ne spécifiez pas cette propriété, 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"
        }
      }
    }
  

{

    "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

• 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. En outre, 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 dans lequel vous définissez chaque propriété d’entrée de l’opération dynamique appelée 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 la section suivante.

  • value— Il s’agit de la 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é à référencer. 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"
        }
      }
    }
    

  Remarque

  Pour référencer une propriété marquée comme interne avec une valeur par défaut, utilisez la valeur par défaut comme valeur statique dans la définition ici, au lieu 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	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.
  itemValuePath	Non	Chaîne de chemin d’accès faisant référence à la propriété possédant le schéma. Si ce paramètre n’est pas spécifié, 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.

  En utilisant x-ms-dynamic-properties, vous pouvez utiliser des références de paramètre avec la chaîne de chemin d’accès de la propriété à référencer, à la fois pour la clé et la valeur de la référence de 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

Informations associées

Vue d’ensemble des connecteurs personnalisés

Fournir des commentaires

Nous apprécions grandement les commentaires sur les problèmes liés à notre plate-forme 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.