Tâche de connecteur

Annonce : Application Integration est désormais disponible pour votre projet Google Cloud. Vous pouvez désormais utiliser Apigee Integration et Application Integration dans le même projet Google Cloud. En savoir plus

La tâche Connectors vous permet de vous connecter rapidement et de manière sécurisée aux différents services Google Cloud et autres applications métier à partir de votre intégration, à l'aide des connecteurs prêts à l'emploi disponibles dans Integration Connectors

Pour obtenir la liste de tous les connecteurs compatibles avec Apigee Integration, consultez la documentation de référence sur le connecteur.

Important : Les connecteurs d'intégration sont un composant facturable de Google Cloud. Pour en savoir plus sur les coûts et les frais d'utilisation des connecteurs d'intégration, consultez la page Tarifs Integration Connectors.

Avant de commencer

• Assurez-vous que le rôle IAM Administrateur de connecteurs (roles/connectors.admin) est attribué sur votre projet Google Cloud. Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.
• Découvrez les concepts généraux d'Integration Connectors.
• Pour vous connecter aux services Google Cloud et à d'autres applications métier à l'aide d'un connecteur, assurez-vous d'avoir associé un compte de service géré par l'utilisateur à votre intégration. Si aucun compte de service géré par l'utilisateur n'est configuré pour l'intégration, le compte de service par défaut ([e-mail]) est utilisé par défaut pour l'authentification.
• Assurez-vous que votre compte de service dispose du rôle IAM requis. Pour en savoir plus sur l'attribution d'un rôle à un compte de service, consultez la page Gérer l'accès aux comptes de service.

Ajouter une tâche Connectors

Pour ajouter la tâche Connectors dans votre intégration, procédez comme suit :

1. Dans l'interface utilisateur Apigee, sélectionnez votre organisation Apigee.
2. Cliquez sur Développer > Intégrations.
3. Sélectionnez une intégration existante ou créez-en une en cliquant sur Créer une intégration.

   Si vous créez une intégration :

   1. Saisissez un nom et une description dans la boîte de dialogue Créer une intégration.
   2. Dans la liste des régions compatibles, sélectionnez une région pour l'intégration.
   3. Cliquez sur Créer.

   La page de conception d'intégration s'affiche.

4. Dans la barre de navigation de la page de conception d'intégration, cliquez sur +Ajouter une tâche ou un déclencheur > Tâches pour afficher la liste des tâches disponibles.



5. Si vous souhaitez configurer une nouvelle connexion, cliquez sur l'élément Connecteurs et placez-le dans l'éditeur d'intégrations. Cliquez ensuite sur Configurer le connecteur pour configurer la connexion.

   

6. Si vous disposez déjà d'une connexion, cliquez sur l'onglet Connecteurs pour afficher les connexions récemment créées. Vous pouvez également rechercher un connecteur, une connexion ou une tâche en saisissant son nom dans le champ Rechercher.

   

7. Cliquez sur l'élément Connecteurs configuré et placez-le dans l'éditeur d'intégrations. Pour en savoir plus sur la configuration d'une tâche de connecteur, consultez la section Configurer la tâche de connecteur.

Configurer la tâche de connecteur

Pour configurer une tâche de Connectors, procédez comme suit :

Remarque : Les détails de configuration tels que l'authentification varient en fonction du type de connexion.

1. Cliquez sur l'élément de tâche Connecteurs dans le concepteur pour afficher le volet de configuration de la tâche Connecteurs.

   Vous pouvez également cliquer sur pour modifier le nom de la tâche.

2. Cliquez sur Configurer le connecteur.
3. Vous pouvez sélectionner une connexion existante dans la région ou en créer une. Pour configurer une connexion existante, procédez comme suit sur la page Éditeur de tâches de connecteur.

   L'image suivante présente un exemple de mise en page de la page Éditeur de tâches Connectors.

1. Dans la section Sélectionner une connexion, sélectionnez la région de la connexion.
2. Choisissez une connexion existante dans la liste des connexions disponibles dans la région sélectionnée.
3. Cliquez sur Suivant.
4. Dans la liste Type, sélectionnez Entités ou Actions.
   • Si vous sélectionnez Entités, la liste des entités compatibles pour la connexion s'affiche dans la section Définir les entités/actions. Sélectionnez une entité suivie de l'opération que vous souhaitez effectuer sur cette entité.
   • Si vous sélectionnez Actions, la liste des actions compatibles pour la connexion s'affiche dans la colonne Définir les entités/actions. Sélectionnez une action pour la connexion.
   Les entités et les actions compatibles sont basées sur le type de connecteur. Pour obtenir la liste de tous les connecteurs compatibles avec Apigee Integration, consultez la documentation de référence sur le connecteur. Pour afficher les actions et les entités compatibles avec un connecteur, consultez la documentation sur le connecteur spécifique.

   Si le connecteur est compatible avec les requêtes SQL personnalisées, vous pouvez sélectionner l'option Exécuter la requête personnalisée dans la liste Actions. Pour savoir comment ajouter une requête SQL personnalisée pour votre connecteur, consultez la section Action : Exécuter une requête SQL personnalisée.

   Remarque : Les types de connexions ne sont pas tous compatibles avec les entités ou les actions. Si un type de connexion n'accepte aucune action ou entité, la liste Entités ou Actions correspondante est vide. Pour plus d'informations sur les entités et les actions, consultez la page Entités, opérations et actions.
5. Cliquez sur Terminé pour terminer la configuration de la connexion et fermer le volet.

Configurer les variables d'entrée et de sortie de tâche

Le volet de configuration d'une tâche Connecteurs affiche les variables Entrée de tâche et Sortie de tâche générées automatiquement en fonction des paramètres Entity and Operation ou Action sélectionnés dans la boîte de dialogue Configurer la tâche de connecteur. Ces variables sont configurables et sont accessibles en tant qu'entrées de la tâche en cours ou en tant que sorties de tâches ultérieures ou de conditions configurées dans l'intégration actuelle.

Pour configurer les variables Entrées de tâche ou Sorties de tâche, cliquez sur la variable correspondante pour ouvrir le volet Configurer la variable et procédez comme suit :

1. Saisissez la valeur de la variable dans le champ Default Value (Valeur par défaut).
2. (Facultatif) Sélectionnez Utiliser comme entrée pour l'intégration ou Utiliser comme sortie pour l'intégration.
3. Cliquez sur Enregistrer.

Pour plus d'informations sur les paramètres d'entrée et de sortie de la tâche Connecteurs, consultez la section Opérations d'entité.

Entités, opérations et actions

Vous pouvez effectuer des opérations CRUD (créer, lire, mettre à jour, supprimer) sur les entités d'un connecteur. Chacune de ces opérations d'entité a un ensemble différent de paramètres d'entrée et de sortie. Le tableau suivant répertorie les paramètres d'entrée et de sortie des différentes opérations d'entité.

Nom de l'opération	Paramètres d'entrée	Paramètres de sortie
Liste	listEntitiesPageSize listEntitiesPageToken listEntitiesSortByColumns filterClause	connectorOutputPayload listEntitiesNextPageToken
Obtenir	entityId	connectorOutputPayload
	Remarque : Vous ne pouvez utiliser l'opération Get que pour extraire un seul enregistrement d'une table contenant une clé primaire. Vous pouvez également utiliser l'opération List avec une variable filterClause.
Créer	connectorInputPayload	connectorOutputPayload
Mettre à jour	connectorInputPayload entityId filterClause	connectorOutputPayload
Supprimer	entityId filterClause	N/A

Paramètres d'entrée

Le tableau suivant décrit les paramètres d'entrée pour les différentes opérations d'entité.

Nom du paramètre	Type de données	Description
entityId	Chaîne	Identifiant unique de la ligne à laquelle vous souhaitez accéder. Normalement, entityId est une valeur de clé primaire d'une table ou d'un ensemble de données. Si vous spécifiez une valeur pour entityId et que la table ou l'ensemble de données ne comporte pas de colonne de clé primaire, l'intégration signale une erreur d'exécution et la tâche Connecteurs échoue. Par exemple, pour obtenir une ligne spécifique d'une table MySQL, entityId est la valeur de clé primaire de la table. Remarque : entityId n'est pas obligatoire pour BigQuery. Ce champ reste vide lorsqu'une table BigQuery ne possède pas de clé primaire.
connectorInputPayload	JSON	Les données réelles à ajouter ou à mettre à jour dans une entité. L'exemple suivant montre l'extrait de code JSON correspondant à des données de ligne à ajouter dans une table : { "employee_first_name": "John", "employee_emailID": "[e-mail]" } Dans cet exemple, employee_first_name et employee_emailID sont les noms de colonne avec les valeurs correspondantes John et [e-mail].
filterClause	Chaîne	Limite le résultat des opérations en fonction d'une condition. Pour en savoir plus sur l'ajout d'une clause de filtre, consultez la section Ajouter un filtre pour une opération.
listEntitiesPageSize	Entier	Spécifie le nombre de résultats à renvoyer sur une page. Une page est un regroupement logique des enregistrements dans un ensemble de résultats. Le concept de page est utile lorsque vous attendez un grand nombre d'enregistrements dans l'ensemble de résultats. Si l'ensemble de résultats est volumineux, la tâche Connectors peut échouer, car il existe une limite sur le volume de données que la tâche Connectors peut traiter. En décomposant l'ensemble de résultats en fragments plus petits, vous pouvez éviter ce problème. Par exemple, si vous attendez 1 000 enregistrements dans votre ensemble de résultats, vous pouvez définir listEntitiesPageSize sur 100. Ainsi, lorsque la tâche Connectors s'exécute pour la première fois, elle renvoie les 100 premiers enregistrements, puis les 100 enregistrements suivants lors de la deuxième exécution, etc. Important : La taille de page par défaut est de 25 et le nombre maximal de pages acceptées par la tâche est de 50 000. À moins que votre table ou votre ensemble de données ne possèdent une clé primaire, vous devez définir le paramètre listEntitiesSortByColumns pour qu'il utilise listEntitiesPageToken. Utilisez le paramètre listEntitiesPageSize conjointement avec le paramètre listEntitiesPageToken pour parcourir les pages.
listEntitiesPageToken	Chaîne	Un identifiant de page (jeton) qui vous permet d'accéder à une page spécifique. Vous pouvez obtenir la valeur d'un jeton de page à partir du paramètre de sortie listEntitiesNextPageToken. Étant donné que chaque page possède un jeton unique, vous avez la possibilité d'accéder à n'importe quelle page de l'ensemble de résultats. Pour comprendre l'utilisation de ce paramètre, lisez également la description du paramètre de sortie listEntitiesNextPageToken.
listEntitiesSortByColumns	Tableau de chaînes.	Nom de la colonne selon laquelle l'ensemble de résultats doit être trié. Remarque : Vous ne pouvez trier l'ensemble de résultats que sur une seule colonne.

Paramètres de sortie

Le tableau suivant décrit les paramètres de sortie des différentes opérations d'entité.

Nom du paramètre	Type de données	Description
connectorOutputPayload	JSON	Résultat d'une opération au format JSON.
listEntitiesNextPageToken	Chaîne	Identifiant généré par le système pour une page. Vous pouvez considérer le jeton comme un pointeur permettant d'accéder à une page particulière de l'ensemble de résultats. Si vous avez divisé votre ensemble de résultats en plusieurs pages en définissant le paramètre listEntitiesPageSize, vous avez besoin d'un mécanisme pour parcourir les pages. C'est exactement ce que le paramètre de sortie listEntitiesNextPageToken vous permet de faire. Chaque fois que la tâche Connectors est exécutée, le système génère un jeton pour la page suivante et définit la valeur de listEntitiesNextPageToken sur le jeton nouvellement généré. Vous pouvez ensuite utiliser ce jeton pour accéder à la page suivante de l'ensemble de résultats. Pour accéder à la page suivante, vous devez définir le paramètre d'entrée listEntitiesPageToken sur la valeur du jeton de la page suivante. Supposons par exemple que vous ayez défini le paramètre listEntitiesPageSize sur 2 et que la tâche Connectors s'exécute pour la première fois, le paramètre listEntitiesNextPageToken est défini sur la valeur de jeton ChoKC2VtcGxveWVlX2lkEgkRAAAAAAAA8D8YDw==. Vous pouvez ensuite définir le paramètre d'entrée listEntitiesPageToken sur cette valeur de jeton pour récupérer la page suivante lors de la prochaine exécution de la tâche Connectors. Si votre ensemble de résultats contient un grand nombre de pages, vous pouvez envisager d'utiliser la tâche For Each Loop pour appeler de manière répétée la tâche Connectors et utiliser la fonction Data Mapping pour attribuer automatiquement des valeurs de jeton au paramètre d'entrée listEntitiesPageToken après chaque exécution.

Clause de filtre pour les opérations d'entité

Vous pouvez limiter les enregistrements traités par la tâche Connecteurs à l'aide de la variable Clause de filtre disponible en tant qu'entrée de tâche. Par exemple, dans le cas d'une opération delete, vous pouvez ajouter une clause de filtre pour supprimer des enregistrements avec un orderId spécifique.

La clause Filtre ne peut être appliquée que pour les opérations d'entités suivantes :

• Liste
• Supprimer
• Mettre à jour

Lorsque vous sélectionnez l'une de ces opérations, la section Task Input (Entrées de tâche) de la tâche Connectors affiche automatiquement le champ Filter clause (Clause de filtre).

Ajouter une clause de filtre

Pour ajouter une clause de filtre, procédez comme suit :

1. Cliquez sur l'élément de tâche Connecteurs dans le concepteur pour afficher le volet de configuration de la tâche Connecteurs.
2. Développez la section Entrée de la tâche et cliquez sur la variable de chaîne filterClause(Connectors).

   La boîte de dialogue "Configurer la variable" s'affiche.

3. Saisir la clause de filtre (en suivant la syntaxe de clause) dans le champ Valeur par défaut.
4. Cliquez sur Enregistrer.

Syntaxe et exemples de clauses de filtre

Une clause de filtre a le format suivant :

FIELD_NAME CONDITION FILTER_VALUE

Exemples

• OwnerId = '0053t000007941XAAQ'

• PoNumber < 2345

• OrderNumber = 00110 AND StatusCode = 'Draft'

• TotalAmount > 2500

• ShippingPostalCode = 94043 OR ShippingPostalCode = 77002

Important : Dans la clause de filtre, spécifiez les valeurs de chaîne entre guillemets simples (') ou doubles (") en fonction de la base de données que vous utilisez. Par exemple, MySQL accepte les guillemets simples et doubles, tandis que BigQuery n'accepte que les guillemets simples.

Utilisation de variables dans une clause de filtre

Vous ne pouvez pas utiliser directement une variable d'intégration dans une clause de filtre. Si vous souhaitez utiliser une variable d'intégration, vous devez d'abord configurer une tâche de mappage de données afin de créer un mappage entre la variable d'intégration et la clause de filtre.

Le tableau suivant montre un exemple de mappage entre une variable d'intégration et la variable filterClause(Connectors) :

Entrée	Sortie
PRIMARY_KEY_ID = ' .CONCAT(INTEGRATION_VARIABLE) .CONCAT(')	filterClause(Connectors)

Où PRIMARY_KEY_ID = ' est saisi en tant que valeur dans la ligne d'entrée.

---

Action : exécuter une requête SQL personnalisée

Pour créer une requête enregistrée, procédez comme suit :

1. Suivez les instructions détaillées pour ajouter une tâche de connecteurs.
2. Lorsque vous configurez la tâche de connecteur, sélectionnez Actions dans le type d'action à effectuer.
3. Dans la liste Action, sélectionnez Exécuter une requête personnalisée, puis cliquez sur OK.

   

4. Développez la section Entrée de la tâche, puis procédez comme suit :
   1. Dans le champ Délai d'inactivité après, saisissez le nombre de secondes d'attente jusqu'à l'exécution de la requête.

      Valeur par défaut : 180 secondes.

   2. Dans le champ Nombre maximal de lignes, saisissez le nombre maximal de lignes à renvoyer à partir de la base de données.

      Valeur par défaut : 25

   3. Pour mettre à jour la requête personnalisée, cliquez sur Modifier le script personnalisé. La boîte de dialogue Éditeur de script s'affiche.

      

   4. Dans la boîte de dialogue Éditeur de script, saisissez la requête SQL, puis cliquez sur Enregistrer.

      Vous pouvez utiliser un point d'interrogation (?) dans une instruction SQL pour représenter un seul paramètre devant être spécifié dans la liste des paramètres de requête. Par exemple, la requête SQL suivante sélectionne toutes les lignes de la table Employees correspondant aux valeurs spécifiées pour la colonne LastName :

      SELECT * FROM Employees where LastName=?

      Remarque : Les instructions LMD (langage de manipulation de données) et LDD (langage de définition de données) sont acceptées.
   5. Si vous avez utilisé des points d'interrogation dans votre requête SQL, vous devez ajouter le paramètre en cliquant sur + Ajouter un nom de paramètre pour chaque point d'interrogation. Lors de l'exécution de l'intégration, ces paramètres remplacent les points d'interrogation (?) de la requête SQL de manière séquentielle. Par exemple, si vous avez ajouté trois points d'interrogation (?), vous devez ajouter trois paramètres dans l'ordre.

      

      Pour ajouter des paramètres de requête, procédez comme suit :

      1. Dans la liste Type, sélectionnez le type de données du paramètre.
      2. Dans le champ Valeur, saisissez la valeur du paramètre.
      3. Pour ajouter plusieurs paramètres, cliquez sur + Ajouter un paramètre de requête.

Actualisation du schéma

Toutes les entités et les actions seront associées à un schéma. Par exemple, un schéma d'action contient les détails des paramètres tels que les noms des paramètres et le type de données correspondant. Le schéma (métadonnées) des entités et des actions est récupéré par la connexion au moment de l'exécution à partir de votre backend. Si des mises à jour sont apportées au schéma, elles ne seront pas automatiquement répercutées dans vos connexions existantes. Vous devez actualiser manuellement le schéma. Pour afficher le schéma mis à jour dans vos tâches de connecteur existantes, procédez comme suit :

1. Dans Integration Connectors, ouvrez la page Détails de la connexion de la connexion, puis cliquez sur Actualiser le schéma de connexion.
2. Dans Apigee Integration, vous devez reconfigurer votre tâche de connecteur existante pour la même connexion.

Création de connexions intégrées

Vous pouvez utiliser la tâche Connecteurs pour créer directement une connexion dans les connecteurs d'intégration.

Avant de commencer

• Ajouter une tâche Connecteurs

Créer une connexion

Pour créer une connexion à partir d'Apigee Integration, procédez comme suit :

1. Cliquez sur l'élément de tâche Connecteurs dans le concepteur pour afficher le volet de configuration de la tâche Connecteurs.
2. Cliquez sur Configurer le connecteur.

   La page Éditeur de tâches Connecteurs s'affiche.

3. Ignorez le champ Région.
4. Cliquez sur Connexion, puis sélectionnez l'option Créer une connexion dans le menu déroulant.
5. Procédez comme suit dans le volet Créer une connexion :
   Remarque : Les instructions ci-dessous sont les étapes génériques permettant de créer une connexion. Bien que la majorité des étapes restent les mêmes pour tous les types de connexions, quelques étapes ou détails supplémentaires liés à l'authentification peuvent varier.

   Nous vous recommandons également de consulter la documentation sur les types de connexions correspondants dans Integration Connectors.

   1. Dans la section Emplacement, choisissez l'emplacement de la connexion.
      1. Cliquez sur Région, puis sélectionnez un emplacement dans la liste déroulante.
      2. Cliquez sur Suivant.
   2. À l'étape Détails de connexion, fournissez les informations suivantes sur la connexion :
      1. Connecteur : sélectionnez le type de connecteur que vous souhaitez créer dans la liste déroulante. Pour en savoir plus sur la liste des connecteurs compatibles, consultez la section Tous les connecteurs Integration Connectors.
      2. Version du connecteur : sélectionnez une version disponible du type de connecteur sélectionné dans la liste déroulante.
      3. Nom de connexion : saisissez un nom pour la nouvelle instance de connexion.
         Remarque : 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 l'instance de connexion.
      5. (Facultatif) Cochez la case Activer Cloud Logging pour stocker les données de journal de l'instance de connexion.
      6. Compte de service : sélectionnez un compte de service disposant des rôles requis.
      7. (Facultatif) Cliquez sur Paramètres avancés pour configurer les paramètres du nœud de connexion.

         Pour en savoir plus, consultez la documentation sur la connexion respective dans Integration Connectors.

      8. Vous pouvez également cliquer sur + AJOUTER UN LIBELLÉ pour ajouter un libellé à la connexion sous la forme d'une paire clé/valeur.
      9. Cliquez sur Suivant.
   3. À l'étape Authentification, fournissez les informations d'authentification de la connexion.
      1. Les méthodes d'authentification renseignées au cours de cette étape dépendent du type de connexion créé.

         Les différents types de connexion utilisent des méthodes d'authentification différentes. Pour en savoir plus, consultez la section Configurer l'authentification de la documentation sur les connexions correspondantes dans Integration Connectors.

      2. Cliquez sur Suivant.
   4. Vérifiez vos informations de connexion et d'authentification.
   5. Cliquez sur Créer.

---

Bonnes pratiques

• Pour plus d'informations sur les limites d'utilisation qui s'appliquent à la tâche Connecteurs, consultez la section Limites d'utilisation.
• Pour en savoir plus sur la résolution des problèmes liés à une tâche Connecteurs ayant échoué, consultez la section Utiliser les journaux pour résoudre et suivre les problèmes liés aux connecteurs.

Stratégie de traitement des erreurs

Une stratégie de traitement des erreurs d'une tâche spécifie l'action à effectuer si celle-ci échoue en raison d'une erreur temporaire. Pour en savoir plus sur l'utilisation et les différents types de stratégies de traitement des erreurs, consultez la page Stratégies de traitement des erreurs.