Créer des requêtes de lots avec l’API REST
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 des instances locales de SharePoint 2016 et versions ultérieures) et les API d’Office 365 utilisent l’option de requête $batch OData, et vous pouvez consulter la documentation officielle pour savoir comment l’utiliser. (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.
- Un composant 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 fonctions). 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.
Important
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 comportent plusieurs opérations. Si l’une des opérations enfants échoue, les autres sont toujours terminées et ne sont pas restaurées.
Exemples de code
Exemples de code qui utilisent l’option de requête $batch sur les API REST/OData SharePoint :
- C# : OfficeDev/Core.ODataBatch
- JavaScript : andrewconnell/sp-o365-rest
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.