BetaExportar dados do HubSpot para o Microsoft Fabric

Observe: se você for um Superadministrador, escolha sua conta no Data Studio beta para usar este recurso.

Use Saída de dados para exportar os dados selecionados do CRM da HubSpot para tabelas nativas em um Microsoft Fabric Warehouse de sua propriedade. Você pode sincronizar dados de objetos, associações e eventos com tabelas em seu warehouse e, em seguida, consultar esses dados com SQL ou usá-los com suas ferramentas de business intelligence e análise.

Cada sincronização cria um instantâneo completo dos dados selecionados. Quando uma sincronização é bem-sucedida, ela substitui o snapshot anterior nas tabelas de destino.

Antes de começar

Noções básicas sobre os requisitos

Para exportar dados para o Microsoft Fabric, você precisará de:

• Um espaço de trabalho do Microsoft Fabric com um Fabric Warehouse
• Uma entidade de serviço do Microsoft Entra ID adicionada ao espaço de trabalho do Fabric com a função Colaborador
• A ID do locatário, a ID do cliente e o segredo do cliente da entidade de serviço
• A cadeia de conexão SQL do Fabric Warehouse (endereço do servidor, sem o número da porta) e o nome do warehouse

A entidade de serviço do Microsoft Entra ID deve ter permissão para criar e gerenciar objetos de propriedade da HubSpot no Fabric Warehouse de destino. Durante a validação e sincronização da conexão, o HubSpot cria esquemas e tabelas, insere dados, renomeia tabelas de preparação e remove objetos temporários. Conceda à entidade de serviço a função de Colaborador no espaço de trabalho do Fabric para permitir que o HubSpot:

• Criar esquemas
• Criar tabelas
• Inserir linhas
• Renomear ou alterar tabelas de propriedade da HubSpot
• Descartar tabelas e esquemas de propriedade da HubSpot

O endpoint SQL do Fabric Warehouse deve estar acessível pelo HubSpot na porta TCP 1433. O HubSpot usa TLS para todas as conexões e valida o certificado do servidor.

Se o espaço de trabalho do Fabric restringir o acesso à rede, adicione os endereços IP de saída da HubSpot para a região da sua conta na lista de permissões.

Compreender limitações e considerações

• O Microsoft Fabric Data Out oferece suporte apenas a Fabric Warehouses. Lakehouses não são suportados.
• Cada execução de sincronização cria um instantâneo completo dos dados selecionados. Uma sincronização bem-sucedida substitui o instantâneo anterior nas tabelas de destino. O HubSpot não retém instantâneos anteriores. Se uma tabela falhar durante uma sincronização, seus dados anteriores permanecerão disponíveis até a próxima sincronização bem-sucedida.
• Cada tipo de objeto, tipo de evento ou par de associação pode ser incluído em uma sincronização recorrente do Microsoft Fabric por conta.
• Cada sincronização substitui a tabela de destino. As concessões ou configurações em nível de tabela adicionadas ao seu Fabric Warehouse não são preservadas entre as sincronizações.
• A reconexão com uma entidade de serviço diferente requer a adição dessa entidade de serviço ao workspace do Fabric com a função Colaborador antes que o teste ou a sincronização de conexão possa ser bem-sucedido.

Conectar o HubSpot ao Microsoft Fabric

É recomendado ter sua conta da HubSpot e os consoles do Microsoft Fabric abertos em guias separadas.

1. Na sua conta HubSpot, clique em Mais e navegue até Gerenciamento de dados > Data Studio. Se Mais não aparecer na sua conta, navegue diretamente para Gerenciamento de dados > Data Studio.
2. No canto superior direito, clique em Conectar fonte de dados externa.
3. No painel Adicionar uma fonte de dados , pesquise ou navegue até o Microsoft Fabric.
4. Clique em Instalar e em Próximo.
5. Insira a ID do locatário, a ID do cliente e o segredo do cliente da entidade de serviço.
6. Insira os seguintes detalhes de destino:
   • String de conexão SQL: o endereço do servidor para o Fabric Warehouse, sem o número da porta.
   • Nome do warehouse: o nome do armazém de malha para o qual exportar.
7. Clique em Testar conexão. Se o teste de conexão for bem-sucedido, clique em Avançar.

Observação: no espaço de trabalho do Fabric, confirme se a entidade de serviço da HubSpot tem a função de Colaborador antes de executar o teste de conexão. Nenhum script SQL é necessário para configurar o acesso.

Configurar a sincronização

1. Selecione as fontes de dados para exportar:
   • Objetos
   • Associações
   • Eventos
2. Selecione os objetos, propriedades, associações ou eventos a incluir.
3. Escolha com que frequência executar a sincronização e quando iniciá-la.
4. Clique em Iniciar sincronização.

As frequências de sincronização disponíveis podem variar durante a versão beta. As opções podem incluir uma vez, a cada 6 horas, a cada 12 horas, diariamente, semanalmente ou mensalmente.

Acesse seus dados exportados

O HubSpot cria um esquema gerenciado pela HubSpot para cada destino. As tabelas usam o seguinte formato:

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

Por exemplo:

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

Você pode encontrar o nome exato do esquema na página de configuração de sincronização.

Nomes de tabelas e colunas

O HubSpot normaliza os nomes de tabelas e colunas exportados para letras maiúsculas, números e sublinhados:

• Espaços e hifens se tornam sublinhados.
• Outros caracteres não alfanuméricos são removidos.
• Nomes com mais de 128 caracteres são encurtados.
• Os nomes das colunas que colidem recebem um sufixo.
• Nomes de tabelas em colisão falham na exportação afetada.

Tipos de coluna

A PROPERTIES coluna em OBJECT_WITH_OBJECT_PROPERTIES é armazenada como uma string formatada em JSON em VARCHAR(MAX), não como um tipo de coluna JSON nativo. Veja os exemplos de consulta nas perguntas frequentes abaixo.

Tabelas de Objetos

Se você selecionar dados do objeto, o HubSpot exportará as tabelas a seguir.

OBJECT_PROPERTIES

Esta tabela contém uma linha para cada valor de objeto propriedade.

OBJECT_WITH_OBJECT_PROPERTIES

Esta tabela contém uma linha para cada objeto registro. Os valores de propriedade selecionados são agrupados na PROPERTIES coluna.

Os dados de Objeto para diferentes tipos de objetos são combinados nesta tabela. Filtrar por OBJECTTYPEID para ler registros de um tipo de objeto específico:

• Contatos: 0-1
• Objetos personalizados: 2-{unique_id}, como 2-12345

OBJECT_PROPERTIES_HISTORY

Esta tabela contém o histórico de alterações de propriedade. Inclui uma linha para cada valor histórico de uma propriedade.

Para exibir o histórico completo de um registro e propriedade específicos, ordene os resultados por UPDATEDAT.

Tabelas de Associação

Se você selecionar associação dados, o HubSpot exportará associação registros e associação definições.

ASSOCIAÇÕES

Esta tabela contém uma linha para cada associação selecionada entre dois registros.

ASSOCIATION_DEFINITIONS

Esta tabela contém uma linha para cada definição de associação selecionada.

Tabelas de associação específicas de pares

Para os pares de associação selecionados, o HubSpot também pode exportar tabelas com o seguinte formato:

ASSOCIATIONS_<FROM_OBJECT_TYPE>_TO_<TO_OBJECT_TYPE>

Por exemplo: ASSOCIATIONS_CONTACTS_TO_COMPANIES

Estas tabelas contêm registros de associação e metadados de definição de associação.

Tabelas de eventos

Se você selecionar dados do evento, o HubSpot exportará uma tabela para cada tipo de evento. Os nomes das tabelas de eventos usam o seguinte formato:

EVENTS_<EVENT_NAME>

Por exemplo: EVENTS_VISITED_PAGE

Cada tabela de eventos contém colunas de eventos padrão e uma coluna para cada propriedade de evento selecionada.

Monitore sua sincronização

1. Na sua conta HubSpot, clique em Mais e navegue até Gerenciamento de dados > Data Studio. Se Mais não aparecer na sua conta, navegue diretamente para Gerenciamento de dados > Data Studio.
2. À esquerda, clique em Sincronizações de aplicativos.
3. Pesquise ou selecione a sincronização do Microsoft Fabric .

Na página de detalhes da sincronização, você pode visualizar o status de sincronização, a hora da última sincronização, os erros, a atividade de sincronização e o histórico de sincronização. Você também pode pausar, arquivar ou executar manualmente a sincronização.

Status de sincronização

Resolver falhas de sincronização

Quando uma sincronização falha:

• A interface de usuário do HubSpot mostra um status de Falha e detalhes em nível de tabela indicando quais tabelas foram bem-sucedidas ou falhar.
• Uma tabela é atualizada somente depois que o HubSpot termina de carregar todos os seus dados. Se uma tabela falhar, seus dados anteriores permanecerão em vigor até a próxima sincronização bem-sucedida.
• A próxima sincronização agendada tenta automaticamente a sincronização completa novamente.
• Você pode executar manualmente uma sincronização a partir da página de detalhes da sincronização.

FAQs

Como consultar os dados exportados?

Consulte as tabelas no esquema de destino com 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';

Posso exportar um tipo de dados em várias sincronizações?

Cada tipo de objeto, tipo de evento ou par de associação pode ser incluído em uma sincronização recorrente do Microsoft Fabric por conta da HubSpot. Isso é independente de outros provedores de Data Out.

Por exemplo, se os contatos já forem exportados para um destino recorrente do Fabric, você não poderá adicionar contatos a outra configuração recorrente do Fabric até arquivar a primeira configuração. Você ainda pode exportar contatos para outro provedor de Data Out compatível ao mesmo tempo.

Há suporte para tabelas específicas de objetos?

Tabelas específicas de objetos, como OBJECTS_CONTACTS, não são suportadas no momento. Use OBJECT_WITH_OBJECT_PROPERTIES e filtre por OBJECTTYPEID para recuperar registros de um tipo de objeto específico.

Dados confidenciais são compatíveis?

Dados confidenciais não são compatíveis atualmente com Dados de saída. Propriedades confidenciais podem ser excluídas das exportações.

O HubSpot mantém instantâneos anteriores?

Não. Cada sincronização bem-sucedida substitui a tabela de destino pelo instantâneo mais recente. O HubSpot não retém instantâneos anteriores. Se uma tabela falhar durante uma sincronização, seus dados anteriores permanecerão em vigor até que a tabela seja atualizada com sucesso.

A HubSpot usa um bucket de staging que eu gerencio?

Não. A HubSpot cria uma exportação temporária do Parquet no armazenamento gerenciado pela HubSpot e grava os resultados no seu Fabric Warehouse. Você não precisa fornecer ou gerenciar um bucket de preparação.

O que acontece se eu me reconectar com uma entidade de serviço diferente?

Se você se reconectar usando uma entidade de serviço diferente, deverá adicionar essa entidade de serviço ao workspace do Fabric com a função Colaborador antes que o teste ou a sincronização de conexão possa ser bem-sucedido.