Oracle Digital Assistant fournit un composant de service REST d'appel intégré que vous pouvez utiliser dans les compétences de dialogue visuel pour envoyer une demande au point d'extrémité d'un service REST. Avant de pouvoir effectuer la demande à partir d'un composant Service REST d'appel, vous devez configurer le point d'extrémité dans l'onglet Services REST.

Pour ajouter un service REST :

1. Dans Oracle Digital Assistant, cliquez sur pour ouvrir le menu latéral, sur Settings, sur API Services, puis sur l'onglet REST Services.

2. Fournissez ces informations générales :

   Champ	Description
   Name (Nom)	Nom unique qui vous permet d'identifier facilement le point d'extrémité que vous configurez. Par exemple, pour une API de rendez-vous, vous pouvez nommer les services REST "appointmentsUser" et "appointmentsUserEntry".
   Point d'extrémité	Point d'extrémité pour 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 points d'extrémité Oracle Cloud Infrastructure, assurez-vous d'utiliser le point d'extrémité pour la région de votre location. Note : N'utilisez pas de paramètres d'interrogation dans ce champ. Si vous voulez spécifier un paramètre d'interrogation 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 le point d'extrémité.
   Description	Description facultative qui explique l'objectif du point d'extrémité. Par exemple : "Ajoute et extrait les rendez-vous d'un utilisateur".
   Type d'authentification	Sélectionnez comment authentifier 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 paramètre d'interrogation, et vous devrez spécifier le nom et la valeur de la clé. Jeton du titulaire : Sélectionnez cette option lorsque le service utilise un jeton du titulaire pour l'authentification. Vous devrez ensuite spécifier le jeton. Principal de ressource OCI : Sélectionnez cette option lorsque vous accédez à une API Oracle Cloud Infrastructure.
   Point d'extrémité privé	Si vous avez configuré un point d'extrémité privé pour le service auquel vous devez accéder, activez ce commutateur à la position Activé et sélectionnez le point d'extrémité privé que vous utilisez. Note : Vous pouvez configurer des points d'extrémité privés pour les services qui ne sont pas exposés publiquement sur Internet. Voir Point d'extrémité privé.

3. Pour chaque méthode à configurer pour le point d'extrémité, cliquez sur + Add Method (Ajouter une méthode), sélectionnez la méthode, puis fournissez les informations suivantes :

   Champ	Description
   Type de contenu	Type de 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 la demande à envoyer avec la demande. Vous pouvez remplacer cette valeur dans le groupe de pages Service REST 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 d'interrogation pour tester la demande. Vous pouvez également ajouter des paramètres de chemin et d'interrogation pour configurer les valeurs par défaut. Notez que les développeurs de compétences peuvent remplacer ces valeurs de paramètre à partir du composant Service REST d'appel. Autrement dit, ils peuvent ajouter des paramètres dans le composant pour remplacer les valeurs configurées dans le service REST, et non ajouter les paramètres où ils souhaitent utiliser les valeurs définies dans la configuration du service REST. Pour les paramètres de chemin qui se trouvent dans le point d'extrémité, 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 d'interrogation que vous voulez transmettre dans la demande REST, ajoutez un paramètre de type Interrogation, définissez la clé pour qu'elle corresponde au paramètre d'interrogation 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 d'interrogation, n'ajoutez pas de paramètre d'interrogation pour cette valeur de clé ici, car elle est déjà configurée. Après avoir modifié le paramètre, cliquez sur pour l'ajouter à la liste. Note : La valeur du paramètre d'interrogation doit être une chaîne (les expressions Freemarker ne sont pas prises en charge). Cette valeur sert uniquement à tester l'API. La valeur réelle que votre compétence utilise doit être configurée dans le composant Appeler le service REST.
   En-têtes	Ajoutez les en-têtes que vous souhaitez transmettre dans 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 fictives à des fins de développement ou de test. Pour configurer une réponse statique, sélectionnez un code de statut de retour, puis définissez le corps de la réponse. Vous pouvez également définir les paramètres et les 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. Si vous voulez tester la méthode, définissez le chemin et les paramètres d'interrogation à utiliser pour le chemin, définissez les en-têtes nécessaires, fournissez un corps de demande si nécessaire, puis cliquez sur Tester la demande. Une boîte de dialogue Statut de la réponse s'affiche 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 compétence doit extraire ou mettre à jour des données au moyen d'un service dorsal, ajoutez un état qui utilise le composant Service REST d'appel. Voici comment utiliser ce composant.

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

2. Dans le flux souhaité dans le concepteur de flux de la compétence, ajoutez l'état, sélectionnez Service Integration > Call Rest Service (Intégration du service > Service de rappel), indiquez un nom, puis cliquez sur Insert (Insérer).

3. Sélectionnez le service REST que vous avez configuré dans 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 activer l'option Expression 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 d'interrogation à envoyer avec la demande.

   Les paramètres que vous définissez dans le groupe de pages remplacent ceux qui sont 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 d'interrogation définis dans la configuration du service REST, si vous ne voulez pas transmettre ce paramètre d'interrogation, réglez sa valeur à ${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 qui sont 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 réelle de l'API REST : Retourne la réponse réelle du service REST.

   • Toujours utiliser une réponse REST statique : Retourne 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 réussit, la réponse REST est retournée. Sinon, la réponse statique configurée dans l'onglet Services REST est retournée.

   Notez que 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 mappage pour stocker les 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, le mappage contiendra 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, spécifiez la transition suivante et les transitions pour les actions Succès et Échec.

    • L'action Succès se produit lorsque statusCode est compris entre 100 et 299.

    • L'action Échec se produit lorsque statusCode a une valeur supérieure ou égale à 300.

Pour plus de détails sur ce composant, voir Appeler un service REST.