Fazer streaming de dados do Microsoft Dataverse

O Datastream permite replicar dados históricos e mudanças incrementais de um ambiente do Microsoft Dataverse para análise e integração de dados. O Dataverse é uma plataforma de dados baseada na nuvem para armazenar e gerenciar dados usados por aplicativos de negócios.

Antes de configurar uma origem do Dataverse, revise os termos-chave, o comportamento de replicação, as versões compatíveis e as limitações conhecidas no Datastream.

Termos-chave

O Dataverse opera usando os seguintes conceitos:

  • Uma tabela, antes chamada de entidade, é semelhante a uma tabela em bancos de dados relacionais. O Dataverse inclui tabelas padrão, mas você também pode criar tabelas personalizadas.
  • Uma coluna, antes chamada de campo, é um atributo de uma tabela e é semelhante a uma coluna em bancos de dados relacionais.
  • Uma linha é um registro específico em uma tabela e é semelhante a uma linha em bancos de dados relacionais.

Comportamento

A compatibilidade com a origem do Dataverse no Datastream depende da API Web do Dataverse, que usa o Open Data Protocol (OData). O Datastream pesquisa mudanças na origem com base no intervalo definido.

Ao replicar dados de uma origem do Dataverse, o seguinte comportamento é observado:

  • Interação com a API: o Datastream interage com a API Web do Dataverse usando solicitações RESTful. O URL do ambiente base é https://ORGANIZATION_ID.crm.dynamics.com/api/data/v9.1/. Cabeçalhos padrão (Accept: application/json, OData-MaxVersion: 4.0, OData-Version: 4.0) são usados.
  • Autenticação: o Datastream processa a autenticação usando o OAuth 2.0 com o tipo de permissão de acesso de credenciais do cliente. O Datastream recebe tokens da plataforma de identidade da Microsoft.

  • Descoberta de esquemas: os esquemas do Dataverse são dinâmicos. O Datastream descobre nomes e esquemas de objetos consultando o endpoint /EntityDefinitions.

    • Nomes de objetos: o Datastream busca nomes de objetos enviando uma solicitação GET para o caminho do conjunto de entidades /EntityDefinitions com o filtro $filter=TableType ne 'Virtual' and IsPrivate eq false e o parâmetro $select=EntitySetName.
    • Esquema de objeto: o Datastream busca o esquema de objeto por entidade enviando uma solicitação GET ao caminho do conjunto de entidades /EntityDefinitions com o parâmetro $expand=Attributes($select=LogicalName,AttributeType,AttributeTypeName) e o filtro $filter=EntitySetName eq '[objectName]'.

  • Replicação de dados:

    • O Datastream replica tabelas padrão e personalizadas do Dataverse. Ele exclui tabelas virtuais e particulares.
    • Preenchimento histórico: se configurado para um stream, o Datastream replica todos os dados históricos das tabelas incluídas. Para isso, envie uma solicitação GET inicial ao conjunto de entidades e itere por todas as páginas usando a propriedade @odata.nextLink fornecida nas respostas da API. O cabeçalho Prefer: odata.maxpagesize=5000 é usado.
    • Sincronização incremental: o Datastream replica eventos de inserção e atualização. Isso é feito usando a sincronização baseada em carimbo de data/hora, filtrando registros em que o campo modifiedon é maior que o último horário de sincronização ($filter=modifiedon gt [last_sync_timestamp]). O Datastream não captura eventos de exclusão.

  • Intervalo de sondagem: o Datastream faz sondagens para identificar mudanças de acordo com o intervalo de sondagem definido ao criar o stream. O intervalo é refletido na métrica de atualização de dados do stream.

Todos os objetos replicados são compatíveis com a sincronização incremental, usando o campo modifiedon, e com o preenchimento completo.

Versões

O Datastream usa a versão v9.1 da API Web do Dataverse.

Limitações conhecidas

As limitações conhecidas do uso do Dataverse como origem incluem:

  • O método de sincronização incremental, com base no carimbo de data/hora modifiedon, não captura eventos de exclusão.
  • O Datastream não é compatível com o recurso de rastreamento de alterações recomendado do Dataverse, que usa links delta (@odata.deltaLink). Isso ocorre porque não é possível armazenar o URL do link delta necessário para as extrações incrementais subsequentes.
  • A replicação é limitada a tabelas padrão e personalizadas. Não há suporte para tabelas virtuais e privadas.
  • A atualização precisa do campo modifiedon nas tabelas de origem é fundamental para garantir que a sincronização incremental funcione conforme o esperado.
  • Para recuperar os rótulos dos campos Picklist, as solicitações de dados precisam incluir o cabeçalho Prefer: data.include-annotations="*", não apenas os valores inteiros.

A seguir