Insert Or Merge Entity

Articolo
06/27/2023

L'operazione Insert Or Merge Entity aggiorna un'entità esistente o inserisce una nuova entità se non esiste nella tabella. Poiché questa operazione può inserire o aggiornare un'entità, è nota anche come operazione upsert .

Richiesta

È possibile costruire la Insert Or Merge Entity richiesta come indicato di seguito. È consigliato il protocollo HTTPS. Sostituire i valori seguenti con valori personalizzati:

myaccount con l'account di archiviazione
mytable con il nome della tabella
myPartitionKey e myRowKey con il nome della chiave di partizione e della chiave di riga per l'entità da aggiornare

Metodo	URI richiesta	Versione HTTP
`MERGE`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Servizio di archiviazione emulato

Quando si effettua una richiesta per il servizio di archiviazione emulato, specificare il nome host dell'emulatore e la porta di archiviazione tabelle di Azure come 127.0.0.1:10002, seguito dal nome dell'account di archiviazione emulato.

Metodo	URI richiesta	Versione HTTP
`MERGE`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Archiviazione tabelle nell'emulatore di archiviazione differisce da Archiviazione tabelle di Azure in diversi modi. Per altre informazioni, vedere Differenze tra l'emulatore di archiviazione e i servizi di archiviazione di Azure.

Parametri URI

È possibile specificare il parametro aggiuntivo seguente nell'URI della richiesta.

Parametro	Descrizione
`timeout`	Facoltativa. Il parametro `timeout` viene espresso in secondi. Per altre informazioni, vedere Impostazione dei timeout per le operazioni di archiviazione tabelle.

Intestazioni della richiesta

Nella seguente tabella vengono descritte le intestazioni di richiesta obbligatorie e facoltative.

Intestazione della richiesta	Descrizione
`Authorization`	Obbligatorio. Specifica lo schema di autorizzazione, il nome dell'account e la firma. Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
`Date` o `x-ms-date`	Obbligatorio. Specifica la data per la richiesta nel fuso orario UTC (Coordinated Universal Time). Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
`x-ms-version`	Obbligatorio. Deve essere impostato su 2011-08-18 o versione successiva. Specifica la versione dell'operazione da usare per questa richiesta. Per altre informazioni, vedere Controllo delle versioni per i servizi di archiviazione di Azure.
`Content-Type`	Obbligatorio. Specifica il tipo di contenuto del payload. I valori possibili sono `application/atom+xml` e `application/json`. Per altre informazioni sui tipi di contenuto validi, vedere Formato del payload per le operazioni di archiviazione tabelle.
`Content-Length`	Obbligatorio. Lunghezza del corpo della richiesta.
`x-ms-client-request-id`	Facoltativa. Fornisce un valore opaco generato dal client con un limite di caratteri di 1 kibibyte (KiB) registrato nei log al momento della configurazione della registrazione. È consigliabile usare questa intestazione per correlare le attività lato client alle richieste ricevute dal server. Per altre informazioni, vedere Monitorare l'archiviazione tabelle di Azure.

Testo della richiesta

L'operazione Insert Or Merge Entity invia l'entità da inserire come OData set di entità. Questo set di entità può essere un payload Atom o JSON. Per altre informazioni, vedere Inserimento e aggiornamento di entità.

Nota

JSON è il formato di payload consigliato ed è l'unico formato supportato per la versione 2015-12-11 e successive.

Risposta

Nella risposta sono inclusi un codice di stato HTTP e un set di intestazioni per la risposta.

Codice stato

Un'operazione completata restituisce il codice di stato 204 (No Content). Per informazioni sui codici di stato, vedere Codici di errore e di stato e codici di errore di archiviazione tabelle.

Intestazioni di risposta

Nella risposta sono incluse le intestazioni seguenti. La risposta può includere anche intestazioni HTTP standard aggiuntive. Tutte le intestazioni standard sono conformi alla specifica del protocollo HTTP/1.1.

Intestazione risposta	Descrizione
`ETag`	Oggetto `ETag` per l'entità.
`x-ms-request-id`	Identifica in modo univoco la richiesta effettuata e può essere usata per la risoluzione dei problemi della richiesta. Per altre informazioni, vedere Risoluzione dei problemi relativi alle operazioni api.
`x-ms-version`	Indica la versione di Archiviazione tabelle utilizzata per eseguire la richiesta. Questa intestazione viene restituita per le richieste effettuate nella versione 2009-09-19 e successive.
`Date`	Valore di data/ora UTC che indica l'ora in cui è stata avviata la risposta. Il servizio genera questo valore.
`x-ms-client-request-id`	Può essere usato per risolvere i problemi relativi alle richieste e alle risposte corrispondenti. Il valore di questa intestazione è uguale al valore dell'intestazione `x-ms-client-request-id` , se presente nella richiesta. Il valore è al massimo 1.024 caratteri ASCII visibili. Se l'intestazione `x-ms-client-request-id` non è presente nella richiesta, non sarà presente nella risposta.

Corpo della risposta

Nessuno.

Autorizzazione

Il proprietario dell'account può eseguire questa operazione. Inoltre, chiunque disponga di una firma di accesso condiviso che dispone dell'autorizzazione per eseguire questa operazione può farlo.

Richiesta e risposta di esempio

Gli esempi seguenti illustrano le richieste di esempio che usano feed JSON e Atom.

Nota

JSON è il formato di payload consigliato ed è l'unico formato supportato per la versione 2015-12-11 e successive.

JSON (versione 2013-08-15 e successive)

Di seguito è riportata una richiesta e una risposta di esempio che usa JSON.

MERGE https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey',RowKey='myRowKey')

La richiesta viene inviata con le intestazioni seguenti:

x-ms-version: 2013-08-15  
Content-Type: application/json  
x-ms-date: Tue, 30 Aug 2013 18:10:24 GMT  
Authorization: SharedKeyLite myaccount:u0sWZKmjBD1B7LY/CwXWCnHdqK4B1P4z8hKy9SVW49o=  
Content-Length: 1135  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx

La richiesta viene inviata con il corpo JSON seguente:

{  
   "Address":"Santa Clara",  
   "Age":23,  
   "AmountDue":200.23,  
   "CustomerCode@odata.type":"Edm.Guid",  
   "CustomerCode":"c9da6455-213d-42c9-9a79-3e9149a57833",  
   "CustomerSince@odata.type":"Edm.DateTime",  
   "CustomerSince":"2008-07-10T00:00:00",  
   "IsActive":false,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey"  
}

Dopo l'invio della richiesta viene restituita la risposta seguente:

  
HTTP/1.1 204 No Content  
  
Connection: Keep-Alive  
x-ms-request-id: 2c085f8f-11a4-4e1d-bd49-82c6bd87649d  
Content-Length: 0  
Cache-Control: no-cache  
Date: Tue, 30 Aug 2013 18:12:54 GMT  
ETag: W/"0x5B168C7B6E589D2"  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  
Server: Windows-Azure-Table/1.0 Microsoft-HTTPAPI/2.0

Feed Atom (versioni precedenti alla versione 2015-12-11)

Di seguito è riportata una richiesta e una risposta di esempio che usa Atom:

MERGE https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey',RowKey='myRowKey')

La richiesta viene inviata con le intestazioni seguenti:

x-ms-version: 2013-08-15  
Accept: application/atom+xml,application/xml  
Accept-Charset: UTF-8  
Content-Type: application/atom+xml  
x-ms-date: Tue, 12 Nov 2013 18:10:24 GMT  
Authorization: SharedKeyLite myaccount:u0sWZKmjBD1B7LY/CwXWCnHdqK4B1P4z8hKy9SVW49o=  
Content-Length: 1135  
DataServiceVersion: 1.0;NetFx  
MaxDataServiceVersion: 2.0;NetFx

La richiesta viene inviata con il corpo XML seguente:

<?xml version="1.0" encoding="utf-8"?>  
<entry xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="https://www.w3.org/2005/Atom">  
  <title />  
  <updated>2013-11-12T18:09:37.168836Z</updated>  
  <author>  
    <name />  
  </author>  
<id>https://myaccount.table.core.windows.net/mytable(PartitionKey='mypartitionkey',RowKey='myrowkey')</id>  
  <content type="application/xml">  
    <m:properties>  
      <d:Address>Santa Clara</d:Address>  
      <d:Age m:type="Edm.Int32">23</d:Age>  
      <d:AmountDue m:type="Edm.Double">200.23</d:AmountDue>  
      <d:CustomerCode m:type="Edm.Guid">c9da6455-213d-42c9-9a79-3e9149a57833</d:CustomerCode>  
      <d:CustomerSince m:type="Edm.DateTime">2008-07-10T00:00:00Z</d:CustomerSince>  
      <d:IsActive m:type="Edm.Boolean">false</d:IsActive>  
      <d:NumOfOrders m:type="Edm.Int64">255</d:NumOfOrders>  
      <d:PartitionKey>mypartitionkey</d:PartitionKey>  
      <d:RowKey>myrowkey1</d:RowKey>  
    </m:properties>  
  </content>  
</entry>

Dopo l'invio della richiesta viene restituita la risposta seguente:

HTTP/1.1 204 No Content  
  
Connection: Keep-Alive  
x-ms-request-id: 2c085f8f-11a4-4e1d-bd49-82c6bd87649d  
Content-Length: 0  
Cache-Control: no-cache  
Date: Tue, 12 Nov 2013 18:12:54 GMT  
ETag: W/"0x5B168C7B6E589D2"  
DataServiceVersion: 1.0;NetFx  
MaxDataServiceVersion: 2.0;NetFx  
Server: Windows-Azure-Table/1.0 Microsoft-HTTPAPI/2.0

Commenti

L'operazione Insert Or Merge Entity usa il MERGE verbo . È necessario chiamare l'operazione usando la versione 2011-08-18 o successiva. Inoltre, questa operazione non usa l'intestazione If-Match . Questi attributi consentono di fare distinzione tra questa operazione e l'operazione Update Entity, sebbene il corpo della richiesta sia lo stesso per entrambe.

Se si usa l'operazione Insert Or Merge Entity per unire un'entità, tutte le proprietà dell'entità precedente vengono mantenute, se la richiesta non li definisce o li include. Vengono mantenute anche le proprietà con un null valore.

Quando si chiama l'operazione Insert or Merge Entity , è necessario specificare i valori per le PartitionKey proprietà di sistema e RowKey . Insieme, queste proprietà formano la chiave primaria e devono essere univoce all'interno della tabella.

Entrambi i PartitionKey valori e RowKey devono essere valori stringa. Ogni valore chiave può avere dimensioni fino a 64 KiB. Se si usa un valore intero per il valore della chiave, è necessario convertire l'intero in una stringa a larghezza fissa. Ciò è dovuto al fatto che sono ordinati in modo canonico. Ad esempio, convertire il valore 1 in 0000001 per garantire l'ordinamento corretto.

Per digitare in modo esplicito una proprietà, specificare il tipo appropriato OData impostando l'attributo m:type all'interno della definizione della proprietà nel feed Atom. Per altre informazioni sulla digitazione delle proprietà, vedere Inserimento e aggiornamento delle entità.

Qualsiasi applicazione in grado di autorizzare e inviare una HTTP MERGE richiesta può inserire o aggiornare un'entità.

Per informazioni sull'esecuzione di operazioni di upsert batch, vedere Esecuzione di transazioni del gruppo di entità.

Vedi anche

Autorizzare le richieste ad Archiviazione di Azure
Impostazione delle intestazioni della versione del servizio dati OData
Inserimento e aggiornamento di entità
Stato e codici errore
Codici di errore di archiviazione tabelle