Condividi tramite

Eseguire operazioni condizionali tramite 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

Microsoft Dynamics 365 offre supporto per una serie di operazioni condizionali che si basano sul meccanismo standard di controllo delle versioni delle risorse HTTP chiamato ETag.

In questo argomento

ETags

Intestazioni If-Match e If-None-Match

Recuperi condizionali

Operazioni di upsert limitate

Applicare la concorrenza ottimistica

ETags

Il protocollo HTTP definisce un tag di entità (o ETag per brevità) per l'identificazione delle specifiche versioni di una risorsa. Gli ETag sono identificatori opachi i cui valori esatti dipendono dall'implementazione. I valori ETag vengono elaborati in due tipi: convalida debole e complessa. La convalida complessa indica che una risorsa univoca, identificata da un URI specifico, sarà identica a livello binario se il corrispondente valore ETag è invariato. La convalida debole garantisce solo che la rappresentazione delle risorse è semanticamente equivalente per lo stesso valore ETag.

Dynamics 365 genera una proprietà @odata.etag di convalida debole per ogni istanza di entità e questa proprietà viene restituita automaticamente con ogni record di entità recuperato. Per ulteriori informazioni, vedere Recupera un'entità utilizzando l'API Web.

Intestazioni If-Match e If-None-Match

Utilizza le intestazioni If-Match e If-None-Match con valori ETag per controllare se la versione corrente di una risorsa corrisponde all'ultima versione recuperata, a una versione precedente o non corrisponde ad alcuna versione. I confronti costituiscono la base del supporto operativo condizionale. Dynamics 365 consente agli ETag di supportare i recuperi condizionali, la concorrenza ottimistica e le operazioni upsert limitate.

Avviso

Il codice client non deve fornire un significato al valore specifico di un ETag né una relazione apparente tra gli ETag oltre l'uguaglianza o la diseguaglianza. Ad esempio, un valore ETag per la versione più recente di una risorsa non è sicuramente maggiore del valore ETag di una versione precedente. Inoltre, l'algoritmo utilizzato per generare i nuovi valori ETag è soggetto a modifiche senza preavviso nelle versioni di un servizio.

Recuperi condizionali

Etag consente di ottimizzare i recuperi dei record quando accedi allo stesso record più volte. Se in precedenza hai recuperato un record, puoi passare il valore ETag con l'intestazione If-None-Match per richiedere i dati da recuperare solo se sono stati modificati dall'ultima volta che sono stati recuperati. Se i dati sono stati modificati, la richiesta restituisce uno stato HTTP di 200 (OK) con gli ultimi dati nel corpo della richiesta. Se i dati non sono stati modificati, il codice di stato HTTP 304 (Not Modified) è stato restituito per indicare che l'entità non è stata modificata. I seguenti due messaggi di esempio restituiscono i dati per un'entità account con accountid uguale a 00000000-0000-0000-0000-000000000001 quando i dati non sono stati modificati da quando sono stati recuperati l'ultima volta.

  • Richiesta

    GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$select=accountcategorycode,accountnumber,creditonhold,createdon,numberofemployees,name,revenue   HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: W/"468026"

  • Risposta

    HTTP/1.1 304 Not Modified
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

Operazioni di upsert limitate

Un upsert di norma funziona creando un'entità se non esiste; in caso contrario, aggiorna un'entità esistente. Tuttavia, è possibile usare gli ETag per ulteriormente vincolare gli upsert per impedire la creazione o l'aggiornamento.

Impedisci creazione in upsert

Se stai aggiornando i dati e c'è una possibilità che l'entità sia stata eliminata intenzionalmente, non vorrai ricreare l'entità. Per evitare questo, aggiungi un'intestazione If-Match alla richiesta con un valore di "*".

  • Richiesta

    PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-Match: "*"

{
    "name": "Updated Sample Account ",
    "creditonhold": true,
    "address1_latitude": 47.639583,
    "description": "This is the updated description of the sample account",
    "revenue": 6000000,
    "accountcategorycode": 2
}

  • Risposta
    Se viene rilevata l'entità, otterrai una risposta normale con stato 204 (No Content). Quando non viene rilevata l'entità, otterrai la seguente risposta con stato 404 (Not Found).

    HTTP/1.1 404 Not Found
OData-Version: 4.0
Content-Type: application/json; odata.metadata=minimal

{
 "error": {
  "code": "",
  "message": "account With Id = 00000000-0000-0000-0000-000000000001 Does Not Exist",
  "innererror": {
   "message": "account With Id = 00000000-0000-0000-0000-000000000001 Does Not Exist",
   "type": "System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
   "stacktrace": <stack trace removed for brevity>
  }
 }
}

Impedisci aggiornamento in upsert

Se stai inserendo i dati, è possibile che un record con lo stesso valore id esista già nel sistema ed è possibile che non desideri eseguirne l'aggiornamento. Per evitare questo, aggiungi un'intestazione If-None-Match alla richiesta con un valore di "*".

  • Richiesta

    PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: "*"

{
    "name": "Updated Sample Account ",
    "creditonhold": true,
    "address1_latitude": 47.639583,
    "description": "This is the updated description of the sample account",
    "revenue": 6000000,
    "accountcategorycode": 2
}

  • Risposta
    Se viene rilevata l'entità, otterrai una risposta normale con stato 204 (No Content). Quando viene rilevata l'entità, otterrai la seguente risposta con stato 412 (Precondition Failed).

    HTTP/1.1 412 Precondition Failed
OData-Version: 4.0
Content-Type: application/json; odata.metadata=minimal

{
  "error":{
   "code":"",
   "message":"A record with matching key values already exists.",
   "innererror":{
    "message":"Cannot insert duplicate key.",
    "type":"System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
    "stacktrace":<stack trace removed for brevity>
    }
  }
}

Applicare la concorrenza ottimistica

Puoi utilizzare la concorrenza ottimistica per rilevare se un'entità è stata modificata da quando è stata recuperata l'ultima volta. Se l'entità da aggiornare o eliminare è cambiata nel server da quando è stata recuperata, non puoi completare l'operazione di aggiornamento o eliminazione. Applicando il modello riportato di seguito puoi rilevare questa situazione, recuperare la versione più recente dell'entità e applicare i criteri necessari per rivalutare se riprovare l'operazione.

Applica la concorrenza ottimistica all'eliminazione

La seguente richiesta di eliminazione per un account con accountid of00000000-0000-0000-0000-000000000001 ha esito negativo perché il valore ETag inviato con l'intestazione If-Match è diverso dal valore corrente. Se il valore corrispondeva, è previsto uno stato 204 (No Content).

  • Richiesta

    DELETE cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
If-Match: W/"470867"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

  • Risposta

    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.",
    "innererror":{
      "message":"The version of the existing record doesn't match the RowVersion property provided.",
      "type":"System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
"stacktrace":"  <stack trace details omitted for brevity>
    }
  }
}

Applica la concorrenza ottimistica all'aggiornamento

La seguente richiesta di aggiornamento per un account con accountid di 00000000-0000-0000-0000-000000000001 ha esito negativo perché il valore ETag inviato con l'intestazione If-Match è diverso dal valore corrente. Se il valore corrispondeva, è previsto uno stato 204 (No Content).

  • Richiesta

    PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
If-Match: W/"470867"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{"name":"Updated Account Name"}

  • Risposta

    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.",
    "innererror":{
      "message":"The version of the existing record doesn't match the RowVersion property provided.",
      "type":"System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
"stacktrace":"  <stack trace details omitted for brevity>
    }
  }
}

Vedere anche

Esempio operazioni condizionali dell'API Web (C#)
Esempio di operazioni condizionali API Web (JavaScript lato client)
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
Eseguire operazioni in batch usando l'API Web
Rappresentare un altro utente usando l'API Web

Microsoft Dynamics 365

© 2017 Microsoft. Tutti i diritti sono riservati. Copyright