Condividi tramite

Aggiornare ed eliminare righe di tabella usando l'API Web

Le operazioni per modificare i dati sono una parte principale dell'API Web. Oltre a semplici operazioni di aggiornamento ed eliminazione, è possibile eseguire operazioni su singole colonne di tabella (attributi di entità) e comporre richieste upsert che aggiorneranno o inseriscono dati a seconda che esistano o meno.

Aggiornamento di base

Le operazioni di aggiornamento usano il verbo HTTP PATCH . Passare un oggetto JSON contenente le proprietà da aggiornare all'URI che rappresenta il record. Se l'aggiornamento ha esito positivo, viene restituita una risposta con stato 204 No Content .

L'intestazione If-Match: * garantisce che non si crei un nuovo record a causa di un'operazione di inserimento o aggiornamento accidentale. Altre informazioni: Impedisci la creazione in upsert.

Importante

Quando si aggiorna un'entità, includere solo le proprietà che si stanno modificando nel corpo della richiesta. Semplicemente aggiornando le proprietà di un'entità recuperata in precedenza e includendo il codice JSON nella richiesta, ogni proprietà verrà aggiornata anche se il valore è lo stesso. Ciò può causare eventi di sistema che possono attivare la logica di business che prevede che i valori siano stati modificati. Ciò può causare l'aggiornamento delle proprietà nei dati di controllo quando in realtà non sono state effettivamente modificate.

Quando si aggiorna la proprietà statecode, è importante impostare sempre il statuscode desiderato. statecode e statuscode hanno valori dipendenti. Possono essere presenti più valori validi statuscode per un determinato statecode valore, ma ogni statecode colonna ha un singolo valore DefaultStatus configurato. Quando si aggiorna statecode senza specificare statuscode, il valore di stato predefinito verrà impostato dal sistema. Inoltre, quando il controllo è abilitato nella tabella e nella statuscode colonna, il valore modificato per la statuscode colonna non verrà acquisito nei dati di controllo, a meno che non sia specificato nell'operazione di aggiornamento.

Annotazioni

La definizione per gli attributi include una RequiredLevel proprietà . Quando questa proprietà è impostata su SystemRequired, non è possibile impostare questi attributi su un valore Null. Altre informazioni: Livello dei requisiti degli attributi

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

Richiesta:

PATCH [Organization URI]/api/data/v9.2/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:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Annotazioni

Per informazioni sull'associazione e la disassociazione delle entità all'aggiornamento, vedere Uso di proprietà di navigazione a valore singolo .

Aggiornare con i dati restituiti

Per recuperare i dati da un'entità che si sta aggiornando, è possibile comporre la PATCH richiesta in modo che i dati del record creato vengano restituiti con lo stato 200 (OK). Per ottenere questo risultato, è necessario usare l'intestazione della richiesta Prefer: return=representation.

Per controllare quali proprietà vengono restituite, aggiungere l'opzione di query $select all'URL dell'insieme di entità. Se usata, l'opzione $expand di query viene ignorata.

Questo esempio aggiorna un'entità account e restituisce i dati richiesti nella risposta.

Richiesta:

PATCH [Organization URI]/api/data/v9.2/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
If-Match: * 
  
{"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": "[Organization URI]/api/data/v9.2/$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"  
}

Aggiornare più record in una singola richiesta

Il modo più rapido per aggiornare più record dello stesso tipo in una singola richiesta consiste nell'usare l'azione UpdateMultiple. Al momento della stesura di questo articolo, l'azione UpdateMultiple. Non tutte le tabelle standard supportano questa azione, ma tutte le tabelle elastiche lo sono.

Ulteriori informazioni:

Aggiornare un singolo valore della proprietà

Quando si desidera aggiornare solo un singolo valore della proprietà, usare una PUT richiesta con il nome della proprietà aggiunto all'URI dell'entità.

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

Richiesta:

PUT [Organization URI]/api/data/v9.2/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

Eliminare un singolo valore della proprietà

Per eliminare il valore di una singola proprietà, usare una DELETE richiesta con il nome della proprietà aggiunto all'URI dell'entità.

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

Richiesta:

DELETE [Organization URI]/api/data/v9.2/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

Annotazioni

Non può essere usato con una proprietà di navigazione a valore singolo per annullare l'associazione di due entità. Per un approccio alternativo, vedi Annullare l'associazione con una proprietà di navigazione a valore singolo.

Inserisci o aggiorna una riga di tabella

Un'operazione upsert è simile a un aggiornamento. Usa una PATCH richiesta e usa un URI per fare riferimento a un record specifico. La differenza è che, se il record non esiste, viene creato. Se esiste già, viene aggiornato.

Upsert è utile quando si sincronizzano i dati tra sistemi esterni. Il sistema esterno potrebbe non contenere un riferimento alla chiave primaria della tabella Dataverse, pertanto è possibile configurare chiavi alternative per la tabella Dataverse usando valori del sistema esterno che identificano in modo univoco il record in entrambi i sistemi. Altre informazioni: Definire chiavi alternative per fare riferimento alle righe

È possibile visualizzare qualsiasi chiave alternativa definita per una tabella nelle annotazioni per il tipo di entità nel documento del servizio $metadata. Altre informazioni: Chiavi alternative.

Nell'esempio seguente è presente una tabella con il nome sample_thing con una chiave alternativa che fa riferimento a due colonne: sample_key1 e sample_key2, che sono entrambe definite per archiviare valori interi.

Richiesta:

PATCH [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1) HTTP/1.1
Accept: application/json 
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Content-Type: application/json

{
    "sample_name": "1:1"
}

Per entrambe le operazioni di creazione o aggiornamento si ottiene la stessa risposta. Si noti che l'intestazione della risposta OData-EntityId utilizza i valori di chiave invece dell'identificatore di chiave primaria GUID per il record.

Risposta:

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1)

Poiché la risposta è la stessa, non è possibile sapere se l'operazione ha rappresentato un'operazione Create o Update .

Se hai bisogno di sapere, puoi usare l'intestazione della richiesta Prefer: return=representation. Con questa intestazione si ottiene una 201 Created risposta quando viene creato un record e una 200 OK risposta quando il record viene aggiornato. Questa opzione aggiunge un'operazione Retrieve che ha un impatto sulle prestazioni. Se usi l'intestazione della richiesta Prefer: return=representation, assicura che $select includa il numero minimo di dati, preferibilmente solo la colonna chiave primaria. Altre informazioni: aggiornare con i dati restituiti e Creare con i dati restituiti.

Quando si usano chiavi alternative, non è consigliabile includere i valori di chiave alternativi nel corpo della richiesta.

  • Quando un upsert rappresenta un Update, questi valori di chiave alternativi vengono ignorati. Non è possibile aggiornare i valori di chiave alternativi durante l'uso per identificare il record.
  • Quando un upsert rappresenta un Create, i valori di chiave nell'URL vengono impostati per il record se non sono presenti nel corpo. Non è quindi necessario includerli nel corpo della richiesta.

Altre informazioni: Usare Upsert per creare o aggiornare un record

Annotazioni

In genere, quando si crea un nuovo record, si consente al sistema di assegnare un valore GUID per la chiave primaria. Si tratta di una procedura consigliata perché il sistema genera chiavi ottimizzate per l'indice e ciò migliora le prestazioni. Tuttavia, se è necessario creare un record con un valore di chiave primaria specifico, ad esempio quando il valore GUID della chiave viene generato da un sistema esterno, l'operazione upsert consente di eseguire questa operazione.

Impedire la creazione o l'aggiornamento con upsert

In alcuni casi è necessario eseguire un oggetto upsert, ma si vuole impedire una delle operazioni potenziali: creare o aggiornare. È possibile eseguire questa operazione utilizzando le intestazioni If-Match o If-None-Match. Per ulteriori informazioni, vedere Limitazioni delle operazioni di upsert.

Eliminazione di base

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

Richiesta:

DELETE [Organization URI]/api/data/v9.2/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, si ottiene una risposta normale con stato 204 per indicare che l'eliminazione è riuscita. Se l'entità non viene trovata, si ottiene una risposta con stato 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Verificare la presenza di record duplicati

Per altre informazioni su come verificare la presenza di record duplicati durante un'operazione di aggiornamento, vedere Rilevare i duplicati durante l'operazione di aggiornamento tramite l'API Web.

Eliminare più record in una singola richiesta

Il modo più rapido per eliminare più record dello stesso tipo in una singola richiesta consiste nell'usare l'azione DeleteMultiple . Al momento della stesura di questo articolo, l'azione DeleteMultiple è una funzionalità di anteprima. Le tabelle standard non supportano questa azione, ma tutte le tabelle elastiche sì.

Annotazioni

Per le tabelle standard, è consigliabile usare l'azione BulkDelete, che consente l'eliminazione asincrona di record che corrispondono a una query. Altre informazioni: Eliminare i dati in blocco

Ulteriori informazioni:

Aggiornare ed eliminare documenti nelle partizioni di archiviazione

Se si aggiornano o si eliminano i dati della tabella elastica archiviati nelle partizioni, assicurarsi di specificare la chiave di partizione durante l'accesso a tali dati.

Altre informazioni: Scelta di un valore PartitionId

Vedere anche

Esempio di operazioni di base dell'API Web (C#)
Esempio di operazioni di base dell'API Web (JavaScript sul lato client)
Eseguire operazioni usando l'API Web
Comporre richieste HTTP e gestire gli errori
Eseguire query di dati utilizzando l'API Web
Creare una riga di tabella usando l'API Web
Recuperare una riga di tabella usando l'API Web
Associare e annullare l'associazione delle righe di tabella usando l'API Web
Usare le funzioni API Web
Utilizzare le azioni API Web
Eseguire operazioni batch con l'API Web
Rappresentare un altro utente usando l'API Web
Eseguire operazioni condizionali usando l'API Web

  • Last updated on