Eseguire operazioni in batch usando l'API Web

  • Articolo

 

Data di pubblicazione: gennaio 2017

Si applica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Puoi raggruppare più operazioni in un'unica richiesta HTTP mediante di un'operazione in batch.

In questo argomento

Quando usare le richieste batch

Richieste batch

Set di modifiche

Esempio

Quando usare le richieste batch

Il valore fornito dalle richieste batch è che possono includere i set delle modifiche, che offrono un modo per combinare una serie di operazioni che riesce o meno come gruppo. in una transazione confrontata con altre operazioni che possono essere eseguite tramite Web API, sono più difficili da comporre senza un modello a oggetti che include la serializzazione di oggetti o una conoscenza più approfondita del protocollo HTTP perché il messaggio della richiesta è essenzialmente un documento di testo che deve soddisfare requisiti molto specifici.

Ricorda che è possibile creare più facilmente entità associate in un'unica operazione rispetto all'uso di una richiesta batch. Le richieste batch sono ottimali per eseguire operazioni su entità non associate tra loro quando tutte le operazioni devono essere eseguite in un'unica operazione transazionale.

Inoltre, le risposte restituite sono essenzialmente documenti di testo e non oggetti facilmente analizzabili in JSON. Dovrai analizzare il testo nella risposta o individuare una libreria di supporto per accedere ai dati nella risposta.

Richieste batch

Usa una richiesta POST per inviare un'operazione in blocco che contiene più richieste. Una richiesta batch può includere le richieste GET e i set di modifiche. Per utilizzare le funzionalità transazionali delle richieste batch, solo le operazioni che cambieranno i dati possono essere incluse in un set di modifiche. Le richieste GET non devono essere incluse nel set di modifiche.

La richiesta POST contenente il batch deve avere un'intestazione Content-Type con un valore impostato su multipart/mixed con un limite impostato per includere l'identificatore del batch che usa questo pattern:

--batch_<unique identifier>

L'identificatore univoco non deve essere un GUID, ma deve essere univoco. Ogni elemento nel batch deve essere preceduto dall'identificatore batch con un'intestazione Content-Type e Content-Transfer-Encoding come illustrato di seguito:

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

La fine di un batch deve contenere un indicatore di chiusura come illustrato di seguito:

--batch_WKQS9Yui9r--

Nota

La preferenza odata.continue-on-error non supportata dall'API Web. Eventuali errori che si verificano nel batch interromperanno l'elaborazione del resto del batch.

Set di modifiche

Se più operazioni sono contenute in un set di modifiche, tutte le operazioni sono considerate atomiche, il che significa che se una delle operazioni non riesce, le eventuali operazioni completate verranno invertite. Analogamente a una richiesta batch, i set di modifiche devono avere un'intestazione Content-Type con un valore impostato su multipart/mixed con un limite impostato per includere l'identificatore del set di modifiche che usa questo pattern:

--changeset_<unique identifier>

L'identificatore univoco non deve essere un GUID, ma deve essere univoco. Ogni elemento nel set di modifiche deve essere preceduto dall'identificatore set di modifiche con un'intestazione Content-Type e Content-Transfer-Encoding come illustrato di seguito:

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

I set di modifiche possono anche includere un'intestazione Content-ID con un valore univoco. Questo valore, se preceduto da $, rappresenta una variabile che contiene l'Uri per qualsiasi entità creata per tale operazione. Ad esempio, quando imposti il valore 1, puoi fare riferimento a quell'entità usando $1 nel set di modifiche.

La fine del set di modifiche deve contenere un indicatore di chiusura come illustrato di seguito:

--changeset_BBB456--

Esempio

Il seguente esempio include un batch con un identificatore univoco di AAA123 e un set di modifiche con un identificatore univoco di BBB456.

Nel set di modifiche, vengono create due attività usando POST e vengono associate a un account esistente con accountid = 00000000-0000-0000-000000000001.

Infine, viene inclusa una richiesta GET all'esterno del set di modifiche per restituire tutte e sei le attività associate all'account, incluse le due create nella richiesta batch.

  • Richiesta

    POST cc_WebAPI_ServiceURI/$batch HTTP/1.1
Content-Type: multipart/mixed;boundary=batch_AAA123
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

--batch_AAA123
Content-Type: multipart/mixed;boundary=changeset_BBB456

--changeset_BBB456
Content-Type: application/http
Content-Transfer-Encoding:binary
Content-ID: 1

POST cc_WebAPI_ServiceURI/tasks HTTP/1.1
Content-Type: application/json;type=entry

{"subject":"Task 1 in batch","regardingobjectid_account_task@odata.bind":"cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-000000000001)"}
--changeset_BBB456
Content-Type: application/http
Content-Transfer-Encoding:binary
Content-ID: 2

POST cc_WebAPI_ServiceURI/tasks HTTP/1.1
Content-Type: application/json;type=entry

{"subject":"Task 2 in batch","regardingobjectid_account_task@odata.bind":"cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-000000000001)"}
--changeset_BBB456--

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

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-000000000001)/Account_Tasks?$select=subject HTTP/1.1
Accept: application/json

--batch_AAA123--

  • Risposta

    --batchresponse_c1bd45c1-dd81-470d-b897-e965846aad2f
Content-Type: multipart/mixed; boundary=changesetresponse_ff83b4f1-ab48-430c-b81c-926a2c596abc

--changesetresponse_ff83b4f1-ab48-430c-b81c-926a2c596abc
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 1

HTTP/1.1 204 No Content
OData-Version: 4.0
Location: cc_WebAPI_ServiceURI/tasks(a59c24f3-fafc-e411-80dd-00155d2a68cb)
OData-EntityId: cc_WebAPI_ServiceURI/tasks(a59c24f3-fafc-e411-80dd-00155d2a68cb)


--changesetresponse_ff83b4f1-ab48-430c-b81c-926a2c596abc
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 2

HTTP/1.1 204 No Content
OData-Version: 4.0
Location: cc_WebAPI_ServiceURI/tasks(a69c24f3-fafc-e411-80dd-00155d2a68cb)
OData-EntityId: cc_WebAPI_ServiceURI/tasks(a69c24f3-fafc-e411-80dd-00155d2a68cb)


--changesetresponse_ff83b4f1-ab48-430c-b81c-926a2c596abc--
--batchresponse_c1bd45c1-dd81-470d-b897-e965846aad2f
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
  "@odata.context":"cc_WebAPI_ServiceURI/$metadata#tasks(subject)","value":[
    {
      "@odata.etag":"W/\"474122\"","subject":"Task Created with Test Account","activityid":"919c24f3-fafc-e411-80dd-00155d2a68cb"
    },{
      "@odata.etag":"W/\"474125\"","subject":"Task 1","activityid":"a29c24f3-fafc-e411-80dd-00155d2a68cb"
    },{
      "@odata.etag":"W/\"474128\"","subject":"Task 2","activityid":"a39c24f3-fafc-e411-80dd-00155d2a68cb"
    },{
      "@odata.etag":"W/\"474131\"","subject":"Task 3","activityid":"a49c24f3-fafc-e411-80dd-00155d2a68cb"
    },{
      "@odata.etag":"W/\"474134\"","subject":"Task 1 in batch","activityid":"a59c24f3-fafc-e411-80dd-00155d2a68cb"
    },{
      "@odata.etag":"W/\"474137\"","subject":"Task 2 in batch","activityid":"a69c24f3-fafc-e411-80dd-00155d2a68cb"
    }
  ]
}
--batchresponse_c1bd45c1-dd81-470d-b897-e965846aad2f--

Vedere anche

Eseguire operazioni tramite l'API Web
Comporre richieste HTTP e gestire gli errori
Query di dati tramite l'API Web
Creare un'entità utilizzando l'API Web
Recupera un'entità utilizzando l'API Web
Aggiorna ed elimina le entità con l'API Web
Associa e annulla associazione entità con l'API Web
Utilizzare le funzioni API Web
Utilizzare le azioni API Web
Rappresentare un altro utente usando l'API Web
Eseguire operazioni condizionali tramite l'API Web

Microsoft Dynamics 365

© 2017 Microsoft. Tutti i diritti sono riservati. Copyright