Condividi tramite

Aggiorna ed elimina le entità con 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

Le operazioni per modificare i dati sono una parte centrale dell'API Web. Oltre a un aggiornamento e un'eliminazione semplice puoi eseguire operazioni in singoli attributi e comporre le richieste upsert che aggiorneranno o inseriranno un'entità in base a se esiste.

Nota

I metadati che definiscono le entità vengono aggiornati in un modo diverso.Ulteriori informazioni:Creare e aggiornare definizioni di entità tramite la Web API

In questo argomento

Aggiornamento di base

Aggiornamento con dati restituiti

Aggiorna un unico valore proprietà

Elimina un unico valore proprietà

Upsert di un'entità

Eliminazione di base

Aggiornamento di base

Le operazioni di aggiornamento utilizzano il verbo HTTP PATCH. Passa un oggetto JSON che contiene le proprietà che desideri aggiornare all'URI che rappresenta l'entità. Una risposta con stato di 204 verrà restituita se l'aggiornamento ha esito positivo.

Questo esempio aggiorna un record di account esempio con il valore accountid di 00000000-0000-0000-0000-000000000001.

Importante

Quando viene aggiornata un'entità, includi solo le proprietà che si stanno modificando nel messaggio di richiesta. Il semplice aggiornamento delle proprietà di un'entità recuperate in precedenza che includono JSON nella richiesta, aggiornerà ogni proprietà anche se il valore è lo stesso. In questo modo potrebbe sembrare che le proprietà siano stato aggiornate nei dati di controllo mentre in effetti non sono state effettivamente modificate.

  • 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

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

    HTTP/1.1 204 No Content
OData-Version: 4.0

Nota

Per informazioni sull'associazione delle entità al momento dell'aggiornamento, vedi Associa le entità in fase di aggiornamento.

Aggiornamento con dati restituiti

Nota

Questa funzionalità è stata aggiunta con Aggiornamento di dicembre 2016 per Dynamics 365 (online e locale).

Per recuperare i dati da un'entità che stai aggiornando puoi creare la richiesta PATCH in modo che i dati del record creato vengano restituiti con lo stato 200 (OK). Per ottenere questo risultato, devi usare la preferenza return=representation nelle intestazioni della richiesta.

Per controllare quali proprietà vengono restituite, aggiungi l'opzione di query $select all'URL del set di entità. L'opzione di query $expand verrà ignorata se utilizzata.

In questo esempio esegui l'aggiornamento di un'entità account che restituisce i dati richiesti nella risposta.

  • Richiesta

    PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
Prefer: return=representation

{"name":"Updated Sample Account"}

  • Risposta

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

{
    "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts/$entity",
    "@odata.etag": "W/\"536537\"",
    "accountid": "00000000-0000-0000-0000-000000000001",
    "accountcategorycode": 1,
    "description": "This is the description of the sample account",
    "address1_latitude": 47.63958,
    "creditonhold": false,
    "name": "Updated Sample Account",
    "createdon": "2016-09-28T23:14:00Z",
    "revenue": 5000000.0000,
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"
}

Aggiorna un unico valore proprietà

Se desideri aggiornare un solo valore di proprietà utilizza una richiesta PUT con il nome proprietà aggiunto all'Uri dell'entità.

Nell'esempio seguente viene aggiornata la proprietà name di un'entità di account esistente con il valore accountid di 00000000-0000-0000-0000-000000000001.

  • Richiesta

    PUT cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{"value": "Updated Sample Account Name"}

  • Risposta

    HTTP/1.1 204 No Content
OData-Version: 4.0

Elimina un unico valore proprietà

Per eliminare il valore di una singola proprietà utilizza una richiesta DELETE con il nome proprietà aggiunto all'Uri dell'entità.

Nell'esempio seguente viene eliminato il valore della proprietà description di un'entità di account esistente con il valore accountid di 00000000-0000-0000-0000-000000000001.

  • Richiesta

    DELETE cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/description HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

  • Risposta

    HTTP/1.1 204 No Content
OData-Version: 4.0

Nota

Questa non può essere utilizzata con una proprietà di navigazione a valore singolo per annullare l'associazione tra due entità. Per un approccio alternativo, vedi Rimuovi un riferimento a un'entità.

Upsert di un'entità

Un'operazione upsert è esattamente come un aggiornamento. Utilizza una richiesta PATCH e utilizza un URI per fare riferimento a un'entità specifica. La differenza è che se l'entità non esiste questa verrà creata. Se esiste già, verrà aggiornata. In genere quando si crea una nuova entità si lascerà che il sistema assegni un identificatore univoco. Questa è una procedura consigliata. Ma se devi creare un record con un valore specifico id, un'operazione upsert fornisce una modalità per eseguire questa operazione. Ciò può risultare utile in una situazione in cui si stanno sincronizzando i dati in sistemi diversi.

Talvolta in alcuni casi preferirai eseguire un upsert, ma desideri evitare una delle possibili azioni predefinite: creazione o aggiornamento. Puoi ottenere questo risultato tramite l'aggiunta dell'intestazione If-Match o If-None-Match. Per ulteriori informazioni, vedere Operazioni di upsert limitate.

Eliminazione di base

Un'operazione di eliminazione è un processo molto semplice. Utilizza il verbo DELETE con l'URI dell'entità che desideri eliminare. Questo messaggio di esempio elimina un'entità account con il valore accountid della chiave primaria uguale a 00000000-0000-0000-0000-000000000001.

  • Richiesta

    DELETE cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

  • Risposta
    Se l'entità esiste, otterrai una risposta con stato 204 che indica la corretta eliminazione. Se non viene rilevata l'entità, otterrai una risposta con stato 404.

    HTTP/1.1 204 No Content
OData-Version: 4.0

Vedere anche

Esempio di operazioni di base dell'API Web (C#)
Esempio di operazioni di base 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
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
Eseguire operazioni condizionali tramite l'API Web

Microsoft Dynamics 365

© 2017 Microsoft. Tutti i diritti sono riservati. Copyright