Executar operações em lote usando a API da WEB

 

Publicado: janeiro de 2017

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

É possível agrupar várias operações em uma única solicitação HTTP usando uma operação em lote.

Neste tópico

Quando usar solicitações em lote

Solicitações em lote

Conjuntos de alterações

Exemplo

Quando usar solicitações em lote

O valor que as solicitações em lote fornecem é que elas podem incluir conjuntos de alterações que fornecem uma maneira de agrupar um número de operações que têm êxito ou falha como um grupo. Em uma transação, em comparação com outras operações que podem ser executadas usando a API Web, elas são mais difíceis de compor sem um modelo de objeto que inclua a serialização de objetos ou uma compreensão mais profunda do protocolo HTTP porque o corpo da solicitação é essencialmente um documento de texto que deve corresponder a muitos requisitos específicos.

Lembre-se de que entidades associadas podem ser criadas em uma única operação mais facilmente do que usando uma solicitação em lote. Solicitações em lote são melhor usadas na realização de operações em entidades que não estão associadas umas às outras quando todas as operações devem ser feitas em uma única operação transacional.

Além disso, as respostas retornadas são basicamente documentos de texto em vez de objetos que podem ser facilmente analisados no JSON. Você precisará analisar o texto na resposta ou localizar uma biblioteca auxiliar para acessar os dados na resposta.

Solicitações em lote

Use uma solicitação POST para enviar uma operação em lote que contém várias solicitações. Uma solicitação em lote pode incluir solicitações GET e conjuntos de alterações. Para usar as funcionalidades transacionais de solicitações em lote, apenas operações que alteram dados podem ser incluídas em um conjunto de alterações. As solicitações GET devem ser incluídas no conjunto de alterações.

A solicitação POST contendo o lote deve ter um cabeçalho de tipo de conteúdo com um valor definido como várias partes/combinado com um limite definido para incluir o identificador do lote usando o padrão:

--batch_<unique identifier>

O identificador exclusivo não precisa ser um GUID, mas deve ser exclusivo. Cada item no lote deve ser precedido pelo identificador do lote com um cabeçalho de Content-Type e Content-Transfer-Encoding como o seguinte:

--batch_WKQS9Yui9r
Content-Type: application/http
Content-Transfer-Encoding:binary

O final do lote deve conter um indicador de término como o seguinte:

--batch_WKQS9Yui9r--

Observação

A preferência odata.continue-on-error não é compatível com a API da WEB. Qualquer erro ocorrido no lote interromperá o processamento do restante do lote.

Conjuntos de alterações

Quando várias operações são contidas em um conjunto de alterações, todas as operações são consideradas atômicas, o que significa que, se qualquer uma das operações falhar, todas as operações concluídas serão revertidas. Como uma solicitação em lote, conjuntos de alterações devem ter um cabeçalho de tipo de conteúdo com um valor definido como várias partes/combinado com um limite definido para incluir o identificador do lote usando o padrão:

--changeset_<unique identifier>

O identificador exclusivo não precisa ser um GUID, mas deve ser exclusivo. Cada item no conjunto de alterações deve ser precedido pelo identificador do conjunto de alterações com um cabeçalho de Content-Type e Content-Transfer-Encoding como o seguinte:

--changeset_BBB456
Content-Type: application/http
Content-Transfer-Encoding:binary

Conjuntos de alterações também podem incluir um cabeçalho de Content-ID com um valor exclusivo. Esse valor, quando prefixado com $, representa uma variável que contém o URI de qualquer entidade criada nessa operação. Por exemplo, ao definir o valor de 1, você pode se referir a essa entidade usando $1 posteriormente no conjunto de alterações.

O final do conjunto de alterações deve conter um indicador de término como o seguinte:

--changeset_BBB456--

Exemplo

O seguinte exemplo inclui um lote com um identificador exclusivo de AAA123 e um conjunto de alterações com um identificador exclusivo de BBB456.

No conjunto de alterações, duas tarefas são criadas usando POST e associadas a um conjunto existente com accountid = 00000000-0000-0000-000000000001.

Por fim, uma solicitação GET é incluída fora do conjunto de alterações para retornar todas as seis tarefas associadas à conta incluindo as duas que foram criadas na solicitação em lote.

• Solicitação

  POST cc_WebAPI_ServiceURI/$batch HTTP/1.1
  Content-Type: multipart/mixed;boundary=batch_AAA123
  Accept: application/json
  OData-MaxVersion: 4.0
  OData-Version: 4.0
  
  --batch_AAA123
  Content-Type: multipart/mixed;boundary=changeset_BBB456
  
  --changeset_BBB456
  Content-Type: application/http
  Content-Transfer-Encoding:binary
  Content-ID: 1
  
  POST cc_WebAPI_ServiceURI/tasks HTTP/1.1
  Content-Type: application/json;type=entry
  
  {"subject":"Task 1 in batch","regardingobjectid_account_task@odata.bind":"cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-000000000001)"}
  --changeset_BBB456
  Content-Type: application/http
  Content-Transfer-Encoding:binary
  Content-ID: 2
  
  POST cc_WebAPI_ServiceURI/tasks HTTP/1.1
  Content-Type: application/json;type=entry
  
  {"subject":"Task 2 in batch","regardingobjectid_account_task@odata.bind":"cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-000000000001)"}
  --changeset_BBB456--
  
  --batch_AAA123
  Content-Type: application/http
  Content-Transfer-Encoding:binary
  
  GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-000000000001)/Account_Tasks?$select=subject HTTP/1.1
  Accept: application/json
  
  --batch_AAA123--
  

• Resposta

  --batchresponse_c1bd45c1-dd81-470d-b897-e965846aad2f
  Content-Type: multipart/mixed; boundary=changesetresponse_ff83b4f1-ab48-430c-b81c-926a2c596abc
  
  --changesetresponse_ff83b4f1-ab48-430c-b81c-926a2c596abc
  Content-Type: application/http
  Content-Transfer-Encoding: binary
  Content-ID: 1
  
  HTTP/1.1 204 No Content
  OData-Version: 4.0
  Location: cc_WebAPI_ServiceURI/tasks(a59c24f3-fafc-e411-80dd-00155d2a68cb)
  OData-EntityId: cc_WebAPI_ServiceURI/tasks(a59c24f3-fafc-e411-80dd-00155d2a68cb)
  
  
  --changesetresponse_ff83b4f1-ab48-430c-b81c-926a2c596abc
  Content-Type: application/http
  Content-Transfer-Encoding: binary
  Content-ID: 2
  
  HTTP/1.1 204 No Content
  OData-Version: 4.0
  Location: cc_WebAPI_ServiceURI/tasks(a69c24f3-fafc-e411-80dd-00155d2a68cb)
  OData-EntityId: cc_WebAPI_ServiceURI/tasks(a69c24f3-fafc-e411-80dd-00155d2a68cb)
  
  
  --changesetresponse_ff83b4f1-ab48-430c-b81c-926a2c596abc--
  --batchresponse_c1bd45c1-dd81-470d-b897-e965846aad2f
  Content-Type: application/http
  Content-Transfer-Encoding: binary
  
  HTTP/1.1 200 OK
  Content-Type: application/json; odata.metadata=minimal
  OData-Version: 4.0
  
  {
    "@odata.context":"cc_WebAPI_ServiceURI/$metadata#tasks(subject)","value":[
      {
        "@odata.etag":"W/\"474122\"","subject":"Task Created with Test Account","activityid":"919c24f3-fafc-e411-80dd-00155d2a68cb"
      },{
        "@odata.etag":"W/\"474125\"","subject":"Task 1","activityid":"a29c24f3-fafc-e411-80dd-00155d2a68cb"
      },{
        "@odata.etag":"W/\"474128\"","subject":"Task 2","activityid":"a39c24f3-fafc-e411-80dd-00155d2a68cb"
      },{
        "@odata.etag":"W/\"474131\"","subject":"Task 3","activityid":"a49c24f3-fafc-e411-80dd-00155d2a68cb"
      },{
        "@odata.etag":"W/\"474134\"","subject":"Task 1 in batch","activityid":"a59c24f3-fafc-e411-80dd-00155d2a68cb"
      },{
        "@odata.etag":"W/\"474137\"","subject":"Task 2 in batch","activityid":"a69c24f3-fafc-e411-80dd-00155d2a68cb"
      }
    ]
  }
  --batchresponse_c1bd45c1-dd81-470d-b897-e965846aad2f--
  

Confira Também

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
Representar outro usuário usando API da Web
Executar operações condicionais usando A API

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais