Condividi tramite

Aggiornare ed eliminare righe di tabella usando l'API Web

Le operazioni che modificano 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 aggiornano o inseriscono i 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, la risposta restituisce lo 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. Per altre informazioni, vedi Impedire la creazione in upsert.

Importante

Quando si aggiorna un'entità, includere solo le proprietà che si stanno modificando nel corpo della richiesta. Se si aggiorna un'entità includendo tutte le proprietà di un'entità recuperata in precedenza, l'operazione aggiorna ogni proprietà anche se il valore è lo stesso. Questo aggiornamento può causare eventi di sistema che attivano la logica di business che prevede che i valori siano stati modificati. Può far sembrare che le proprietà siano state aggiornate nei dati di controllo quando in realtà non sono cambiate.

Quando si aggiorna la statecode proprietà, impostare sempre il valore desiderato statuscode. I statecode valori e statuscode dipendono l'uno dall'altro. Per un determinato statecode valore, possono essere presenti più valori validi statuscode . Tuttavia, ogni statecode colonna ha un singolo valore DefaultStatus configurato. Quando si esegue l'aggiornamento di statecode senza specificare statuscode, il sistema imposta il valore di stato predefinito. Inoltre, se si abilita il controllo nella tabella e nella statuscode colonna, il valore modificato per la statuscode colonna non viene acquisito nei dati di controllo, a meno che non venga 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. Per altre informazioni, vedere 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, comporre la PATCH richiesta in modo che restituisca dati dal record aggiornato con stato 200 (OK). Per ottenere questo risultato, usare l'header di richiesta Prefer: return=representation.

Per controllare quali proprietà vengono restituite, aggiungere l'opzione $select di query all'URL del set 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. Non tutte le tabelle standard supportano questa azione, ma tutte le tabelle elastiche lo sono.

Ulteriori informazioni:

Aggiornare un singolo valore della proprietà

Per aggiornare un singolo valore della proprietà, usare una PUT richiesta e aggiungere il nome della proprietà all'URI dell'entità.

Nell'esempio seguente, viene aggiornata la proprietà name di una riga esistente account al valore accountid di 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à di account con valore accountid di 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 è possibile usare questo approccio con una proprietà di navigazione a valore singolo per annullare l'associazione di due entità. Per un approccio alternativo, vedere Disassociare usando 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 i 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. Usando 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 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 durante la creazione di un nuovo record si consente al sistema di assegnare un valore GUID per la chiave primaria. Questa procedura è ottimale perché il sistema genera chiavi ottimizzate per l'indice e questa scelta 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, si desidera eseguire un upsert ma impedire una delle possibili operazioni: creare o aggiornare. È possibile impedire queste operazioni usando 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

Per eliminare più record dello stesso tipo in una singola richiesta, usare l'azione DeleteMultiple . Le tabelle standard non supportano questa azione DeleteMultiple, ma tutte le tabelle elastiche sì.

Annotazioni

Per le tabelle standard, usare l'azione BulkDelete. Questa azione consente l'eliminazione di record che corrispondono a una query in modo asincrono. Per altre informazioni, vedere 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, specificare la chiave di partizione quando si accede 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