Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Microsoft Dataverse dá suporte a operações condicionais que usam o mecanismo de controle de versão de recurso HTTP padrão conhecido como ETags. Use operações condicionais usando a API Web para otimizar as recuperações de registro, limitar operações upsert e aplicar concorrência otimista para evitar sobrescrever alterações feitas por outras pessoas.
ETags e controle de versão de recursos
O protocolo HTTP define uma entity tag, ou ETag, para identificar versões específicas de um recurso. ETags são identificadores opacos cujos valores exatos dependem da implementação. Os valores de ETag ocorrem em duas variedades: fortes e fracos. A validação forte indica que um recurso exclusivo, identificado por um URI específico, é idêntico no nível binário se o valor de ETag correspondente estiver inalterado. A validação fraca garante apenas que a representação de recurso seja semanticamente equivalente para o mesmo valor de ETag.
O Dataverse gera uma propriedade fracamente validada @odata.etag para cada instância de entidade e retorna automaticamente essa propriedade com cada registro de entidade recuperado. Para obter mais informações, consulte Recuperar uma linha de tabela usando a API Web.
cabeçalhos If-Match e If-None-Match
Use os cabeçalhos If-Match e If-None-Match com valores ETag para verificar se a versão atual de um recurso corresponde à que você recuperou pela última vez, corresponde a qualquer versão anterior ou não corresponde a nenhuma versão. Essas comparações formam a base do suporte à operação condicional. O Dataverse fornece ETags para dar suporte a recuperações condicionais, simultaneidade otimista e operações upsert limitadas.
Warning
O código do cliente não deve dar nenhum significado ao valor específico de uma ETag, nem a qualquer relação aparente entre ETags além da igualdade ou desigualdade. Por exemplo, um valor ETag para uma versão mais recente de um recurso não tem a garantia de ser maior que o valor de ETag para uma versão anterior. Além disso, o algoritmo usado para gerar novos valores ETag pode ser alterado sem aviso prévio entre versões de um serviço.
Recuperações condicionais
As etags ajudam a otimizar as recuperações de registro quando você acessa o mesmo registro várias vezes. Se você recuperou um registro anteriormente, passe o valor ETag com o cabeçalho If-None-Match para solicitar dados somente se ele tiver sido alterado desde a última vez que você o recuperou. Se os dados forem alterados, a solicitação retornará um status HTTP de 200 OK com os dados mais recentes no corpo da resposta. Se os dados não forem alterados, a solicitação retornará o código 304 Not Modified de status HTTP para indicar que o registro não foi modificado.
O par de mensagens de exemplo a seguir retorna dados para um registro de conta com o accountid igual a 00000000-0000-0000-0000-000000000001 quando os dados não foram alterados desde a última vez que você os recuperou e o valor de Etag foi W/"468026".
Solicitação:
GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)?$select=accountcategorycode,accountnumber,creditonhold,createdon,numberofemployees,name,revenue HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: W/"468026"
Resposta:
HTTP/1.1 304 Not Modified
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
As seções a seguir descrevem as limitações ao uso de recuperações com condição.
A tabela deve ter a concorrência otimista habilitada
Verifique se uma tabela tem simultaneidade otimista habilitada usando a solicitação de API Web a seguir. As tabelas que têm a simultaneidade otimista habilitada têm a propriedade EntityMetadata.IsOptimisticConcurrencyEnabled definida como true. Use esta URL para recuperar o valor:
GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='<Entity Logical Name>')?$select=IsOptimisticConcurrencyEnabled
Este exemplo recupera o valor da tabela de contatos:
Solicitação:
GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='contact')?$select=IsOptimisticConcurrencyEnabled HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Resposta:
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#EntityDefinitions(IsOptimisticConcurrencyEnabled)/$entity",
"MetadataId": "608861bc-50a4-4c5f-a02c-21fe1943e2cf",
"IsOptimisticConcurrencyEnabled": true
}
A consulta não deve incluir $expand
A Etag só pode detectar se o único registro que você está recuperando foi alterado. Ao usar $expand em sua consulta, você pode retornar mais registros e não é possível detectar se algum desses registros foi alterado. Se a consulta incluir $expand, a solicitação nunca retornará 304 Not Modified.
A consulta não deve incluir anotações
Quando você inclui o Prefer: odata.include-annotations cabeçalho em uma GET solicitação, o servidor nunca retorna 304 Not Modified. Os valores de anotações podem se referir a valores de registros relacionados. Esses registros podem ter sido alterados e o servidor não pode detectar essa alteração, portanto, seria incorreto indicar que nada mudou.
Limitar operações upsert
Uma operação upsert criará um registro se ele não existir; caso contrário, ele atualiza um registro existente. No entanto, você pode usar ETags para restringir ainda mais os upserts para impedir criações ou impedir atualizações.
Impedir criação em upsert
Se você estiver atualizando dados e houver a possibilidade de que o registro tenha sido excluído intencionalmente, talvez você não queira recriar o registro. Para evitar essa condição, adicione um If-Match cabeçalho à solicitação com um valor de *.
Solicitação:
PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-Match: *
{
"name": "Updated Sample Account ",
"creditonhold": true,
"address1_latitude": 47.639583,
"description": "This is the updated description of the sample account",
"revenue": 6000000,
"accountcategorycode": 2
}
Resposta:
Se o servidor encontrar o registro, você obterá uma resposta normal com status 204 No Content. Se o servidor não encontrar o registro, você obterá a seguinte resposta com status 404 Not Found.
HTTP/1.1 404 Not Found
OData-Version: 4.0
Content-Type: application/json; odata.metadata=minimal
{
"error": {
"code": "",
"message": "account With Id = 00000000-0000-0000-0000-000000000001 Does Not Exist"
}
}
Impedir a atualização no upsert
Se você estiver inserindo dados, um registro com o mesmo id valor poderá já existir no sistema. Talvez você não queira atualizar esse registro existente. Para impedir a atualização do registro, adicione um cabeçalho If-None-Match à solicitação com um valor de "*".
Solicitação:
PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: *
{
"name": "Updated Sample Account ",
"creditonhold": true,
"address1_latitude": 47.639583,
"description": "This is the updated description of the sample account",
"revenue": 6000000,
"accountcategorycode": 2
}
Resposta:
Se o registro não for encontrado, você receberá uma resposta normal com status 204 No Content. Se o registro for encontrado, você receberá a seguinte resposta com status 412 Precondition Failed.
HTTP/1.1 412 Precondition Failed
OData-Version: 4.0
Content-Type: application/json; odata.metadata=minimal
{
"error":{
"code":"",
"message":"A record with matching key values already exists."
}
}
Aplicar concorrência otimista
Use a concorrência otimista para detectar se um registro foi modificado desde a última vez que você o recuperou. Se o registro que você pretende atualizar ou excluir foi alterado no servidor desde que o recuperou, talvez você não queira concluir a operação de atualização ou exclusão. Usando o padrão a seguir, você pode detectar essa situação, recuperar a versão mais recente do registro e aplicar todos os critérios necessários para reavaliar se deve tentar executar a operação novamente.
Aplicar concorrência otimista na exclusão
A solicitação de exclusão a seguir para uma conta com accountid de 00000000-0000-0000-0000-000000000001 falha porque o valor ETag enviado com o cabeçalho If-Match é diferente do valor atual. Se o valor correspondeu, você receberá um status 204 No Content.
Solicitação:
DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
If-Match: W/"470867"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Resposta:
HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
"error":{
"code":"","message":"The version of the existing record doesn't match the RowVersion property provided."
}
}
Aplicar concorrência otimista na atualização
A solicitação de atualização a seguir para uma conta com accountid de 00000000-0000-0000-0000-000000000001 falha porque o valor ETag enviado com o cabeçalho If-Match é diferente do valor atual. Se o valor correspondeu, você receberá um 204 No Content estado.
Solicitação:
PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
If-Match: W/"470867"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
{"name":"Updated Account Name"}
Resposta:
HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
"error":{
"code":"","message":"The version of the existing record doesn't match the RowVersion property provided."
}
}
Consulte também
Exemplo de operações condicionais da API Web (PowerShell)
Exemplo de operações condicionais da API Web (C#)
Exemplo de operações condicionais da API Web (JavaScript do lado do cliente)
Executar operações usando a API Web
Redigir solicitações Http e manipular erros