Costruire un'estensione personalizzata
Se devi integrare il tuo assistente con un servizio esterno che ha un'API REST, puoi creare un'estensione personalizzata importando un documento OpenAPI.
Dopo aver creato un'estensione personalizzata, è possibile collegarlo ad un assistente come integrazione. Nelle tue azioni è quindi possibile definire passi che interagiscono con il servizio esterno richiamando l'estensione.
Il repository Kit starter di estensione watsonx Assistant su GitHub fornisce i file e Suggerimenti per l'utilizzo avanzato che puoi utilizzare per creare rapidamente un'estensione funzionante. Ogni kit starter include una definizione OpenAPI testata che puoi usare per creare un'estensione che accede a un'API di terze parti, insieme a un file JSON scaricabile che puoi importare per creare un assistente che accede all'estensione.
Panoramica
OpenAPI (precedentemente noto come Swagger) è un open standard per descrivere e documentare le API REST. Un documento OpenAPI definisce le risorse e operazioni supportate da un'API, inclusi i parametri di richiesta e i dati di risposta, insieme a dettagli quali gli URL del server e i metodi di autenticazione.
Un documento OpenAPI descrive un'API REST in termini di percorsi e operazioni. Un percorso identifica una particolare risorsa a cui è possibile accedere utilizzando l'API (ad esempio, una prenotazione hotel o un record cliente). Un' operazione definisce una particolare azione che può essere eseguita su tale risorsa (come la creazione, il richiamo, l'aggiornamento o l'eliminazione).
Il documento OpenAPI specifica tutti i dettagli di ogni operazione, compreso il metodo HTTP utilizzato, i parametri della richiesta, i dati inclusi nel corpo della richiesta e la struttura del corpo della risposta.
Per ulteriori informazioni sulla specifica OpenAPI, vedi OpenAPI Specification.
Quando crei un'estensione personalizzata, importi un documento OpenAPI che descrive l'API REST di un servizio esterno. IBM® watsonx™ Assistant analizza il documento OpenAPI per identificare le operazioni supportate dal servizio esterno, insieme a informazioni sui parametri di immissione e sulla risposta per ciascuna operazione e i metodi di autenticazione supportati.
Una volta completata questa elaborazione, l'estensione personalizzata diventa disponibile come una nuova integrazione che puoi connettere all'assistente. Il tuo assistente può quindi utilizzare l'estensione per inviare richieste al servizio esterno in base alle conversazioni con i tuoi clienti. I valori inclusi nella risposta dal servizio vengono quindi associati alle variabili dell'azione, a cui possono accedere le successive fasi dell'azione.
(Per ulteriori informazioni sulla connessione di un'estensione personalizzata a un assistente, consultare Aggiungi un'estensione personalizzata.)
Preparazione della definizione API
Per creare un'estensione personalizzata, devi accedere a un documento OpenAPI che descrive l'API REST con cui vuoi eseguire l'integrazione. Molti servizi di terze parti pubblicano documenti OpenAPI che descrivono le loro API, che puoi scaricare e importare. Per un'API che la tua società gestisce, puoi utilizzare strumenti standard per creare un documento OpenAPI che lo descrive.
Il sito web SwaggerHub offre un'esercitazione OpenAPI 3.0e strumenti per aiutarti a sviluppare e convalidare il tuo documento OpenAPI. Puoi utilizzare l'editor Swagger in linea per convertire il tuo documento OpenAPI nel formato corretto e nella versione OpenAPI.
Il documento OpenAPI deve soddisfare i seguenti requisiti e limitazioni:
-
Il documento deve essere conforme alla specifica OpenAPI 3.0. Se hai un documento OpenAPI (o Swagger) che utilizza una versione precedente della specifica, puoi usare l'editor Swagger online per convertirlo in OpenAPI 3.0.
-
Il documento deve essere in formato JSON (YAML non è supportato). Se si dispone di un documento YAML, è possibile utilizzare l'Swagger editor online per convertirlo in JSON.
-
Il corpo della richiesta nello script JSON deve essere presentato come oggetto. Ad esempio:
{ name: "Bob", hobbies: ["sleeping", "eating", "walking"] }
-
La dimensione del documento non deve essere superiore a
4 MB
se hai un piano Plus o superiore di watsonx Assistant. Tuttavia, se si dispone di un piano Enteprise con isolamento dei dati, la dimensione del documento non deve essere maggiore di8 MB
. -
Il sito
content-type
deve essereapplication/json
. -
Per eseguire lo streaming da un'estensione, il tipo di contenuto della risposta deve essere
text/event-stream
. -
Ogni operazione deve avere un
summary
chiaro e conciso. Il testo di riepilogo viene utilizzato nell'IU per descrivere le operazioni disponibili da un'azione, quindi dovrebbe essere breve e significativo per qualcuno che sta creando un assistente. -
URL relativi attualmente non sono supportati.
-
Sono supportati solo Basic, Bearer, OAuth 2.0e l'autenticazione della chiave API.
-
Per l'autenticazione OAuth 2.0, sono supportati il codice di autorizzazione, le credenziali client, la password e i tipi di concessione personalizzati che iniziano con
x-
. Notare chex-
viene utilizzato da IBM IAM authentication mechanism e da watsonx. -
Gli schemi definiti utilizzando
anyOf
,oneOf
eallOf
non sono attualmente supportati.
Rispetto del limite di timeout di risposta
È necessario rispettare il limite di timeout della risposta, che è di 48 secondi, quando si chiama un'API esterna. Il valore di timeout per un'estensione personalizzata non è configurabile.
Costruire l'estensione personalizzata
Per costruire un'estensione personalizzata in base alla definizione API, seguire questi passaggi:
-
Vai alla pagina
Integrazioni.
-
Scorrere la sezione Estensioni e fare clic su Crea estensione personalizzata.
-
Leggere le informazioni Get started e fare clic su Avanti per continuare.
-
Nella fase Informazioni di base, specificare le seguenti informazioni relative all'estensione che si sta creando:
- Nome estensione: Un nome breve, descrittivo per l'estensione (ad esempio
CRM system
oWeather service
). Questo nome viene visualizzato nel riquadro dell'estensione nella pagina Integrazioni e nell'elenco delle estensioni disponibili nell'Editor azioni. - Descrizione estensione: Un breve riepilogo dell'estensione e di quello che fa. La descrizione è disponibile dalla pagina Integrazioni.
Fai clic su Next.
- Nome estensione: Un nome breve, descrittivo per l'estensione (ad esempio
-
Nel passo Importa OpenAPI, fai clic o trascina per aggiungere il documento OpenAPI che descrive l'API REST con cui vuoi eseguire l'integrazione.
Se riscontri un errore quando tenti di importare il file JSON, assicurati che il file soddisfi tutti i requisiti elencati in Preparazione della definizione API. Modificare il file per correggere gli errori o rimuovere le funzioni non supportate. Fare clic su X per cancellare il messaggio di errore e provare nuovamente l'importazione.
Dopo aver importato correttamente il file, fare clic su Avanti.
-
Nella fase Gestione dell'estensione, è possibile rivedere e sostituire il documento OpenAPI importato, se necessario. Per ulteriori informazioni sulla sostituzione del documento OpenAPI, vedere Sostituzione del documento OpenAPI.
-
Nella scheda Authentication, vedi le informazioni sui metodi di autenticazione che sono definiti nel documento OpenAPI. Tabella. Campi nella scheda Autenticazione fornisce dettagli sui campi nella scheda Autenticazione:
Nome campo Descrizione Valori Tipo di autenticazione Il tipo di autenticazione impostato nello script OpenAPI. - OAuth 2.0
-Basic Auth
-API key auth
-Bearer auth
Nome utente La credenziale del nome utente nello script OpenAPI. Ad esempio, user
Password La credenziale password impostata nello script OpenAPI. Ad esempio, Password@123
Server Il link al server definito nel documento Open API per la connessione. all'estensione API. Ad esempio, https://custom-extension-server.xyz
-
La tabella Operazioni di revisione mostra le operazioni che l'assistente può richiamare da un passo dell'azione. Un' operazione è una richiesta effettuata con un particolare metodo HTTP, come
GET
oPOST
, su una particolare risorsa.For each operation, a row in the table shows the following information:
- Operazione: una descrizione dell'operazione, derivata da
summary
(se presente) odescription
nel file OpenAPI. - Metodo: Il metodo HTTP utilizzato per inviare la richiesta API per l'operazione.
- Risorse: Il percorso alla risorsa a cui l'operazione agisce.
Per visualizzare ulteriori informazioni su un'operazione, fare clic sull'icona
accanto alla sua riga in tabella. Vengono mostrati i seguenti dettagli:
- Parametri di richiesta: l'elenco dei parametri di input definiti per l'operazione, insieme al tipo di ciascun parametro e se il parametro è richiesto o facoltativo.
- Proprietà della risposta: le proprietà del corpo della risposta associate alle variabili a cui può accedere l'assistente.
- Operazione: una descrizione dell'operazione, derivata da
-
Se si è soddisfatti dell'estensione, fare clic su Fine.
Se si desidera modificare qualcosa, eliminare l'estensione, modificare il file JSON per apportare le modifiche e ripetere il processo di importazione.
La nuova estensione è ora disponibile come tile nella sezione Estensioni del catalogo delle integrazioni e potete aggiungelo al vostro assistente.
Sostituzione del documento OpenAPI
Per sostituire un documento OpenAPI esistente, procedere come segue:
-
Andate in Integrazioni (
) > Estensioni.
-
Fare clic sul pulsante Apri nella scheda dell'estensione personalizzata per la quale si desidera modificare la documentazione OpenAPI.
-
Nella finestra di dialogo Apri estensione personalizzata, fare clic su Conferma per passare alla scheda Gestione estensione.
-
Fare clic sul pulsante Replace per selezionare il nuovo documento OpenAPI dal sistema e fare clic su Open.
-
È possibile rivedere gli operatori nella sezione Revisione operazioni della scheda Gestione estensione.
-
Rivedere e aggiornare le informazioni di autenticazione nella scheda Autenticazione dopo aver sostituito il documento OpenAPI.
-
Andare alla pagina Azioni e riparare qualsiasi abilità di azione interrotta a causa della sostituzione del documento OpenAPI.