BetaEsporta i dati di HubSpot su Microsoft Fabric

Nota: se sei un Super Admin, attivala versione beta di Data Studio per il tuo account per poter utilizzare questa funzionalità.

Utilizza Data Out per esportare i dati selezionati di HubSpot CRM in tabelle native all'interno di un Microsoft Fabric Warehouse di tua proprietà. Puoi sincronizzare i dati relativi a oggetti, associazioni ed eventi con le tabelle del tuo warehouse, quindi eseguire query su tali 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

Per esportare i dati su Microsoft Fabric, è necessario:

• Un workspace Microsoft Fabric con un Fabric Warehouse
• Un entità di servizio Microsoft Entra ID aggiunta all’area di lavoro Fabric con il ruolo di Collaboratore
• L’ID tenant, l’ID client e il segreto client dell’entità di servizio
• La stringa di connessione SQL del tuo Fabric Warehouse (indirizzo del server, senza il numero di porta) e il nome del warehouse

L’entità di servizio Microsoft Entra ID deve disporre dell’autorizzazione per creare e gestire oggetti di proprietà di HubSpot nel Fabric Warehouse di destinazione. Durante la convalida della connessione e le sincronizzazioni, HubSpot crea schemi e tabelle, inserisce dati, rinomina le tabelle di staging e rimuove gli oggetti temporanei. Assegna all’entità di servizio il ruolo di Collaboratore nell’area di lavoro di Fabric per consentire a HubSpot di:

• Crea schemi
• Creare tabelle
• Inserire righe
• Rinominare o modificare le tabelle di proprietà di HubSpot
• Eliminare tabelle e schemi di proprietà di HubSpot

L’endpoint SQL del tuo Fabric Warehouse deve essere raggiungibile da HubSpot sulla porta TCP 1433. HubSpot utilizza TLS per tutte le connessioni e convalida il certificato del server.

Se il tuo spazio di lavoro Fabric limita l’accesso alla rete, aggiungi alla lista dei permessi gli indirizzi IP in uscita di HubSpot relativi alla regione del tuo account.

Comprendere le limitazioni e le considerazioni

• Microsoft Fabric Data Out supporta solo i Fabric Warehouse. I Lakehouse non sono supportati.
• 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 suoi 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 sola sincronizzazione ricorrente di Microsoft Fabric per account.
• Ogni sincronizzazione sostituisce la tabella di destinazione. Le autorizzazioni o le impostazioni a livello di tabella aggiunte nel tuo Fabric Warehouse non vengono conservate tra una sincronizzazione e l’altra.
• Per ricollegarsi a un'entità di servizio diversa, è necessario aggiungere tale entità di servizio all'area di lavoro di Fabric con il ruolo di Collaboratore prima che il test di connessione o la sincronizzazione possano andare a buon fine.

Collegare HubSpot a Microsoft Fabric

Si consiglia di tenere aperte le console dell’account HubSpot e di Microsoft Fabric in schede separate.

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, fare clic su Connetti origine dati esterna.
3. Nel pannello " Aggiungi una fonte dati ", cerca o seleziona Microsoft Fabric.
4. Fare clic su Installa, quindi su Avanti.
5. Immettere l'ID tenant, l'ID client e il segreto client del proprio entità di servizio.
6. Inserisci i seguenti dettagli di destinazione:
   • Stringa di connessione SQL: l'indirizzo del server del proprio Fabric Warehouse, senza il numero di porta.
   • Nome del magazzino: il nome del Fabric Warehouse in cui eseguire l'esportazione.
7. Fare clic su Verifica connessione. Se la verifica della connessione ha esito positivo, fare clic su Avanti.

Nota: nel tuo spazio di lavoro Fabric, verifica che l’entità di servizio di HubSpot abbia il ruolo di Collaboratore prima di eseguire il test di connessione. Non sono necessari script SQL per configurare l’accesso.

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 dati esportati

HubSpot crea uno schema gestito da HubSpot per ogni destinazione. Le tabelle 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

È possibile trovare il nome esatto dello schema nella pagina di configurazione della sincronizzazione.

Nomi delle tabelle e delle colonne

HubSpot normalizza i nomi delle tabelle e delle colonne esportate utilizzando lettere maiuscole, numeri e trattini bassi:

• Gli spazi e i trattini vengono sostituiti da trattini bassi.
• Gli altri caratteri non alfanumerici vengono rimossi.
• I nomi più lunghi di 128 caratteri vengono abbreviati.
• Ai nomi delle colonne in conflitto viene aggiunto un suffisso.
• I nomi delle tabelle in conflitto causano l'errore dell'esportazione interessata.

Tipi di colonna

La colonna PROPERTIES in OBJECT_WITH_OBJECT_PROPERTIES viene memorizzata come stringa in formato JSON in VARCHAR(MAX), non come tipo di colonna JSON nativo. Consulta gli esempi di query nelle FAQ riportate di seguito.

Tabelle degli oggetti

Se selezioni 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 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 di un record e di 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 seguente formato:

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.

Monitora la sincronizzazione

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. A sinistra, fare clic su Sincronizzazioni app.
3. Cerca o seleziona la sincronizzazione Microsoft Fabric.

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 non va a buon fine:

• 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.

Domande frequenti

Come si eseguono query sui dati esportati?

Eseguire una query sulle tabelle nello schema di destinazione utilizzando SQL.

-- Read all contact records
SELECT *
FROM [your_database].[hubspot_data_out_456].[OBJECT_WITH_OBJECT_PROPERTIES]
WHERE [OBJECTTYPEID] = '0-1'; -- Read a specific property from the PROPERTIES JSON string
SELECT
  [OBJECTID],
  JSON_VALUE([PROPERTIES], '$.email') AS [email]
FROM [your_database].[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 sola sincronizzazione ricorrente di Microsoft Fabric per ogni account HubSpot. Ciò è indipendente dagli altri provider Data Out.

Ad esempio, se i contatti sono già stati esportati in una destinazione Fabric ricorrente, non è possibile aggiungere contatti a un’altra configurazione Fabric ricorrente finché non si archivia la prima configurazione. È comunque possibile esportare i contatti verso un altro provider Data Out supportato 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 in base a 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 inalterati fino a quando la tabella non viene aggiornata con successo.

HubSpot utilizza un bucket di staging gestito dall’utente?

No. HubSpot crea un’esportazione Parquet temporanea nell’archivio gestito da HubSpot e scrive i risultati nel tuo Fabric Warehouse. Non è necessario fornire o gestire un bucket di staging.

Cosa succede se mi ricollego con un'entità di servizio diversa?

Se ti ricolleghi utilizzando un'entità di servizio diversa, devi aggiungere tale entità di servizio all’area di lavoro di Fabric con il ruolo di Collaboratore prima che il test di connessione o la sincronizzazione possano andare a buon fine.