Elaborazione batch | Concetti relativi all'API Graph

Articolo
06/09/2016

Si applica a: API Graph | Azure Active Directory (AD)

Con l'API di Azure AD Graph è possibile raggruppare in batch le operazioni sulle entità per ridurre i round trip al server. Raggruppando in batch le richieste, è possibile riduce il carico di rete e completare le operazioni più rapidamente.

Importante

Per accedere alle risorse di Azure Active Directory è fortemente consigliabile usare Microsoft Graph anziché l'API di Azure AD Graph. Le attività di sviluppo Microsoft sono ora concentrate su Microsoft Graph e non sono previsti altri miglioramenti per l'API di Azure AD Graph. Può essere ancora opportuno usare questa API in un numero molto limitato di scenari. Per altre informazioni, vedere il post di blog Microsoft Graph or the Azure AD Graph (Microsoft Graph o Azure AD Graph) in Office Developer Center. Si noti che l'elaborazione batch non è attualmente supportata in Microsoft Graph. Per questa funzionalità è necessario usare l'API di Azure AD Graph.

Supporto dell'API Graph per richieste batch OData

La semantica per l'elaborazione batch delle entità è definita dalla specifica di elaborazione batch OData 3.0. Nella specifica OData sono definiti i concetti seguenti relativi alle richieste batch:

Una query è una singola chiamata di funzione o query.
Un insieme di modifiche è un gruppo di una o più operazioni di inserimento, aggiornamento o eliminazione, chiamate di azioni o chiamate di servizi.
Un batch è un contenitore di operazioni, inclusi uno o più insiemi di modifiche e operazioni di query.

L'API Graph supporta un subset delle funzionalità definite dalla specifica OData:

Un singolo batch può contenere un massimo di cinque query e/o insiemi di modifiche combinati.
Un insieme di modifiche può contenere un massimo di una modifica dell'oggetto di origine e fino a 20 operazioni di aggiunta ed eliminazione di collegamenti combinate. Tutte le operazioni dell'insieme di modifiche devono essere eseguite su un'unica entità di origine.

Richieste batch dell'API Graph

Le sezioni seguenti descrivono come creare una richiesta batch e interpretare la risposta batch e contengono esempi per ogni operazione.

Sintassi della richiesta batch

Per eseguire una richiesta batch, specificare l'opzione $batch nell'URI della richiesta. Ad esempio:

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

Una richiesta batch viene inviata al server con una singola direttiva POST.

Il payload è un messaggio MIME multiparte contenente il batch, le query che lo costituiscono e l'insieme di modifiche. Il payload include due tipi di limiti MIME:

Un limite batch separa ogni query e/o insieme di modifiche nel batch.
Un limite dell'insieme di modifiche separa le singole operazioni dell'insieme.

Una singola richiesta in un insieme di modifiche è identica a una richiesta effettuata quando l'operazione viene chiamata da se stessa. Ad esempio:

Per specificare il formato del payload (JSON o ATOM) per ogni operazione nell'insieme di modifiche, includere l'oggetto Content-Type appropriato e, se necessario, intestazioni Accept.
Per eliminare l'eco del contenuto della risposta quando si crea un'entità, specificare l'intestazione Prefer con il valore return-no-content per ogni operazione di inserimento in un insieme di modifiche.

Richiesta di esempio

L'esempio seguente mostra una richiesta batch che contiene cinque elementi:

Un set di modifiche che crea un utente, testuser@contoso.onmicrosoft.com (POST). Questa operazione include l'intestazione Prefer: response-no-content che elimina l'utente appena creato che viene restituito.
Un insieme di modifiche che aggiorna le proprietà relative a reparto e posizione del nuovo utente (PATCH) e imposta la proprietà di navigazione relativa al manager dell'utente (PUT).
Una query per il manager del nuovo utente (GET).
Un insieme di modifiche che elimina il nuovo utente (DELETE).
Una query per l'utente (GET). Questa operazione avrà esito negativo perché l'utente è stato eliminato nel passaggio precedente.

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

Sintassi della risposta batch

La risposta restituisce un codice di stato globale per la richiesta batch e singoli codici di stato e frammenti di risultato per ogni elemento nel batch. La risposta è un messaggio MIME multiparte che include limiti batch e limiti dell'insieme di modifiche.

Supponendo che la richiesta batch sia stata autenticata in modo appropriato e che sia stata ricevuta correttamente dall'API Graph, la richiesta batch restituisce il codice di stato 202 Accettato, anche in caso di esito negativo di una delle operazioni nel batch. Se la richiesta batch ha esito negativo, l'errore si verifica prima che venga eseguita qualsiasi operazione nel batch. Ad esempio, se la richiesta batch ha esito negativo a causa di un errore di autenticazione, il codice di stato indicherà questo tipo di errore.

Il frammento di risposta per un elemento di query contiene un singolo codice di stato che indica l'esito positivo o negativo dell'operazione, nonché il corpo della risposta appropriato.

Le operazioni in un insieme di modifiche vengono elaborate in modo atomico. Ciò significa che tutte le operazioni nell'insieme di modifiche avranno esito positivo e in caso contrario l'intero insieme avrà esito negativo. L'API Graph continua l'elaborazione delle operazioni nell'insieme di modifiche finché una non ha esito negativo. Se un'operazione ha esito negativo, viene eseguito il rollback di tutte le operazioni precedenti nell'insieme di modifiche.

Se tutte le operazioni in un insieme di modifiche vengono elaborate correttamente, il codice di stato (e il corpo della risposta) per ogni operazione all'interno dell'insieme di modifiche viene visualizzato nella risposta dell'insieme di modifiche. Se un'operazione in un insieme di modifiche ha esito negativo, viene restituito un singolo codice di stato per l'insieme di modifiche, corrispondente al codice di stato restituito dall'operazione con esito negativo, ad esempio 400 Richiesta non valida o 404 Non trovato.

Risposta di esempio

L'esempio seguente mostra la risposta per l'operazione batch inviata nella richiesta di esempio illustrata in precedenza. Lo stato per la richiesta batch è impostato su 202 Accettato. Ciò indica l'assenza di problemi relativi alla richiesta batch. La risposta per ogni elemento del batch è delimitata dall'identificatore del limite batchresponse e ogni risposta per un'operazione in un insieme di modifiche è delimitata dall'identificatore del limite changesetresponse.

Di seguito sono elencati i frammenti di risposta per ogni elemento del batch:

Lo stato per la richiesta POST di creazione del nuovo utente è impostato su 204 Nessun contenuto. Questa impostazione è dovuta al fatto che l'intestazione Prefer è stata impostata su return-no-content nella richiesta e indica che l'utente è stato creato.
La risposta per il secondo elemento del batch contiene due risposte 204 Nessun contenuto, una per l'aggiornamento dell'oggetto utente (PATCH) e una per l'impostazione del collegamento al responsabile (PUT) nell'insieme di modifiche. Ciò indica che entrambe le operazioni sono state eseguite correttamente.
La risposta per la richiesta di lettura del responsabile dell'utente restituisce il collegamento al responsabile e lo stato 200 OK.
Lo stato per il tentativo di eliminazione dell'utente è 204 Nessun contenuto. Ciò indica che l'operazione è stata eseguita correttamente.
Lo stato per il tentativo di lettura dell'utente eliminato è 404 Non trovato e la risposta contiene un codice e un messaggio che indica che l'utente (risorsa) non è stato trovato.

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

Risposta con errore di esempio

Come illustrato in precedenza l'API Graph restituisce un codice errore 202 Accettato per l'intero batch se può accettare il batch, ovvero se il formato della richiesta batch è corretto e non si verificano errori, ad esempio un errore di autenticazione. In caso contrario, l'API Graph restituisce l'errore appropriato e non elabora il batch. Se un singolo elemento all'interno del batch ha esito negativo, il frammento di risposta per l'elemento conterrà un codice di stato e un corpo della risposta che indica l'errore. Quando un'operazione all'interno di un insieme di modifiche ha esito negativo, viene restituito un singolo frammento di risposta per l'intero insieme di modifiche e tale frammento contiene il codice di stato e il corpo della risposta associati all'operazione non riuscita.

L'esempio seguente mostra una risposta per una richiesta batch che contiene un insieme di modifiche in cui una delle operazioni non è riuscita. Si noti che la risposta batch restituisce il codice di stato 202 Accettato. Il codice di stato restituito per l'insieme di modifiche indica che un'operazione non è riuscita con stato 404 Non trovato. Il corpo della risposta per l'operazione non riuscita include informazioni aggiuntive sull'errore. L'elemento code specifica il codice errore dell'API Graph e l'elemento message contiene la stringa del messaggio di errore. In questo esempio è stato impostato un rientro per il corpo della risposta per semplificare la lettura.

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

Come riferimento, l'esempio seguente mostra il batch che ha generato la risposta precedente. È incluso un singolo insieme di modifiche che aggiunge tre utenti a un gruppo. Gli ID oggetto per gli ultimi due utenti sono fittizi: eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee e ffffffff-ffff-ffff-ffff-ffffffffffff. L'URL del batch e le intestazioni di richiesta associate sono stati omessi per brevità.

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

Risorse aggiuntive

Specifica di elaborazione batch OData 3.0
Specifica OData
Azure AD Graph API reference (Informazioni di riferimento sull'API di Azure AD Graph)

Condividi tramite

Elaborazione batch | Concetti relativi all'API Graph

Supporto dell'API Graph per richieste batch OData

Richieste batch dell'API Graph

Sintassi della richiesta batch

Richiesta di esempio

Sintassi della risposta batch

Risposta di esempio

Risposta con errore di esempio

Risorse aggiuntive

Risorse aggiuntive