Créer un connecteur personnalisé

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

Pour établir une connectivité avec votre backend à l'aide d'un connecteur personnalisé, procédez comme suit:

  1. Créer un connecteur personnalisé : dans cette tâche, vous allez définir le contrat entre les connecteurs Integration Connectors et votre point de terminaison (backend) en fournissant la spécification OpenAPI du point de terminaison. Actuellement, seule la version 3.0 d'OpenAPI et toutes ses versions mineures sont compatibles. La spécification est une activité ponctuelle.
  2. Créer une connexion de connecteur personnalisée : dans cette tâche, vous allez configurer les informations de connexion de votre backend, telles 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 la section Connecteur par rapport à la connexion.

Avant de commencer

Créer un connecteur personnalisé

Comme décrit dans les scénarios de connectivité 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 via un point de terminaison public intermédiaire.

La procédure de création de connecteurs personnalisés diffère légèrement pour ces deux modèles.

Créer 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 Integration Connectors > Custom connectors (Connecteurs d'intégration > Connecteurs personnalisés), puis sélectionnez ou créez un Google Cloud projet.

    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.
  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 Open API 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, il s'affiche sur la page Accéder à la page des connecteurs personnalisés. S'il s'agit d'un nouveau connecteur, une première version 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 connecteur nouvellement créé. Pour en savoir plus, consultez la section Créer une connexion de connecteur personnalisé.

API

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

  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 Google Cloud projet.
    • UNIQUE_IDENTIFIER: identifiant unique du connecteur. Par 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"

    3. Remplacez les éléments suivants :

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

Créer avec une connectivité indirecte

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

Console

  1. Dans la console, accédez à la page Integration Connectors > Custom connectors (Connecteurs d'intégration > 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. 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.
  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 Open API 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 hôte.
    2. Hôte: saisissez le nom d'hôte sur lequel votre service intermédiaire s'exécute.
    3. Port: saisissez le numéro de port de votre service intermédiaire.
  8. Cliquez sur Suivant.
  9. Dans la section Authentication connector (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 des connecteurs d'intégration au service intermédiaire.

    La configuration de l'authentification du service intermédiaire vers le backend ne peut pas être configurée dans les connecteurs d'intégration. C'est au service intermédiaire de choisir comment s'authentifier auprès du backend.

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

    • Authentification par compte de service
    • Authentification par clé API
    • OAuth 2.0 : Authentification par identifiants client
    • Authentification de base
    • Authentification condensée

      • Pour comprendre comment configurer ces types d'authentification, consultez la section Configurer l'authentification.

    Si l'accès aux ressources de l'API n'est pas limité 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 via le 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: indiquez comment le connecteur doit envoyer les variables au service intermédiaire. Les options disponibles sont Header, Request payload et Query parameter.
    • Vous pouvez également sélectionner Required pour spécifier que la variable est obligatoire.
  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 nouvellement créé 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 la section Gérer les versions de connecteurs personnalisés.

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

Configurer l'authentification

Saisissez les détails en fonction de l'authentification que vous souhaitez utiliser.

  • Authentification des comptes de service

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

    • Champs d'application: sélectionnez les champs d'application OAuth 2.0 requis dans le menu déroulant. Pour en savoir plus, consultez la section Champs d'application 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 la 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 clé pour la clé API que vous avez précédemment sélectionnée.
    • Emplacement de la clé API: sélectionnez l'emplacement où vous souhaitez ajouter la clé API dans la requête.
  • OAuth 2.0 : octroi d'identifiants client
    • ID client: ID client à utiliser pour authentifier l'accès au 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 utilisé pour 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 condensée
    • Nom d'utilisateur: nom d'utilisateur utilisé pour 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 Integration Connectors:

  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 Google Cloud projet.
    • UNIQUE_IDENTIFIER: identifiant unique du connecteur. Par 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"

    3. Remplacez les éléments suivants :

    • SPECIFICATION_URL: URL de la spécification Open API. Par exemple, https://petstore3.swagger.io/api/v3/openapi.json.
    • PROJECT_ID: ID de votre Google Cloud projet.
    • 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 hôte du service intermédiaire. Exemple :http://www.test.com:80
    • CONNECTOR_VERSION_NUMBER: numéro de version du connecteur personnalisé. Exemple :1

Créer une connexion de connecteur personnalisé

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

  1. Dans la console Cloud, accédez à la page Integration Connectors > Connections (Connecteurs d'intégration > Connexions), puis sélectionnez ou créez un projet Google Cloud.

    Accéder à la page "Connexions"

  2. Cliquez sur Créer pour ouvrir la page Créer une connexion.
  3. 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 la page Emplacements.

  4. Cliquez sur Suivant.
  5. 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 la connexion, saisissez un nom pour la connexion.

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

      • Les noms de connexion peuvent contenir des lettres, des chiffres ou des traits d'union.
      • Les lettres doivent être en minuscules.
      • Les noms de connexion doivent commencer par une lettre et se terminer par une lettre ou un chiffre.
      • Les noms de connexion ne peuvent pas dépasser 63 caractères.
    4. Saisissez éventuellement une description pour la connexion.
    5. Vous pouvez également sélectionner Activer Cloud Logging pour activer la journalisation cloud.
    6. Compte de service: sélectionnez un compte de service disposant des rôles requis.
    7. Vous pouvez également configurer les paramètres du nœud 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 plus de transactions pour une connexion, plus de nœuds sont nécessaires. À l'inverse, moins de nœuds sont nécessaires pour traiter moins de transactions. Pour comprendre comment les nœuds affectent la tarification de votre connecteur, consultez la section 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 une meilleure disponibilité) et le nombre maximal sur 50.

    8. Vous pouvez également cliquer sur Ajouter un libellé pour ajouter un libellé à la connexion sous la forme d'une paire clé-valeur.
  6. Cliquez sur Suivant.
  7. Dans la section Authentification, saisissez les informations d'authentification de votre backend.
    • Si vous vous connectez directement à votre backend, Integration Connectors vous invite à configurer l'authentification pour votre backend.
    • Si vous vous connectez indirectement à votre backend via un service intermédiaire, Integration Connectors ne vous invite pas à configurer les informations d'authentification. Lorsque vous avez créé le connecteur, vous avez déjà configuré l'authentification entre les connecteurs d'intégration et le service intermédiaire. Les connecteurs d'intégration ne nécessitent 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.
  8. Cliquez sur Suivant.
  9. 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 est listée sur la page Toutes les connexions et devient disponible dans l'intégration d'applications. Vous pouvez utiliser la connexion dans votre intégration via la tâche Connecteurs.

Remarques

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

  • Les connecteurs d'intégration ne sont compatibles 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é, Integration Connectors valide la spécification. En cas d'erreur, la connexion est à l'état Error.
  • Les connecteurs d'intégration ne font 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 comme Actions dans votre connecteur personnalisé.
  • Les connecteurs personnalisés ne sont pas compatibles avec les Google Cloud projets 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 au public. Cela signifie que vous ne pouvez pas établir de connectivité privée avec votre backend.
  • Le type de contenu multimédia multiparti n'est pas accepté dans la spécification Open API.
  • Vous ne pouvez pas modifier les informations de version d'un connecteur personnalisé.