Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Les plug-ins d’API permettent aux agents de Microsoft 365 Copilot d’interagir avec les services web et d’accéder à des informations en temps réel. Un plug-in d’API permet aux utilisateurs d’interagir avec les données en temps réel de leur système métier (LOB) via des commandes en langage naturel vers un agent dans Copilot Chat.
Un plug-in API est composé d’un service API, de sa description OpenAPI et d’un fichier manifeste. Le manifeste du plug-in informe l’orchestrateur Copilot des fonctionnalités de l’API. Le manifeste du plug-in comprend une description OpenAPI pour le service API. La description OpenAPI est importante car elle décrit à Copilot comment se connecter à l’API. Pour optimiser la détectabilité et les performances des plug-ins avec Copilot, fournissez une description OpenAPI claire et significative.
Cet article décrit les éléments qui rendent une description OpenAPI efficace pour un plug-in qui étend les fonctionnalités de l’agent Copilot.
Éléments de description OpenAPI
Cette section décrit les éléments d’une description OpenAPI et comment les optimiser pour les assistants Copilot.
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 les descriptions d’OpenAPI entre autres cas d’utilisation, ou tout autre outil de votre choix. Une description OpenAPI valide fonctionne non seulement bien avec Copilot, mais garantit également que votre description OpenAPI peut fonctionner avec d’autres outils.
La 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 de 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 d’informations est utilisée comme description du manifeste du plug-in. Par conséquent, il est important de toujours avoir un champ de description bref et clair. Par exemple, voici une section d’informations de la description d’un atelier de réparation OpenAPI.
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’accès API et de méthode HTTP offerte par l’API. Les ID d’opération sont des identificateurs uniques d’une opération dans l’API et sont utilisés par Copilot pour créer des fonctions qui sont 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 satisfaire la demande de l’utilisateur.
Les ID d’opération sont affichés pendant le débogage sous forme de 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 ces paramètres dans la description OpenAPI. Incluez un champ de description pour chaque paramètre afin de le décrire brièvement et, le cas échéant, de donner 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 effectuer 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 de status et une description de ce qu’il représente. L’inclusion d’exemples de réponses aide Copilot à comprendre ce qu’il peut 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