HTTP
Le connecteur HTTP fournit une connectivité au service HTTP et utilise des API basées sur HTTP. Le connecteur est également compatible avec la connectivité SSL/TLS via une configuration personnalisée, et prend en charge diverses des mécanismes comme l'octroi d'identifiants client OAuth 2.0, Basic et Digest.
Avant de commencer
Avant d'utiliser le connecteur HTTP, effectuez les tâches suivantes :
- Dans votre projet Google Cloud :
- Attribuez le rôle IAM roles/connectors.admin à l'utilisateur qui configure le connecteur.
- Attribuez les rôles IAM suivants au compte de service que vous souhaitez utiliser pour le connecteur :
roles/secretmanager.viewer
roles/secretmanager.secretAccessor
Un compte de service est un compte Google spécial destiné à représenter un utilisateur non humain qui doit s'authentifier et obtenir les autorisations permettant d'accéder aux données des API Google. Si vous ne possédez pas de compte de service, vous devez en créer un. Pour plus d'informations, consultez la section Créer un compte de service.
- Activez les services suivants :
secretmanager.googleapis.com
(API Secret Manager)connectors.googleapis.com
(API Connectors)
Pour savoir comment activer des services, consultez la page Activer des services.
Si ces services ou autorisations n'ont pas encore été activés pour votre projet, vous êtes invité à les activer lors de la configuration du connecteur.
Configurer le connecteur
Pour configurer le connecteur, vous devez créer une connexion à votre source de données (système backend). Une connexion est spécifique à une source de données. Cela signifie que si vous disposez de nombreuses sources de données, vous devez créer une connexion distincte pour chacune d'elles. Pour créer une connexion, procédez comme suit :
- 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.
- Cliquez sur + Créer pour ouvrir la page Créer une connexion.
- Dans la section Emplacement, choisissez l'emplacement de la connexion.
- Région : sélectionnez un emplacement dans la liste déroulante.
Pour obtenir la liste de toutes les régions disponibles, consultez la page Emplacements.
- Cliquez sur Next (Suivant).
- Région : sélectionnez un emplacement dans la liste déroulante.
- Dans la section Détails de connexion, procédez comme suit :
- Connecteur : sélectionnez HTTP dans la liste déroulante des connecteurs disponibles.
- Version du connecteur : sélectionnez la version du connecteur dans la liste déroulante des versions disponibles.
- Dans le champ Nom de connexion, saisissez un nom pour l'instance de 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 49 caractères.
- Saisissez éventuellement une Description pour l'instance de connexion.
- Vous pouvez également activer Cloud Logging, puis sélectionner un niveau de journalisation. Par défaut, le niveau de journalisation est défini sur
Error
. - Compte de service : sélectionnez un compte de service disposant des rôles requis.
- Si vous souhaitez vérifier l'état de la connexion, vous pouvez spécifier une URL de point de terminaison dans le champ Status Check (Vérification de l'état). L'URL peut également inclure une adresse IP de rattachement de point de terminaison. L'état est actif par défaut.
- 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.
-
Utiliser un proxy : cochez cette case pour configurer un serveur proxy pour la connexion.
- Cliquez sur + Ajouter une destination.
- Sélectionnez un type de destination.
- Adresse de l'hôte : spécifiez le nom d'hôte ou l'adresse IP de la destination.
Si vous souhaitez établir une connexion privée à votre backend, procédez comme suit :
- Créez un rattachement de service PSC.
- Créez un rattachement de point de terminaison, puis saisissez les détails du rattachement de point de terminaison dans le champ Adresse de l'hôte.
- Adresse de l'hôte : spécifiez le nom d'hôte ou l'adresse IP de la destination.
- Vous pouvez également cliquer sur + AJOUTER UN LIBELLÉ pour ajouter un libellé à la connexion sous la forme d'une paire clé/valeur.
- Si vous souhaitez utiliser SSL, sélectionnez Activer SSL. Les détails de la configuration SSL s'affichent.
- Sélectionnez un type de truststore. Il peut s'agir de Public, Privé ou Connexion non sécurisée.
- Sélectionnez les certificats comme affiché en fonction de votre choix de truststore.
- Si vous utilisez mTLS, sélectionnez les certificats du magasin de clés dans la section Magasin de clés.
- Si vous le souhaitez, sélectionnez la version TLS.
- Indiquez la suite de chiffrement compatible. Saisir plusieurs suites de chiffrement, comme des valeurs séparées par une virgule. Pour en savoir plus, consultez la page Suites de chiffrement compatibles.
- Cliquez sur Suivant.
- Dans la section Destinations, saisissez les informations concernant l'hôte distant (système backend) auquel vous souhaitez vous connecter.
- Type de destination : sélectionnez un type de destination.
- Sélectionnez Adresse hôte dans la liste pour spécifier le nom d'hôte ou l'adresse IP de la destination.
- Si vous souhaitez établir une connexion privée à vos systèmes backend, sélectionnez Rattachement du point de terminaison dans la liste, puis sélectionnez le rattachement du point de terminaison requis dans la liste Rattachement du point de terminaison.
Si vous souhaitez établir une connexion publique à vos systèmes backend avec une sécurité supplémentaire, vous pouvez envisager de configurer des adresses IP sortantes statiques pour vos connexions, puis de configurer vos règles de pare-feu pour ajouter à la liste d'autorisation uniquement les adresses IP statiques spécifiques.
Pour saisir d'autres destinations, cliquez sur + Ajouter une destination.
- Cliquez sur Suivant.
- Type de destination : sélectionnez un type de destination.
-
Dans la section Authentification, saisissez les informations d'authentification.
- Sélectionnez un type d'authentification, puis saisissez les informations appropriées.
Les types d'authentification suivants sont compatibles avec la connexion HTTP :
- Authentification personnalisée
- OAuth 2.0 : octroi d'identifiants client
- Authentification de base
- Authentification condensée
- OAuth 2.0 - Code d'autorisation
- Compte de service
- Authentification par jeton d'ID de compte de service
- Authentification par clé API
- Cliquez sur Next (Suivant).
Pour comprendre comment configurer ces types d'authentification, consultez la section Configurer l'authentification.
- Sélectionnez un type d'authentification, puis saisissez les informations appropriées.
- Vérifiez vos informations de connexion et d'authentification.
- Cliquez sur Créer.
Configurer l'authentification
Saisissez les détails en fonction de l'authentification que vous souhaitez utiliser.
- Authentification personnalisée
Les détails d'autorisation personnalisée peuvent être ajoutés en tant qu'en-tête de requête lors de l'exécution d'une action de la tâche Connecteurs.
- OAuth 2.0 – Attribution des identifiants client
- ID client : ID client à utiliser pour authentifier les requêtes HTTP.
- Code secret client : secret Secret Manager contenant le code secret client pour l'authentification des requêtes HTTP.
- 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, ouheader
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.
- Délai d'expiration par défaut : délai d'expiration par défaut (en secondes) du jeton d'accès. Ce délai sera utilisé si la réponse du jeton d'accès n'a pas de délai d'expiration. Si la valeur n'est pas fournie, le jeton sera actualisé dans six heures.
- Authentification de base
- Nom d'utilisateur : nom d'utilisateur utilisé pour effectuer une requête HTTP.
- 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 effectuer une requête HTTP.
- Mot de passe : secret Secret Manager contenant le mot de passe associé au nom d'utilisateur fourni.
- OAuth 2.0 - Code d'autorisation
- ID client : ID client fourni par votre application externe.
- Champs d'application : champs d'application d'autorisation compatibles avec votre application externe.
- Secret du client : sélectionnez le secret Secret Manager. Vous devez avoir créé le secret Secret Manager avant de configurer cette autorisation.
- Version du secret : version du secret Secret Manager pour le code secret du client.
- Vous pouvez activer la clé de vérification pour l'échange de code (PKCE) si votre serveur backend le prend en charge.
- URL d'autorisation : saisissez l'URL d'autorisation de votre application externe.
- URL du jeton d'accès : saisissez l'URL permettant d'obtenir le jeton d'accès de votre application externe.
- Compte de service
Sélectionnez cette option pour vous authentifier à l'aide du compte de service que vous avez fourni dans les étapes précédentes lors de la configuration de cette connexion. Assurez-vous d'avoir a fourni au compte de service les rôles et autorisations IAM nécessaires à l'authentification.
- Scopes (Champs d'application) : sélectionnez les champs d'application OAuth 2.0 requis dans la liste déroulante. Pour en savoir plus, consultez Niveaux d'accès
- Authentification par jeton d'ID de compte de service
Sélectionnez cette option pour vous authentifier à l'aide du jeton d'ID généré à partir du compte de service que vous avez fourni aux étapes précédentes. Cette authentification utilise Jetons Web JSON (JWT) pour l'authentification. Le fournisseur du jeton d'ID signe et émet Jetons JWT pour l'authentification à l'aide d'un compte de service.
- Audience : saisissez les destinataires auxquels le jeton JWT est destiné.
- Nom de l'en-tête : saisissez le nom de l'en-tête du jeton d'ID généré à utiliser dans l'en-tête HTTP. Si vous ne
spécifiez une valeur pour ce champ. Par défaut, la valeur de la clé est définie sur
Authorization
.
- 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 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.
Pour le type d'authentification Authorization code
, après avoir créé la connexion, vous
doit effectuer quelques étapes supplémentaires
pour configurer l'authentification. Pour plus d'informations,
consultez la section Étapes supplémentaires après la création d'une connexion.
Suites de chiffrement compatibles
Version TLS | Suites de chiffrement compatibles |
---|---|
1.2 |
|
1.3 |
|
Étapes supplémentaires après la création de la connexion
Si vous avez sélectionné OAuth 2.0 - Authorization code
pour l'authentification, vous devez effectuer les étapes supplémentaires suivantes après avoir créé la connexion :
- Sur la page Connexions :
localisez la connexion qui vient d'être créée.
Notez que l'état du nouveau connecteur sera Autorisation requise.
- Cliquez sur Autorisation requise.
Le volet Modifier l'autorisation s'affiche.
- Copiez la valeur de l'URI de redirection dans votre application externe.
- Vérifiez les détails de l'autorisation.
- Cliquez sur Autoriser.
Si l'autorisation aboutit, l'état de la connexion est défini sur Active (Actif) dans la Page "Connexions".
Nouvelle autorisation pour le code d'autorisation
Si vous utilisez le type d'authentification Authorization code
et que vous avez modifié la configuration de votre application HTTP backend, vous devez autoriser à nouveau votre connexion HTTP. Pour autoriser à nouveau une connexion, procédez comme suit:
- Cliquez sur la connexion requise sur la page Connexions.
La page "Détails de la connexion" s'ouvre.
- Cliquez sur Modifier pour modifier les détails de la connexion.
- Vérifiez les informations OAuth 2.0 – Code d'autorisation dans la section Authentification.
Si nécessaire, apportez les modifications nécessaires.
- Cliquez sur Enregistrer. La page des détails de la connexion s'affiche.
- Cliquez sur Modifier l'autorisation dans la section Authentification. Le volet Autoriser s'affiche.
- Cliquez sur Autoriser.
Si l'autorisation aboutit, l'état de la connexion est défini sur Active (Actif) sur la page Connexions.
Entités, opérations et actions
Tous les connecteurs Integration Connectors fournissent une couche d'abstraction pour les objets de l'application connectée. Vous ne pouvez accéder aux objets d'une application que via cette abstraction. L'abstraction vous est présentée en tant qu'entités, opérations et actions.
- Entité : une entité peut être considérée comme un objet ou un ensemble de propriétés dans l'application ou le service connecté. La définition d'une entité diffère d'un connecteur à l'autre. Par exemple, dans un connecteur de base de données, les tables sont les entités, dans un connecteur de serveur de fichiers, les dossiers sont les entités et, dans un connecteur de système de messagerie, les files d'attente sont les entités.
Toutefois, il est possible qu'un connecteur ne soit pas compatible ou ne possède aucune entité. Dans ce cas, la liste
Entities
est vide. - Opération : une opération est l'activité que vous pouvez effectuer sur une entité. Vous pouvez effectuer l'une des opérations suivantes sur une entité :
La sélection d'une entité dans la liste disponible génère une liste d'opérations disponibles pour l'entité. Pour obtenir une description détaillée des opérations, consultez les opérations d'entité de la tâche de connecteur. Toutefois, si un connecteur n'est pas compatible avec l'une des opérations d'entité, ces opérations non compatibles ne sont pas listées dans la liste
Operations
. - Action : une action est une fonction de première classe mise à la disposition de l'intégration via l'interface du connecteur. Une action vous permet de modifier une ou plusieurs entités, et varie d'un connecteur à l'autre. Normalement, une action comporte des paramètres d'entrée et un paramètre de sortie. Toutefois, il est possible qu'un connecteur ne prenne en charge aucune action, auquel cas la liste
Actions
est vide.
Limites du système
Le connecteur HTTP peut traiter 100 transactions par seconde et par nœud, et limite les transactions au-delà de cette limite. Par défaut, Integration Connectors alloue deux nœuds (pour une meilleure disponibilité) à une connexion.
Pour en savoir plus sur les limites applicables à Integration Connectors, consultez Limites.
Actions autorisées
Le connecteur HTTP accepte les actions suivantes :
Action HttpRequest
Les tableaux suivants décrivent les paramètres d'entrée et de sortie de l'action HttpRequest.
Paramètres d'entrée de l'action HttpRequest
Nom du paramètre | Type de données | Requis | Description |
---|---|---|---|
URL | Struct | Non | URL à laquelle vous souhaitez envoyer la requête.
L'URL est au format <scheme>://<netloc>/<path>;<params>?<query>#<fragment> .
Si vous fournissez netloc , la valeur remplace le nom d'hôte fourni lors de la création de la connexion. |
Méthode | String | Non | Méthode de requête HTTP telle que GET, POST, DELETE ou PUT. La valeur par défaut est GET. |
En-têtes | Struct | Non | En-têtes de requête HTTP. |
Corps | String | Non | Corps de requête HTTP |
RequestHasBytes | Booléen | Non | Indique s'il faut envoyer la requête sous forme d'octets. Si ce paramètre est défini sur true , vous devez envoyer la requête sous forme de chaîne encodée en Base64 dans le paramètre Body . La valeur par défaut est false . |
ResponseHasBytes | Booléen | Non | Indique si la réponse doit être reçue sous forme d'octets. Si la valeur est définie sur true , vous recevrez la réponse sous forme de chaîne encodée en base64 dans le paramètre de sortie ResponseBody . La valeur par défaut est false . |
HttpVersion | String | Non | Version HTTP à utiliser lors de l'envoi d'une requête. Les valeurs acceptées sont 1.1 et 2. Si vous spécifiez la version 2, la négociation ALPN (Application-Layer Protocol Negotiation) a lieu et la version 1.1 est utilisée si le serveur n'est pas compatible avec la version 2. La valeur par défaut est "2". |
ResponseFormat | Chaîne | Non | Spécifie le format de la réponse du connecteur. Les valeurs acceptées sont v1 et v2 .
La valeur par défaut est v1 .
Exemple de réponse v1: [{ "ResponseBody": "{\n \"status\": 200\n}" }, { "StatusCode": 200.0 }, { "HttpVersion": "2" }, { "ResponseHeaders": { ":status": "200", "content-length": "19" } }] Exemple de réponse dans la version 2: [{ "ResponseBody": "{\n \"status\": 200\n}", "StatusCode": 200.0, "HttpVersion": "2", "ResponseHeaders": { ":status": "200", "content-length": "19" } }] |
FailOnError | Booléen | Non | Spécifie le comportement de la connexion en cas d'erreur dans votre application backend.
La valeur par défaut est |
Délai avant expiration | Integer | Non | Valeur du délai avant expiration de la requête HTTP (en secondes). La valeur maximale autorisée est de 150 secondes. |
Paramètres de sortie de l'action HttpRequest
Nom du paramètre | Type de données | Description |
---|---|---|
ResponseBody | String | Réponse reçue du serveur HTTP. |
StatusCode | Integer | Code d'état reçu du serveur HTTP. |
HttpVersion | String | Version négociée pour la requête HTTP. |
ResponseHeaders | Struct | En-têtes de réponse HTTP sous forme de paires key,value . |
Examples
Les exemples de cette section décrivent les opérations suivantes :
- Configurer une charge utile de requête
- Envoyer le contenu en octets
- Obtenir le contenu des octets
Le tableau suivant fournit une liste d'exemples de scénarios et la configuration correspondante dans la tâche de connecteur :
Tâche | Configuration |
---|---|
Configurer une charge utile de requête |
Cet exemple envoie une requête POST à l'URL |
Envoyer des octets de contenu |
Pour envoyer des octets (comme des fichiers) de contenu, vous devez définir l'attribut de requête
Cet exemple envoie une requête POST au serveur |
Obtenir le contenu des octets |
Pour obtenir des octets (sous forme de chaîne Base64) à partir du serveur, vous devez définir l'attribut de requête
Cet exemple envoie une requête GET au serveur |
Codes d'erreur
Cette section décrit les messages d'erreur que vous pouvez obtenir lors de l'utilisation de la connexion HTTP.
Message d'erreur | Cause |
---|---|
Erreur de connexion au serveur HTTP | La connexion HTTP n'a pas pu établir la connexion avec le serveur en raison de l'échec du handshake SSL ou d'un point de terminaison de serveur HTTP incorrect. |
Réponse d'erreur reçue du serveur HTTP | Le serveur HTTP que vous essayez de connecter renvoie une réponse d'erreur avec le code d'état 4xx ou 5xx. Exemple de réponse :
{ "error": { "code": 400, "details": [ { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "metadata": { "Body": "{\"thisIsResponseJSON\":\"someValue\"}" "Error": "Error response received from the HTTP server", "Headers": "{\":status\":[\"400\"], \"access-control-allow-credentials\":[\"true\"]}", "StatusCode": "400", "connection_type": "Http" } } ], "message": "Unable to execute HTTP Request", "status": "FAILED_PRECONDITION" } } |
Erreur lors de la récupération du jeton d'accès | Une erreur s'est produite lors de la récupération du jeton d'accès pour le type d'authentification OAuth Client Credentials Grant . |
Erreur d'authentification condensée | L'environnement d'exécution du connecteur n'a pas reçu de challenge condensé ou son type n'est pas compatible. |
Utiliser Terraform pour créer des connexions
Vous pouvez utiliser l'outil Terraform ressource pour créer une connexion.Pour savoir comment appliquer ou supprimer une configuration Terraform, consultez la page Commandes Terraform de base.
Pour consulter un exemple de modèle Terraform permettant de créer une connexion, consultez l'exemple de modèle.
Lorsque vous créez cette connexion à l'aide de Terraform, vous devez définir les variables suivantes dans votre fichier de configuration Terraform :
Nom du paramètre | Type de données | Requis | Description |
---|---|---|---|
proxy_enabled | VALEUR BOOLÉENNE | Faux | Cochez cette case pour configurer un serveur proxy pour la connexion. |
Utiliser la connexion HTTP dans une intégration
Une fois la connexion créée, elle devient disponible à la fois Apigee Integration et Application Integration. Vous pouvez utiliser la connexion dans une intégration via la tâche Connecteurs.
- Pour comprendre comment créer et utiliser la tâche "Connecteurs" dans Apigee Integration, consultez la section Tâche Connecteurs.
- Pour savoir comment créer et utiliser la tâche Connecteurs dans Application Integration, consultez la section Tâche Connecteurs.
Obtenir de l'aide auprès de la communauté Google Cloud
Vous pouvez publier vos questions et discuter de ce connecteur sur les forums Cloud de la communauté Google Cloud.Étape suivante
- Découvrez comment suspendre et réactiver une connexion.
- Découvrez comment surveiller l'utilisation des connecteurs.
- Découvrez comment afficher les journaux de connecteur.