Rastrear as alterações de dados da entidade com o controle de alterações e a API Web

  • 15 minutos

Normalmente, as organizações precisam sincronizar dados em vários sistemas. O Microsoft Dataverse fornece um recurso para gerenciar com eficiência esse cenário, chamado controle de alterações. Com o controle de alterações habilitado, você pode criar aplicativos para consultar essas alterações.

Habilitar o controle de alterações para uma tabela

Você pode habilitar o controle de alterações em uma tabela definindo o sinalizador Controlar alterações nas configurações da tabela no Power Apps maker portal, encontrado na seção Opções avançadas > Para esta tabela.

De acordo com a documentação do OData 4.0, os links delta são "links opacos gerados pelo serviço que o cliente usa para recuperar alterações subsequentes em um resultado". A Microsoft criou esse padrão no controle de alterações no Dataverse para fornecer um método padrão comum de interface com os dados alterados à medida que ocorrem ao longo do tempo. Para obter mais informações sobre links delta, consulte OData Versão 4.0 – links Delta.

Após a emissão de uma solicitação de controle de alterações, sua resposta contém um link delta, que você passa para sua próxima solicitação para obter as alterações que ocorreram desde a solicitação inicial. Cabe a seu aplicativo manter o link delta, da mesma forma que você poderia ter feito o rastreamento com carimbos de data/hora no passado.

Recuperar alterações em tabelas usando a API Web

Após habilitar o controle de alterações em uma tabela, você poderá recuperar suas alterações por meio da API Web adicionando odata.track-changes como um cabeçalho de preferência em sua solicitação Web. O exemplo a seguir solicita alterações da tabela de contas para um conjunto específico de campos (name, account number, telephone1 e fax).

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

Na solicitação inicial, você recebe todo o conjunto de dados que se aplica à consulta porque um delta não foi aplicado. No entanto, a resposta mostra um valor @odata.deltaLink. Esse link contém um parâmetro deltatoken, que deverá ser passado na solicitação subsequente quando você quiser ver quais alterações foram aplicadas desde que essa consulta foi executada. Considere esse processo como semelhante ao tratamento da paginação no OData.

O exemplo a seguir é uma resposta à solicitação de conta anterior:

{
          "@odata.context":"[Organization URI]/data/v9.2/$metadata#accounts(name,telephone1,fax)/$delta",
          "@odata.deltaLink":"[Organization URI]/api/data/v9.2/accounts?$select=name,telephone1,fax&$deltatoken=919042%2108%2f22%2f2017%2008%3a10%3a44",
"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.2/$metadata#accounts/$deletedEntity",
            "id":"2e451703-c686-e711-80e5-00155db19e6d",
            "reason":"deleted"
        }
    ]
}

Nesse cenário, considere que algum tempo se passou e, agora, você deseja ver se alguma outra alteração foi aplicada. Você pode usar o parâmetro @odata.deltaLink para executar sua consulta (ou extrair seu deltatoken se estiver gerenciando cadeias de conexão de maneira diferente) e ver quais alterações aconteceram desde sua última solicitação.

O exemplo a seguir mostra como você recuperaria as alterações desde a última solicitação executando o @odata.deltaLink retornado:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,accountnumber,telephone1,fax&$deltatoken=919042%2108%2f22%2f2017%2008%3a10%3a44

Nesse cenário, imagine que uma nova conta foi criada e outra foi excluída. A resposta seria semelhante ao seguinte exemplo:

{
          "@odata.context":"[Organization URI]/data/v9.2/$metadata#accounts(name,telephone1,fax)/$delta",
          "@odata.deltaLink":"[Organization URI]/api/data/v9.2/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.1/$metadata#accounts/$deletedEntity",
            "id":"2e451703-c686-e711-80e5-00155db19e6d",
            "reason":"deleted"
        }
    ]
}

Conforme mostrado no exemplo, foi fornecido outro link delta, que você poderá usar na próxima vez que precisar ver quais alterações ocorreram.

Recuperar o número de alterações em um delta

Você também pode recuperar o número de alterações feitas em um determinado delta adicionando o parâmetro $count à sua solicitação.

GET [Organization URI]/api/data/v9.2/accounts/$count?$deltatoken=919042%2108%2f22%2f2017%2008%3a10%3a44