Exécuter des opérations par lots à l'aide de l'API Web

Article
10/31/2017

Date de publication : janvier 2017

S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Vous pouvez regrouper plusieurs opérations en une seule demande HTTP à l'aide d'une opération par lots.

Contenu de la rubrique

Quand utiliser les demandes par lots ?

Demandes traitées par lots

Ensembles de modifications

Exemple

Quand utiliser les demandes par lots ?

Les demandes par lots peuvent inclure des ensembles de modifications, qui sont un moyen de regrouper un certain nombre d'opérations qui réussissent ou échouent en tant que groupe. dans une transaction Par rapport à d'autres opérations qui peuvent être effectuées à l'aide de l'API Web, elles sont plus difficiles à composer sans certains modèles d'objet qui incluent la sérialisation des objets ou une meilleure compréhension du protocole HTTP car le corps de requête est essentiellement un document texte qui doit répondre à des exigences très spécifiques.

N'oubliez pas que les entités associées peuvent être créées dans une opération unique plus facilement que l'utilisation d'une demande par lots. Les demandes par lots sont mieux utilisées en effectuant des opérations sur les entités qui ne sont pas associées entre elles lorsque les opérations doivent être effectuées dans une opération transactionnelle unique.

En outre, les réponses renvoyées sont essentiellement des documents texte et non des objets pouvant être facilement analysés au format JSON. Vous devez analyser le texte dans la réponse ou rechercher une bibliothèque d'assistance pour accéder aux données de la réponse.

Demandes traitées par lots

Utilisez une demande POST pour envoyer une opération par lots contenant plusieurs requêtes. Une demande par lots peut inclure des demandes et des ensembles de modifications GET. Pour utiliser les fonctionnalités transactionnelles des demandes par lots, seules les opérations qui modifient les données peuvent être incluses dans un ensemble de modifications. Les requêtes GET ne doivent pas être incluses dans l'ensemble de modifications.

La demande POST contenant le lot doit avoir un en-tête Content-Type avec une valeur définie sur multipart/mixed avec une limite définie pour contenir l'identificateur du lot à l'aide de ce modèle :

--batch_<unique identifier>

L'identificateur unique n'a pas nécessairement besoin d'être un GUID, mais doit être unique. Chaque élément du lot doit être précédé de l'identificateur du lot avec un en-tête Content-Type et Content-Transfer-Encoding comme suit :

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

L'arrêt du lot doit contenir un indicateur de fin comme suit :

--batch_WKQS9Yui9r--

Notes

Les préférences odata.continue-on-error ne sont pas prises en charge par l'API Web. Toute erreur qui se produit dans le lot arrête le traitement du reste du lot.

Ensembles de modifications

Lorsque plusieurs opérations sont contenues dans un ensemble de modifications, toutes les opérations sont considérées atomiques, ce qui signifie que si l'une des opérations échoue, toutes les opérations terminées seront annulées. Comme pour une demande par lots, les ensembles de modifications doivent avoir un en-tête Content-Type avec une valeur définie sur multipart/mixed avec une limite définie pour contenir l'identificateur du lot à l'aide de ce modèle :

--changeset_<unique identifier>

L'identificateur unique n'a pas nécessairement besoin d'être un GUID, mais doit être unique. Chaque élément de l'ensemble de modifications doit être précédé de l'identificateur de l'ensemble de modifications avec un en-tête Content-Type et Content-Transfer-Encoding comme suit :

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

Des ensembles de modifications peuvent également inclure un en-tête Content-ID avec une valeur unique. Cette valeur, une fois mise en préfixe avec $, représente une variable contenant l'URI pour toute entité créée au cours de cette opération. Par exemple, lorsque vous définissez la valeur 1, vous pouvez faire référence à cette entité avec $1 ultérieurement dans votre ensemble de modifications.

L'arrêt de l'ensemble de modifications doit contenir un indicateur de fin comme suit :

--changeset_BBB456--

Exemple

L'exemple ci-dessous inclut un lot avec un identificateur unique de AAA123 et un ensemble de modifications défini avec un identificateur unique de BBB456.

Dans l'ensemble de modifications, deux tâches sont créées à l'aide de POST et associées à un compte existant avec accountid = 00000000-0000-0000-000000000001.

Enfin, une demande GET est incluse en dehors de l'ensemble de modifications pour retourner les six tâches liées au compte, notamment les deux créées dans la demande par lots.

Demande

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

Réponse

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

Voir aussi

Microsoft Dynamics 365

Exécuter des opérations par lots à l'aide de l'API Web

Contenu de la rubrique

Quand utiliser les demandes par lots ?

Demandes traitées par lots

Ensembles de modifications

Exemple

Voir aussi

Ressources supplémentaires