Ausführen von Batchbetrieben mithilfe der Web-API

 

Veröffentlicht: Januar 2017

Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Sie können mehrere Vorgänge in einer einzelnen HTTP-Anforderung gruppieren mithilfe des Batchvorgangs.

In diesem Thema

Verwenden der Batchanforderungen

Batchanforderungen

Änderungssätze

Beispiel

Verwenden der Batchanforderungen

Der Wert, den Stapelverarbeitungsanfragen bieten, ist, dass sie Änderungssätze umfassen können, die eine Weise liefern, einige Operationen zusammenzufassen, die als Gruppe entweder erfolgreich durchgeführt werden oder scheitern. in einer Buchung Verglichen mit anderen Operationen, die unter Verwendung der Web-API durchgeführt werden können, sind sie schwieriger zu verfassen ohne irgendein Objektmodell, das Serialisierung von Objekten oder ein tieferes Verständnis des HTTP-Protokolls umfasst, weil der Anfragekörper im Wesentlichen ein Textdokument ist, das sehr spezifische Anforderungen erfüllen muss.

Beachten Sie, dass zugeordnete Entitäten leichter in einem einzelnen Vorgang erstellt werden können als in einer Batchanforderung. Batchanforderungen werden am besten verwendet, wenn Sie Vorgänge an Entitäten ausführen, die nicht die einander zugeordnet sind, wenn alle Vorgänge in einem einzigen Transaktionsvorgang ausgeführt werden müssen.

Auch die zurückgegebenen Antworten sind im Wesentlichen Textdateien und nicht Objekte, die in JSON einfach analysiert werden können. Sie müssen den Text in der Antwort analsieren oder eine Hilfsbibliothek finden, um auf Daten in der Antwort zuzugreifen.

Batchanforderungen

Nutzen Sie eine POST-Anfrage, um eine Batch-Operation zu senden, die mehrere Anforderungen enthält. Eine Batchanforderung kann GET-Anforderungen und Änderungsätze enthalten. Um die Transaktionsfunktionen von Anforderungen für Stapelverarbeitung verwenden zu können, dürfen nur Vorgänge die Daten ändern in einem Changesets berücksichtigt werden.GET-Anfragen dürfen nicht im Änderungssatz eingeschlossen sein.

Die POST Batchanforderung müssen eine Inhaltstyp-Kopfzeile mit einem Wert besitzen, der auf mehrteilig/gemischt festgelegt ist, mit einer Grenze, die so eingerichtet ist, dass sie den Bezeichner des Änderungssets mithilfe dieses Musters einbezieht:

--batch_<unique identifier>

Die eindeutige Kennung muss kein GUID sein, aber einzigartig. Jedem Element im Batch muss der Batchbezeichner vorausgehen mit einer Content-Type werden mit einem Wert in Content-Transfer-Encoding-Kopfzeile wie der Folgenden:

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

Das Batchende muss einen Indikator für das Beenden wie den folgenden enthalten:

--batch_WKQS9Yui9r--

Hinweis

Die odata.continue-on-error Einstellung wird von der über das Internet zugreifende API nicht unterstützt. Jeder Fehler, der im Batch auftritt, beendet die Verarbeitung des restlichen Batches.

Änderungssätze

Wenn mehrere Vorgänge in einem Changeset enthalten sind, gelten alle Vorgänge gelten als unteilbar. Das bedeutet, dass bei einem Fehlerschlag einer der folgenden Vorgänge alle abgeschlossenen Vorgänge rückgängig gemacht werden. Wie eine Batchanforderung müssen Änderungssets eine Inhaltstyp-Kopfzeile mit einem Wert besitzen, der auf mehrteilig/gemischt festgelegt ist, mit einer Grenze, die so eingerichtet ist, dass sie den Bezeichner des Änderungssets mithilfe dieses Musters einbezieht:

--changeset_<unique identifier>

Die eindeutige Kennung muss kein GUID sein, aber einzigartig. Jedem Element im Änderungssatz muss der Änderungssatzbezeichner vorausgehen mit einer Content-Type werden mit einem Wert in Content-Transfer-Encoding-Kopfzeile wie der Folgenden:

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

Änderungssätze können eine auch eine Content-ID-Kopfzeile mit einem eindeutigen Wert enthalten. Wenn diesem Wert $ vorangestellt wird, stellt er eine Variable dar, die eine URI für eine beliebige Entität in diesem Vorgang erhält. Wenn Sie z. B. den Wert auf 1 festlegen, können Sie über $1 später auf diese Entität zurückgreifen.

Das Ende des Änderungssatzes muss einen Indikator für das Beenden wie den folgenden enthalten:

--changeset_BBB456--

Beispiel

Das folgende Beispiel enthält einen Batch mit einem eindeutigen Bezeichner von AAA123 und einen Änderungssatz mit einem eindeutigen Bezeichner von BBB456.

Innerhalb des Änderungssatzes werden zwei Aufgaben mithilfe von POST erstellt und einem vorhandenen Konto mit accountid = 00000000-0000-0000-000000000001 zugeordnet.

Und schließlich ist eine GET-Anforderung außerhalb des Änderungssatzes enthalten, um alle sechs Aufgaben zu diesem Konto wiederzugeben, einschließlich der beiden, die in der Batchanforderung erstellt wurden.

• Anforderung

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

• Antwort

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

Siehe auch

Vorgänge mithilfe der Web-API ausführen
HTTP-Anforderungen verfassen und Fehler beheben
Datenabfrage mit Web-API
Erstellen einer Entität mithilfe des Web-API
Abrufen einer Entität mithilfe des Web-API
Entitäten aktualisieren und löschen mithilfe der Web API
Entitäten zuordnen und Zuordnungen aufheben mithilfe der Web API
Nutzen von Web-API-Funktionen
Nutzen von Web-API-Aktionen
Annehmen eines anderen Benutzerkontos mit Web API
Bedingte Vorgänge mithilfe der Web-API ausführen

Microsoft Dynamics 365

© 2017 Microsoft. Alle Rechte vorbehalten. Copyright