Partilhar via

Amostra de operações de condição de API da Web

  • Artigo

 

Publicado: janeiro de 2017

Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Esse grupo de exemplos demonstra como realizar operações que são condicionalmente baseadas na versão do registro da entidade contida no servidor do Dynamics 365 e/ou atualmente mantida pelo cliente. Para obter mais informações, consulte Executar operações condicionais usando A API. Este exemplo foi implementado como um projeto separado para as seguintes linguagens:

Amostra de operações de condição API da Web (C#)

Exemplo de operações condicionais da API Web (JavaScript do lado do cliente)

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

Este tópico explica a estrutura e o conteúdo dos exemplos em nível superior e linguisticamente neutro. Detalha as solicitações e respostas de HTTP e a saída do programa associado, quando aplicável. Revise os tópicos vinculados de exemplo acima para obter implementações específicas por idioma e detalhes relacionados sobre como realizar as operações descritas neste tópico.

Demonstrações

Este exemplo é dividido em três seções principais, listadas na seguinte tabela. Cada seção contém um conjunto de operações de API da Web relacionadas que são discutidas mais detalhadamente na seção conceitual associada do tópico Executar operações condicionais usando A API.

Seção de código

Tópicos conceituais associados

GET condicional

Recuperações condicionais

Simultaneidade otimista ao excluir e atualizar

Aplicar simultaneidade otimista

Controle de operações de upsert

Limite de operações de upsert

As seções a seguir contêm uma breve discussão das operações executadas do Dynamics 365 usando a API da Web, juntamente com as mensagens HTTP correspondentes e saídas de console associadas, que são as mesmas de cada implementação de idioma. Para facilitar, os cabeçalhos HTTP pertinentes foram omitidos. Os URIs dos registros podem variar com base no endereço da organização e na ID do registro atribuído pelo servidor do Dynamics 365.

Dados de exemplo

O exemplo cria o seguinte registro antes de as seções do código principal serem executadas.

Tipo de entidade

Propriedades atribuídas por cliente

Propriedades atribuídas por servidor

account EntityType

Nome: Contoso Ltd.
Receita: 5000000
Telefone: 555-0000
Descrição: Parent company of Contoso Pharmaceuticals, etc.

ID: 14e151db-9b4f-e611-80e0-00155da84c08
Etag inicial: W/"628448"

GET condicional

Esta seção do programa demonstra como realizar recuperações condicionais para otimizar a largura de banda de rede e o processamento de servidor ainda mantendo o estado de registro mais atual no cliente.Para obter mais informações:Recuperações condicionais

  1. Tente recuperar a conta Contoso Ltd. apenas se ela não corresponder à versão atual, identificada pelo valor de ETag inicial que foi retornado na criação do registro da conta. Essa condição é representada pelo cabeçalho If-None-Match.

    Solicitação HTTP

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    Resposta HTTP

    HTTP/1.1 304 Not Modified

    Saída do console

    Instance retrieved using ETag: W/"628448"
Expected outcome: Entity was not modified so nothing was returned.

    Como o valor de resposta, 304 Not Modified, indica que o registro atual é o mais atual, o servidor não retorna o registro solicitado no corpo da resposta.

  2. Atualize a conta modificando sua propriedade primária de número de telefone.

    Solicitação HTTP

    PUT http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)/telephone1 HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json
{
  "value": "555-0001"
}

    Resposta HTTP

    HTTP/1.1 204 No Content

    Saída do console

    Account telephone number updated.

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

    Solicitação HTTP

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    Resposta HTTP

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628460"
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628460\"",
  "name":"Contoso Ltd",
  "revenue":5000000.0000,
  "telephone1":"555-0001",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

    Saída do console

    Instance retrieved using ETag: W/"628448"
{
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628460\"",
  "name": "Contoso Ltd",
  "revenue": 5000000.0,
  "telephone1": "555-0001",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

Simultaneidade otimista ao excluir e atualizar

Esta seção do programa demonstra como realizar operações de exclusão e atualização condicionais. O uso mais comum dessas operações é implementar uma abordagem de simultaneidade otimista para processamento de registros em um ambiente de vários usuários.Para obter mais informações:Aplicar simultaneidade otimista

  1. Tente excluir a conta original se e apenas se ela corresponder à versão original (valor de ETag). Essa condição é representada pelo cabeçalho If-Match. Essa operação falha porque o registro da conta foi atualizado na seção anterior e, como resultado, sua versão foi atualizada no servidor.

    Solicitação HTTP

    DELETE http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    Resposta HTTP

    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.", . . .
    }
}

    Saída do console

    Expected Error: The version of the existing record doesn't match the property provided.
        Account not deleted using ETag 'W/"628448"', status code: '412'.

  2. Tente atualizar a conta se e apenas se ela corresponder ao valor de ETag original. Novamente, essa condição é representada pelo cabeçalho If-Match, e a operação falha pela mesma razão.

    Solicitação HTTP

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0002",
  "revenue": 6000000
}

    Resposta HTTP

    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.", . . . 
  }
}

    Saída do console

    Expected Error: The version of the existing record doesn't match the property provided.
        Account not updated using ETag 'W/"628448"', status code: '412'.

  3. Tente atualizar novamente, mas, em vez disso, use o valor de ETag atual obtido na última recuperação de registro na seção anterior.

    Solicitação HTTP

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628460"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
  "telephone1": "555-0003",
  "revenue": 6000000
}

    Resposta HTTP

    HTTP/1.1 204 No Content

    Saída do console

    Account successfully updated using ETag: W/"628460", status code: '204'.

  4. Confirme a atualização realizada recuperando e fornecendo o estado de conta atual. Ela usa uma solicitação GET básica

    Solicitação HTTP

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    Resposta HTTP

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628461"
OData-Version: 4.0
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628461\"",
  "name":"Contoso Ltd",
  "revenue":6000000.0000,
  "telephone1":"555-0003",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

    Saída do console

    {
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628461\"",
  "name": "Contoso Ltd",
  "revenue": 6000000.0,
  "telephone1": "555-0003",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

Controle de operações de upsert

Esta seção do programa demonstra como realizar operações PATCH condicionais, limitando operações de upsert que serão realizadas como apenas atualização ou apenas inserção.Para obter mais informações:Limite de operações de upsert

  1. Tente inserir, sem atualizar, as propriedades de telefone primárias e as propriedades de receita dessa conta. O cabeçalho If-None-Match com o valor de * representa essa condição de upsert. Essa operação falha porque esse registro de conta ainda existe no servidor (a menos que ele tenha sido excluído atualmente por outro usuário ou processo).

    Solicitação HTTP

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-None-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0004",
  "revenue": 7500000
}

    Resposta HTTP

    HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"A record with matching key values already exists.", . . .
  }
}

    Saída do console

    Expected Error: A record with matching key values already exists.
        Account not updated using ETag 'W/"628448", status code: '412'.

  2. Tente realizar a mesma operação de atualização sem criação. Para isso, o cabeçalho condicional If-Match é usado com um valor de *. Essa operação ocorre porque o registro existe no servidor.

    Solicitação HTTP

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0005",
  "revenue": 7500000
}

    Resposta HTTP

    HTTP/1.1 204 No Content

    Saída do console

    Account updated using If-Match '*'

  3. Recupere e forneça o estado de conta atual com uma solicitação básica GET. Observe que o valor de ETag retornado foi alterado para refletir a versão nova e atualizada do registro da conta.

    Solicitação HTTP

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    Resposta HTTP

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628463"
OData-Version: 4.0
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628463\"",
  "name":"Contoso Ltd","revenue":7500000.0000,
  "telephone1":"555-0005",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

    Saída do console

    {
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628463\"",
  "name": "Contoso Ltd",
  "revenue": 7500000.0,
  "telephone1": "555-0005",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

  4. Exclua a conta com um DELETE básico.

    Solicitação HTTP

    DELETE http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    Resposta HTTP

    HTTP/1.1 204 No Content

    Saída do console

    Account was deleted.

  5. Assim como na etapa 2, tente atualizar a conta se ela existir. Novamente, essa condição é representada pelo cabeçalho If-Match com um valor de *. Essa operação falha porque esse registro foi simplesmente excluído. No entanto, se esse cabeçalho If-Match estava ausente, logo a operação de upsert básica resultante deve criar um novo registro com êxito.

    Solicitação HTTP

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0006",
  "revenue": 7500000
}

    Resposta HTTP

    HTTP/1.1 404 Not Found
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"account With Id = 14e151db-9b4f-e611-80e0-00155da84c08 Does Not Exist", . . .
  }
}

    Saída do console

    Expected Error: Account with Id = 14e151db-9b4f-e611-80e0-00155da84c08 does not exist.
Account not updated because it does not exist, status code: '404'.

Não há necessidade de limpar os dados de exemplo porque um registro de conta já foi excluído na etapa 4.

Confira Também

Use a API da Web do Microsoft Dynamics 365
Executar operações condicionais usando A API
Amostra de operações de condição API da Web (C#)
Exemplo de operações condicionais da API Web (JavaScript do lado do cliente)

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais