Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
I plug-in API consentono agli agenti di Microsoft 365 Copilot di interagire con i servizi Web e accedere alle informazioni in tempo reale. Un plug-in API consente agli utenti di interagire con i dati in tempo reale del loro sistema line-of-business (LOB) tramite comandi in linguaggio naturale a un agente all'interno di Copilot Chat.
Un plug-in API è composto da un servizio API, dalla sua descrizione OpenAPI e da un file manifesto. Il manifesto del plug-in informa l'agente di orchestrazione Copilot sulle funzionalità dell'API. Il manifesto del plug-in include una descrizione OpenAPI per il servizio API. La descrizione OpenAPI è importante perché descrive a Copilot come connettersi all'API. Per ottenere risultati ottimali per l'individuazione e le prestazioni dei plug-in con Copilot, fornire una descrizione chiara e significativa dell'API OpenAPI.
Questo articolo descrive gli elementi che rendono efficace una descrizione OpenAPI per un plug-in che estende le funzionalità dell'agente Copilot.
Elementi di descrizione di OpenAPI
Questa sezione descrive gli elementi di una descrizione OpenAPI e come ottimizzarli per gli agenti Copilot.
Convalida OpenAPI: un buon primo passo è verificare che la descrizione di OpenAPI segua le regole della specifica OpenAPI. Puoi usare Hidi, uno strumento da riga di comando in grado di convalidare le descrizioni OpenAPI tra gli altri casi d'uso, o qualsiasi altro strumento a tua scelta. Una descrizione OpenAPI valida non solo funziona bene con Copilot, ma garantisce anche che la descrizione OpenAPI possa funzionare con altri strumenti.
Sezione informazioni: il campo della descrizione è facoltativo nella specifica OpenAPI, ma è essenziale per una descrizione OpenAPI destinata ad estendere le competenze di Copilot. Copilot ha bisogno del campo descrizione per sapere cosa fa l'API e quando usare il plug-in. Quando si genera un file manifest del plugin da un documento OpenAPI, la descrizione nella sezione info viene usata come descrizione per il file manifest del plugin. Per questo motivo, è importante disporre sempre di un campo descrizione breve e chiaro. Ad esempio, ecco una sezione info della descrizione OpenAPI di un'officina di riparazione.
info:
title: Repair Service
description: A simple service to manage repairs for various items
version: 1.0.0
ID operazione: Una tecnica utile per migliorare l'usabilità di una descrizione OpenAPI è l'aggiunta di una operationID combinazione per ogni percorso API e metodo HTTP offerta dall'API. Gli ID operazione sono identificatori univoci per un'operazione nell'API e vengono utilizzati da Copilot per creare funzioni che vengono eseguite quando si risponde alla richiesta di un utente.
Aggiungere anche una descrizione significativa di ogni operazione supportata dall'API. Dopo che Copilot sceglie di usare un plug-in in base alla richiesta dell'utente e alla descrizione del plug-in, Copilot esegue una ricerca nelle descrizioni dei percorsi per determinare l'endpoint da usare per soddisfare la richiesta dell'utente.
Gli ID operazione vengono visualizzati durante il debug come funzioni per indicare le operazioni che Copilot sta tentando di eseguire. Ecco un esempio di documento OpenAPI e un esempio dell'output del debugger corrispondente:
paths:
/repairs:
get:
operationId: listRepairs
summary: List all repairs
description: Returns a list of repairs with their details and images
Output del debugger:
Parametri: Se un'operazione supportata dall'API accetta parametri, includerli nella descrizione di OpenAPI. Includere un campo di descrizione per ogni parametro per descriverlo brevemente e, se necessario, fornire un esempio di utilizzo del parametro. I parametri vengono usati da Copilot per ottenere tutte le informazioni necessarie dalla richiesta di un utente per effettuare una richiesta all'API.
Ecco un esempio:
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
Risposte: Definire chiaramente tutte le risposte possibili per ogni operazione, incluse le risposte di esito positivo e di errore. Ogni risposta deve avere un codice di stato e una descrizione di ciò che rappresenta. Includere esempi di risposte aiuta Copilot a capire cosa aspettarsi dall'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