HubSpot

Il connettore HubSpot consente di eseguire operazioni di inserimento, eliminazione, aggiornamento e lettura sul set di dati HubSpot.

Versioni supportate

Questo connettore supporta le seguenti versioni dell'API HubSpot:

  • HubSpot
  • HubSpotV3
  • HubSpotV4

Prima di iniziare

Prima di utilizzare il connettore HubSpot, esegui queste attività:

  • Nel tuo progetto Google Cloud:
    • Concedi il ruolo IAM roles/connectors.admin all'utente che configura il connettore.
    • Concedi i seguenti ruoli IAM all'account di servizio che vuoi utilizzare per il connettore:
      • roles/secretmanager.viewer
      • roles/secretmanager.secretAccessor

      Un account di servizio è un tipo speciale di Account Google destinato a rappresentare un utente "non umano" che deve autenticarsi ed essere autorizzato ad accedere ai dati nelle API di Google. Se non hai un account di servizio, devi crearne uno. Per saperne di più, consulta la pagina sulla creazione di un account di servizio.

    • Abilita i seguenti servizi:
      • secretmanager.googleapis.com (API Secret Manager)
      • connectors.googleapis.com (API Connectors)

      Per informazioni su come abilitare i servizi, vedi Abilitazione dei servizi.

    Se questi servizi o queste autorizzazioni non sono stati abilitati per il tuo progetto in precedenza, ti verrà chiesto di abilitarli durante la configurazione del connettore.

Configura il connettore

Per configurare il connettore è necessario creare una connessione all'origine dati (sistema di backend). Una connessione è specifica per un'origine dati. Ciò significa che se disponi di molte origini dati, devi creare una connessione separata per ciascuna. Per creare una connessione, segui questi passaggi:

  1. Nella console Cloud, vai alla pagina Connettori di integrazione > Connessioni, quindi seleziona o crea un progetto Google Cloud.

    Vai alla pagina Connessioni

  2. Fai clic su + Crea nuova per aprire la pagina Crea connessione.
  3. Nella sezione Posizione, scegli la località per la connessione.
    1. Regione: seleziona una località dall'elenco a discesa.

      Le regioni supportate per i connettori includono:

      Per l'elenco di tutte le regioni supportate, vedi Località.

    2. Tocca Avanti.
  4. Nella sezione Dettagli connessione, completa quanto segue:
    1. Connettore: seleziona HubSpot dall'elenco a discesa dei connettori disponibili.
    2. Versione connettore: seleziona la versione del connettore dall'elenco a discesa delle versioni disponibili.
    3. Nel campo Nome connessione, inserisci un nome per l'istanza di connessione.

      I nomi delle connessioni devono soddisfare i seguenti criteri:

      • I nomi delle connessioni possono contenere lettere, numeri o trattini.
      • Le lettere devono essere minuscole.
      • I nomi delle connessioni devono iniziare con una lettera e terminare con una lettera o un numero.
      • I nomi delle connessioni non possono superare i 63 caratteri.
    4. (Facoltativo) Inserisci una descrizione per l'istanza di connessione.
    5. Account di servizio: seleziona un account di servizio con i ruoli richiesti.
    6. Per utilizzare la connessione per le sottoscrizioni agli eventi, seleziona Abilita sottoscrizione agli eventi. Se selezioni questa opzione, vengono visualizzate le seguenti opzioni:
      • Abilita la sottoscrizione agli eventi con entità e azioni: seleziona questa opzione per utilizzare la connessione sia per la sottoscrizione agli eventi sia per le operazioni del connettore (entità e azioni).
      • Abilita solo la sottoscrizione all'evento: seleziona questa opzione per utilizzare la connessione solo per la sottoscrizione all'evento.

      Per entrambe le selezioni, ti verrà chiesto di configurare i dettagli dell'evento nei passaggi successivi.

    7. Schema: specifica la versione dell'API HubSpot da utilizzare. HubSpotV4 è la nuova API.
    8. BrowsableSchemas: questa proprietà limita gli schemi segnalati a un sottoinsieme di schemi disponibili. Ad esempio: BrowsableSchemas=SchemaA,SchemaB,SchemaC.
    9. Proprietà dei contatti: inserisci i nomi dei campi separati da virgole dell'entità Contacts che vuoi selezionare dall'operazione dell'entità List. Ad esempio, fieldA, fieldB, fieldC
    10. Proprietà delle aziende: inserisci i nomi dei campi separati da virgole dell'entità Companies che vuoi selezionare dall'operazione dell'entità List. Ad esempio, fieldA, fieldB, fieldC
    11. Proprietà dei deal: inserisci i nomi dei campi separati da virgole dell'entità Deals che vuoi selezionare dall'operazione dell'entità List. Ad esempio, fieldA, fieldB, fieldC
    12. Utilizza proxy: seleziona questa casella di controllo per configurare un server proxy per la connessione.
    13. Schema di autenticazione proxy: il tipo di autenticazione da utilizzare per eseguire l'autenticazione al proxy ProxyServer.
    14. Utente proxy: un nome utente da utilizzare per l'autenticazione al proxy ProxyServer.
    15. Proxy Password (Password proxy): una password da utilizzare per l'autenticazione al proxy ProxyServer.
    16. Tipo SSL proxy: il tipo SSL da utilizzare per la connessione al proxy ProxyServer.
    17. Facoltativamente, configura le impostazioni del nodo di connessione:

      • Numero minimo di nodi: inserisci il numero minimo di nodi di connessione.
      • Numero massimo di nodi: inserisci il numero massimo di nodi di connessione.

      Un nodo è un'unità (o una replica) di una connessione che elabora le transazioni. Sono necessari più nodi per elaborare più transazioni per una connessione e, al contrario, sono necessari meno nodi per elaborare un numero minore di transazioni. Per capire in che modo i nodi influiscono sui prezzi del connettore, consulta Prezzi dei nodi di connessione. Se non inserisci alcun valore, per impostazione predefinita il numero minimo di nodi è impostato su 2 (per una migliore disponibilità) e il numero massimo di nodi è impostato su 50.

    18. (Facoltativo) Fai clic su + Aggiungi etichetta per aggiungere un'etichetta alla connessione sotto forma di coppia chiave-valore.
    19. Tocca Avanti.
  5. Nella sezione Destinazioni, inserisci i dettagli dell'host remoto (sistema di backend) a cui vuoi connetterti.
    1. Tipo di destinazione: puoi specificare i dettagli della destinazione come indirizzo host o collegamento a un servizio. Seleziona uno dei seguenti tipi di destinazione:
      • Indirizzo host: se vuoi specificare il nome host o l'indirizzo IP della destinazione.
      • Collegamento al servizio: se vuoi specificare l'endpoint privato per i tuoi indirizzi IP interni. Il collegamento al servizio ti consente di nascondere gli indirizzi IP interni dalla rete esterna. Puoi creare il collegamento a un servizio in Google Cloud utilizzando la funzionalità Private Service Connect. Per informazioni sulla configurazione di Private Service Connect, consulta Pubblicare servizi gestiti.

      In base alla selezione del tipo di destinazione, inserisci l'indirizzo host o il nome del collegamento al servizio.

      Per inserire altre destinazioni, fai clic su +Aggiungi destinazione.

    2. Tocca Avanti.
  6. Nella sezione Autenticazione, inserisci i dettagli di autenticazione.
    1. Seleziona un Tipo di autenticazione e inserisci i dettagli pertinenti.

      La connessione HubSpot supporta i seguenti tipi di autenticazione:

      • Token di accesso all'app privata : seleziona il secret di Secret Manager contenente il token di accesso all'app privata.

        Le app private ti consentono di utilizzare le API di HubSpot per accedere a dati specifici dal tuo account HubSpot. Puoi autorizzare le richieste o le modifiche che ogni app privata può richiedere o modificare nel tuo account, generando un token di accesso univoco per la tua app privata. Nella tua app privata, assicurati di aver fornito l'autorizzazione di lettura almeno nei seguenti ambiti:

        • 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

        Per ulteriori informazioni, vedi App private.

    2. Tocca Avanti.
  7. Se hai abilitato l'iscrizione all'evento, nella pagina di creazione della connessione viene visualizzata la sezione Dettagli abbonamento all'evento. Nel passaggio Dettagli abbonamento evento, fornisci i dettagli di autenticazione che verranno utilizzati per convalidare il payload del token HubSpot:
    1. (Facoltativo) Client secret: seleziona il secret di Secret Manager del client secret della tua app privata e la versione del secret corrispondente dall'elenco a discesa Versione secret.

      2. Per ulteriori informazioni, vedi App private.

    2. Seleziona Abilita connettività privata per la connettività sicura tra l'applicazione di backend e la connessione. Se selezioni questa opzione, devi eseguire ulteriori passaggi di configurazione dopo aver creato la connessione. Per saperne di più, consulta Connettività privata per la sottoscrizione agli eventi.
    3. Inserisci la configurazione messaggi non recapitabili. Se configuri i messaggi non recapitabili, la connessione scrive gli eventi non elaborati nell'argomento Pub/Sub specificato. Inserisci i seguenti dettagli:
      1. ID progetto messaggi non recapitabili: l'ID progetto Google Cloud in cui hai configurato l'argomento Pub/Sub messaggi non recapitabili.
      2. Argomento messaggi non recapitabili: l'argomento Pub/Sub in cui vuoi scrivere i dettagli dell'evento non elaborato.
    4. Tocca Avanti.
  8. Verifica: controlla i dettagli di connessione e autenticazione.
  9. Fai clic su Crea.

Entità, operazioni e azioni

Tutti i connettori di integrazione forniscono un livello di astrazione per gli oggetti dell'applicazione connessa. Puoi accedere agli oggetti di un'applicazione solo tramite questa astrazione. L'astrazione è esposta come entità, operazioni e azioni.

  • Entità: un'entità può essere considerata come un oggetto o una raccolta di proprietà nell'applicazione o nel servizio collegato. La definizione di un'entità è diversa da un connettore a un connettore. Ad esempio, in un connettore di database, le tabelle sono le entità, in un connettore di file server, le cartelle sono le entità e in un connettore di sistema di messaggistica le code sono le entità.

    Tuttavia, è possibile che un connettore non supporti o non abbia entità, nel qual caso l'elenco Entities sarà vuoto.

  • Operazione : un'operazione è l'attività che puoi eseguire su un'entità. Su un'entità puoi eseguire una qualsiasi delle seguenti operazioni:

    Se selezioni un'entità dall'elenco disponibile, viene generato un elenco di operazioni disponibili per l'entità. Per una descrizione dettagliata delle operazioni, consulta le operazioni delle entità dell'attività Connettori. Tuttavia, se un connettore non supporta nessuna delle operazioni delle entità, queste operazioni non supportate non sono elencate nell'elenco Operations.

  • Azione: un'azione è una funzione di prima classe resa disponibile per l'integrazione attraverso l'interfaccia del connettore. Un'azione consente di apportare modifiche a una o più entità e di variare da connettore a connettore. Tuttavia, è possibile che un connettore non supporti alcuna azione, nel qual caso l'elenco Actions sarà vuoto.

Problemi noti

  • L'operazione di aggiornamento su alcune entità restituisce una risposta vuota anche se l'aggiornamento ha esito positivo. In questi casi, ti consigliamo di verificare l'aggiornamento nell'istanza di HubSpot.
  • In HubSpot, potresti avere molti campi personalizzati per le seguenti entità:
    • Contatti
    • Società
    • Promozioni

    Per queste entità, la selezione di tutti i campi contemporaneamente nell'operazione dell'entità List potrebbe causare un errore nel connettore HubSpot. Negli scenari in cui vuoi limitare il numero di campi personalizzati dall'operazione List, specifica i nomi dei campi obbligatori (come valori separati da virgole) nella configurazione del connettore HubSpot. Ad esempio, per limitare i campi dell'entità Contacts, specifica i nomi dei campi obbligatori nel campo Contacts Properties della configurazione del connettore. In modo simile, per l'entità Companies, specifica i nomi dei campi obbligatori nel campo Companies Properties e per l'entità Deals, specifica i nomi dei campi obbligatori nel campo Deals Properties.

    Puoi specificare i campi durante il passaggio di creazione della connessione. Tuttavia, se hai già una connessione esistente, devi modificarla e specificare i campi obbligatori.

  • Se hai impostato un set di risultati molto grande, l'operazione List potrebbe non riuscire a causa di un timeout della connessione. In questo scenario, puoi esplorare l'opzione di limitare il set di risultati specificando la clausola di filtro per l'operazione Elenco.

Esempi di operazioni sull'entità

Questa sezione mostra come eseguire alcune delle operazioni sulle entità in questo connettore.

Esempio: elenca tutti i contatti

In questo esempio sono elencati tutti i record dell'entità Contacts.

  1. Nella finestra di dialogo Configure connector task, fai clic su Entities.
  2. Seleziona Contacts dall'elenco Entity.
  3. Seleziona l'operazione LIST, quindi fai clic su Fine.

Esempio: recupera una registrazione dell'offerta

In questo esempio viene recuperato un record il cui ID è 45 dall'entità Deals.

  1. Nella finestra di dialogo Configure connector task, fai clic su Entities.
  2. Seleziona Deals dall'elenco Entity.
  3. Seleziona l'operazione GET, quindi fai clic su Fine.
  4. Nella sezione Input attività dell'attività Connettori, fai clic su EntityId e inserisci 45 nel campo Valore predefinito.

    In questo caso, 45 è un valore di chiave primaria nell'entità Deals.

Esempio: creare un ticket

In questo esempio viene creato un ticket nell'entità Ticket.

  1. Nella finestra di dialogo Configure connector task, fai clic su Entities.
  2. Seleziona Tickets dall'elenco Entity.
  3. Seleziona l'operazione Create, quindi fai clic su Fine.
  4. Nella sezione Input attività dell'attività Connettori, fai clic su connectorInputPayload e inserisci un valore simile al seguente nel campo Default Value: 
    {
"Name": "Test735362767",
"Label": "Test735362767",
"Type": "String",
"FieldType": "Insert ticket1",
"GroupName": "ticketinformation",
"Description": "Test ticket"
}

    Se l'integrazione ha esito positivo, il campo connectorOutputPayload dell'attività del connettore avrà un valore simile al seguente:

    {
"Name": "Test1695971640609"
}

Esempio: aggiornare una voce di deal

Questo esempio aggiorna il record il cui ID è 97 nell'entità Contacts.

  1. Nella finestra di dialogo Configure connector task, fai clic su Entities.
  2. Seleziona Deals dall'elenco Entity.
  3. Seleziona l'operazione Update, quindi fai clic su Fine.
  4. Nella sezione Input attività dell'attività Connettori, fai clic su connectorInputPayload e inserisci un valore simile al seguente nel campo Default Value: 
    {
"Description": "New description"
}
  5. Fai clic su entityId, quindi inserisci 97 nel campo Default Value (Valore predefinito).

    In alternativa, anziché specificare entityId, puoi anche impostare filterClause su 97.

Esempio - Eliminare un modulo

Questo esempio elimina il record il cui ID è 78 nell'entità Forms.

  1. Nella finestra di dialogo Configure connector task, fai clic su Entities.
  2. Seleziona Forms dall'elenco Entity.
  3. Seleziona l'operazione Delete, quindi fai clic su Fine.
  4. Nella sezione Input attività dell'attività Connettori, fai clic su entityId, quindi inserisci 78 nel campo Valore predefinito.

Utilizzare Terraform per creare connessioni

Puoi utilizzare la risorsa Terraform per creare una nuova connessione.

Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base.

Per visualizzare un modello Terraform di esempio per la creazione delle connessioni, guarda il modello di esempio.

Quando crei questa connessione utilizzando Terraform, devi impostare le seguenti variabili nel file di configurazione Terraform:

Nome parametro Tipo di dati Obbligatorio Descrizione
schema ENUM True Specifica la versione dell'API HubSpot da utilizzare. HubSpotV4 è la nuova API. I valori supportati sono: HubSpot, HubSpotV3, HubSpotV4
browsable_schemas STRING False Questa proprietà limita gli schemi segnalati a un sottoinsieme di schemi disponibili. Ad esempio: BrowsableSchemas=SchemaA,SchemaB,SchemaC.
contacts_columns STRING False Elenco separato da virgole di proprietà da selezionare da HubSpot per l'entità Contacts.
companies_columns STRING False Elenco separato da virgole di proprietà da selezionare da HubSpot per l'entità Companies.
deals_columns STRING False Elenco separato da virgole di proprietà da selezionare da HubSpot per l'entità Deal.
proxy_enabled BOOLEANO False Seleziona questa casella di controllo per configurare un server proxy per la connessione.
proxy_auth_scheme ENUM False Il tipo di autenticazione da utilizzare per eseguire l'autenticazione sul proxy ProxyServer. I valori supportati sono: BASIC, DIGEST, NONE
proxy_user STRING False Un nome utente da utilizzare per l'autenticazione al proxy ProxyServer.
proxy_password SECRET False Una password da utilizzare per l'autenticazione al proxy ProxyServer.
proxy_ssltype ENUM False Il tipo di SSL da utilizzare per la connessione al proxy ProxyServer. I valori supportati sono: AUTO, ALWAYS, NEVER, GCP

Utilizzare la connessione HubSpot in un'integrazione

Dopo aver creato la connessione, diventa disponibile sia in Apigee Integration che in Application Integration. Puoi usare la connessione in un'integrazione tramite l'attività Connettori.

  • Per capire come creare e utilizzare l'attività Connettori in Apigee Integration, consulta Attività Connettori.
  • Per capire come creare e utilizzare l'attività Connettori in Application Integration, consulta Attività Connettori.

Ricevi assistenza dalla community Google Cloud

Puoi pubblicare le tue domande e discutere di questo connettore nella community Google Cloud sui forum Cloud.

Passaggi successivi