Oracle Digital Assistant fornisce un componente del servizio REST di chiamata integrato che è possibile utilizzare nelle competenze della finestra di dialogo visiva per inviare una richiesta all'endpoint di un servizio REST. Prima di poter effettuare la richiesta da un componente Servizio REST di chiamata, è necessario configurare l'endpoint nella scheda Servizi REST.

Per aggiungere un servizio REST:

1. In Oracle Digital Assistant, fare clic su per aprire il menu laterale, selezionare Impostazioni, selezionare Servizi API, quindi fare clic sulla scheda Servizi REST.

2. Fornire queste informazioni generali:

   Campo	descrizione;
   Nome	Un nome univoco che consente di identificare facilmente l'endpoint che si sta configurando. Ad esempio, per un'API di appuntamenti, è possibile assegnare un nome ai servizi REST "appointmentsUser" e "appointmentsUserEntry".
   endpoint	Endpoint per accedere all'operazione REST. Utilizzare parentesi graffe per delineare i parametri del percorso. Ad esempio: https://example.com/appointments/{userId}. Per gli endpoint Oracle Cloud Infrastructure, assicurati di utilizzare l'endpoint per l'area della tua tenancy. Nota: non utilizzare i parametri di query in questo campo. Se si desidera specificare un parametro di query per eseguire il test dell'API, è possibile utilizzare la proprietà Parametri (come descritto nella tabella riportata di seguito) per ogni metodo definito per l'endpoint.
   descrizione;	Descrizione facoltativa che spiega lo scopo dell'endpoint. Ad esempio: "Aggiunge e recupera gli appuntamenti di un utente".
   Tipo di autenticazione	Selezionare la modalità di autenticazione della chiamata REST. Nessuna autenticazione richiesta: selezionare questa opzione quando il servizio non richiede l'autenticazione. Autenticazione di base: selezionare questa opzione quando il servizio utilizza un'autenticazione di base. Sarà quindi necessario fornire un nome utente e una password. API Key: selezionare questa opzione quando il servizio utilizza una API Key per l'autenticazione. Dovrai quindi indicare se la chiave deve essere passata come parametro di percorso o parametro di query e dovrai specificare il nome e il valore della chiave. Token Bearer: selezionare questa opzione quando il servizio utilizza un token Bearer per l'autenticazione. Sarà quindi necessario specificare il token. Principal risorsa OCI: selezionare questa opzione quando si accede a un'API di Oracle Cloud Infrastructure.
   Endpoint privato	Se per il servizio a cui è necessario accedere è impostato un endpoint privato, attivare questa opzione e selezionare l'endpoint privato in uso. Nota: è possibile impostare endpoint privati per i servizi non esposti pubblicamente su Internet. Vedere Endpoint privato.

3. Per ogni metodo che si desidera configurare per l'endpoint, fare clic su + Aggiungi metodo, selezionare il metodo, quindi fornire le informazioni riportate di seguito.

   Campo	descrizione;
   Tipo di contenuto	Il tipo di contenuto incluso nel corpo della richiesta. Sono supportati application/json e text/plain.
   Corpo	Per le richieste POST, PUT e PATCH, il corpo della richiesta da inviare con la richiesta. È possibile sostituire questo valore nel componente Servizio REST chiamata. Per i corpi delle richieste di grandi dimensioni, fare clic su Usa finestra di dialogo Modifica per aprire un editor.
   Parametri	È possibile aggiungere parametri di percorso e query per eseguire il test della richiesta. È inoltre possibile aggiungere parametri di percorso e query per configurare i valori predefiniti. Gli sviluppatori di skill possono eseguire l'override di questi valori dei parametri dal componente Servizio REST chiamata. In altre parole, possono aggiungere parametri nel componente per sostituire i valori configurati nel servizio REST e non aggiungere i parametri in cui desiderano utilizzare i valori impostati nella configurazione del servizio REST. Per i parametri di percorso presenti nell'endpoint, aggiungere un parametro di tipo Percorso, impostare la chiave in modo che corrisponda al parametro di percorso e impostare il valore desiderato. Per i parametri di query che si desidera passare nella richiesta REST, aggiungere un parametro di tipo Query, impostare la chiave in modo che corrisponda al parametro di query e impostare il valore desiderato. Se il tipo di autenticazione è Chiave API e la chiave viene passata come parametro di query, non aggiungere un parametro di query per tale valore chiave qui poiché è già configurato. Dopo aver modificato il parametro, fare clic su per aggiungerlo all'elenco. Nota: il valore del parametro di query deve essere una stringa (le espressioni Freemarker non sono supportate). Questo valore è solo per il test dell'API. Il valore reale utilizzato dallo skill deve essere configurato nel componente Chiama servizio REST.
   Intestazioni	Aggiungere le intestazioni che si desidera passare nella richiesta. Se il tipo di autenticazione è Chiave API e la chiave viene passata in un'intestazione, non aggiungere qui un'intestazione per tale valore chiave poiché è già configurata.
   Risposta statica	È possibile utilizzare la configurazione di risposta statica per i casi in cui è necessaria una risposta di fallback ogni volta che si verifica un errore. È inoltre possibile utilizzarlo per impostare dati falsi a scopo di sviluppo o test. Per configurare una risposta statica, selezionare un codice di stato di restituzione, quindi definire il corpo della risposta. In alternativa, impostare i parametri e le intestazioni desiderati, fare clic su Richiesta di test e quindi su Salva come risposta statica per salvare i valori per la risposta statica.

4. Se si desidera eseguire il test del metodo, impostare il percorso e i parametri di query da utilizzare per il percorso, impostare le intestazioni necessarie, fornire un corpo della richiesta, se necessario, e fare clic su Richiesta di test. Viene visualizzata una finestra di dialogo Stato risposta con lo stato e il corpo della risposta.

   Suggerimento

   È possibile fare clic su Salva come risposta statica per salvare il codice e il corpo dello stato nei campi di risposta statica.

Quando uno skill deve recuperare o aggiornare alcuni dati tramite un servizio backend, aggiungere uno stato che utilizza il componente Servizio REST chiamata. Di seguito viene descritto come utilizzare il componente.

1. Configurare l'endpoint nella pagina Impostazioni > Servizi API > Servizi REST come descritto nella sezione Aggiungere un servizio REST per un endpoint. In questa area è possibile definire l'endpoint, il tipo di autenticazione, i metodi supportati, il corpo della richiesta, i parametri di percorso e query, le intestazioni e una risposta statica facoltativa.

2. Nel flusso desiderato nella finestra di progettazione del flusso dello skill aggiungere lo stato, scegliere Service Integration > Call Rest Service, fornire un nome, quindi fare clic su Inserisci.

3. Selezionare il servizio REST configurato nella pagina Servizi REST.

4. Selezionare il metodo.

5. Per le richieste POST, PUT e PATCH, in genere è necessario fornire un corpo della richiesta.

   Suggerimento

   Se il corpo contiene espressioni FreeMarker, è possibile passare da Espressione ad On per visualizzare la colorazione della sintassi FreeMarker. Tuttavia, in questo caso, la convalida della sintassi JSON è disattivata.

6. Nella sezione Parametri configurare i parametri di percorso e di query che si desidera inviare con la richiesta.

   I parametri impostati nel componente sostituiscono i parametri impostati nella configurazione del servizio REST. Al contrario, se non si imposta un parametro nel componente, la richiesta utilizza il valore del parametro dalla configurazione del servizio REST.

   Per i parametri di query definiti nella configurazione del servizio REST, se non si desidera passare tale parametro di query, impostarne il valore su ${r""}.

7. Impostare le intestazioni che si desidera inviare con la richiesta.

   Le intestazioni impostate nel componente sostituiscono le intestazioni impostate nella configurazione del servizio REST. Al contrario, se non si imposta un'intestazione nel componente, la richiesta utilizza il valore dell'intestazione dalla configurazione del servizio REST.

8. Specificare la risposta che si desidera restituire al termine della chiamata:

   • Usa risposta API REST effettiva: restituisce la risposta effettiva dal servizio REST.

   • Usa sempre risposta REST statica: restituisce la risposta statica configurata nella scheda Servizi REST. Questa risposta è utile durante le fasi di sviluppo e test, tra gli altri usi.

   • Fallback mediante risposta statica: se la richiesta REST riesce, viene restituita la risposta REST. In caso contrario, viene restituita la risposta statica configurata nella scheda Servizi REST.

   Tenere presente che se la configurazione del servizio REST non dispone di una risposta statica, l'unica scelta è Usa risposta effettiva.

9. Per la variabile risultato, selezionare la variabile mappa per memorizzare i dati di risposta. Se non esiste ancora, fare clic su Crea per crearne uno.

   Al termine della richiesta, la mappa conterrà una proprietà responsePayload per il corpo della risposta e una proprietà statusCode per il codice di stato. La modalità di memorizzazione del corpo della risposta nella variabile dipende dal fatto che la risposta sia un oggetto JSON, un array JSON o un testo normale (stringa):

   • Oggetto JSON: l'oggetto viene memorizzato nella proprietà responsePayload.

   • Array JSON: l'array viene memorizzato nella proprietà responsePayload.responseItems.

   • Testo normale: il testo viene memorizzato nella proprietà responsePayload.message.

10. Nella scheda Transizioni, specificare la transizione successiva e le transizioni per le azioni success e failure.

    • L'azione success si verifica quando il valore statusCode è compreso tra 100 e 299.

    • L'azione failure si verifica quando statusCode è uguale o superiore a 300.

Per ulteriori dettagli su questo componente, vedere Servizio REST di chiamata.