Créer des requêtes de lots avec l’API REST

  • Article

Cet article explique comment regrouper des requêtes et des opérations dans l’API REST/OData de Microsoft SharePoint Online (et des instances locales de SharePoint 2016 et versions ultérieures) et le sous-ensemble dédié aux fichiers et dossiers de l’API REST d’Office 365. Cette technique vous permet d’améliorer les performances de votre complément en combinant plusieurs opérations dans une seule requête au serveur et en obtenant une seule réponse.

Récapitulatif sur l’option $batch

SharePoint Online (et SharePoint local 2016 et versions ultérieures) et les API Office 365 implémentent l’option de requête OData$batch. Vous pouvez donc vous appuyer sur la documentation officielle pour plus d’informations sur son utilisation. (vous pouvez aussi consulter les billets de blog d’Andrew Connell sur le sujet, en commençant par la partie 1, relative au regroupement par lots pour les API REST SharePoint).

Cet article est un rappel des points principaux :

  • L’URL de requête se compose de l’URL du service racine et de l’option $batch ; par exemple, https://fabrikam.sharepoint.com/_api/$batch ou https://fabrikam.office365.com/api/v1.0/me/$batch.
  • Le corps de la requête HTTP est de type MIME mixte/multipartie.
  • Le corps de la requête est divisé en plusieurs parties, séparées par une chaîne de limitation spécifiée dans l’en-tête de la requête.
  • Chaque partie possède son propre verbe HTTP, sa propre URL REST et son propre corps interne, le cas échéant.
  • Une partie peut être une opération de lecture (ou un appel de fonction), ou un ensemble de modifications d’une ou plusieurs opérations d’écriture (ou appels de fonction). Un ensemble de modifications est lui-même un type MIME multipart/mixed avec des sous-parties contenant des opérations d’insertion, de mise à jour ou de suppression.

Importante

Les API SharePoint et Office 365 ne sont pas transactionnelles et ne prennent pas en charge la fonctionnalité « tout ou rien » pour les ensembles de modifications qui contiennent plusieurs opérations. Si l’une des opérations enfant échoue, les autres sont quand même exécutées et ne sont pas annulées.

Exemples de code

Exemples de code qui utilisent l’option de requête $batch sur les API REST/OData SharePoint :

Exemples de requêtes et de réponses

Voici un exemple de requête HTTP brute effectuant un traitement par lots de deux opérations GET qui extraient les titres de tous les éléments de deux listes différentes.

POST https://fabrikam.sharepoint.com/_api/$batch HTTP/1.1
Authorization: Bearer <access token omitted>
Content-Type: multipart/mixed; boundary=batch_e3b6819b-13c3-43bb-85b2-24b14122fed1
Host: fabrikam.sharepoint.com
Content-Length: 527
Expect: 100-continue

--batch_e3b6819b-13c3-43bb-85b2-24b14122fed1
Content-Type: application/http
Content-Transfer-Encoding: binary

GET https://fabrikam.sharepoint.com/_api/Web/lists/getbytitle('Composed%20Looks')/items?$select=Title HTTP/1.1

--batch_e3b6819b-13c3-43bb-85b2-24b14122fed1
Content-Type: application/http
Content-Transfer-Encoding: binary

GET https://fabrikam.sharepoint.com/_api/Web/lists/getbytitle('User%20Information%20List')/items?$select=Title HTTP/1.1

--batch_e3b6819b-13c3-43bb-85b2-24b14122fed1--

Voici un exemple de corps d’une demande HTTP brute qui effectue le traitement par lots d’une opération DELETE sur une liste et d’une opération GET sur la liste des listes SharePoint.

POST https://fabrikam.sharepoint.com/_api/$batch HTTP/1.1
Authorization: Bearer <access token omitted>
Content-Type: multipart/mixed; boundary=batch_7ba8d60b-efce-4a2f-b719-60c27cc0e70e
Host: fabrikam.sharepoint.com
Content-Length: 647
Expect: 100-continue

--batch_7ba8d60b-efce-4a2f-b719-60c27cc0e70e
Content-Type: multipart/mixed; boundary=changeset_efb6b37c-a5cd-45cb-8f5f-4d648006e65d

--changeset_efb6b37c-a5cd-45cb-8f5f-4d648006e65d
Content-Type: application/http
Content-Transfer-Encoding: binary

DELETE https://fabrikam.sharepoint.com/_api/Web/lists/getbytitle('OldList') HTTP/1.1
If-Match: "1"

--changeset_efb6b37c-a5cd-45cb-8f5f-4d648006e65d--
--batch_7ba8d60b-efce-4a2f-b719-60c27cc0e70e
Content-Type: application/http
Content-Transfer-Encoding: binary

GET https://fabrikam.sharepoint.com/_api/Web/lists HTTP/1.1

--batch_7ba8d60b-efce-4a2f-b719-60c27cc0e70e--

Attention

Les demandes par lots peuvent réduire le nombre de demandes aller-retour à l’API REST SharePoint. Toutefois, le chargement de plusieurs fichiers dans un lot unique n’est pas pris en charge.

Bibliothèques OData

Des bibliothèques OData prennent en charge le regroupement OData pour de nombreux langages. Voici deux exemples. Pour une liste plus complète, voir Bibliothèques OData.

Voir aussi