Génération d'une extension personnalisée

Présentation

OpenAPI (anciennement Swagger) est une norme ouverte pour décrire et documenter les API REST. Un document OpenAPI définit les ressources et les opérations prises en charge par une API, y compris les paramètres de demande et les données de réponse, ainsi que des détails tels que les URL du serveur et les méthodes d'authentification.

Un document d' OpenAPI s décrit une API REST en termes de _chemins_ et d'_opérations_. Un chemin identifie une ressource particulière accessible via l'API (par exemple, une réservation d'hôtel ou une fiche client). Une _opération_ désigne une action spécifique pouvant être effectuée sur cette ressource (comme la créer, la récupérer, la mettre à jour ou la supprimer).

Le document OpenAPI spécifie tous les détails de chaque opération, y compris la méthode HTTP utilisée, les paramètres de la demande, les données incluses dans le corps de la demande et la structure du corps de la réponse.

Pour plus d'informations sur la spécification « OpenAPI », consultez la page OpenAPI Specification.

Lorsque vous créez une extension personnalisée, vous importez un document « OpenAPI » qui décrit l'API REST d'un service externe. L'outil de création d'assistants IA analyse le document « OpenAPI » afin d'identifier les opérations prises en charge par le service externe, ainsi que les informations relatives aux paramètres d'entrée et à la réponse pour chaque opération, et les méthodes d'authentification prises en charge.

Une fois ce traitement terminé, l'extension personnalisée devient disponible en tant que nouvelle intégration que vous pouvez connecter à l'assistant. Votre assistant peut alors utiliser l'extension pour envoyer des demandes au service externe en fonction des conversations avec vos clients. Les valeurs incluses dans la réponse du service sont ensuite mises en correspondance avec les variables d'action, auxquelles les étapes d'action suivantes peuvent accéder.

(Pour plus d'informations sur la connexion d'une extension personnalisée à un assistant, voir Ajouter une extension personnalisée).

Préparation de la définition d'API

Pour créer une extension personnalisée, vous devez accéder à un document OpenAPI qui décrit l'API REST à laquelle vous souhaitez vous intégrer. De nombreux services tiers publient des documents OpenAPI qui décrivent leurs API, que vous pouvez télécharger et importer. Pour une API gérée par votre entreprise, vous pouvez utiliser des outils standard pour créer un document OpenAPI qui la décrit.

Le site web de l' SwaggerHub propose un tutoriel sur l' OpenAPI 3.0, ainsi que des outils pour vous aider à élaborer et à valider votre document OpenAPI. Vous pouvez utiliser l 'éditeur Swagger en ligne pour convertir votre document « OpenAPI » au format approprié et à la version « OpenAPI ».

Le document OpenAPI doit satisfaire aux exigences et restrictions suivantes :

• Le document doit être conforme à la spécification OpenAPI 3.0. Si vous disposez d'un document OpenAPI (ou Swagger) qui utilise une version antérieure de la spécification, vous pouvez utiliser l'éditeur Swagger en ligne pour le convertir en OpenAPI 3.0.

• Le document doit être au format JSON (YAML n'est pas pris en charge). Si vous disposez d'un document YAML, vous pouvez utiliser l'éditeur Swagger en ligne pour le convertir en JSON.

• Le corps de la requête dans le script JSON doit être présenté comme un objet. Par exemple :

    {
        name: "Bob",
        hobbies: ["sleeping", "eating", "walking"]
    }

• La taille du document ne doit pas être supérieure à " 8 MB.

• content-type doit être application/json.

• Chaque opération doit avoir un summary clair et concis. Le texte du résumé est utilisé dans l'interface utilisateur pour décrire les opérations disponibles à partir d'une action, il doit donc être court et significatif pour quelqu'un qui construit un assistant.

• Les URL relatives ne sont actuellement pas prises en charge.

• Seuls les modes d'authentification Basic, Bearer, OAuth 2.0 et par clé API sont pris en charge.

• Pour l'authentification via l' OAuth2.0, les types d'autorisation suivants sont pris en charge : code d'autorisation, identifiants client, mot x- de passe et types d'autorisation personnalisés commençant par. Notez que x- est utilisé par le mécanisme d'authentification IAM d' IBM, ainsi que par watsonx.

• Les schémas définis à l'aide de " anyOf, " oneOf et " allOf ne sont actuellement pas pris en charge.

En outre, tout appel à l'API externe doit se terminer dans les 48 secondes.

Génération de l'extension personnalisée

Lorsque vous configurez une extension personnalisée avec l'authentification « OAuth », l'outil de création d'assistants IA ne prend pas en charge la spécification ou la définition des champs d'application « OAuth ». Cependant, l'outil de création d'assistants IA prend en charge les champs d'application « OAuth » grâce au nouveau OAuth 2.0 mécanisme d'authentification utilisé dans les webhooks pré-message et post-message.

Pour générer une extension personnalisée basée sur la définition d'API, procédez comme suit :

1. Accédez à la page Intégrations.

2. Accédez à la section Extensions et cliquez sur Générer une extension personnalisée.

3. Lisez les informations relatives au Démarrage et cliquez sur Suivant pour continuer.

4. Dans l'étape Informations de base, indiquez les informations suivantes sur l'extension que vous créez :

   • Nom d'extension : Nom court et descriptif de l'extension (par exemple, CRM system ou Weather service). Ce nom est affiché sur la tuile de l'extension sur la page Intégrations, et dans la liste des extensions disponibles dans l'éditeur d'actions.

   • Description de l'extension : Bref récapitulatif de l'extension et de ce qu'elle fait. La description est disponible sur la page Intégrations.

Cliquez sur Suivant.

1. Dans l'étape Importer OpenAPI, cliquez ou faites glisser pour ajouter le document OpenAPI qui décrit l'API REST avec laquelle vous voulez vous intégrer.

Si vous rencontrez une erreur lorsque vous essayez d'importer le fichier JSON, assurez-vous que le fichier satisfait à toutes les exigences énumérées dans la section Préparation de la définition de l'API. Éditez le fichier pour corriger les erreurs ou supprimer les fonctionnalités non prises en charge. Cliquez sur le X pour effacer le message d'erreur, puis réessayez l'importation.

Après avoir importé le fichier avec succès, cliquez sur Suivant.

1. Dans l'étape Gérer l'extension, vous pouvez revoir le document OpenAPI importé si nécessaire.

2. Dans l'onglet Authentification, vous trouverez des informations sur les méthodes d'authentification définies dans le document OpenAPI. Tableau. Champs de l'onglet Authentification donne des détails sur les champs de l'onglet Authentification :

1. Le tableau des opérations de révision présente les opérations que l'assistant peut appeler à partir d'une étape d'action. Une _opération_ est une requête effectuée à l'aide d'une méthode d' HTTP spécifique, telle que GET ou POST, sur une ressource donnée.

Pour chaque opération, une ligne du tableau affiche les informations suivantes :

• Opération : Description de l'opération, dérivée de summary (le cas échéant) ou de description dans le fichier OpenAPI.

• Méthode : Méthode HTTP utilisée pour envoyer la demande d'API pour l'opération.

• Ressource : Chemin d'accès à la ressource sur laquelle l'opération agit.

Pour obtenir plus d'informations sur une opération, cliquez sur l'icône située à côté de sa ligne dans le tableau. Les détails suivants sont affichés :

• Paramètres de la demande : Liste des paramètres d'entrée définis pour l'opération, ainsi que le type de chaque paramètre et si le paramètre est obligatoire ou facultatif.

• Propriétés de la réponse: Les propriétés du corps de la réponse qui sont associées à des variables auxquelles l'assistant peut accéder.

1. Si vous êtes satisfait de l'extension, cliquez sur Terminer.

Si vous souhaitez modifier quelque chose, supprimez l'extension, éditez le fichier JSON pour effectuer vos modifications et répétez le processus d'importation.

La nouvelle extension est désormais disponible sous forme de vignette dans la section Extensions du catalogue d'intégrations, et vous pouvez l'ajouter à votre assistant.