Comment rendre un document OpenAPI efficace dans l’extension de Copilot

Les plug-ins permettent Microsoft Copilot de travailler avec des services web et d’obtenir des informations en temps réel. Copilot utilise ces informations pour étendre ses compétences. Avec un plug-in, un utilisateur peut importer des données en temps réel de son système métier vers Copilot.

Un plug-in se compose d’un service d’API, de sa description OpenAPI et d’un fichier manifeste. Le manifeste du plug-in informe Copilot sur les fonctionnalités de l’API. Le manifeste du plug-in inclut une description OpenAPI pour le service d’API. La description OpenAPI est importante, car elle explique à Copilot comment se connecter à l’API. Pour des performances optimales du plug-in avec Copilot, fournissez une description OpenAPI claire et explicite. Ce document explique les éléments qui rendent une description OpenAPI efficace pour un plug-in qui étend Copilot.

Ici, nous supposons que vous disposez d’une API et d’une description OpenAPI pour celle-ci.

Validation OpenAPI : une bonne première étape consiste à vérifier que votre description OpenAPI suit les règles de la spécification OpenAPI. Vous pouvez utiliser Hidi, un outil en ligne de commande qui peut valider des descriptions OpenAPI parmi d’autres cas d’usage, ou tout autre outil de votre choix. Une description OpenAPI valide fonctionne bien avec Copilot, mais elle garantit également que votre description OpenAPI peut fonctionner avec d’autres outils.

Section d’informations : le champ de description est facultatif dans la spécification OpenAPI, mais il est essentiel pour une description OpenAPI destinée à étendre les compétences Copilot. Copilot a besoin du champ de description pour savoir ce que fait l’API et quand utiliser le plug-in. Lors de la génération d’un manifeste de plug-in à partir d’un document OpenAPI, la description dans la section infos est utilisée comme description du manifeste de plug-in. Il est donc important de toujours disposer d’un champ de description bref et clair. Par exemple, voici une section d’informations d’une description OpenAPI d’un atelier de réparation.

info:
  title: Repair Service
  description: A simple service to manage repairs for various items
  version: 1.0.0

ID d’opération : Une technique utile pour améliorer la facilité d’utilisation d’une description OpenAPI consiste à ajouter un operationID pour chaque combinaison de chemin d’API et de méthode HTTP offerte par l’API. Les ID d’opération sont des identificateurs uniques pour une opération dans l’API et sont utilisés par Copilot pour créer des fonctions exécutées lors de la réponse à l’invite d’un utilisateur.

Ajoutez également une description explicite de chaque opération prise en charge par votre API. Une fois que Copilot a choisi d’utiliser un plug-in en fonction de l’invite de l’utilisateur et de la description du plug-in, il recherche dans les descriptions des chemins d’accès pour déterminer le point de terminaison à utiliser pour répondre à la demande de l’utilisateur.

Les ID d’opération sont affichés pendant le débogage en tant que fonctions pour indiquer les opérations que Copilot tente d’exécuter. Voici un exemple de document OpenAPI et un exemple de sortie du débogueur correspondant :

paths:
  /repairs:
    get:
      operationId: listRepairs
      summary: List all repairs
      description: Returns a list of repairs with their details and images

Sortie du débogueur :

Paramètres: Si une opération prise en charge par votre API accepte des paramètres, incluez les paramètres dans la description OpenAPI. Incluez un champ de description pour chaque paramètre afin de le décrire brièvement et, si nécessaire, donnez un exemple d’utilisation du paramètre. Les paramètres sont utilisés par Copilot pour obtenir toutes les informations requises à partir de l’invite d’un utilisateur pour envoyer une requête à l’API.

Voici un exemple :

parameters:
  - name: assignedTo
    in: query
    description: The name or ID of the person or team to whom the repair is assigned.
    schema:
      type: string
    required: false

Réponses: Définissez clairement toutes les réponses possibles pour chaque opération, y compris les réponses de réussite et d’erreur. Chaque réponse doit avoir un code status et une description de ce qu’elle représente. L’inclusion d’exemples de réponses permet à Copilot de comprendre ce qu’il faut attendre de l’API.

responses:
  '200':
    description: A list of repairs
    content:
      application/json:
        schema:
          type: array
          items:
            $ref: '#/components/schemas/Repair'
        examples:
          example1:
            value:
              [
                {
                  "id": "1",
                  "item": "Laptop",
                  "status": "In Progress",
                  "assignedTo": "John Doe"
                }
              ]
  '404':
    description: No repairs found
  '500':
    description: Server error