Exemplo de operações condicionais da API Web

Essa coleção de exemplos demonstra como executar operações condicionais com base na versão da linha da tabela contida no servidor Microsoft Dataverse e na versão atualmente mantida pelo cliente. Saiba como executar operações condicionais usando a API Web. Este exemplo é implementado como um projeto separado para os seguintes idiomas:

A API Web do Dataverse segue as convenções do protocolo OData v4.0 , que usa ETags para implementar o controle de versão do recurso. As operações condicionais da API Web dependem desse mecanismo de controle de versão.

Este artigo explica a estrutura e o conteúdo dos exemplos em um nível mais alto e neutro em idioma. Ele detalha as solicitações e respostas HTTP e a saída do programa associado, quando aplicável. Examine os artigos de exemplo vinculados para obter implementações específicas do idioma e detalhes relacionados sobre como executar as operações descritas neste artigo.

Demonstrações

Este exemplo é dividido em três seções principais, listadas na tabela a seguir. Cada seção contém um conjunto de operações de API Web relacionadas que são discutidas com mais detalhes na seção conceitual associada do artigo Executar operações condicionais usando a API Web.

Seção de código	Artigos conceituais associados
Seção 0: Criar registros de exemplo	Criar uma linha de tabela usando a API Web
Seção 1: GET condicional	Recuperações condicionais
Seção 2: Simultaneidade otimista ao excluir e atualizar	Aplicar concorrência otimista Limitar operações upsert
Seção 3: Excluir registros de exemplo	Exclusão básica Executar operações em lote usando a API Web

As seções a seguir contêm uma breve discussão sobre as operações da API Web do Dataverse executadas, as mensagens HTTP correspondentes e a saída do console associada, que é a mesma para cada implementação de idioma. Para fins de brevidade, cabeçalhos HTTP menos pertinentes são omitidos. Os URIs das linhas da tabela variam com o endereço da organização base e a ID da linha atribuída pelo servidor do Dataverse.

Seção 0: Criar registros de exemplo

Antes de executar as seções de código principal, o exemplo cria a linha de tabela a seguir.

Solicitação:

POST [Organization Uri]/api/data/v9.2/accounts?$select=name,revenue,telephone1,description HTTP/1.1
Prefer: return=representation
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
  "name": "Contoso Ltd",
  "telephone1": "555-0000",
  "revenue": 5000000,
  "description": "Parent company of Contoso Pharmaceuticals, etc."
}

Resposta:

HTTP/1.1 201 Created
Preference-Applied: return=representation
OData-Version: 4.0

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"72965013\"",
  "name": "Contoso Ltd",
  "revenue": 5000000.0,
  "telephone1": "555-0000",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

Saída do console:

Created and retrieved the initial account, shown below:
{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"72965013\"",
  "name": "Contoso Ltd",
  "revenue": 5000000.0,
  "telephone1": "555-0000",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

Seção 1: GET condicional

Esta seção do programa demonstra como executar recuperações condicionais para otimizar a largura de banda de rede e o processamento do servidor, mantendo o estado de linha mais atual no cliente. Saiba como executar recuperações condicionais

Tente recuperar a conta Contoso Ltd. apenas se ela não corresponder à versão atual, identificada pelo valor ETag inicial que a operação retorna ao criar a linha da conta. O If-None-Match cabeçalho representa essa condição.

Solicitação:
```
GET [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"72965013"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
```
Resposta:
```
HTTP/1.1 304 NotModified
```
Saída do console:
```
Account record retrieved using ETag: W/"72965013"
Expected outcome: Entity was not modified so nothing was returned.
```
O valor 304 NotModifiedda resposta indica que a linha da tabela atual é a mais atual, portanto, o servidor não retorna a linha solicitada no corpo da resposta.

Atualize a conta modificando a propriedade do número de telefone primário.

Solicitação:

PUT [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)/telephone1 HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{"value": "555-0001"}

Resposta:

HTTP/1.1 204 NoContent
OData-Version: 4.0

Saída do console:

Modified account record retrieved using ETag: W/"72965013"

Tente novamente a mesma operação GET condicional, usando o valor ETag original. Desta vez, a operação retorna os dados solicitados porque a versão no servidor é diferente (e mais recente) da versão identificada na solicitação. Como em todas as recuperações de linha de tabela, a resposta inclui um cabeçalho ETag que identifica a versão atual.

Solicitação:

GET [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"72965013"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

Resposta:

HTTP/1.1 200 OK
ETag: W/"72965025"
OData-Version: 4.0

{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
"@odata.etag": "W/\"72965025\"",
"name": "Contoso Ltd",
"revenue": 5000000.0,
"telephone1": "555-0001",
"description": "Parent company of Contoso Pharmaceuticals, etc.",
"accountid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

Saída do console:

Modified account record retrieved using ETag: W/"72965013"
Notice the updated ETag value and telephone number
{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
"@odata.etag": "W/\"72965025\"",
"name": "Contoso Ltd",
"revenue": 5000000.0,
"telephone1": "555-0001",
"description": "Parent company of Contoso Pharmaceuticals, etc.",
"accountid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

Seção 2: Simultaneidade otimista ao excluir e atualizar

Esta seção do programa demonstra como executar operações condicionais de exclusão e atualização. O uso mais comum para essas operações é implementar uma abordagem de simultaneidade otimista para o processamento de linhas em um ambiente multiusuário. Aprenda a aplicar simultaneidade otimista

Tente excluir a conta original se, e somente se, ela corresponder à versão original (valor ETag). O If-Match cabeçalho representa essa condição. Essa operação falha porque a linha da conta foi atualizada na seção anterior, portanto, como resultado, sua versão é atualizada no servidor.

Solicitação:

DELETE [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee) HTTP/1.1
If-Match: W/"72965013"
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Resposta:

HTTP/1.1 412 PreconditionFailed
OData-Version: 4.0

{
"error": {
   "code": "0x80060882",
   "message": "The version of the existing record doesn't match the RowVersion property provided."
 }
}

Saída do console:

Attempting to delete the account using the original ETag value
Expected Error: The version of the existing record doesn't match the RowVersion property provided.
      Account not deleted using ETag 'W/"72965013"', status code: 'PreconditionFailed'.

Tente atualizar a conta original se, e somente se, ela corresponder ao valor ETag original. Novamente, essa condição é representada pelo If-Match cabeçalho e a operação falha pelo mesmo motivo.

Solicitação:

PATCH [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee) HTTP/1.1
If-Match: W/"72965013"
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
"telephone1": "555-0002",
"revenue": 6000000
}

Resposta:

HTTP/1.1 412 PreconditionFailed
OData-Version: 4.0

{
"error": {
   "code": "0x80060882",
   "message": "The version of the existing record doesn't match the RowVersion property provided."
 }
}

Saída do console:

Attempting to update the account using the original ETag value
Expected Error: The version of the existing record doesn't match the RowVersion property provided.
      Account not updated using ETag 'W/"72965013"', status code: 'PreconditionFailed'.

Tente novamente uma atualização, mas, em vez disso, use o valor ETag atual obtido da recuperação da última linha na seção anterior.

Solicitação:

PATCH [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee) HTTP/1.1
If-Match: W/"72965025"
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
"telephone1": "555-0003",
"revenue": 6000000
}

Resposta:

HTTP/1.1 204 NoContent
OData-Version: 4.0
OData-EntityId: [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)

Saída do console:

Attempting to update the account using the current ETag value

Account successfully updated using ETag: W/"72965025".

Confirme se a atualização foi bem-sucedida recuperando e gerando o estado da conta atual usando uma solicitação GET .

Solicitação:

GET [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)?$select=name,revenue,telephone1,description HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Resposta:

HTTP/1.1 200 OK
ETag: W/"72965035"
OData-Version: 4.0

{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
"@odata.etag": "W/\"72965035\"",
"name": "Contoso Ltd",
"revenue": 6000000.0,
"telephone1": "555-0003",
"description": "Parent company of Contoso Pharmaceuticals, etc.",
"accountid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

Saída do console:

Below is the final state of the account
{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
"@odata.etag": "W/\"72965035\"",
"name": "Contoso Ltd",
"revenue": 6000000.0,
"telephone1": "555-0003",
"description": "Parent company of Contoso Pharmaceuticals, etc.",
"accountid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

Seção 3: Excluir registros de exemplo

Esta seção exclui o registro que você criou na Seção 0: Criar registros de exemplo. Ele usa uma solicitação $batch .

Solicitação:

POST [Organization Uri]/api/data/v9.2/$batch HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

--batch_98e0fdc2-a298-4f42-85a8-da0536140b78
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-Length: 115

DELETE /api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee) HTTP/1.1


--batch_98e0fdc2-a298-4f42-85a8-da0536140b78--

Resposta:

HTTP/1.1 200 OK
OData-Version: 4.0

--batchresponse_7bf5a9a8-5b97-4fb0-9243-668f3113e6eb
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content
OData-Version: 4.0


--batchresponse_7bf5a9a8-5b97-4fb0-9243-668f3113e6eb--

Saída do console:

Deleting created records.

Consulte também

Utilizar a API Web do Dataverse
Executar operações condicionais usando a API Web
Exemplo de operações condicionais da API Web (C#)
Exemplo de operações condicionais da API Web (JavaScript do lado do cliente)
Exemplo de operações condicionais da API Web (PowerShell)

Comentários

Esta página foi útil?

Last updated on 2026-03-10

Exemplo de operações condicionais da API Web

Demonstrações

Seção 0: Criar registros de exemplo

Seção 1: GET condicional

Seção 2: Simultaneidade otimista ao excluir e atualizar

Seção 3: Excluir registros de exemplo

Consulte também

Comentários

Recursos adicionais