Esempio operazioni condizionali dell'API Web

  • Articolo

 

Data di pubblicazione: gennaio 2017

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

Questo gruppo di esempi dimostra come eseguire determinate operazioni condizionalmente basate sulla versione del record di entità contenuto nel server Dynamics 365 e/o attualmente gestito dal client. Per ulteriori informazioni, vedere Eseguire operazioni condizionali tramite l'API Web. Questo esempio è implementato come un progetto distinto per le lingue seguenti:

Esempio operazioni condizionali dell'API Web (C#)

Esempio di operazioni condizionali API Web (JavaScript lato client)

L'API Web di Dynamics 365 segue le convenzioni del protocollo OData v4.0 che utilizza ETags per implementare il controllo della versione della risorsa. Le operazioni condizionali API Web dipendono da questo meccanismo di controllo della versione.

In questo argomento vengono illustrati la struttura e il contenuto degli esempi a un livello superiore e indipendente dal linguaggio. Fornisce i dettagli sulle richieste e sulle risposte HTTP e l'output collegato di programma, se applicabile. Rivedi gli argomenti di esempio collegati sopra per ottenere le implementazione specifiche del linguaggio e i dettagli correlati su come eseguire le operazioni descritte in questo argomento.

Dimostra

Questo esempio è suddiviso in tre sezioni principali, elencate nella tabella seguente. Ogni sezione contiene un set di operazioni correlate API Web che vengono descritte in dettaglio nella sezione concettuale associata dell'argomento Eseguire operazioni condizionali tramite l'API Web.

Sezione codice

Argomenti concettuali associati

GET condizionale

Recuperi condizionali

Concorrenza ottimistica all'eliminazione e all'aggiornamento

Applicare la concorrenza ottimistica

Controllo delle operazioni di upsert

Operazioni di upsert limitate

Le sezioni seguenti contengono una breve discussione delle operazioni dell'API Web di Dynamics 365 eseguite insieme ai messaggi HTTP corrispondenti e all'output associato alla console che è uguale per ogni implementazione di linguaggio. Per brevità, le intestazioni HTTP meno pertinenti sono state omesse. Gli URI dei record varieranno con l'indirizzo base dell'organizzazione e l'ID del record assegnato dal server Dynamics 365.

Dati di esempio

Nell'esempio viene creato il record seguente prima dell'esecuzione delle sezioni principali di codice.

Tipo di entità

Proprietà assegnate dal client

Proprietà assegnate dal server

account EntityType

Nome: Contoso Ltd.
Ricavi: 5000000
Telefono: 555-0000
Descrizione: Parent company of Contoso Pharmaceuticals, etc.

ID: 14e151db-9b4f-e611-80e0-00155da84c08
Etag iniziale: W/"628448"

GET condizionale

Questa sezione del programma illustra come eseguire i recuperi condizionali per ottimizzare la larghezza di banda e l'esecuzione del server mentre gestisce lo stato del record più recente nel client.Ulteriori informazioni:Recuperi condizionali

  1. Tenta di recuperare l'account Contoso Ltd. solo se non corrisponde alla versione esistente, identificato dal valore ETag iniziale restituito alla creazione del record account. Questa condizione è rappresentata dall'intestazione If-None-Match.

    Richiesta HTTP

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    Risposta HTTP

    HTTP/1.1 304 Not Modified

    Output della console

    Instance retrieved using ETag: W/"628448"
Expected outcome: Entity was not modified so nothing was returned.

    Il valore risposta, 304 Not Modified, indica che il record corrente è il più aggiornato, in modo che il server non restituisce il record necessario nel corpo della risposta.

  2. Aggiornare l'account modificando la proprietà primaria del numero di telefono.

    Richiesta HTTP

    PUT http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)/telephone1 HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json
{
  "value": "555-0001"
}

    Risposta HTTP

    HTTP/1.1 204 No Content

    Output della console

    Account telephone number updated.

  3. Ritenta la stessa operazione condizionale GET utilizzando il valore ETag originale. Questa volta che l'operazione restituisce i dati richiesti perché la versione del server è diversa (più nuova) dalla versione identificata nella richiesta. Come in tutti i recuperi di record, la risposta include un'intestazione ETag che identifica la versione corrente.

    Richiesta HTTP

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    Risposta HTTP

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628460"
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628460\"",
  "name":"Contoso Ltd",
  "revenue":5000000.0000,
  "telephone1":"555-0001",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

    Output della console

    Instance retrieved using ETag: W/"628448"
{
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628460\"",
  "name": "Contoso Ltd",
  "revenue": 5000000.0,
  "telephone1": "555-0001",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

Concorrenza ottimistica all'eliminazione e all'aggiornamento

Questa sezione del programma illustra come eseguire le operazioni di aggiornamento ed eliminazione condizionale. L'uso più comune per tali operazioni consiste nell'implementare un approccio di concorrenza ottimistica all'elaborazione record in un ambiente multiutente.Ulteriori informazioni:Applicare la concorrenza ottimistica

  1. Tenta di eliminare l'account originale solo se corrisponde alla versione originale (valore ETag). Questa condizione è rappresentata dall'intestazione If-Match. Questa procedura non riesce perché il record account è stato aggiornato nella sezione precedente e pertanto la relativa versione è stata aggiornata nel server.

    Richiesta HTTP

    DELETE http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    Risposta HTTP

    HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"The version of the existing record doesn't match the RowVersion property provided.", . . .
    }
}

    Output della console

    Expected Error: The version of the existing record doesn't match the property provided.
        Account not deleted using ETag 'W/"628448"', status code: '412'.

  2. Tenta di aggiornare l'account solo se corrisponde al valore ETag originale. Di nuovo, questa condizione è rappresentata dall'intestazione If-Match e l'operazione non riesce per lo stesso motivo.

    Richiesta HTTP

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0002",
  "revenue": 6000000
}

    Risposta HTTP

    HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"The version of the existing record doesn't match the RowVersion property provided.", . . . 
  }
}

    Output della console

    Expected Error: The version of the existing record doesn't match the property provided.
        Account not updated using ETag 'W/"628448"', status code: '412'.

  3. Ritenta un aggiornamento, ma utilizza invece il valore ETag corrente ottenuto dall'ultimo recupero record nella sezione precedente.

    Richiesta HTTP

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628460"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
  "telephone1": "555-0003",
  "revenue": 6000000
}

    Risposta HTTP

    HTTP/1.1 204 No Content

    Output della console

    Account successfully updated using ETag: W/"628460", status code: '204'.

  4. Conferma il completamento dell'aggiornamento recuperando e producendo l'output con lo stato corrente. Utilizza una richiesta GET di base.

    Richiesta HTTP

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    Risposta HTTP

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628461"
OData-Version: 4.0
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628461\"",
  "name":"Contoso Ltd",
  "revenue":6000000.0000,
  "telephone1":"555-0003",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

    Output della console

    {
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628461\"",
  "name": "Contoso Ltd",
  "revenue": 6000000.0,
  "telephone1": "555-0003",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

Controllo delle operazioni di upsert

Questa sezione del programma illustra come eseguire le operazioni condizionali PATCH, limitando le operazioni di upsert per eseguirle come operazioni di solo aggiornamento o solo inserimento.Ulteriori informazioni:Operazioni di upsert limitate

  1. Tenta di inserire, senza aggiornare, le proprietà dei ricavi e del telefono principale per l'account. L'intestazione If-None-Match con il valore * rappresenta questa condizione di upsert. Questa procedura non riesce perché questo record account esiste ancora nel server (a meno che non sia stato eliminato simultaneamente da un altro utente o processo).

    Richiesta HTTP

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-None-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0004",
  "revenue": 7500000
}

    Risposta HTTP

    HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"A record with matching key values already exists.", . . .
  }
}

    Output della console

    Expected Error: A record with matching key values already exists.
        Account not updated using ETag 'W/"628448", status code: '412'.

  2. Tenta di eseguire la stessa operazione di aggiornamento senza creazione. A tale scopo, l'intestazione condizionale If-Match viene utilizzata con un valore *. Questa operazione riesce perché il record esiste nel server.

    Richiesta HTTP

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0005",
  "revenue": 7500000
}

    Risposta HTTP

    HTTP/1.1 204 No Content

    Output della console

    Account updated using If-Match '*'

  3. Recupera e produci l'output dello stato corrente con una richiesta GET di base. Il valore ETag restituito è cambiato in modo da riflettere la nuova versione aggiornata del record account.

    Richiesta HTTP

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    Risposta HTTP

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628463"
OData-Version: 4.0
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628463\"",
  "name":"Contoso Ltd","revenue":7500000.0000,
  "telephone1":"555-0005",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

    Output della console

    {
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628463\"",
  "name": "Contoso Ltd",
  "revenue": 7500000.0,
  "telephone1": "555-0005",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

  4. Elimina l'account con un DELETE di base.

    Richiesta HTTP

    DELETE http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    Risposta HTTP

    HTTP/1.1 204 No Content

    Output della console

    Account was deleted.

  5. Come nel passaggio 2, tenta di aggiornare l'account se esiste. Di nuovo, questa condizione è rappresentata dall'intestazione If-Match con un valore *. Questa procedura non riesce perché il record è stato eliminato. Tuttavia, se l'intestazione If-Match non è presente, l'operazione di upsert di base risultante correttamente crea un nuovo record.

    Richiesta HTTP

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0006",
  "revenue": 7500000
}

    Risposta HTTP

    HTTP/1.1 404 Not Found
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"account With Id = 14e151db-9b4f-e611-80e0-00155da84c08 Does Not Exist", . . .
  }
}

    Output della console

    Expected Error: Account with Id = 14e151db-9b4f-e611-80e0-00155da84c08 does not exist.
Account not updated because it does not exist, status code: '404'.

Nessuna necessità di pulire i dati di esempio perché l'unico record account è già stato eliminato nel passaggio 4.

Vedere anche

Utilizzare l'API Web di Microsoft Dynamics 365
Eseguire operazioni condizionali tramite l'API Web
Esempio operazioni condizionali dell'API Web (C#)
Esempio di operazioni condizionali API Web (JavaScript lato client)

Microsoft Dynamics 365

© 2017 Microsoft. Tutti i diritti sono riservati. Copyright