HubSpot

Le connecteur HubSpot vous permet d'effectuer des opérations d'insertion, de suppression, de mise à jour et de lecture sur des ensembles de données HubSpot.

Versions compatibles

Ce connecteur est compatible avec les versions de l'API HubSpot suivantes :

  • HubSpot
  • HubSpotV3
  • HubSpotV4

Avant de commencer

Avant d'utiliser le connecteur HubSpot, effectuez les tâches suivantes :

  • Dans votre projet Google Cloud :
    • Assurez-vous que la connectivité réseau est configurée. Pour en savoir plus sur les schémas de réseau, consultez Connectivité réseau.
    • 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 type spécial de compte Google 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 en savoir plus, consultez 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 Activer des services.

    Si ces services ou autorisations n'ont pas encore été activés pour votre projet, vous êtes invité à les activer au moment de configurer le connecteur.

Configurer le connecteur

Une connexion est propre à 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 :

  1. Dans la console Cloud, accédez à la page 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, choisissez l'emplacement de la connexion.
    1. Région : sélectionnez un emplacement dans la liste déroulante.

      Les régions disponibles pour les connecteurs sont les suivantes :

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

    2. Cliquez sur Suivant.
  4. Dans la section Détails de connexion, procédez comme suit :
    1. Connecteur : sélectionnez HubSpot 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 l'instance de 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 49 caractères.
      • Pour les connecteurs qui acceptent les abonnements aux événements, les noms de connexion ne peuvent pas commencer par le préfixe "goog".
    4. (Facultatif) Saisissez une description de l'instance de connexion.
    5. Compte de service : sélectionnez un compte de service disposant des rôles requis.
    6. Pour utiliser la connexion pour les abonnements aux événements, sélectionnez Activer l'abonnement aux événements. Si vous sélectionnez cette option, les options suivantes s'affichent :
      • Activer l'abonnement aux événements avec entité et actions : sélectionnez cette option pour utiliser la connexion à la fois pour l'abonnement aux événements et les opérations de connecteur (entités et actions).
      • Activer uniquement l'abonnement aux événements : sélectionnez cette option afin d'utiliser la connexion uniquement pour l'abonnement aux événements. Si vous sélectionnez cette option, cliquez sur Suivant, puis configurez l'abonnement aux événements.
    7. Schéma : spécifiez la version de l'API HubSpot à utiliser. HubSpotV4 est la nouvelle API.
    8. BrowsableSchemas : cette propriété restreint les schémas signalés à un sous-ensemble des schémas disponibles. Par exemple : BrowsableSchemas=SchemaA,SchemaB,SchemaC.
    9. Propriétés des contacts : saisissez les noms de champs de l'entité Contacts que vous souhaitez sélectionner dans l'opération d'entité List, séparés par une virgule. Par exemple : fieldA, fieldB, fieldC.
    10. Propriétés des entreprises : saisissez les noms de champ de l'entité Companies que vous souhaitez sélectionner dans l'opération d'entité List, séparés par une virgule. Par exemple : fieldA, fieldB, fieldC.
    11. Propriétés des offres : saisissez les noms de champ de l'entité Deals que vous souhaitez sélectionner dans l'opération d'entité List, séparés par une virgule. Par exemple : fieldA, fieldB, fieldC.
    12. Utiliser un proxy : cochez cette case pour configurer un serveur proxy pour la connexion.
    13. Schéma d'authentification du proxy : type d'authentification à utiliser pour s'authentifier auprès du proxy ProxyServer.
    14. Utilisateur du proxy : nom d'utilisateur permettant de s'authentifier auprès du proxy ProxyServer.
    15. Mot de passe du proxy : mot de passe à utiliser pour s'authentifier auprès du proxy ProxyServer.
    16. Type SSL du proxy : type SSL à utiliser pour se connecter au proxy ProxyServer.
    17. (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.

    18. (Facultatif) Cliquez sur + Ajouter une étiquette pour ajouter une étiquette à la connexion sous la forme d'une paire clé/valeur.
    19. Cliquez sur Suivant.
  5. Dans la section Destinations, saisissez des informations sur l'hôte distant (système backend) auquel vous souhaitez vous connecter.
    1. Type de destination : vous pouvez spécifier les détails de destination sous la forme d'une adresse d'hôte ou d'un rattachement de service. Sélectionnez l'un des types de destination suivants :
      • Adresse de l'hôte : si vous souhaitez spécifier le nom d'hôte ou l'adresse IP de la destination.
      • Rattachement de service : si vous souhaitez spécifier le point de terminaison privé pour vos adresses IP internes. Le rattachement de service vous permet de masquer vos adresses IP internes dans le réseau externe. Vous pouvez créer un rattachement de service dans Google Cloud à l'aide de la fonctionnalité Private Service Connect. Pour en savoir plus sur la configuration de Private Service Connect, consultez Publier des services gérés.

      En fonction du type de destination sélectionné, saisissez l'adresse de l'hôte ou le nom du rattachement de service.

      Pour saisir d'autres destinations, cliquez sur + Ajouter une destination.

    2. Cliquez sur Suivant.
  6. Dans la section Authentification, saisissez les informations d'authentification.
    1. Sélectionnez un type d'authentification, puis saisissez les informations appropriées.

      Le type d'authentification suivant est compatible avec la connexion HubSpot :

      • Jeton d'accès à l'application privée : sélectionnez le secret Secret Manager contenant le jeton d'accès à l'application privée.

        Les applications privées vous permettent d'utiliser les API HubSpot pour accéder à des données spécifiques de votre compte HubSpot. Vous pouvez autoriser ce que chaque application privée peut demander ou modifier dans votre compte, ce qui génère un jeton d'accès unique pour votre application privée. Dans votre application privée, assurez-vous d'avoir accordé l'autorisation de lecture au moins aux niveaux d'accès suivants :

        • crm.schemas.line_items.read
        • crm.schemas.quotes.read
        • crm.schemas.deals.read
        • crm.schemas.companies.read
        • crm.schemas.custom.read
        • crm.schemas.contacts.read

        Pour en savoir plus, consultez Applications privées.

    2. Cliquez sur Suivant.
  7. Si vous avez activé l'abonnement aux événements, la section Détails de l'abonnement aux événements s'affiche sur la page de création de la connexion. À l'étape Détails de l'abonnement à l'événement, fournissez les informations d'authentification qui seront utilisées pour valider la charge utile du jeton HubSpot :
    1. Code secret du client (facultatif) : sélectionnez le secret Secret Manager du code secret du client de votre application privée, puis la version de secret correspondante dans le menu déroulant Version du secret.

      2. Pour en savoir plus, consultez Applications privées.

    2. Sélectionnez Activer la connectivité privée pour la connectivité sécurisée entre votre application backend et votre connexion. Si vous sélectionnez cette option, vous devez effectuer des étapes de configuration supplémentaires après avoir créé la connexion. Pour en savoir plus, consultez Connectivité privée pour l'abonnement aux événements.
    3. Saisissez la configuration de lettres mortes. Si vous configurez les lettres mortes, la connexion écrit les événements non traités dans le sujet Pub/Sub spécifié. Saisissez les informations suivantes :
      1. ID du projet de lettres mortes : ID du projet Google Cloud dans lequel vous avez configuré la file d'attente Pub/Sub de lettres mortes.
      2. File d'attente de lettres mortes : sujet Pub/Sub dans lequel vous souhaitez écrire les détails des événements non traités.
    4. Cliquez sur Suivant.
  8. Vérifier : vérifiez vos informations de connexion et d'authentification.
  9. Cliquez sur Créer.

Type de connexion au serveur HubSpot V1

Le tableau suivant présente des exemples de valeurs pour les différents champs que vous configurez lorsque vous créez la connexion HubSpot.
Nom du champ Détails
Région us-central1
Connecteur HubSpot
Version du connecteur 1
Nom de connexion hub-spot-conn
Compte de service SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com/td>
Schéma Hubspot
Nombre minimal de nœuds 2
Nombre maximal de nœuds 50
Jeton d'accès à l'application privée PRIVATE_APP_ACCESS_TOKEN
Version du secret 1

Créer un jeton d'accès à une application privée dans HubSpot

  1. Créez un compte HubSpot et connectez-vous à HubSpot.
  2. Cliquez sur Paramètres, puis accédez à Intégrations > Applications privées.
  3. Cliquez sur Créer une application privée.
  4. Dans l'onglet Informations de base, configurez les détails de votre application, tels que le nom, le logo et la description.
  5. Dans l'onglet Niveaux d'accès, sélectionnez Lecture ou Écriture pour chaque niveau d'accès auquel vous souhaitez que votre application privée puisse accéder.
  6. Une fois l'application configurée, cliquez sur Créer l'application.
  7. Examinez les informations sur le jeton d'accès de votre application, et cliquez sur Continuer la création, puis sur Afficher le jeton.

    8. Utilisez cette valeur de jeton pour spécifier le jeton d'accès à l'application privée lorsque vous configurez la connexion dans Google Cloud.

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 par le biais de 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és. 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, alors que dans un connecteur de serveur de fichiers, ce sont les dossiers, et dans un connecteur de système de messagerie, ce sont les files d'attente.

    Toutefois, il est possible qu'un connecteur n'accepte 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é. Voici les opérations possibles :

    Lorsque vous sélectionnez une entité dans la liste proposée, cela 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 "Connecteurs". Cependant, si un connecteur n'accepte pas l'une des opérations d'entité, cette opération non compatible ne figure pas dans la liste Operations.

  • Action : une action est une fonction de première classe mise à la disposition de l'intégration par le biais de 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 n'accepte aucune action, auquel cas la liste Actions est vide.

Problèmes connus

  • L'opération de mise à jour de certaines entités renvoie une réponse vide, même si la mise à jour aboutit. Dans ce cas, nous vous recommandons de vérifier la mise à jour dans votre instance HubSpot.
  • Dans HubSpot, vous pouvez avoir de nombreux champs personnalisés pour les entités suivantes :
    • Contacts
    • Entreprises
    • Transactions

    Pour ces entités, si tous les champs sont sélectionnés en même temps dans l'opération d'entité List, le connecteur HubSpot peut renvoyer une erreur. Dans les cas où vous souhaitez limiter le nombre de champs personnalisés de l'opération List, spécifiez les noms de champ requis (sous forme de valeurs séparées par une virgule) dans la configuration du connecteur HubSpot. Par exemple, pour limiter les champs de l'entité Contacts, spécifiez les noms de champ obligatoires dans le champ Contacts Properties de la configuration du connecteur. De même, pour l'entité Companies, spécifiez les noms de champs obligatoires dans le champ Companies Properties, et pour l'entité Deals, spécifiez les noms de champs obligatoires dans le champ Deals Properties.

    Vous pouvez spécifier les champs lors de la création de la connexion. Toutefois, si vous disposez déjà d'une connexion, vous devez la modifier, puis spécifier les champs obligatoires.

  • Si votre ensemble de résultats est très volumineux, l'opération List peut échouer en raison d'un délai avant expiration de la connexion. Dans ce cas, vous pouvez limiter votre ensemble de résultats en spécifiant la clause de filtre pour l'opération "List".

Exemples d'opérations d'entité

Cette section explique comment effectuer certaines opérations d'entité dans ce connecteur.

Exemple : Lister tous les contacts

Cet exemple liste tous les enregistrements de l'entité Contacts.

  1. Dans la boîte de dialogue Configure connector task, cliquez sur Entities.
  2. Sélectionnez Contacts dans la liste Entity.
  3. Sélectionnez l'opération LIST, puis cliquez sur OK.

Exemple : Récupérer un enregistrement de transaction

Cet exemple récupère un enregistrement dont l'ID est 45 à partir de l'entité Deals.

  1. Dans la boîte de dialogue Configure connector task, cliquez sur Entities.
  2. Sélectionnez Deals dans la liste Entity.
  3. Sélectionnez l'opération GET, puis cliquez sur OK.
  4. Dans la section Entrée de la tâche de la tâche Connecteurs, cliquez sur EntityId, puis saisissez 45 dans le champ Valeur par défaut.

    Ici, 45 est une valeur de clé primaire dans l'entité Deals.

Exemple : Créer une demande

Cet exemple crée une demande dans l'entité Ticket.

  1. Dans la boîte de dialogue Configure connector task, cliquez sur Entities.
  2. Sélectionnez Tickets dans la liste Entity.
  3. Sélectionnez l'opération Create, puis cliquez sur OK.
  4. Dans la section Entrée de la tâche de la tâche Connecteurs, cliquez sur connectorInputPayload, puis saisissez une valeur semblable à la suivante dans le champ Default Value : 
    {
"Name": "Test735362767",
"Label": "Test735362767",
"Type": "String",
"FieldType": "Insert ticket1",
"GroupName": "ticketinformation",
"Description": "Test ticket"
}

    Si l'intégration aboutit, le champ connectorOutputPayload de la tâche "Connecteurs" aura une valeur semblable à la suivante :

    {
"Name": "Test1695971640609"
}

Exemple : Mettre à jour une entrée de transaction

Cet exemple met à jour l'enregistrement dont l'ID est 97 dans l'entité Contacts.

  1. Dans la boîte de dialogue Configure connector task, cliquez sur Entities.
  2. Sélectionnez Deals dans la liste Entity.
  3. Sélectionnez l'opération Update, puis cliquez sur OK.
  4. Dans la section Entrée de la tâche de la tâche Connecteurs, cliquez sur connectorInputPayload, puis saisissez une valeur semblable à la suivante dans le champ Default Value : 
    {
"Description": "New description"
}
  5. Cliquez sur entityId, puis saisissez 97 dans le champ Valeur par défaut.

    Sinon, au lieu de spécifier entityId, vous pouvez définir filterClause sur 97.

Exemple : Supprimer un formulaire

Cet exemple supprime l'enregistrement dont l'ID est 78 dans l'entité Forms.

  1. Dans la boîte de dialogue Configure connector task, cliquez sur Entities.
  2. Sélectionnez Forms dans la liste Entity.
  3. Sélectionnez l'opération Delete, puis cliquez sur OK.
  4. Dans la section Entrée de la tâche de la tâche Connecteurs, cliquez sur entityId, puis saisissez 78 dans le champ Valeur par défaut.

Créer des connexions à l'aide de Terraform

Vous pouvez utiliser la ressource Terraform pour créer une connexion.

Pour savoir comment appliquer ou supprimer une configuration Terraform, consultez Commandes Terraform de base.

Pour afficher un exemple de modèle Terraform permettant de créer une connexion, consultez 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 Obligatoire Description
schema ENUM Oui Spécifiez la version de l'API HubSpot à utiliser. HubSpotV4 est la nouvelle API. Valeurs acceptées : HubSpot, HubSpotV3 et HubSpotV4.
browsable_schemas STRING False Cette propriété restreint les schémas signalés à un sous-ensemble des schémas disponibles. Par exemple : BrowsableSchemas=SchemaA,SchemaB,SchemaC.
contacts_columns CHAÎNE Non Liste de propriétés à sélectionner dans HubSpot pour l'entité Contacts, séparées par une virgule.
companies_columns CHAÎNE Non Liste de propriétés à sélectionner dans HubSpot pour l'entité Entreprises, séparées par une virgule.
deals_columns CHAÎNE Non Liste de propriétés à sélectionner dans HubSpot pour l'entité Transactions, séparées par une virgule.
proxy_enabled BOOLEAN False Cochez cette case afin de configurer un serveur proxy pour la connexion.
proxy_auth_scheme ENUM False Type d'authentification à utiliser pour s'authentifier auprès du proxy ProxyServer. Valeurs acceptées : BASIC, DIGEST et NONE.
proxy_user STRING False Nom d'utilisateur permettant de s'authentifier auprès du proxy ProxyServer.
proxy_password SECRET False Mot de passe à utiliser pour s'authentifier auprès du proxy ProxyServer.
proxy_ssltype ENUM False Type SSL à utiliser pour se connecter au proxy ProxyServer. Valeurs acceptées : AUTO, ALWAYS, NEVER et TUNNEL.

Utiliser la connexion HubSpot dans une intégration

Une fois la connexion créée, elle devient disponible dans Apigee Integration et Application Integration. Vous pouvez utiliser la connexion dans une intégration au moyen de la tâche "Connecteurs".

  • Pour savoir comment créer et utiliser la tâche "Connecteurs" dans Apigee Integration, consultez Tâche "Connecteurs".
  • Pour savoir comment créer et utiliser la tâche "Connecteurs" dans Application Integration, consultez Tâche "Connecteurs".

Demander de l'aide à la communauté Google Cloud

Vous pouvez publier vos questions et discuter de ce connecteur sur les forums Cloud de la communauté Google Cloud.

Étapes suivantes