Traitement par lots | Concepts de l’API Graph

Article
10/21/2021

S’applique à : API Graph | Azure Active Directory (AD)

L’API Azure AD Graph vous permet de traiter des opérations par lots sur des entités afin de réduire les boucles de serveur. Le traitement par lots réduisant la charge pesant sur le réseau, vos opérations sont accomplies plus rapidement.

Important

Nous vous recommandons fortement d’utiliser Microsoft Graph plutôt que l’API Graph Azure AD pour accéder aux ressources Azure Active Directory. Nos efforts de développement sont désormais axés sur Microsoft Graph et aucune autre amélioration n’est prévue pour l’API Graph Azure AD. Il existe un nombre très limité de scénarios pour lesquels l’API Graph Azure AD peut être encore appropriée ; pour plus d’informations, consultez le billet de blog Microsoft Graph ou l’API Azure AD dans le Centre de développement Office. Il est important de noter que le traitement par lots n’est actuellement pas pris en charge dans Microsoft Graph ; vous devrez utiliser l’API Azure AD Graph pour cette fonctionnalité.

Prise en charge de l’API Graph pour les demandes de traitement par lots OData

La sémantique relative aux opérations de traitement par lots d’entités figure dans Spécification du traitement par lots OData 3.0. La spécification OData définit les concepts suivants pour les demandes de lot :

Une requête est un appel de fonction ou de requête unique.
Un ensemble de modifications est un groupe d’une ou plusieurs opérations d’insertion, de mise à jour ou de suppression, ou d’appels de service.
Un lot est un conteneur d’opérations, qui comprend un ou plusieurs ensembles de modifications et opérations de requête.

L’API Graph prend en charge un sous-ensemble des fonctionnalités définies par la spécification OData :

Un lot unique peut contenir jusqu’à cinq requêtes et/ou ensembles de modifications combinés.
Un ensemble de modifications peut contenir une modification d’objet source et jusqu’à 20 opérations d’ajout et de suppression de lien combinées. Toutes les opérations de l’ensemble de modifications doivent porter sur une seule entité source.

Demandes de lot dans l’API Graph

Les sections suivantes décrivent comment construire une demande de lot et interpréter la réponse par lot, et fournissent des exemples.

Syntaxe de demande de lots

Pour effectuer une demande de lots, spécifiez l’option $batch dans l’URI de demande. Par exemple :

https://graph.windows.net/contoso.onmicrosoft.com/$batch?api-version=1.6

Une demande de lots est envoyée au serveur avec une seule directive POST.

La charge utile est un message MIME à parties multiples contenant le lot ainsi que les requêtes et ensembles de modifications qui le constituent. La charge utile comprend deux types de limites MIME :

Une limite de lots sépare chaque requête et/ou ensemble de modifications dans le lot.
Une limite d’ensemble de modifications sépare les opérations individuelles à l’intérieur d’un ensemble de modifications.

Une demande individuelle au sein d’un ensemble de modifications est identique à une demande faite quand cette opération est appelée isolément. Par exemple :

Pour spécifier le format de charge utile (JSON ou ATOM) pour chaque opération de l’ensemble de modifications, incluez les en-têtes Content-Type et, si nécessaire, Accept appropriés.
Pour supprimer l’écho de contenu de réponse lors de la création d’une entité, spécifiez l’en-tête Prefer avec la valeur return-no-content pour chaque opération d’insertion dans l’ensemble de modifications.

Exemple de demande

L’exemple suivant présente une demande de lots contenant cinq éléments :

Un ensemble de modifications qui crée un utilisateur, testuser@contoso.onmicrosoft.com (POST). Cette opération inclut l’en-tête Prefer: response-no-content pour supprimer l’utilisateur nouvellement créé qui est renvoyé.
Un ensemble de modifications qui met à jour les propriétés Department (service) et JobTitle (fonction) du nouvel utilisateur (PATCH), et définit sa propriété de navigation de gestionnaire (PUT).
Une requête pour le gestionnaire du nouvel utilisateur (GET).
Un ensemble de modifications qui supprime le nouvel utilisateur (DELETE).
Une requête pour l’utilisateur (GET). Cette opération échoue parce que l’utilisateur a été supprimé à l’étape précédente.

POST https://graph.windows.net/contoso.onmicrosoft.com/$batch?api-version=1.5 HTTP/1.1
Authorization: Bearer ey … jQA
Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b 
Host: graph.windows.net
Content-Length: 2961

--batch_36522ad7-fc75-4b56-8c71-56071383e77b 
Content-Type: multipart/mixed; boundary=changeset_77162fcd-b8da-41ac-a9f8-9357efbbd620 
Content-Length: 631       

--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd620 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

POST /contoso.onmicrosoft.com/users?api-version=1.5 HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 256
Prefer: return-no-content
Host: graph.windows.net

{
    "accountEnabled": true,
    "displayName": "Test User",
    "mailNickname": "testuser",
    "passwordProfile": { "password" : "Test1234", "forceChangePasswordNextLogin": false },
    "userPrincipalName": "testuser@contoso.onmicrosoft.com"
}

--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd620----batch_36522ad7-fc75-4b56-8c71-56071383e77b 
Content-Type: multipart/mixed; boundary=changeset_4b2cbfb7-011d-4edb-8bbf-e044f9830aaf 
Content-Length: 909

--changeset_4b2cbfb7-011d-4edb-8bbf-e044f9830aaf 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

PATCH /contoso.onmicrosoft.com/users/testuser@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 72
Host: graph.windows.net

{
    "department": "Engineering",
    "jobTitle": "Test Engineer"
}

--changeset_4b2cbfb7-011d-4edb-8bbf-e044f9830aaf 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

PUT /contoso.onmicrosoft.com/users/testuser@contoso.onmicrosoft.com/$links/manager?api-version=1.5 HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 112
Host: graph.windows.net

{
  "url":"https://graph.windows.net/contoso.onmicrosoft.com/users/a71e4d1c-ce99-40dc-8d4b-390eac63e039"
}

--changeset_4b2cbfb7-011d-4edb-8bbf-e044f9830aaf----batch_36522ad7-fc75-4b56-8c71-56071383e77b 
Content-Type: application/http 
Content-Transfer-Encoding:binary

GET /contoso.onmicrosoft.com/users/testuser@contoso.onmicrosoft.com/$links/manager?api-version=1.5 HTTP/1.1
Accept: application/json
Host: graph.windows.net

--batch_36522ad7-fc75-4b56-8c71-56071383e77b 
Content-Type: multipart/mixed; boundary=changeset_9a0b5878-0f4a-4f57-91c5-9792cdd5ef20 
Content-Length: 331       

--changeset_9a0b5878-0f4a-4f57-91c5-9792cdd5ef20 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

DELETE /contoso.onmicrosoft.com/users/testuser@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Accept: application/json
Host: graph.windows.net


--changeset_9a0b5878-0f4a-4f57-91c5-9792cdd5ef20----batch_36522ad7-fc75-4b56-8c71-56071383e77b 
Content-Type: application/http 
Content-Transfer-Encoding:binary

GET /contoso.onmicrosoft.com/users/testuser@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Accept: application/json
Host: graph.windows.net

--batch_36522ad7-fc75-4b56-8c71-56071383e77b--

Syntaxe de réponse de lot

La réponse renvoie un code d’état général pour la demande de lots, ainsi que des codes d’état individuels et des fragments de résultat pour chaque élément du lot. La réponse est un message MIME à parties multiples, qui comprend des limites de lots et d’ensembles de modifications.

En supposant que la demande de lots ait été correctement authentifiée et reçue par l’API Graph, elle renvoie un code d’état 202 Accepté, même si l’une des opérations du lot échoue. Si la demande de lot proprement dite échoue, elle échoue avant l’exécution d’une quelconque opération du lot. Par exemple, la demande de lot peut échouer en raison d’une erreur d’authentification, auquel cas le code d’état indiquera cette défaillance.

Le fragment de réponse pour un élément de requête contient un code d’état unique qui indique la réussite ou l’échec de l’opération, ainsi que tout corps de réponse approprié.

Les opérations d’un ensemble de modifications sont traitées de façon atomique. Autrement dit, toutes les opérations de l’ensemble de modifications soit réussissent, soit échouent. L’API graphique continue de traiter les opérations de l’ensemble de modifications jusqu’à ce que l’une d’elles échoue. En cas d’échec d’une opération, toutes les opérations précédentes de l’ensemble de modifications sont restaurées.

Si toutes les opérations d’un ensemble de modifications sont correctement traitées, le code d’état (et le corps de réponse) pour chaque opération de l’ensemble de modifications apparaît dans la réponse de celui-ci. En cas d’échec d’une opération d’un ensemble de modifications, un seul code d’état est renvoyé pour l’ensemble de modifications. Il s’agit du code d’état (et du corps de réponse) renvoyé par l’opération qui a échoué, par exemple, 400 Demande incorrecte ou 404 Introuvable.

Exemple de réponse

L’exemple suivant montre la réponse pour l’opération par lot envoyée dans l’exemple de demande présenté ci-dessus. L’état de la demande de lots proprement dite a la valeur 202 Accepté. Cela indique qu’il n’y a aucun problème avec la demande de lot elle-même. La réponse à chaque élément du lot est délimitée par l’identificateur de limite batchresponse, et chaque réponse à une opération d’un ensemble de modifications est délimitée par un identificateur de limite changesetresponse.

La section suivante répertorie les fragments de réponse pour chaque élément de lot :

L’état de la demande POST pour créer le nouvel utilisateur est défini sur 204 Pas de contenu. Cela est dû au fait que l’en-tête Prefer a été défini sur return-no-content dans la demande. Cela indique que l’utilisateur a été correctement créé.
La réponse au deuxième élément du lot contient deux réponses 204 Pas de contenu, l’une pour la mise à jour de l’objet utilisateur (PATCH), et l’autre pour la définition du lien de gestionnaire (PUT) dans l’ensemble de modifications. Cela indique que les deux opérations ont réussi.
La réponse à la demande de lecture du gestionnaire de l’utilisateur renvoie le lien du gestionnaire et un état 200 OK.
L’état de la tentative de suppression de l’utilisateur est 204 Pas de contenu. Cela indique que l’opération a réussi.
L’état de la tentative de lecture de l’utilisateur supprimé est 404 Introuvable, et la réponse contient un code et un message indiquant que l’utilisateur (ressource) est introuvable.

HTTP/1.1 202 Accepted
Cache-Control: no-cache
Pragma: no-cache
Content-Type: multipart/mixed; boundary=batchresponse_1eb70252-25d2-466c-9a1d-7a3f45378b06
Expires: -1
Server: Microsoft-IIS/8.5
ocp-aad-diagnostics-server-name: Nv0YIi2YUldDWu0YPQAXsYwXQ4ttyr7ded6Waf8xyCc=
request-id: 2f7d2f81-3441-4c2a-b494-25cd1d6ce624
client-request-id: f40c00af-3e1f-4198-9261-386f0e3aecc6
x-ms-gateway-rewrite: false
x-ms-dirapi-data-contract-version: 1.5
ocp-aad-session-key: cdhenl3mgHuI3vaRRIQ14uXdwRLUqirNpDXjJP42EzUEvqhhn2NFr22ulR4PsqrM1UD_eSUDItt7J9kUQhNvTT_48q90coHHt2RutCIgPNg.lD81Z0iS2SaHbqkfAaDvbbigoX7ak7rfiUGFby0LOIE
X-Content-Type-Options: nosniff
DataServiceVersion: 1.0;
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
X-Powered-By: ASP.NET
Date: Tue, 20 Jan 2015 23:21:15 GMT
Content-Length: 3065

--batchresponse_1eb70252-25d2-466c-9a1d-7a3f45378b06
Content-Type: multipart/mixed; boundary=changesetresponse_8a63ce5e-ed31-4de6-bc90-9d3ff31debbb--changesetresponse_8a63ce5e-ed31-4de6-bc90-9d3ff31debbb
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
Cache-Control: no-cache
Preference-Applied: return-no-content
DataServiceVersion: 3.0;
Location: https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/6a287a96-ede9-44d2-b685-d6fc03a124c5/Microsoft.DirectoryServices.User
DataServiceId: https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/6a287a96-ede9-44d2-b685-d6fc03a124c5


--changesetresponse_8a63ce5e-ed31-4de6-bc90-9d3ff31debbb----batchresponse_1eb70252-25d2-466c-9a1d-7a3f45378b06
Content-Type: multipart/mixed; boundary=changesetresponse_11ba5cf0-9fba-4995-9f15-bd5c9981cdd6--changesetresponse_11ba5cf0-9fba-4995-9f15-bd5c9981cdd6
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
Cache-Control: no-cache
DataServiceVersion: 1.0;


--changesetresponse_11ba5cf0-9fba-4995-9f15-bd5c9981cdd6
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
Cache-Control: no-cache
DataServiceVersion: 1.0;


--changesetresponse_11ba5cf0-9fba-4995-9f15-bd5c9981cdd6----batchresponse_1eb70252-25d2-466c-9a1d-7a3f45378b06
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 200 OK
DataServiceVersion: 3.0;
Content-Type: application/json;odata=minimalmetadata;streaming=true;charset=utf-8
X-Content-Type-Options: nosniff
Cache-Control: no-cache

{
  "odata.metadata":"https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/$links/manager",
  "url":"https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/a71e4d1c-ce99-40dc-8d4b-390eac63e039/Microsoft.DirectoryServices.User"
}
--batchresponse_1eb70252-25d2-466c-9a1d-7a3f45378b06
Content-Type: multipart/mixed; boundary=changesetresponse_bb215a84-f91e-4486-a771-ba2cc5d429d1--changesetresponse_bb215a84-f91e-4486-a771-ba2cc5d429d1
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
Cache-Control: no-cache
DataServiceVersion: 1.0;


--changesetresponse_bb215a84-f91e-4486-a771-ba2cc5d429d1----batchresponse_1eb70252-25d2-466c-9a1d-7a3f45378b06
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 404 Not Found
X-Content-Type-Options: nosniff
Cache-Control: no-cache
DataServiceVersion: 3.0;
Content-Type: application/json;odata=minimalmetadata;streaming=true;charset=utf-8

{
  "odata.error":
    {
      "code":"Request_ResourceNotFound",
      "message":
        {
          "lang":"en",
          "value":"Resource 'testuser@contoso.onmicrosoft.com' does not exist or one of its queried reference-property objects are not present."
        }
    }
}
--batchresponse_1eb70252-25d2-466c-9a1d-7a3f45378b06--

Exemple de réponse d’erreur

Comme expliqué ci-dessus, l’API Graph renvoie un code d’erreur 202 Accepté pour l’ensemble du lot si elle peut accepter le lot, c’est-à-dire, si la demande de lot est correctement formée et s’il n’y a pas d’erreur, par exemple, d’authentification. Sinon, l’API Graph renvoie l’erreur appropriée et ne traite pas le lot. En cas d’échec d’un élément du lot, le fragment de réponse pour cet élément contient un code d’état et un corps de réponse indiquant cette erreur. En cas d’échec d’une opération d’un ensemble de modifications, un fragment de réponse est renvoyé pour l’ensemble de modifications entier, et ce fragment contient le code d’état et le corps de réponse associés à l’opération qui a échoué.

L’exemple suivant présente une réponse de demande de lot contenant un ensemble de modifications dans lequel l’une des opérations a échoué. Notez que la réponse par lot renvoie le code d’état 202 Accepté. Le code d’état renvoyé pour l’ensemble de modifications indique qu’une opération a échoué avec l’état 404 Introuvable. Des informations d’erreur supplémentaires sont incluses dans le corps de la réponse pour l’opération qui a échoué. L’élément code spécifie le code d’erreur de l’API Graph et l’élément message contient la chaîne du message d’erreur. Dans cet exemple, le corps de la réponse a été mis en retrait pour une meilleure lisibilité.

HTTP/1.1 202 Accepted
Cache-Control: no-cache
Pragma: no-cache
Content-Type: multipart/mixed; boundary=batchresponse_3ac28387-a100-4758-8998-8b9ec36f9fdc
Expires: -1
Server: Microsoft-IIS/8.5
ocp-aad-diagnostics-server-name: 1l3fvSoDCV+VKoBCuHRN+HIwCACBOck3dqmtCGj+aiU=
request-id: e434261b-c32f-48b4-b21d-3e1beab6d525
client-request-id: 236bf26e-b4e8-40a4-b6fb-d41105a7b178
x-ms-gateway-rewrite: false
x-ms-dirapi-data-contract-version: 1.5
ocp-aad-session-key: 9aOaAUxX95OZ0ctrYbeLUproN-37GypZXrss0PYKhEfqamKRG-C68hFcCw5h-ZCWFqBrXPrldGEnjq4CKKr0bW91tjrdo-BlwAqHxbP5jq4.FaXtVZni3cSsWFRMSjQAbjiluPcEvZofwp9OH3t1fyk
X-Content-Type-Options: nosniff
DataServiceVersion: 1.0;
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
X-Powered-By: ASP.NET
Date: Wed, 21 Jan 2015 21:13:25 GMT
Content-Length: 779

--batchresponse_3ac28387-a100-4758-8998-8b9ec36f9fdc
Content-Type: multipart/mixed; boundary=changesetresponse_72ba9a5a-2da3-4d39-ae4f-dd9527efd742--changesetresponse_72ba9a5a-2da3-4d39-ae4f-dd9527efd742
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 404 Not Found
X-Content-Type-Options: nosniff
DataServiceVersion: 3.0;
Content-Type: application/json;odata=minimalmetadata;streaming=true;charset=utf-8

{
  "odata.error":
    {
      "code":"Request_ResourceNotFound",
      "message":
        {
          "lang":"en",
          "value":"Resource 'eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee' does not exist or one of its queried reference-property objects are not present."
        }
    }
}
--changesetresponse_72ba9a5a-2da3-4d39-ae4f-dd9527efd742----batchresponse_3ac28387-a100-4758-8998-8b9ec36f9fdc--

Pour référence, l’exemple suivant présente le lot qui a généré la réponse ci-dessus. Il contient un ensemble de modifications qui ajoute trois utilisateurs à un groupe. Les ID d’objet pour les deux derniers utilisateurs sont fictifs : eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee et ffffffff-ffff-ffff-ffff-ffffffffffff. L’URL du lot et les en-têtes de demande associés sont omis par souci de concision.

--batch_36522ad7-fc75-4b56-8c71-56071383e77b 
Content-Type: multipart/mixed; boundary=changeset_5a769eb2-d1a7-4a10-94f6-d1a5ed5c4bc0 
Content-Length: 1432

--changeset_5a769eb2-d1a7-4a10-94f6-d1a5ed5c4bc0 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

POST /contoso.onmicrosoft.com/groups/fc15e7ef-993f-4865-bf37-317d9b8017b8/$links/members?api-version=1.5 HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 112
Host: graph.windows.net

{
  "url":"https://graph.windows.net/contoso.onmicrosoft.com/users/a71e4d1c-ce99-40dc-8d4b-390eac63e039"
}

--changeset_5a769eb2-d1a7-4a10-94f6-d1a5ed5c4bc0 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

POST /contoso.onmicrosoft.com/groups/fc15e7ef-993f-4865-bf37-317d9b8017b8/$links/members?api-version=1.5 HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 112
Host: graph.windows.net

{
  "url":"https://graph.windows.net/contoso.onmicrosoft.com/users/eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee
"
}

--changeset_5a769eb2-d1a7-4a10-94f6-d1a5ed5c4bc0 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

POST /contoso.onmicrosoft.com/groups/fc15e7ef-993f-4865-bf37-317d9b8017b8/$links/members?api-version=1.5 HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 112
Host: graph.windows.net

{
  "url":"https://graph.windows.net/contoso.onmicrosoft.com/users/ffffffff-ffff-ffff-ffff-ffffffffffff"
}

--changeset_5a769eb2-d1a7-4a10-94f6-d1a5ed5c4bc0----batch_36522ad7-fc75-4b56-8c71-56071383e77b--

Partager via