Udføre batchhandlinger ved hjælp af Web-API

 

Udgivet: januar 2017

Gælder for: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Du kan gruppere flere handlinger i en enkelt HTTP-anmodning ved hjælp af en batchhandling.

Dette emne indeholder

Hvornår kan jeg bruge batchanmodninger?

Batchanmodninger

Ændre sæt

Eksempel

Hvornår kan jeg bruge batchanmodninger?

Den værdi, som batchanmodninger giver, er, at de kan omfatte ændringssæt, som giver en måde at samle en række operationer, der enten lykkes eller mislykkes som en gruppe, på. Sammenlignet med andre operationer, der kan udføres ved hjælp af web-API'et, er de sværere at sammensætte i en transaktion uden nogle objektmodel, der omfatter serialisering af objekter eller en dybere forståelse af HTTP-protokollen, fordi anmodningsteksten hovedsagelig er et tekstdokument, der skal stemme overens med meget specifikke krav.

Husk, at tilknyttede objekter lettere kan oprettes med en enkelt handling end ved hjælp af en batchanmodning. Batchanmodninger bruges bedst, når du udfører handlinger på objekter, der ikke er knyttet til hinanden, når alle handlingerne skal udføres i en enkelt transaktionshandling.

Desuden er de svar, der returneres, grundlæggende tekstdokumenter frem for objekter, der let kan opdeles i JSON. Du skal opdele teksten i svaret eller finde et Hjælp-bibliotek for at få adgang til dataene i svaret.

Batchanmodninger

Brug en POST-anmodning for at sende en batchhandling, der indeholder flere anmodninger. En batchanmodning kan omfatte GET-anmodninger og ændringssæt. Hvis du vil bruge de transaktionsfunktioner i batch-anmodninger, kan kun de handlinger, der ændrer data, medtages i et ændringssæt.GET-anmodninger skal ikke medtages i ændringssættet.

Den POST-anmodning, der indeholder batchen, skal have en Content-Type-header med en værdi, der er indstillet til multipart/mixed, og med en grænse, der er indstillet til at medtage id'et for det batch, der bruger dette mønster:

--batch_<unique identifier>

Det entydige id behøver ikke at være et GUID, men skal være entydigt. Hvert element i batchen skal indledes med batch-id'et, som skal have en Content-Type- og Content-Transfer-Encoding-header som denne:

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

Batchen skal til sidst indeholde et afslutnings-id som dette:

--batch_WKQS9Yui9r--

Bemærk

Indstillingen odata.continue-on-error understøttes ikke af web-API'en. Eventuelle fejl, der opstår i batchen, stopper behandlingen af resten af batchen.

Ændre sæt

Når flere operationer er indeholdt i et ændringssæt, betragtes alle handlinger som atomiske, hvilket betyder, at hvis en af handlingerne mislykkes, annulleres fuldførte handlinger. Som ved en batchanmodning, skal ændringssæt have en Content-Type-header, hvor værdien er indstillet til multipart/mixed, og med en grænse, der er indstillet til at medtage id'et for det ændringssæt, der bruger dette mønster:

--changeset_<unique identifier>

Det entydige id behøver ikke at være et GUID, men skal være entydigt. Hvert element i ændringssættet skal indledes med ændringssættets id, som skal have en Content-Type- og Content-Transfer-Encoding-header som denne:

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

Ændringssæt kan også omfatte en Content-ID-header med en entydig værdi. Når denne værdi har præfikset $, repræsenterer den en variabel, der indeholder URI'en for ethvert objekt, der er oprettet i den pågældende handling. For eksempel, når du angiver værdien 1, kan du referere til dette objekt ved hjælp af $1 senere i ændringssættet.

Ændringssættet skal til sidst indeholde et afslutnings-id som dette:

--changeset_BBB456--

Eksempel

Følgende eksempel indeholder et batch med det entydige id AAA123 og et ændringssæt med det entydige id BBB456.

I ændringssættet oprettes to opgaver ved hjælp af POST og er knyttet til en eksisterende konto med accountid = 00000000-0000-0000-000000000001.

Endelig er der medtaget en GET-anmodning uden for ændringssættet, som kan returnere alle seks opgaver, der er knyttet til kontoen, herunder de to, der blev oprettet i batchanmodningen.

• Anmodning

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

• Svar

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

Se også

Udføre operationer ved hjælp af web-API
Skrive HTTP-anmodninger og håndtere fejl
Forespørg på data ved hjælp af Web-API'en
Oprette et objekt ved hjælp af Web-API
Hente et objekt ved hjælp af web-API'et
Opdatere og slette objekter ved hjælp af web-API'et
Tilknytte og fjerne tilknytningen af objekter ved hjælp af web-API'et
Bruge Web-API-funktioner
Brug Web API-handlinger
Efterligne en anden bruger ved hjælp af Web-API'en
Udfør betingede operationer ved hjælp af web-API

Microsoft Dynamics 365

© 2017 Microsoft. Alle rettigheder forbeholdes. Ophavsret