BetaEsportare i dati di HubSpot su PostgreSQL o MySQL

Nota: se sei un super amministratore, attivala versione beta di Data Studio sul tuo account per poter utilizzare questa funzione.

Riepilogo

Utilizza Data Out per esportare i dati selezionati di HubSpot CRM in un database PostgreSQL o MySQL di tua gestione. Puoi sincronizzare i dati relativi a oggetti, associazioni ed eventi con le tabelle del tuo database, quindi eseguire query sui dati tramite SQL o utilizzarli con i tuoi strumenti di business intelligence e analisi.

Ogni sincronizzazione crea un’istantanea completa dei dati selezionati. Quando una sincronizzazione va a buon fine, sostituisce l’istantanea precedente nelle tabelle di destinazione.

Prima di iniziare

Comprendere i requisiti

• Il database PostgreSQL o MySQL deve essere raggiungibile dagli intervalli di indirizzi IP di HubSpot relativi alla regione del tuo account.
• Il server del database deve supportare le connessioni SSL.
• È necessario disporre di un utente del database con le autorizzazioni richieste:
  • PostgreSQL: autorizzazione CREATE e accesso in scrittura allo schema di destinazione.
  • MySQL: autorizzazione CREATE sul database e accesso in scrittura.
• Assicurati che l’utente del database possa creare tabelle e scrivere dati.
• Tieni aperti l’account HubSpot e le console del database in schede separate.

Consenti gli indirizzi IP di HubSpot

Aggiungi l’intervallo di indirizzi IP di HubSpot relativo alla regione del tuo account alla lista dei permessi del tuo server di database.

Comprendere le limitazioni e le considerazioni

• Ogni esecuzione della sincronizzazione crea un'istantanea completa dei dati selezionati.
• Una sincronizzazione riuscita sostituisce l’istantanea precedente nelle tabelle di destinazione.
• HubSpot non conserva le istantanee precedenti.
• Se una tabella non viene sincronizzata correttamente, i dati precedenti rimangono disponibili fino alla successiva sincronizzazione riuscita.
• Ogni tipo di oggetto, tipo di evento o coppia di associazioni può essere incluso in una sincronizzazione ricorrente su PostgreSQL e in una su MySQL per ogni account.
• Ogni sincronizzazione sostituisce la tabella di destinazione. Le autorizzazioni o le impostazioni a livello di tabella aggiunte nel tuo provider di database non vengono conservate tra una sincronizzazione e l’altra.
• Se ti riconnetti utilizzando un utente del database diverso, devi concedere a tale utente l'accesso agli schemi, ai database o alle tabelle esistenti gestiti da HubSpot.

Collega HubSpot a PostgreSQL o MySQL

1. Nel tuo account HubSpot, fai clic su Altro, quindi vai a Gestione dei dati > Data Studio. Se Altro non compare nel tuo account, vai direttamente a Gestione dei dati > Data Studio.
2. In alto a destra, clicca su " Connetti fonte dati esterna".
3. Nel pannello " Aggiungi una fonte dati ", cerca o seleziona il provider del database.
4. Fai clic su PostgreSQL o MySQL.
5. Inserisci i dettagli di connessione al database:
   • Host
   • Porta
   • SSL
   • Nome utente
   • Password
6. Per PostgreSQL, inserisci il nome del database in cui HubSpot deve creare lo schema.
7. Fai clic su Connetti a PostgreSQL o su Connetti a MySQL.

HubSpot utilizza l'utente del database collegato per creare tabelle e caricare i dati nel tuo database.

Configurare la sincronizzazione

1. Seleziona le origini dati da esportare:
   • Oggetti
   • Associazioni
   • Eventi
2. Seleziona gli oggetti, le proprietà, le associazioni o gli eventi da includere.
3. Scegli la frequenza di esecuzione della sincronizzazione e quando avviarla.
4. Fare clic su Avvia sincronizzazione.

Le frequenze di sincronizzazione disponibili potrebbero variare durante la fase beta. Le opzioni possono includere una volta, ogni 6 ore, ogni 12 ore, giornalmente, settimanalmente o mensilmente.

Accedi ai tuoi dati esportati

HubSpot crea uno schema o un database gestito da HubSpot per ogni destinazione.

PostgreSQL

Le tabelle PostgreSQL utilizzano il seguente formato:

<database>.hubspot_data_out_<destination-id>.<table-name>

Ad esempio:

your_database.hubspot_data_out_456."OBJECT_WITH_OBJECT_PROPERTIES"
your_database.hubspot_data_out_456."EVENTS_VISITED_PAGE"
your_database.hubspot_data_out_456."ASSOCIATIONS_CONTACTS_TO_COMPANIES"

MySQL

Le tabelle MySQL utilizzano il seguente formato:

hubspot_data_out_<destination-id>.<table-name>

Ad esempio:

hubspot_data_out_456.OBJECT_WITH_OBJECT_PROPERTIES
hubspot_data_out_456.EVENTS_VISITED_PAGE
hubspot_data_out_456.ASSOCIATIONS_CONTACTS_TO_COMPANIES

È possibile trovare lo schema esatto o il nome del database nella pagina di configurazione della sincronizzazione.

Nomi delle tabelle e delle colonne

I nomi delle tabelle e delle colonne si basano sui dati esportati. Gli identificatori PostgreSQL possono contenere fino a 63 caratteri. Gli identificatori MySQL possono contenere fino a 64 caratteri. I nomi più lunghi vengono abbreviati per rispettare il limite applicabile.

HubSpot crea tabelle e colonne PostgreSQL con nomi racchiusi tra virgolette e con il rispetto delle maiuscole/minuscole. Quando si eseguono query su PostgreSQL, utilizzare le virgolette doppie e rispettare le maiuscole/minuscole indicate nel nome della tabella e della colonna.

Per MySQL, utilizzare i backtick e rispettare le maiuscole indicate. La distinzione tra maiuscole e minuscole nei nomi delle tabelle può variare a seconda della configurazione del server MySQL.

Tipi di colonna

La colonna PROPERTIES nella tabella OBJECT_WITH_OBJECT_PROPERTIES è memorizzata come stringa in formato JSON. Viene memorizzata come TEXT in PostgreSQL e come LONGTEXT in MySQL, non come tipo di colonna JSON nativo.

Tabelle degli oggetti

Se si selezionano i dati degli oggetti, HubSpot esporta le seguenti tabelle.

OBJECT_PROPERTIES

Questa tabella contiene una riga per ogni valore di proprietà dell’oggetto.

OBJECT_WITH_OBJECT_PROPERTIES

Questa tabella contiene una riga per ogni record dell’oggetto. I valori delle proprietà selezionate sono raggruppati nella colonna PROPERTIES.

I dati degli oggetti relativi a diversi tipi di oggetto vengono combinati in questa tabella. Filtra in base a OBJECTTYPEID per visualizzare i record relativi a un tipo di oggetto specifico.

• Contatti: 0-1
• Oggetti personalizzati: 2-{unique_id}, ad esempio 2-12345

OBJECT_PROPERTIES_HISTORY

Questa tabella contiene la cronologia delle modifiche alle proprietà. Include una riga per ogni valore storico di una proprietà.

Per visualizzare la cronologia completa relativa a un record e a una proprietà specifici, ordinare i risultati in base a UPDATEDAT.

Tabelle di associazione

Se si selezionano i dati di associazione, HubSpot esporta i record di associazione e le definizioni di associazione.

ASSOCIATIONS

Questa tabella contiene una riga per ogni associazione selezionata tra due record.

ASSOCIATION_DEFINITIONS

Questa tabella contiene una riga per ogni definizione di associazione selezionata.

Tabelle di associazioni specifiche per coppia

Per le coppie di associazioni selezionate, HubSpot può anche esportare tabelle con il seguente formato:

ASSOCIATIONS_<FROM_OBJECT_TYPE>_TO_<TO_OBJECT_TYPE>

Ad esempio:

ASSOCIATIONS_CONTACTS_TO_COMPANIES

Queste tabelle contengono record di associazione e metadati relativi alle definizioni di associazione.

Tabelle degli eventi

Se selezioni i dati relativi agli eventi, HubSpot esporta una tabella per ogni tipo di evento. I nomi delle tabelle degli eventi seguono il formato seguente:

EVENTS_<EVENT_NAME>

Ad esempio:

EVENTS_VISITED_PAGE

Ogni tabella degli eventi contiene colonne standard relative agli eventi e una colonna per ciascuna proprietà dell’evento selezionata.

Monitorare la sincronizzazione

1. Nel tuo account HubSpot, fai clic su Altro, quindi vai a Gestione dei dati > Integrazione dei dati. Se Altro non appare nel tuo account, vai direttamente a Gestione dei dati > Integrazione dei dati.
2. A sinistra, clicca su Sincronizzazioni app.
3. Cerca o seleziona la sincronizzazione PostgreSQL o MySQL.

Dalla pagina dei dettagli della sincronizzazione, puoi visualizzare lo stato della sincronizzazione, l’ora dell’ultima sincronizzazione, gli errori, l’attività di sincronizzazione e la cronologia delle sincronizzazioni. Puoi anche mettere in pausa, archiviare o eseguire manualmente la sincronizzazione.

Stati di sincronizzazione

Risolvi gli errori di sincronizzazione

Quando una sincronizzazione fallisce:

• L'interfaccia utente di HubSpot mostra lo stato "Failed " e i dettagli a livello di tabella che indicano quali tabelle hanno avuto esito positivo o negativo.
• Una tabella viene aggiornata solo dopo che HubSpot ha completato il caricamento di tutti i suoi dati.
• Se una tabella non viene sincronizzata correttamente, i dati precedenti rimangono inalterati fino alla successiva sincronizzazione riuscita.
• La successiva sincronizzazione pianificata riproverà automaticamente a eseguire la sincronizzazione completa.
• È possibile eseguire manualmente una sincronizzazione dalla pagina dei dettagli della sincronizzazione.

Le tabelle che sono state sincronizzate correttamente durante un'esecuzione precedente non vengono modificate quando un'esecuzione successiva fallisce.

Domande frequenti

Come posso eseguire query sui dati esportati?

Eseguire query sulle tabelle nello schema o nel database di destinazione utilizzando SQL.

PostgreSQL

-- Read all contact records
SELECT *
FROM your_database.hubspot_data_out_456."OBJECT_WITH_OBJECT_PROPERTIES"
WHERE "OBJECTTYPEID" = '0-1';

-- Read a property from the PROPERTIES column
SELECT
  "OBJECTID",
  json_extract_path_text("PROPERTIES"::json, 'email') AS email
FROM your_database.hubspot_data_out_456."OBJECT_WITH_OBJECT_PROPERTIES"
WHERE "OBJECTTYPEID" = '0-1';

MySQL

-- Read all contact records
SELECT *
FROM `hubspot_data_out_456`.`OBJECT_WITH_OBJECT_PROPERTIES`
WHERE `OBJECTTYPEID` = '0-1';

-- Read a property from the PROPERTIES column
SELECT
  `OBJECTID`,
  JSON_EXTRACT(`PROPERTIES`, '$.email') AS email
FROM `hubspot_data_out_456`.`OBJECT_WITH_OBJECT_PROPERTIES`
WHERE `OBJECTTYPEID` = '0-1';

È possibile esportare un tipo di dati in più sincronizzazioni?

Ogni tipo di oggetto, tipo di evento o coppia di associazioni può essere incluso in una sincronizzazione ricorrente PostgreSQL e in una sincronizzazione ricorrente MySQL per ogni account HubSpot.

Ad esempio, se i contatti sono già stati esportati in una destinazione PostgreSQL ricorrente, non è possibile aggiungere contatti a un’altra configurazione PostgreSQL ricorrente finché non si archivia la prima configurazione. È comunque possibile esportare i contatti in una configurazione MySQL ricorrente contemporaneamente.

Le tabelle specifiche per oggetto sono supportate?

Le tabelle specifiche per oggetto, come OBJECTS_CONTACTS, al momento non sono supportate. Utilizza OBJECT_WITH_OBJECT_PROPERTIES e filtra per OBJECTTYPEID per recuperare i record relativi a un tipo di oggetto specifico.

I dati sensibili sono supportati?

I dati sensibili non sono attualmente supportati per Data Out. Le proprietà sensibili possono essere escluse dalle esportazioni.

HubSpot conserva le istantanee precedenti?

No. Ogni sincronizzazione riuscita sostituisce la tabella di destinazione con l’istantanea più recente. HubSpot non conserva le istantanee precedenti.

Se una tabella non viene sincronizzata correttamente, i dati precedenti rimangono in essere fino a quando la tabella non viene aggiornata con successo.

HubSpot utilizza un bucket di staging gestito da me?

No. HubSpot esporta i dati in formato Parquet e gestisce internamente la fase di staging. Non è necessario fornire un bucket di staging di proprietà del cliente per PostgreSQL o MySQL.

Cosa succede se cambio l’utente del database?

Se ti ricolleghi utilizzando un utente del database diverso, devi concedere al nuovo utente l’accesso agli schemi, ai database o alle tabelle esistenti gestiti da HubSpot.