Batchbewerkingen uitvoeren met de Web API

 

Gepubliceerd: januari 2017

Is van toepassing op: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

U kunt meerdere bewerkingen in één HTTP-aanvraag groeperen met een batchbewerking.

In dit onderwerp

Wanneer u batchaanvragen dient te gebruiken

Batchaanvragen

Wijzigingsets

Voorbeeld

Wanneer u batchaanvragen dient te gebruiken

De waarde die de batchaanvragen bieden, is dat ze wijzigingsets kunnen bevatten die een manier bieden om een aantal bewerkingen samen te voegen die als groep slagen of mislukken. in een transactie In vergelijking met andere bewerkingen die kunnen worden uitgevoerd met de web-API, zijn deze moeilijker op te stellen zonder een objectmodel dat serialisatie van objecten omvat, of een dieper inzicht in het HTTP-protocol, omdat de aanvraagtekst in feite een tekstdocument is dat moet voldoen aan zeer specifieke vereisten.

Denk eraan dat gekoppelde entiteiten eenvoudiger in één enkele bewerking kunnen worden gemaakt dan met een batchaanvraag. Batchaanvragen zijn het handigst voor het uitvoeren van bewerkingen op entiteiten die niet aan elkaar zijn gekoppeld wanneer alle bewerkingen in één transactiebewerking moeten worden uitgevoerd.

Bovendien zijn de responsen in feite tekstdocumenten in plaats van objecten die gemakkelijk kunnen worden geparseerd in. JSON U moet de tekst in de respons parseren of een helperbibliotheek zoeken om de gegevens in de respons te kunnen gebruiken.

Batchaanvragen

Gebruik een POST-aanvraag om een batchbewerking met meerdere aanvragen uit te voeren. Een batchaanvraag kan GET-aanvragen en wijzigingsets bevatten. Als u de transactiemogelijkheden van batchaanvragen wilt gebruiken, kunnen alleen bewerkingen die gegevens wijzigen, worden opgenomen in een wijzigingset.GET-aanvragen mogen niet in de wijzigingset worden opgenomen.

De POST-aanvraag die de batch bevat, moet een inhoudstypekoptekst bevatten met een waarde die op meerdelig/gemengd is ingesteld met een begrenzing die zo is ingesteld dat deze de id van de batch bevat, waarbij het volgende patroon moet worden gebruikt:

--batch_<unique identifier>

De unieke id hoeft geen GUID te zijn, maar moet wel uniek zijn. Elk item in de batch moet vooraf worden gegaan door de batch-id met een koptekst Content-Transfer-Encoding en een koptekst Content-Type, zoals:

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

Het einde van de batch moet een beëindigingsindicator bevatten, zoals:

--batch_WKQS9Yui9r--

Notitie

De odata.continue-on-error-voorkeur wordt niet ondersteund door Web API. Eventuele fouten die optreden in de batch beëindigen de verwerking van de rest van de batch.

Wijzigingsets

Als meerdere processen in een wijzigingset zijn opgenomen, worden alle bewerkingen als atomaire werkeenheid gezien, wat betekent dat als een van de bewerkingen mislukt, alle voltooide bewerkingen worden teruggedraaid. Net als een batchaanvraag moeten wijzigingsets een inhoudstypekoptekst bevatten met een waarde die op meerdelig/gemengd is ingesteld met een begrenzing die zo is ingesteld dat deze de id van de wijzigingset bevat, waarbij het volgende patroon moet worden gebruikt:

--changeset_<unique identifier>

De unieke id hoeft geen GUID te zijn, maar moet wel uniek zijn. Elk item in de wijzigingset moet vooraf worden gegaan door de wijzigingset-id met een koptekst Content-Transfer-Encoding en een koptekst Content-Type, zoals:

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

Wijzigingsets kunnen ook een koptekst Content-ID met een unieke waarde bevatten. Deze waarde vertegenwoordigt, wanneer deze is voorzien van een voorvoegsel $, een variabele met de Uri voor elke entiteit die in die bewerking is gemaakt. Bijvoorbeeld, als u de waarde 1 instelt, kunt u verderop in uw wijzigingset naar deze entiteit verwijzen met $1.

Het einde van de wijzigingset moet een beëindigingsindicator bevatten, zoals deze:

--changeset_BBB456--

Voorbeeld

Het volgende voorbeeld omvat een batch met een unieke id AAA123 en een wijzigingset met een unieke id BBB456.

In de wijzigingset worden twee taken gemaakt met POST en gekoppeld aan een bestaand account met accountid = 00000000-0000-0000-000000000001.

Ten slotte is een GET-aanvraag opgenomen buiten de wijzigingsset met het doel alle zes de taken te vinden die aan het account zijn gekoppeld, met inbegrip van de twee die in de batchaanvraag zijn gemaakt.

• Aanvraag

  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--
  

• Respons

  --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--
  

Zie ook

Bewerkingen uitvoeren met de web-API
HTTP-aanvragen opstellen en fouten afhandelen
Querygegevens met behulp van de web-API
Een entiteit maken met de web-API
Een entiteit ophalen met de web-API
Entiteiten bijwerken en verwijderen met de Web-API
Entiteiten koppelen en ontkoppelen met de web-API
Web-API-functies gebruiken
Web-API-acties gebruiken
Zich als een andere gebruiker voordoen die de Web API gebruikt
Voorwaardelijke bewerkingen uitvoer met de web-API

Microsoft Dynamics 365

© 2017 Microsoft. Alle rechten voorbehouden. Auteursrecht