Compartilhar via

Usar o controle de alterações para sincronizar dados com sistemas externos

O recurso de controle de alterações no Microsoft Dataverse fornece uma maneira de manter os dados sincronizados com eficiência detectando quais dados foram alterados desde que os dados foram inicialmente extraídos ou sincronizados pela última vez. Este artigo discute como habilitar e recuperar alterações para uma tabela.

Habilitar o controle de alterações para uma tabela

Antes de recuperar as alterações de uma tabela, verifique se o controle de alterações está habilitado para essa tabela.

Você pode verificar se esse recurso está habilitado ou habilitá-lo usando o Power Apps. Selecione Dados>Tabelas e a tabela específica. Em opções avançadas, você encontra a propriedade Controlar modificações.

Defina essa propriedade programaticamente definindo a propriedade EntityMetadata.ChangeTrackingEnabled como True.

Observação

Depois de habilitar o controle de alterações para uma tabela, você não poderá desabilitá-la.

Para obter mais informações sobre como usar o Power Apps, consulte Criar e editar tabelas usando o Power Apps.

Para verificar se o controle de alterações está habilitado para uma tabela usando a API Web do Dataverse, use um dos seguintes métodos:

  1. Execute uma consulta EntityDefinitions usando a seguinte solicitação GET:

    GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=SchemaName&$filter=ChangeTrackingEnabled eq true

    Algumas tabelas do sistema têm o controle de alterações habilitado, como Auditoria (Auditoria). Para ver a lista completa, use a seguinte consulta:

    GET [Organization URI]/api/data/v9.2/EntityDefinitions?$filter=ChangeTrackingEnabled eq true and IsCustomEntity eq false&$select=LogicalName

    Para obter mais informações, consulte definições de tabela de consulta usando a API Web.

  2. Verifique o documento de serviço $metadata da API Web. A anotação Org.OData.Capabilities.V1.ChangeTracking é definida para conjuntos de entidades que têm o controle de alterações habilitado.

    Para ver anotações no documento de serviço CDSL da API Web, use esta consulta de API Web:

    GET [Organization URI]/api/data/v9.2/$metadata?annotations=true

    Os conjuntos de entidades que representam tabelas em que o controle de alterações está habilitado têm essa anotação:

    <Annotation Term="Org.OData.Capabilities.V1.ChangeTracking">
   <Record>
         <PropertyValue Property="Supported" Bool="true" />
   </Record>
</Annotation>

    Para obter mais informações, consulte anotações de metadados.

Tabelas não qualificadas para controle de alterações

Você não pode habilitar o controle de alterações para algumas tabelas. Para verificar se uma tabela está qualificada para controle de alterações, verifique o valor da propriedade gerenciada EntityMetadata.CanChangeTrackingBeEnabled . Para ver quais tabelas não podem ser habilitadas para controle de alterações, use esta consulta da API Web:

GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=SchemaName,ChangeTrackingEnabled&$filter=ChangeTrackingEnabled eq false and CanChangeTrackingBeEnabled/Value eq false

Mais informações:

Recuperar alterações para uma tabela usando a API Web

Você pode acompanhar as alterações feitas em tabelas usando solicitações de API Web que incluem o Prefer: odata.track-changes cabeçalho. Esse cabeçalho solicita que um link delta seja retornado, que você pode usar posteriormente para recuperar as alterações de tabela.

Os links delta são links opacos gerados pelo serviço que o cliente usa para recuperar alterações subsequentes em um resultado. Eles se baseiam em uma consulta definidora que descreve o conjunto de resultados para os quais as alterações estão sendo controladas. Por exemplo, a solicitação que gerou os resultados que contêm o link delta. O link delta codifica a coleção de tabelas para as quais as alterações estão sendo controladas, juntamente com um ponto de partida do qual acompanhar as alterações. Para obter mais informações, consulte Oasis OData Versão 4.0 – Delta Links.

Recuperar alterações em tabelas usando o exemplo de API Web

Este exemplo mostra como recuperar as alterações feitas para a tabela de conta usando a API Web.

Solicitação:

GET [Organization URI]/api/data/v9.0/accounts?$select=name,accountnumber,telephone1,fax HTTP/1.1
Prefer: odata.track-changes
OData-Version: 4.0
Content-Type: application/json

Resposta:

HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.track-changes

{
  "@odata.context":"[Organization URI]/api/data/v9.0/$metadata#accounts(name,accountnumber,telephone1,fax)",
"@odata.deltaLink": "[Organization URI]/api/data/v9.0/accounts?$select=name,accountnumber,telephone1,fax&$deltatoken=919042%2108%2f22%2f2017%2008%3a10%3a44",
"value":[
           {
              "@odata.etag":"W/\"915244\"",
              "name":"Monte Orton",
              "accountnumber":null,
              "telephone1":"555000",
              "fax":"10101",
              "accountid":"60c4e274-0d87-e711-80e5-00155db19e6d"
           }
       ]
}

Use o @odata.deltaLink URI retornado do exemplo anterior para buscar alterações nas tabelas. Neste exemplo, você criou uma nova conta e excluiu uma conta existente. O link delta retornado da solicitação anterior busca essas alterações, conforme mostrado no exemplo a seguir.

Solicitação:

GET [Organization URI]/api/data/v9.0/accounts?$select=name,accountnumber,telephone1,fax&$deltatoken=919042%2108%2f22%2f2017%2008%3a10%3a44
OData-Version: 4.0
Content-Type: application/json

Resposta:

HTTP/1.1 200 OK
OData-Version: 4.0

{
          "@odata.context":"[Organization URI]/data/v9.0/$metadata#accounts(name,telephone1,fax)/$delta",
          "@odata.deltaLink":"[Organization URI]/api/data/v9.0/accounts?$select=name,telephone1,fax&$deltatoken=919058%2108%2f22%2f2017%2008%3a21%3a20",
"value":
    [
        {
            "@odata.etag":"W/\"915244\"",
            "name":"Monte Orton",
            "telephone1":"555000",
            "fax":"10101",
            "accountid":"60c4e274-0d87-e711-80e5-00155db19e6d"
        },
        {
            "@odata.context":"[Organization URI]/api/data/v9.0/$metadata#accounts/$deletedEntity",
            "id":"2e451703-c686-e711-80e5-00155db19e6d",
            "reason":"deleted"
        }
    ]
}

A resposta para o link delta retornado na solicitação inicial de controle de alterações contém outro link delta. Esse link delta ajuda a recuperar todas as alterações subsequentes nas tabelas. Se nenhuma alteração de tabela ocorrer após a solicitação inicial de controle de alterações, a resposta conterá JSON vazio.

Recuperar a contagem das alterações feitas em tabelas usando a API Web

Para obter o número de alterações, adicione $count ao link delta retornado da solicitação inicial de controle de alterações, conforme mostrado no exemplo a seguir.

Solicitação:

GET [Organization URI]/api/data/v9.0/accounts/$count?$deltatoken=919042%2108%2f22%2f2017%2008%3a10%3a44
OData-Version: 4.0
Content-Type: application/json

Opções de consulta sem suporte na solicitação da API Web de Rastreamento de Alterações

Opções de consulta do sistema $filter, $orderby, $expand e $top não são suportadas quando você usa o cabeçalho Prefer: odata.track-changes em uma solicitação de API da Web. Se você usar essas opções de consulta na solicitação da API Web, receberá uma mensagem de erro: The \"${filter|orderby|expand|top}\" query parameter isn't supported when Change Tracking is enabled..

Recuperar alterações para uma tabela usando o SDK do .NET

Ao habilitar o controle de alterações para uma tabela, use a RetrieveEntityChanges mensagem com a Classe RetrieveEntityChangesRequest para recuperar as alterações dessa tabela.

Na primeira vez que você usar essa mensagem, ela retornará todos os registros da tabela. Você pode usar esses dados para preencher o armazenamento externo. A mensagem também retorna um número de versão, que você envia de volta ao usar novamente a mensagem RetrieveEntityChanges, garantindo que apenas os dados das alterações ocorridas desde aquela versão sejam retornados.

Lembre-se das seguintes restrições ao recuperar alterações para uma tabela:

  • Você pode acompanhar apenas uma tabela no rastreamento de alterações. Se você executar RetrieveEntityChanges sem nenhuma versão ou token, o servidor o tratará como a versão mínima do sistema e retornará todos os registros como novos. Objetos excluídos não são retornados.
  • As alterações serão retornadas se o último token estiver dentro de um valor padrão de sete dias. O valor da tabela Organization coluna ExpireChangeTrackingInDays controla essa duração e pode ser alterado. Se as alterações não processadas forem mais antigas do que o valor configurado, o sistema gerará uma exceção.
  • Se um cliente possui um conjunto de alterações para uma tabela, por exemplo, a versão 1, um registro é criado e excluído antes da próxima consulta por alterações. Nesse caso, o cliente recebe o item excluído, mesmo que não o tivesse inicialmente.
  • Os registros são recuperados na ordem determinada pela lógica do lado do servidor. Normalmente, o chamador obtém todos os registros novos ou atualizados primeiro (classificados por número de versão) seguidos por registros excluídos. Se houver 3.000 registros criados ou atualizados e 2.000 registros excluídos, o Dataverse retornará uma coleção de 5.000 registros para tabelas padrão, que têm as primeiras 3.000 entradas compostas por registros novos ou atualizados e as últimas 2.000 entradas para registros excluídos.
  • Se a coleção de itens nova ou atualizada for maior que 5.000, o usuário poderá percorrer a coleção.
  • O usuário solicitante deve ter acesso de leitura no nível da organização à tabela. Se o usuário tiver acesso de leitura limitado, o sistema gerará um erro de verificação de privilégios.

Código de exemplo do SDK do .NET

O snippet de código a seguir mostra como usar a RetrieveEntityChanges mensagem para recuperar as alterações de uma tabela. Para obter o exemplo completo, consulte Sincronizar dados com sistemas externos usando o controle de alterações.

string token;

// Initialize page number.
int pageNumber = 1;
List<Entity> initialrecords = new List<Entity>();

// Retrieve records by using Change Tracking feature.
RetrieveEntityChangesRequest request = new RetrieveEntityChangesRequest();
request.EntityName = _customBooksEntityName.ToLower();
request.Columns = new ColumnSet("sample_bookcode", "sample_name", "sample_author");
request.PageInfo = new PagingInfo() { Count = 5000, PageNumber = 1, ReturnTotalRecordCount = false };


// Initial Synchronization. Retrieves all records as well as token value.
Console.WriteLine("Initial synchronization....retrieving all records.");
while (true)
{
    RetrieveEntityChangesResponse response = (RetrieveEntityChangesResponse)_serviceProxy.Execute(request);

    initialrecords.AddRange(response.EntityChanges.Changes.Select(x => (x as NewOrUpdatedItem).NewOrUpdatedEntity).ToArray());
    initialrecords.ForEach(x => Console.WriteLine("initial record id:{0}", x.Id));
    if (!response.EntityChanges.MoreRecords)
    {
        // Store token for later query
        token = response.EntityChanges.DataToken;
        break;

    }
    // Increment the page number to retrieve the next page.
    request.PageInfo.PageNumber++;
    // Set the paging cookie to the paging cookie returned from current results.
    request.PageInfo.PagingCookie = response.EntityChanges.PagingCookie;
}

Consulte também

Definir chaves alternativas para uma tabela
Usar uma chave alternativa para fazer referência a um registro
Atualizar o Dynamics 365 com dados externos usando Upsert
Consultar definições de tabela usando a API Web

  • Last updated on