Envoyer des requêtes REST Outlook par lots (version 2.0)

  • Article

S’applique à : Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Le traitement par lots vous permet de placer plusieurs requêtes REST Outlook dans une seule requête HTTP groupée, ce qui réduit le nombre de connexions HTTP et la charge. Les demandes dans un lot accèdent aux données de l’utilisateur connecté, sécurisées par Azure Active Directory dans Office 365 ou dans un compte Microsoft (Hotmail.com, Live.com, MSN.com, Outlook.com ou Passport.com).

Notes

Afin de simplifier les explications, le reste de l’article utilise Outlook.com pour inclure ces domaines de comptes Microsoft.

La version 2.0 de l’API ne vous intéresse pas ? Dans la table des matières sur la gauche, accédez à la section Référence API REST Office 365 et sélectionnez la version souhaitée.

Vue d’ensemble

Une demande REST nécessite une connexion HTTP entre le client et le serveur, ce qui entraîne une certaine charge. Le traitement par lots vous permet de réduire la charge de connexion en combinant plusieurs appels d’API REST pour le même contexte en une seule demande HTTP POST vers le point de terminaison $batch.

Par exemple, vous pouvez combiner des appels d’API pour le contexte me de cette façon :

POST https://outlook.office.com/api/v2.0/me/$batch

Une requête par lots peut inclure jusqu’à 20 appels d’API REST individuels, qui peuvent être des requêtes de données (par exemple GET) ou des opérations de modifications (par exemple, POST). Vous pouvez spécifier un en-tête Prefer pour que le traitement du lot continue même si un ou plusieurs appels REST échouent.

Le traitement par lots est particulièrement utile pour synchroniser de grandes quantités de données. Les appels d’API dans le même lot peuvent accéder à différentes ressources, telles que des messages et des événements, appartenant à la même boîte aux lettres.

Si vous devez effectuer plus de 20 appels ou si l’ordre d’exécution des appels est important, utilisez plusieurs demandes par lots.

Exemple

Un exemple simple illustre mieux le traitement par lots. La requête par lots suivante place deux appels d’API Outlook REST dans un seul lot pour le contexte me :

  1. GET (Obtenir) tous les événements de l’utilisateur connecté
  2. POST (Publier) et envoyez un message.

Requête par lot

POST https://outlook.office.com/api/v2.0/me/$batch HTTP/1.1

Authorization: Bearer aGFwcHlnQGRr==
Host: outlook.office.com
Content-Type: multipart/mixed; boundary=batch_myBatchId


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

GET /api/v2.0/me/events?$select=subject,organizer HTTP/1.1

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

POST /api/v2.0/me/sendmail HTTP/1.1
Content-Type: application/json

{
  "Message": {
    "Subject": "Meet for lunch?",
    "Body": {
      "ContentType": "Text",
      "Content": "The new cafeteria is open."
    },
    "ToRecipients": [
      {
        "EmailAddress": {
          "Address": "rufus@contoso.com"
        }
      }
    ]
  }
}
 
--batch_myBatchId--

Notes

Dans l’exemple précédent, qui montre une opération POST à ​​la fin du lot, une nouvelle ligne est actuellement nécessaire après le tout dernier délimiteur de lot --batch_{batchId}--. Voir plus de notes de mise en forme pour les corps des requêtes par lots.

Réponse par lot

La réponse par lot inclut des codes et des corps de réponse séparés, lorsque c’est possible, pour la requête par lot et les appels individuels.

HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a
Content-Length: 786

--batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 200 OK
OData-Version: 4.0
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8

{
    "@odata.context":"https://outlook.office.com/api/v2.0/$metadata#Me/Events(Subject,Organizer)",
    "value":[
        {
            "@odata.id":"https://outlook.office.com/api/v2.0/Users('cd209b0b-3f83-4c35-82d2-d88a61820480@8b5d41d8-b1af-495e-b871-8bbd867ba67a')/Events('AAMkAGI1AAAt9AHkAAA=')",
            "@odata.etag":"W/\"ZlnW4RIAV06KYYwlrfNZvQAALfZeSA==\"",
            "Id":"AAMkAGI1AAAt9AHkAAA=",
            "Subject":"Let's go for lunch",
            "Organizer":{
                "EmailAddress":{
                    "Name":"Dana Swope",
                    "Address":"danas@contoso.onmicrosoft.com"
                }
            }
        },
        {
            "@odata.id":"https://outlook.office.com/api/v2.0/Users('cd209b0b-3f83-4c35-82d2-d88a61820480@8b5d41d8-b1af-495e-b871-8bbd867ba67a')/Events('AAMkAGI1AAAtCq6LAAA=')",
            "@odata.etag":"W/\"ZlnW4RIAV06KYYwlrfNZvQAALQzodA==\"",
            "Id":"AAMkAGI1AAAtCq6LAAA=",
            "Subject":"Prep for customer visit",
            "Organizer":{
                "EmailAddress":{
                    "Name":"Dana Swope",
                    "Address":"danas@contoso.onmicrosoft.com"
                }
            }
        }
    ]
}
--batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 202 Accepted

--batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a--

URL du point de terminaison

Vous pouvez effectuer un POST sur le point de terminaison $batch pour l’un des deux contextes suivants :

  • Pour l’utilisateur connecté me :

    POST https://outlook.office.com/api/v2.0/me/$batch HTTP/1.1

  • Pour un utilisateur spécifique, où user_id peut être un ID d’utilisateur ou une adresse e-mail d’utilisateur :

    POST https://outlook.office.com/api/v2.0/users('{user_id}')/$batch

Une fois que vous avez défini le contexte dans la demande POST vers le point de terminaison $batch, tous les appels d’API REST inclus dans la même demande par lot doivent s’appliquer au même contexte.

Important

  • Si votre demande par lot concerne un utilisateur spécifique, assurez-vous de référencer l’utilisateur de manière cohérente tout au long du jeu des demandes groupées. C’est-à-dire, utilisez seulement .../users('{user_id}') ou .../users/'{user_id}' mais pas les deux.
  • Pour des performances optimales, lors de l’utilisation de l’URL racine https://outlook.office.com, ajoutez un en-tête x-AnchorMailbox avec l’adresse e-mail de l'utilisateur.
  • Gérez également le cas où la boîte aux lettres d’un utilisateur Outlook.com n’a pas encore été activée pour l’API REST d’Outlook. Recherchez les codes d’erreur MailboxNotEnabledForRESTAPI et MailboxNotSupportedForRESTAPI. Plus d’information ici.

Notes

Remarques pour les développeurs en Chine

Version de l’API

Le traitement par lots a été promu de préversion au statut de disponibilité générale (GA). Elle est prise en charge dans les versions v2.0 et bêta de l’API REST d’Outlook.

Vous devez spécifier le même hôte et la même version dans la demande par lots que dans les appels REST du lot.

Utilisateur cible

Vous pouvez regrouper les appels d’API REST d’Outlook pour la même boîte aux lettres dans un lot. La boîte aux lettres peut être sur Office 365 ou sur Outlook.com. Tenter d’accéder à plusieurs boîtes aux lettres dans un jeu de demandes par lots provoque une exception.

Authentification

De la même façon que pour les appels à l’API REST d’Outlook par demandes individuelles, vous devez inclure un jeton d’accès valide dans un en-tête de demande Autorisation. Si vous spécifiez cet en-tête pour la demande par lots, le jeton d’accès doit fournir l’autorisation nécessaire pour tous les appels de ce lot. Vous pouvez éventuellement spécifier un jeton d’accès pour un appel spécifique dans le lot si cet appel nécessite un jeton d’accès différent.

Pour obtenir un jeton d’accès, vous devez avoir inscrit et identifié votre application et obtenu l’autorisation appropriée. Vous pouvez en apprendre plus sur un certain nombre d’options simplifiées pour l’autorisation et l’inscription. Gardez cela à l’esprit durant votre apprentissage sur les demandes de traitement par lots.

En-têtes de demandes par lots

Incluez les en-têtes suivants pour chaque demande par lots :

Host: outlook.office.com
Content-Type: multipart/mixed; boundary=batch_<batchId>

où {batchId} identifie un lot et sert à délimiter les demandes dans le lot. Ce peut être un GUID ou n’importe quelle chaîne distinctive.

Vous pouvez inclure d’autres en-têtes, le cas échéant. Sauf pour les en-têtes liés au contenu tels que Content-Type, les en-têtes de la demande par lots s’appliquent généralement à toutes les opérations du lot. Si vous spécifiez un en-tête aussi bien dans la requête par lots que dans une opération spécifique du lot, ce dernier a la priorité et s’applique à cette opération.

Corps de la demande par lots

Commencez chaque opération d’un lot avec les lignes d'en-tête suivantes :

--batch_{batchId} 
Content-Type: application/http 
Content-Transfer-Encoding: binary

Terminez la dernière opération dans le lot avec ceci :

--batch_{batchId}--

Formatage d’un corps de requête par lots

Notez les exigences de mise en forme suivantes, sinon votre requête par lots peut échouer ou ne pas renvoyer les réponses attendues :

  • Veillez à ajouter une nouvelle ligne avant un délimiteur de lot, comme indiqué dans le corps de demande suivant contient 2 opérations GET groupées.
  • En particulier, si vous avez une demande POST à ​​la fin d’un lot similaire au premier exemple de demande de lot, assurez-vous d’ajouter une nouvelle ligne après le tout dernier délimiteur de lot --batch_{batchId}--.

Vous pouvez consulter plus d’exemples de corps de requête par lots dans Traitement par lots (OData version 3.0).


--batch_{batchId} 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

GET  /api/v2.0/me/messages    HTTP/1.1

--batch_{batchId} 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

GET  /api/v2.0/me/events    HTTP/1.1

--batch_{batchId}--

Opérations dans un lot

Vous pouvez spécifier jusqu’à 20 opérations dans une demande par lots.

Une opération d’un lot peut être une requête de données, une modification, une action ou une demande d’appel de fonction. Bien qu’il ne soit pas demandé de répéter les URL complètes et d’indiquer tous les en-têtes pour chaque opération du lot, assurez-vous d’inclure des en-têtes et un corps de demande spécifiques s’ils sont nécessaires pour une opération.

Formats pris en charge des demandes dans un lot

Comme mentionné ci-dessus, l’hôte, la version et le contexte doivent rester cohérents tout au long d’un jeu de demandes groupées. Les demandes incluses dans le même lot peuvent être un mélange de l’un des trois formats suivants. Pour les exemples ci-dessous, supposons que la requête POST vers le point de terminaison $batch ressemble à ceci :

POST https://outlook.office.com/api/v2.0/me/$batch HTTP/1.1

URL absolue

Inclure l’hôte, la version et le contexte dans l’URL. Par exemple :

GET https://outlook.office.com/api/v2.0/me/messages?$select=subject,sender HTTP/1.1

URL relative à l’hôte

Inclure une URL relative à l’hôte spécifié dans la demande de traitement par lots. Bien que vous ne répétiez pas l’hôte dans chaque requête par lot, incluez la version et le contexte. Par exemple :

GET /api/v2.0/me/messages?$select=subject,sender HTTP/1.1

URL relative au lot

Dans ce format, vous ne répétez pas l’hôte, la version et le contexte dans la demande par lot. Par exemple :

GET messages?$select=subject,sender HTTP/1.1

Traitement d’une demande par lots

Une demande par lots est traitée comme une seule requête et renvoie son propre code de réponse. Une demande par lots bien formée avec des en-têtes corrects renvoie HTTP 200 OK. Toutefois, cela ne signifie pas que toutes les demandes du lot ont réussi.

Chaque demande du corps de la demande par lots est à son tour traitée séparément et renvoie son propre code de réponse, corps de réponse et message d’erreur.

Le serveur peut effectuer des opérations dans un lot dans n’importe quel ordre. Si vous devez effectuer des opérations dans un ordre spécifique, vous ne devez pas les placer dans la même demande de traitement par lots. Au lieu de cela, envoyez les opérations une à une en attendant la réponse entre chaque.

Par défaut, le traitement s’arrête sur la première opération qui renvoie une erreur. Vous pouvez spécifier l’en-tête suivant pour que le traitement ignore l’erreur et continue avec l’opération suivante dans le lot :

Prefer: odata.continue-on-error

Étapes suivantes

Que vous soyez prêt à commencer à créer une application ou que vous souhaitiez simplement en apprendre plus, nous avons ce qu’il vous faut.

Ou, pour en savoir plus sur l’utilisation de la plateforme Office 365 :