Consultez les connecteurs compatibles avec Application Integration.

Afficher la spécification OpenAPI pour votre intégration

Preview — OpenAPI Specification

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

L'Application Integration vous permet de générer et d'afficher de manière dynamique les spécifications OpenAPI de vos intégrations publiées configurées avec un ou plusieurs déclencheurs d'API. Accéder à la spécification OpenAPI de votre intégration vous permet de:

• Obtenez une compréhension complète des points de terminaison, des méthodes et des structures de données de votre intégration.
• Améliorez le développement et le dépannage en fournissant une vue détaillée et centralisée de l'API de votre intégration.
• Exposez vos API d'intégration et intégrez-les facilement aux agents conversationnels, tels que les agents conversationnels Google Cloud.

Qu'est-ce que la spécification OpenAPI ?

La spécification OpenAPI (OAS) est un format standard, indépendant du langage, qui permet de décrire les API RESTful. Généralement écrite au format YAML ou JSON, la spécification OpenAPI présente une description formelle des éléments de l'API, tels que son URL de base, ses chemins et verbes, ses en-têtes, ses paramètres de requête, ses types de contenu, ses modèles de requête et de réponse, etc. Pour en savoir plus sur la spécification OpenAPI, consultez la page Spécification OpenAPI.

Remarque:L'Application Integration n'est compatible qu'avec la version 3.0.1 de la spécification OpenAPI.

Générer et afficher la spécification OpenAPI

Vous pouvez générer et afficher dynamiquement la spécification OpenAPI de vos intégrations à partir de l'éditeur d'intégration de la console Google Cloud ou à l'aide d'un appel d'API.

Avant de commencer

• Vérifiez que votre intégration est configurée avec un ou plusieurs déclencheurs d'API. Pour en savoir plus sur la configuration des déclencheurs d'API, consultez la page Déclencheurs d'API.
• Publiez votre intégration. Pour savoir comment publier une intégration, consultez la page Tester et publier des intégrations.

Consulter la spécification OpenAPI

Pour afficher la spécification OpenAPI de votre intégration, sélectionnez l'une des options suivantes:

Console

Pour afficher la spécification OpenAPI d'une intégration spécifique, procédez comme suit:

1. Accédez à la page Application Integration.

   Accéder à Application Integration

2. Dans le menu de navigation, cliquez sur Intégrations.

   La page Intégrations s'affiche, listant toutes les intégrations disponibles dans le projet Google Cloud .

3. Cliquez sur l'intégration pour laquelle vous souhaitez afficher la spécification OpenAPI. L'intégration s'ouvre dans l'éditeur d'intégration.
4. Cliquez sur  (menu d'actions) dans la barre d'outils de l'éditeur d'intégration, puis sélectionnez Afficher la spécification OpenAPI.

   Le volet Afficher la spécification OpenAPI s'affiche et affiche la spécification OpenAPI de l'intégration. Par défaut, la spécification OpenAPI générée contient tous les déclencheurs d'API configurés dans l'intégration.

   • Pour afficher la spécification OpenAPI d'un déclencheur d'API spécifique, sélectionnez le déclencheur d'API dans la liste déroulante API.
   • Pour télécharger la spécification OpenAPI au format YAML, cliquez sur Télécharger .

Remarque:Vous ne pouvez afficher et télécharger la spécification OpenAPI, au format YAML, que pour une seule intégration à la fois dans l'éditeur d'intégration. Pour afficher et télécharger la spécification OpenAPI aux formats YAML ou JSON, suivez les instructions de la section API.

API

La méthode generateOpenApiSpec de l'API Application Integration vous permet d'afficher la spécification OpenAPI de votre intégration à l'aide d'un appel d'API.

Utilisez la commande curl suivante pour afficher la spécification OpenAPI d'une ou de plusieurs intégrations dans la même région:

Remarque:curl est généralement préinstallé sur les systèmes d'exploitation Linux et macOS. Si vous ne disposez pas de curl, vous pouvez le télécharger sur la page Versions et téléchargements de curl.

curl -X POST \
    -H "authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
    "apiTriggerResources": [{
    "integrationResource": "INTEGRATION_NAME",
    "triggerId": ["api_trigger/TRIGGER_NAME", "api_trigger/TRIGGER_NAME_2", "api_trigger/TRIGGER_NAME_n"]
    },
    {
    "integrationResource": "INTEGRATION_NAME",
      "triggerId": ["api_trigger/TRIGGER_NAME"]
    }],
    "fileFormat": "DOC_TYPE"
    }' \
    "https://LOCATION-integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/-:generateOpenApiSpec"
          

Remplacez les éléments suivants :

• TRIGGER_NAME, TRIGGER_NAME_2, TRIGGER_NAME_n: noms des déclencheurs d'API de votre intégration pour lesquels vous souhaitez afficher la spécification OpenAPI.
• INTEGRATION_NAME: nom de votre intégration.
• DOC_TYPE: type de document à générer. Les valeurs suivantes sont acceptées: YAML ou JSON.
• PROJECT_ID: ID de votre projet Google Cloud .
• LOCATION: emplacement de votre projet Google Cloud .
  Remarque:Vous ne pouvez afficher la spécification OpenAPI que pour plusieurs intégrations dans la même région.

Comprendre la spécification OpenAPI

L'Application Integration génère la spécification OpenAPI pour vos intégrations publiées conformément à la norme OpenAPI 3.0. Le tableau suivant décrit les éléments de la spécification OpenAPI générés dans Application Integration:

Élément	Description
openapi	Version de la spécification OpenAPI utilisée.
info	Informations sur l'intégration, comme son nom (titre), sa description et sa version publiée.
servers	URL des serveurs qui hébergent l'intégration.
paths	Des chemins d'accès sont créés pour chaque déclencheur d'API sélectionné dans l'intégration. L'URL du serveur combinée au chemin d'accès constitue le point de terminaison de l'API pour effectuer des appels d'API. Les champs Request et Response sont renseignés en fonction des variables d'entrée et de sortie configurées pour le déclencheur d'API correspondant. Remarque:L'Application Integration n'est actuellement compatible qu'avec un nombre limité de mots clés de schéma JSON. Pour en savoir plus sur les mots clés acceptés, consultez la section Considérations.
components	Le champ schemas contient le schéma JSON des variables d'entrée et de sortie du déclencheur d'API. Le champ securitySchemes contient les informations d'authentification des déclencheurs d'API.

Remarques

Les considérations suivantes s'appliquent lorsque vous consultez la spécification OpenAPI de votre intégration:

• La spécification OpenAPI n'est générée que pour les intégrations publiées.
• La spécification OpenAPI n'est générée que pour les intégrations configurées avec un ou plusieurs déclencheurs d'API.
• La spécification OpenAPI n'est générée que pour les intégrations dans la même région.
• La spécification OpenAPI est générée au format YAML par défaut. Pour générer et afficher la spécification OpenAPI au format JSON, définissez le paramètre fileFormat sur JSON dans l'appel d'API.
• L'Application Integration n'est actuellement compatible qu'avec l'ensemble limité de mots clés de schéma JSON suivants :
  • type
  • items
  • properties
  • description
  • required
  • array
  • object
  • oneOf
  • allOf
  • anyOf
  • not
  • null
  • enum
  • additionalProperties
  • default
• Lorsque vous validez la spécification OpenAPI à l'aide de l'éditeur Swagger, vous pouvez rencontrer des erreurs sémantiques liées aux chemins d'API, comme illustré ci-dessous:

  

  Vous pouvez les ignorer. La spécification OpenAPI reste valide.