Oracle Digital Assistant fournit un composant de service REST d'appel intégré que vous pouvez utiliser dans les briques Visual Dialog pour envoyer une demande à l'adresse d'un service REST. Pour pouvoir effectuer la demande à partir d'un composant Service REST d'appel, vous devez d'abord configurer l'adresse dans l'onglet Services REST.

Pour ajouter un service REST, procédez comme suit :

1. Dans Oracle Digital Assistant, cliquez sur pour ouvrir le menu latéral, sélectionnez Paramètres, sélectionnez Services d'API, puis cliquez sur l'onglet Services REST.

2. Fournissez les informations générales suivantes :

   Champ	Description
   Nom	Nom unique qui vous permet d'identifier facilement l'adresse que vous configurez. Par exemple, pour une API de rendez-vous, vous pouvez nommer les services REST "appointmentsUser" et "appointmentsUserEntry".
   Adresse	Adresse permettant d'accéder à l'opération REST. Utilisez des accolades pour délimiter les paramètres de chemin. Par exemple : https://example.com/appointments/{userId}. Pour les adresses Oracle Cloud Infrastructure, veillez à utiliser l'adresse pour la région de votre location. Note : N'utilisez pas les paramètres de requête dans ce champ. Si vous voulez indiquer un paramètre de requête pour tester l'API, vous pouvez utiliser la propriété Paramètres (comme décrit dans le tableau ci-dessous) pour chaque méthode que vous définissez pour l'adresse.
   Description	Description facultative expliquant l'objectif du point de terminaison. Par exemple : "Ajoute et extrait les rendez-vous d'un utilisateur".
   Type d'authentification	Sélectionnez le mode d'authentification de l'appel REST. Aucune authentification requise : sélectionnez cette option lorsque le service ne nécessite pas d'authentification. Authentification de base : sélectionnez cette option lorsque le service utilise une authentification de base. Vous devrez alors fournir un nom d'utilisateur et un mot de passe. Clé d'API : sélectionnez cette option lorsque le service utilise une clé d'API pour l'authentification. Vous devrez ensuite indiquer si la clé doit être transmise en tant que paramètre de chemin ou de requête, et vous devrez indiquer le nom et la valeur de la clé. Jeton de service client : sélectionnez cette option lorsque le service utilise un jeton de service client pour l'authentification. Vous devrez alors spécifier le jeton. Principal de ressource OCI : sélectionnez cette option lorsque vous accédez à une API Oracle Cloud Infrastructure.
   Adresse privée	Si une adresse privée est configurée pour le service auquel vous devez accéder, activez cette option et sélectionnez l'adresse privée que vous utilisez. Remarque : vous pouvez configurer des adresses privées pour les services qui ne sont pas affichés publiquement sur Internet. Reportez-vous à Adresse privée.

3. Pour chaque méthode à configurer pour l'adresse, cliquez sur + Ajouter une méthode, sélectionnez la méthode, puis fournissez les informations suivantes :

   Champ	Description
   Type de contenu	Type du contenu inclus dans le corps de la demande. application/json et text/plain sont pris en charge.
   Corps	Pour les demandes POST, PUT et PATCH, corps de demande à envoyer avec la demande. Vous pouvez remplacer cette valeur dans le composant Service REST d'appel. Pour les corps de demande volumineux, cliquez sur Utiliser la boîte de dialogue Modifier pour ouvrir un éditeur.
   Paramètres	Vous pouvez ajouter des paramètres de chemin et de requête pour tester la demande. Vous pouvez également ajouter des paramètres de chemin et de requête pour configurer les valeurs par défaut. Les développeurs de briques peuvent remplacer ces valeurs de paramètre à partir du composant Appeler le service REST. Autrement dit, ils peuvent ajouter des paramètres dans le composant pour remplacer les valeurs configurées dans le service REST et ne pas ajouter les paramètres dans lesquels ils souhaitent utiliser les valeurs définies dans la configuration du service REST. Pour les paramètres de chemin figurant dans l'adresse, ajoutez un paramètre de type Chemin, définissez la clé pour qu'elle corresponde au paramètre de chemin et définissez la valeur souhaitée. Pour les paramètres de requête à transmettre dans la demande REST, ajoutez un paramètre de type Requête, définissez la clé pour qu'elle corresponde au paramètre de requête et définissez la valeur souhaitée. Si le type d'authentification est Clé d'API et que la clé est transmise en tant que paramètre de requête, n'ajoutez pas de paramètre de requête pour cette valeur de clé ici car elle est déjà configurée. Une fois le paramètre modifié, cliquez sur pour l'ajouter à la liste. Remarque : La valeur du paramètre de requête doit être une chaîne (les expressions Freemarker ne sont pas prises en charge). Cette valeur est uniquement destinée au test de l'API. La valeur réelle utilisée par votre brique doit être configurée dans le composant Service REST d'appel.
   En-têtes	Ajoutez les en-têtes que vous souhaitez transmettre à la demande. Si le type d'authentification est Clé d'API et que la clé est transmise dans un en-tête, n'ajoutez pas d'en-tête pour cette valeur de clé ici car elle est déjà configurée.
   Réponse statique	Vous pouvez utiliser la configuration de réponse statique pour les cas où vous avez besoin d'une réponse de secours en cas d'erreur. Vous pouvez également l'utiliser pour configurer des données de simulation à des fins de développement ou de test. Pour configurer une réponse statique, sélectionnez un code d'état de retour, puis définissez le corps de la réponse. Vous pouvez également définir les paramètres et en-têtes souhaités, cliquer sur Tester la demande, puis sur Enregistrer en tant que réponse statique pour enregistrer les valeurs de la réponse statique.

4. Pour tester la méthode, définissez les paramètres de chemin et de requête à utiliser pour le chemin, définissez les en-têtes nécessaires, indiquez un corps de demande si nécessaire, puis cliquez sur Tester la demande. Une boîte de dialogue Statut de la réponse apparaît avec le statut et le corps de la réponse.

   Conseil :

   Vous pouvez cliquer sur Enregistrer en tant que réponse statique pour enregistrer le code de statut et le corps dans les champs de réponse statique.

Lorsqu'une brique doit extraire ou mettre à jour certaines données via un service back-end, ajoutez un état qui utilise le composant Appeler le service REST. Voici comment utiliser ce composant.

1. Configurez l'adresse sur la page Paramètres > Services d'API > Services REST comme décrit dans Ajout d'un service REST pour une adresse. C'est là que vous définissez l'adresse, le type d'authentification, les méthodes prises en charge, le corps de la demande, les paramètres de chemin et de requête, les en-têtes et une réponse statique facultative.

2. Dans le flux souhaité du concepteur de flux de la brique, ajoutez l'état, choisissez Intégration de service > Appeler le service Rest, indiquez un nom, puis cliquez sur Insérer.

3. Sélectionnez le service REST que vous avez configuré sur la page Services REST.

4. Sélectionnez la méthode.

5. Pour les demandes POST, PUT et PATCH, vous devez généralement fournir un corps de demande.

   Conseil :

   Si le corps contient des expressions FreeMarker, vous pouvez basculer Expression sur Activé pour voir la coloration de la syntaxe FreeMarker. Toutefois, si vous le faites, la validation de la syntaxe JSON est désactivée.

6. Dans la section Paramètres, configurez les paramètres de chemin et de requête à envoyer avec la demande.

   Les paramètres que vous définissez dans le composant remplacent ceux définis dans la configuration du service REST. Inversement, si vous ne définissez pas de paramètre dans le composant, la demande utilise la valeur de paramètre de la configuration du service REST.

   Pour les paramètres de requête définis dans la configuration du service REST, si vous ne voulez pas transmettre ce paramètre de requête, définissez sa valeur sur ${r""}.

7. Définissez les en-têtes que vous souhaitez envoyer avec la demande.

   Les en-têtes que vous définissez dans le composant remplacent ceux définis dans la configuration du service REST. Inversement, si vous ne définissez pas d'en-tête dans le composant, la demande utilise la valeur d'en-tête de la configuration du service REST.

8. Indiquez la réponse à renvoyer une fois l'appel terminé :

   • Utiliser la réponse d'API REST réelle : renvoie la réponse réelle du service REST.

   • Toujours utiliser une réponse REST statique : cette option renvoie la réponse statique configurée dans l'onglet Services REST. Cette réponse est utile lors des phases de développement et de test, entre autres utilisations.

   • Retour à l'aide d'une réponse statique : si la demande REST aboutit, la réponse REST est renvoyée. Sinon, la réponse statique configurée dans l'onglet Services REST est renvoyée.

   Si la configuration du service REST n'a pas de réponse statique, le seul choix est Utiliser la réponse réelle.

9. Pour la variable de résultat, sélectionnez la variable de correspondance pour le stockage des données de réponse. S'il n'existe pas encore, cliquez sur Créer pour en créer un.

   Une fois la demande terminée, la correspondance contient une propriété responsePayload pour le corps de la réponse et une propriété statusCode pour le code de statut. La façon dont le corps de la réponse est stocké dans la variable dépend du fait que la réponse soit un objet JSON, un tableau JSON ou un texte brut (chaîne) :

   • Objet JSON : l'objet est stocké dans la propriété responsePayload.

   • Tableau JSON : le tableau est stocké dans la propriété responsePayload.responseItems.

   • Texte brut : le texte est stocké dans la propriété responsePayload.message.

10. Dans l'onglet Transitions, indiquez la transition suivante et les transitions pour les actions succès et échec.

    • L'action success se produit lorsque statusCode est compris entre 100 et 299.

    • L'action failure se produit lorsque la valeur de statusCode est égale ou supérieure à 300.

Pour plus de détails sur ce composant, reportez-vous à Appel d'un service REST.