Compartilhar via

Executar operações condicionais usando A API

  • Artigo

 

Publicado: janeiro de 2017

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

Microsoft Dynamics 365 oferece suporte para um conjunto de operações condicionais baseados em mecanismo padrão de HTTP de controle de versão do recurso conhecido como ETags.

Neste tópico

ETags

Cabeçalhos de correspondência e não correspondência

Recuperações condicionais

Limite de operações de upsert

Aplicar simultaneidade otimista

ETags

O protocolo HTTP define uma marca de entidade, ou ETag para identificação breve de versões específicas de um recurso. ETags são identificadores opacos cujos valores exatos sejam dependentes de implementação. Os valores de ETag ocorrem em duas variedades: validação fraca e forte. Validação forte indica que um recurso único, identificado pelo URI específico, serão idênticos no nível de binário se o valor de ETag correspondente for inalterado. A validação fraca garante que somente representação é semanticamente de recursos equivalentes para o mesmo valor de ETag.

Dynamics 365 gera uma propriedade fracamente validação @odata.etag para cada instância da entidade, e esta propriedade é retornada automaticamente com cada registro da entidade recuperado. Para obter mais informações, consulte Recuperar uma entidade usando a API Web.

Cabeçalhos de correspondência e não correspondência

Os títulos eSem Nenhuma correspondência o uso Sem correspondência de valores de ETag verifique se a versão atual de um recurso corresponda a ela um sobrenome, e qualquer versão antiga ou não correspondem a uma versão. Essas comparações formam a base de suporte condicional a operação. O Dynamics 365 oferece a ETags condicionais recuperações de suporte, à simultaneidade otimista, e as operações de upsert limitadas.

Aviso

Código do cliente não precisa inserir sentido para um valor específico de ETag, nem visível a qualquer relacionamento entre ETags além de igualdade ou desigualdade. Por exemplo, um valor de ETag para uma versão mais recente de um recurso não ser garantido é maior que o valor de ETag para uma versão anterior. Além disso, o algoritmo usado para gerar novos valores de ETag pode ser alterados sem prévio aviso entre versões de um serviço.

Recuperações condicionais

Etags permite otimizar recuperações de registro sempre que você acessa o mesmo registro várias vezes. Se já tiver recuperado um registro, você poderá passar o valor ETag com o cabeçalho If-None-Match para solicitar que dados sejam recuperados apenas se tiverem sido alterados desde a última recuperação. Se os dados tiverem sido alterados, a solicitação retornará o status HTTP (OK) de 200 com os últimos dados no corpo da solicitação. Se os dados não tiverem sido alterados, o código de status HTTP (Not Modified) 304 será retornado para indicar que a entidade não foi modificada. A mensagem de exemplo a seguir devolve dados de uma entidade de conta com o accountid igual a 00000000-0000-0000-0000-000000000001 quando os dados não mudaram desde a última tentativa.

  • Solicitação

    GET cc_WebAPI_ServiceURI/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

Limite de operações de upsert

Um upsert criando uma entidade funciona geralmente se não existe; se não, atualizar uma entidade existente. Entretanto, ETags pode ser usado para restringir ainda mais upserts evitar a criação ou para evitar atualizações.

Evitar a criação no upsert

Se estiver atualizando dados e houver alguma possibilidade de que a entidade tenha sido excluída intencionalmente, você não desejará recriar a entidade. Para evitar isso, adicione um cabeçalho If-Match à solicitação com um valor de “*”.

  • Solicitação

    PATCH cc_WebAPI_ServiceURI/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 a entidade for encontrada, você receberá uma resposta normal com o status 204 (No Content). Se a entidade não for encontrada, você receberá a resposta a seguir com o 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",
  "innererror": {
   "message": "account With Id = 00000000-0000-0000-0000-000000000001 Does Not Exist",
   "type": "System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
   "stacktrace": <stack trace removed for brevity>
  }
 }
}

Evitar a atualização no upsert

Se você estiver inserindo dados, há alguma possibilidade de que um registro com o mesmo valor de id já exista no sistema e você não quer atualizá-lo. Para evitar isso, adicione um cabeçalho If-None-Match à solicitação com um valor de "*".

  • Solicitação

    PATCH cc_WebAPI_ServiceURI/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 a entidade não for encontrada, você receberá uma resposta normal com o status 204 (No Content). Se a entidade for encontrada, você receberá a resposta a seguir com o 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.",
   "innererror":{
    "message":"Cannot insert duplicate key.",
    "type":"System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
    "stacktrace":<stack trace removed for brevity>
    }
  }
}

Aplicar simultaneidade otimista

Você pode usar a simultaneidade otimista para detectar se uma entidade foi alterada desde a última recuperação. Se a entidade que você quer atualizar ou excluir foi alterada no servidor desde que você a recuperou, talvez você não queira concluir a operação de atualização ou de exclusão. Aplicando o padrão mostrado aqui, você pode detectar essa situação, recuperar a versão mais recente da entidade e aplicar os critérios necessários para reavaliar se deve tentar a operação novamente.

Aplicar simultaneidade otimista na exclusão

A solicitação de exclusão a seguir de uma conta com o valor accountid of00000000-0000-0000-0000-000000000001 falha porque o valor ETag enviado com o cabeçalho If-Match é diferente do valor atual. Se o valor foi correspondido, um status 204 (No Content) é esperado.

  • Solicitação

    DELETE cc_WebAPI_ServiceURI/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.",
    "innererror":{
      "message":"The version of the existing record doesn't match the RowVersion property provided.",
      "type":"System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
"stacktrace":"  <stack trace details omitted for brevity>
    }
  }
}

Aplicar simultaneidade otimista na atualização

A solicitação de atualização a seguir de uma conta com o valor accountid falha porque o valor 00000000-0000-0000-0000-000000000001 enviado com o cabeçalho ETag é diferente do valor atual If-Match. Se o valor foi correspondido, um status 204 (No Content) é esperado.

  • Solicitação

    PATCH cc_WebAPI_ServiceURI/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.",
    "innererror":{
      "message":"The version of the existing record doesn't match the RowVersion property provided.",
      "type":"System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
"stacktrace":"  <stack trace details omitted for brevity>
    }
  }
}

Confira Também

Amostra de operações de condição API da Web (C#)
Exemplo de operações condicionais da API Web (JavaScript do lado do cliente)
Executar operações usando A API
Compor solicitações de HTTP e lidar com erros
Consultar dados usando a API da Web
Criar uma entidade usando a API da Web
Recuperar uma entidade usando a API Web
Atualizar e excluir entidades que usam a API Web
Associar e desassociar entidades usando a API Web
Usar funções da API Web
Use ações API da Web
Executar operações em lote usando a API da WEB
Representar outro usuário usando API da Web

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais