Consultez les connecteurs compatibles avec Application Integration.

Créer un connecteur personnalisé

Preview

Ce produit ou cette fonctionnalité est soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités de pré-DG sont proposés "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Cette page explique comment créer un connecteur personnalisé. Pour en savoir plus sur les connecteurs personnalisés, consultez Connecteurs personnalisés.

Remarque  : Un connecteur personnalisé est une ressource globale. Cela signifie qu'une fois créé, vous pouvez l'utiliser dans l'un des emplacements compatibles avec Application Integration.

Pour établir la connectivité à votre backend à l'aide d'un connecteur personnalisé, vous devez effectuer les tâches suivantes :

1. Créer un connecteur personnalisé : cette tâche consiste à définir le contrat entre Application Integration et votre point de terminaison (backend) en fournissant la spécification OpenAPI du point de terminaison. Actuellement, seules la version 3.0 d'OpenAPI et toutes ses versions mineures sont compatibles. Vous ne devez définir la spécification qu'une fois.
2. Créer une connexion de connecteur personnalisée : cette tâche consiste à configurer les détails de connexion de votre backend, tels que le nom d'hôte et l'authentification. Pour un connecteur personnalisé spécifique, vous pouvez créer autant de connexions que nécessaire.

Pour comprendre la différence entre un connecteur et une connexion, consultez Différence entre connecteur et connexion.

Avant de commencer

• Afin d'obtenir les autorisations nécessaires pour créer le connecteur personnalisé, demandez à votre administrateur de vous accorder le rôle IAM Administrateur des connecteurs personnalisés (roles/connectors.customConnectorAdmin) sur le projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

  Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

• Activez l'API Connector :
  Activer l'API Connector

Créer un connecteur personnalisé

Comme décrit dans la section sur les types de connectivité du backend, les connecteurs personnalisés peuvent avoir l'un des modèles de connectivité suivants :

• Connectivité directe au point de terminaison public de votre backend
• Connectivité indirecte à votre backend par le biais d'un point de terminaison public intermédiaire

Les étapes de création d'un connecteur personnalisé varient légèrement pour ces deux modèles.

Créer un connecteur personnalisé avec une connectivité directe

Pour créer un connecteur personnalisé avec une connectivité directe au point de terminaison de votre backend, procédez comme suit :

Console

1. Dans la console, accédez à la page Application Integration> Connecteurs personnalisés, puis sélectionnez ou créez un projet Google Cloud .

   Accéder à la page "Connecteurs personnalisés"

2. Cliquez sur Créer pour ouvrir la page Créer un connecteur personnalisé.
3. Dans la section Détails du connecteur, définissez les champs suivants :
   1. Nom du connecteur : saisissez un nom pour le connecteur.
   2. Nom à afficher : saisissez un nom à afficher pour le connecteur.
   3. Description : saisissez une description.
   4. Compte de service : sélectionnez un compte de service disposant des rôles requis.
   5. Logo : importez l'image dans un bucket Cloud Storage pour l'utiliser comme logo du connecteur.
      Remarque : Assurez-vous que la protection contre l'accès public est désactivée pour votre bucket Cloud Storage.
4. Cliquez sur Suivant.
5. Dans la section Spécification du connecteur, définissez les champs suivants :
   1. Type de connecteur personnalisé : sélectionnez le type de connecteur personnalisé.
   2. Spécification du connecteur : saisissez l'URL publique de votre spécification OpenAPI ou importez votre fichier de spécification dans un bucket Cloud Storage.
6. Vérifiez les détails de la configuration du connecteur, puis cliquez sur Créer.

Si la création du connecteur aboutit, le connecteur que vous venez de créer s'affiche sur la page Connecteurs personnalisés. S'il s'agit d'un nouveau connecteur, une première version du connecteur est également créée. Vous pouvez consulter les détails de la version dans l'onglet Version de la page Détails du connecteur personnalisé. Pour en savoir plus, consultez .

Toutefois, notez que pour vous connecter à votre backend, vous devez créer une connexion pour le nouveau connecteur. Pour en savoir plus, consultez Créer une connexion de connecteur personnalisé.

API

Les exemples de commandes suivants montrent comment créer un connecteur personnalisé à l'aide des API Application Integration :

1. Créez le connecteur.

   curl -X POST \
   -H "authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json"
   -d '{"customConnectorType":"OPEN_API", \
   "displayName":"CUSTOM_CONNECTOR_NAME", \
   "description": "an open api based custom connector for hrms"}' \
   "https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors?custom_connector_id=UNIQUE_IDENTIFIER"
   

   Remplacez les éléments suivants :

   • CUSTOM_CONNECTOR_NAME : nom du connecteur personnalisé.
   • PROJECT_ID : ID de votre projet Google Cloud .
   • UNIQUE_IDENTIFIER : identifiant unique du connecteur. Exemple : custom-connector-1.
2. Configurez la version du connecteur personnalisé.

   curl -X POST \
   -H "authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -d '{"spec_location": "SPECIFICATION_URL",}' \
   "https://connectors.googleapis.comv1/projects/PROJECT_ID/locations/global/customConnectors/openapi-customconnector/customConnectorVersions?custom_connector_version_id=VERSION_NUMBER"
   

Remplacez les éléments suivants :

• SPECIFICATION_URL : URL de la spécification OpenAPI. Exemple : https://petstore3.swagger.io/api/v3/openapi.json.
• PROJECT_ID : ID de votre projet Google Cloud .
• VERSION_NUMBER : numéro de version du connecteur. Exemple : 2.

Créer un connecteur personnalisé avec une connectivité indirecte

Pour créer un connecteur personnalisé qui se connecte à votre backend par le biais d'un point de terminaison intermédiaire, procédez comme suit :

Console

1. Dans la console, accédez à la page Application Integration> Connecteurs personnalisés, puis sélectionnez ou créez un projet Google Cloud .

   Accéder à la page "Connecteurs personnalisés"

2. Cliquez sur Créer pour ouvrir la page Créer un connecteur personnalisé.
3. Dans la section Informations sur le connecteur, définissez les champs suivants :
   1. Nom du connecteur : saisissez un nom pour le connecteur.
   2. Nom à afficher : saisissez un nom à afficher pour le connecteur.
   3. Description : saisissez une description.
   4. Configurer la destination du connecteur pour l'accès au backend : activez cette option. Les sections de configuration supplémentaires s'affichent sur la page.
   5. Compte de service : sélectionnez un compte de service disposant des rôles requis.
   6. Logo : importez l'image dans un bucket Cloud Storage pour l'utiliser comme logo du connecteur.
      Remarque : Assurez-vous que la protection contre l'accès public est désactivée pour votre bucket Cloud Storage.
4. Cliquez sur Suivant.
5. Dans la section Spécification du connecteur, définissez les champs suivants :
   1. Type de connecteur personnalisé : sélectionnez le type de connecteur personnalisé.
   2. Spécification du connecteur : saisissez l'URL publique de votre spécification OpenAPI ou importez votre fichier de spécification dans un bucket Cloud Storage.
6. Cliquez sur Suivant.
7. Dans la section Destination du connecteur, définissez les champs suivants :
   1. Type de destination : sélectionnez Adresse de l'hôte.
   2. Hôte : saisissez le nom de l'hôte sur lequel votre service intermédiaire est exécuté et incluez le schéma http:// ou https://.
   3. Port : saisissez le numéro de port de votre service intermédiaire.
8. Cliquez sur Suivant.
9. Dans la section Authentification du connecteur, sélectionnez le type d'authentification du service intermédiaire, puis saisissez les informations correspondantes lorsque vous y êtes invité. Cette étape consiste à configurer l'authentification d'Application Integration vers le service intermédiaire.

   La configuration de l'authentification du service intermédiaire vers le backend ne peut pas être définie dans Application Integration. C'est au service intermédiaire de décider comment s'authentifier auprès du backend.

   Vous pouvez utiliser les types d'authentification suivants pour l'authentification auprès du service intermédiaire :

   • Authentification par compte de service
   • Authentification par clé API
   • Authentification à l'aide d'identifiants client OAuth 2.0
   • Authentification de base
   • Authentification Digest

   Pour savoir comment configurer ces types d'authentification, consultez Configurer l'authentification.

   Si l'accès aux ressources de l'API est illimité et ne nécessite aucune authentification, sélectionnez Aucune authentification.

10. Cliquez sur Suivant.
11. Dans la section Variables de backend, saisissez les valeurs que vous souhaitez envoyer à votre backend par le biais du service intermédiaire. Vous devez configurer les valeurs en tant que paires clé/valeur. Pour saisir une paire clé/valeur, cliquez sur Ajouter une variable, puis définissez les champs suivants :
    • Clé : saisissez le nom de la clé.
    • Type de valeur : sélectionnez le type de données de la variable.
    • Nom à afficher : saisissez un nom à afficher.
    • Emplacement : spécifiez comment le connecteur doit envoyer les variables au service intermédiaire. Les options disponibles sont les suivantes : Header, Request payload et Query parameter.
    • Vous pouvez également sélectionner Required pour indiquer que la variable est obligatoire.
    Remarque : Vous serez invité à saisir les valeurs des variables configurées lorsque vous créerez une connexion.
12. Cliquez sur Suivant.
13. Vérifiez les détails de la configuration du connecteur, puis cliquez sur Créer.

Si la création du connecteur aboutit, le connecteur que vous venez de créer s'affiche sur la page Connecteurs personnalisés. S'il s'agit d'un nouveau connecteur, une première version du connecteur est également créée. Vous pouvez consulter les détails de la version dans l'onglet Version de la page Détails du connecteur personnalisé. Pour en savoir plus sur la création et la modification d'une version de connecteur personnalisé, consultez Gérer la version du connecteur personnalisé.

Toutefois, notez que pour vous connecter à votre backend, vous devez créer une connexion pour le nouveau connecteur. Pour en savoir plus, consultez Créer une connexion de connecteur personnalisé.

Configurer l'authentification

Saisissez les informations en fonction de l'authentification que vous souhaitez utiliser.

• Authentification par compte de service

  Sélectionnez cette option pour vous authentifier à l'aide d'un compte de service Google Cloud. Assurez-vous d'avoir fourni le compte de service disposant des rôles et des autorisations IAM appropriés pour l'authentification.

  • Niveaux d'accès : sélectionnez les niveaux d'accès OAuth 2.0 requis dans le menu déroulant. Pour en savoir plus, consultez Niveaux d'accès.
• Authentification par clé API

  Sélectionnez cette option pour vous authentifier à l'aide d'une clé API.

  • Clé API : sélectionnez le secret Secret Manager de la clé API.
  • Version du secret : sélectionnez la version du secret.
  • Nom du paramètre de clé API : saisissez un nom de paramètre pour la clé API. Une clé API est envoyée à votre serveur backend sous la forme d'une paire clé/valeur. La valeur que vous saisissez ici sera utilisée comme nom de la clé API que vous avez sélectionnée précédemment.
  • Emplacement de la clé API : sélectionnez l'emplacement où vous souhaitez ajouter la clé API dans la requête.
• Attribution des identifiants client OAuth 2.0
  • ID client : ID client à utiliser pour l'authentification auprès du service intermédiaire.
  • Code secret client : secret Secret Manager contenant le code secret client pour l'authentification auprès du service intermédiaire.
  • Format de requête pour le jeton d'accès : format de requête à utiliser dans les requêtes effectuées pour récupérer le jeton d'accès sur le serveur d'authentification. Sélectionnez body pour transmettre l'ID client et le secret en tant que corps de requête, ou header pour les transmettre en tant qu'en-tête encodé.
  • Chemin de requête du jeton : chemin d'accès de la requête à ajouter à l'URL du serveur d'authentification pour récupérer l'URL du jeton d'accès.
• Authentification de base
  • Nom d'utilisateur : nom d'utilisateur permettant de s'authentifier auprès du service intermédiaire.
  • Mot de passe : secret Secret Manager contenant le mot de passe associé au nom d'utilisateur fourni.
• Authentification Digest
  • Nom d'utilisateur : nom d'utilisateur permettant de s'authentifier auprès du service intermédiaire.
  • Mot de passe : secret Secret Manager contenant le mot de passe associé au nom d'utilisateur fourni.

API

Les exemples de commandes suivants montrent comment créer un connecteur personnalisé à l'aide des API Application Integration :

1. Créez le connecteur.

   curl -X POST \
   -H "authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json"
   -d '{"customConnectorType":"OPEN_API", \
   "displayName":"CUSTOM_CONNECTOR_NAME", \
   "description": "an open api based custom connector for hrms"}' \
   "https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors?custom_connector_id=UNIQUE_IDENTIFIER"
   

   Remplacez les éléments suivants :

   • CUSTOM_CONNECTOR_NAME : nom du connecteur personnalisé.
   • PROJECT_ID : ID de votre projet Google Cloud .
   • UNIQUE_IDENTIFIER : identifiant unique du connecteur. Exemple : custom-connector-1.
2. Configurez la version du connecteur personnalisé et l'authentification.

   curl -X POST \
   -H "authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -d '{"spec_location": "SPECIFICATION_URL", \
   "service_account":"test-sa", \
   "enable_backend_destination_config": true, \
   "auth_config": { \
   "auth_type":"USER_PASSWORD", \
   "auth_key": "basic", \
   "user_password": { \
   "username":"USERNAME", \
   "password": {"secret_version":"projects/PROJECT_ID/secrets/fidelity-secret/versions/SECRET_VERSION_NUMBER"} \
   }}, \
   "backend_variable_templates": [{ \
   "key":"authkey", \
   "value_type":"SECRET", \
   "display_name":"Authorization Key", \
   "required":true, \
   "location_type": "HEADER" \
   }], \
   "destination_configs":[{ \
   "key":"base_url", \
   "destinations": [{ \
   "host":"DESTINATION_HOST_ADDRESS" \
   }]} \
   ]}' \
   "https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors/facade-connector/customConnectorVersions?custom_connector_version_id=CONNECTOR_VERSION_NUMBER"
   

Remplacez les éléments suivants :

• SPECIFICATION_URL : URL de la spécification OpenAPI. Exemple : https://petstore3.swagger.io/api/v3/openapi.json.
• PROJECT_ID : ID de votre projet Google Cloud .
• USERNAME : nom d'utilisateur pour l'authentification auprès du service intermédiaire.
• SECRET_VERSION_NUMBER : numéro de version du secret Secret Manager. Exemple : 2.
• DESTINATION_HOST_ADDRESS : adresse de l'hôte du service intermédiaire. Exemple : http://www.test.com:80.
• CONNECTOR_VERSION_NUMBER : numéro de version du connecteur personnalisé. Exemple : 1.
Remarque : Cet exemple d'appel d'API utilise l'authentification Username and Password. Selon vos besoins, vous pouvez utiliser un autre type d'authentification.

Créer une connexion de connecteur personnalisé

Après avoir créé votre connecteur personnalisé, vous devez créer une connexion de ce type pour vous connecter à votre backend. Voici les principales étapes à suivre pour créer une connexion :

1. Cliquez sur Créer pour ouvrir la page Créer une connexion.
2. Dans la section Emplacement, sélectionnez un emplacement pour la connexion dans le champ Région.

   Pour obtenir la liste de toutes les régions disponibles, consultez Emplacements.

3. Cliquez sur Suivant.
4. Dans la section Détails de connexion, définissez les champs suivants :
   1. Connecteur : sélectionnez votre connecteur personnalisé dans la liste déroulante des connecteurs disponibles.
   2. Version du connecteur : sélectionnez la version du connecteur dans la liste déroulante des versions disponibles.
   3. Dans le champ Nom de connexion, indiquez le nom de la connexion.

      Les noms de connexion doivent répondre aux critères suivants :

      • Ils peuvent contenir des lettres, des chiffres ou des traits d'union.
      • Les lettres doivent être en minuscules.
      • Ils doivent commencer par une lettre et se terminer par une lettre ou un chiffre.
      • Ils ne peuvent pas dépasser 63 caractères.
   4. (Facultatif) Saisissez une description de la connexion.
   5. (Facultatif) Sélectionnez Activer Cloud Logging pour activer Cloud Logging.
   6. Compte de service : sélectionnez un compte de service disposant des rôles requis.
   7. (Facultatif) Configurez les paramètres des nœuds de connexion :
      • Nombre minimal de nœuds : saisissez le nombre minimal de nœuds de connexion.
      • Nombre maximal de nœuds : saisissez le nombre maximal de nœuds de connexion.

      Un nœud est une unité (ou instance répliquée) de connexion qui traite des transactions. Pour traiter davantage de transactions pour une connexion, vous devez disposer de plus de nœuds. À l'inverse, moins de nœuds sont nécessaires si une connexion traite moins de transactions. Pour comprendre comment les nœuds affectent la tarification de votre connecteur, consultez Tarifs des nœuds de connexion. Si vous ne saisissez aucune valeur, le nombre minimal de nœuds est défini par défaut sur 2 (pour améliorer la disponibilité) et le nombre maximal de nœuds sur 50.

   Remarque : Vous ne pouvez personnaliser les valeurs des nœuds de connexion que si vous avez opté pour le paiement à l'usage.
   8. (Facultatif) Cliquez sur Ajouter une étiquette pour ajouter une étiquette à la connexion sous la forme d'une paire clé/valeur.
5. Cliquez sur Suivant.
6. Si le connecteur utilise un service intermédiaire pour se connecter à votre backend, procédez comme suit :

   Dans la section Destinations, définissez les champs suivants :

   1. Type de destination : sélectionnez Adresse de l'hôte.
   2. Hôte : saisissez le nom de l'hôte sur lequel votre service intermédiaire est exécuté et incluez le schéma http:// ou https://.
   3. Port : saisissez le numéro de port de votre service intermédiaire.

   Par défaut, le champ de destination contient l'URL de la spécification OpenAPI. Lorsque plusieurs URL de serveur existent, la première est affichée.

7. Cliquez sur Suivant.
8. Dans la section Authentification, saisissez les informations d'authentification de votre backend.
   • Si vous vous connectez directement à votre backend, Application Integration vous invite à configurer son authentification.
   • Si vous vous connectez indirectement à votre backend par le biais d'un service intermédiaire, Application Integration ne vous invite pas à configurer les détails d'authentification. Lorsque vous avez créé le connecteur, vous avez déjà configuré l'authentification entre Application Integration et le service intermédiaire. Application Integration ne nécessite pas de configurer l'authentification entre le service intermédiaire et le backend. C'est au service intermédiaire de choisir comment s'authentifier auprès du backend.
9. Cliquez sur Suivant.
10. Vérifiez les détails de la configuration de la connexion, puis cliquez sur Créer.

Si la création de la connexion aboutit, elle figure sur la page Toutes les connexions et la connexion devient disponible dans Application Integration. Vous pouvez utiliser la connexion dans votre intégration au moyen de la tâche Connecteurs.

Remarques

Tenez compte des points suivants lorsque vous créez un connecteur personnalisé :

• Application Integration n'est compatible qu'avec la version 3.0 d'OpenAPI et toutes ses versions mineures.
• La spécification OpenAPI n'est pas validée lors de la création du connecteur personnalisé. Lorsque vous créez une connexion pour le connecteur personnalisé, Application Integration valide la spécification. Si elle contient des erreurs, la connexion est à l'état Error.
• Application Integration ne fait pas la distinction entre les entités et les actions. Par conséquent, les entités et les actions de votre backend seront listées en tant que Actions dans votre connecteur personnalisé.
• Les connecteurs personnalisés ne sont pas compatibles avec les projets Google Cloud pour lesquels VPC Service Controls est activé.
• Le point de terminaison de la spécification OpenAPI et le point de terminaison du backend doivent être accessibles publiquement. Cela signifie que vous ne pouvez pas établir de connectivité privée à votre backend.
• Le type de contenu en plusieurs parties n'est pas compatible avec la spécification OpenAPI.
• Vous ne pouvez pas modifier les détails de la version d'un connecteur personnalisé.

Quotas et limites

Pour plus d'informations sur les quotas et les limites, consultez la section Quotas et limites.

Étape suivante

• Découvrez toutes les tâches et tous les déclencheurs.
• Découvrez comment tester et publier une intégration.
• En savoir plus sur la gestion des erreurs
• En savoir plus sur les journaux d'exécution d'intégration