Insert Or Merge Entity

Artikel
06/27/2023

Der Insert Or Merge Entity Vorgang aktualisiert eine vorhandene Entität oder fügt eine neue Entität ein, wenn sie nicht in der Tabelle vorhanden ist. Da dieser Vorgang eine Entität einfügen oder aktualisieren kann, wird er auch als Upsert-Vorgang bezeichnet.

Anforderung

Sie können die Insert Or Merge Entity Anforderung wie folgt erstellen. HTTPS wird empfohlen. Ersetzen Sie die folgenden Werte durch eigene Werte:

myaccount durch den Namen des Speicherkontos
mytable durch den Namen der Tabelle
myPartitionKey und myRowKey mit dem Namen des Partitionsschlüssels und des Zeilenschlüssels für die zu aktualisierende Entität

Methode	Anforderungs-URI	HTTP-Version
`MERGE`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Emulierter Speicherdienst

Wenn Sie eine Anforderung für den emulierten Speicherdienst stellen, geben Sie den Hostnamen des Emulators und den Azure Table Storage-Port als 127.0.0.1:10002 an, gefolgt vom Namen des emulierten Speicherkontos.

Methode	Anforderungs-URI	HTTP-Version
`MERGE`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Der Tabellenspeicher im Speicheremulator unterscheidet sich in vielerlei Hinsicht vom Azure Table Storage. Weitere Informationen finden Sie unter Unterschiede zwischen dem Speicheremulator und Azure Storage-Diensten.

URI-Parameter

Sie können den folgenden zusätzlichen Parameter für den Anforderungs-URI angeben.

Parameter	BESCHREIBUNG
`timeout`	Optional. Der `timeout`-Parameter wird in Sekunden angegeben. Weitere Informationen finden Sie unter Festlegen von Timeouts für Tabellenspeichervorgänge.

Anforderungsheader

In der folgenden Tabelle werden erforderliche und optionale Anforderungsheader beschrieben.

Anforderungsheader	BESCHREIBUNG
`Authorization`	Erforderlich. Gibt das Autorisierungsschema, den Kontonamen und die Signatur an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
`Date` oder `x-ms-date`	Erforderlich. Gibt die koordinierte Weltzeit (Coordinated Universal Time, UTC) für die Anforderung an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
`x-ms-version`	Erforderlich. Muss auf 2011-08-18 oder höher festgelegt werden. Gibt die Version des für die Anforderung zu verwendenden Vorgangs an. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure-Speicherdienste.
`Content-Type`	Erforderlich. Gibt den Inhaltstyp der Nutzlast an. Mögliche Werte sind `application/atom+xml` und `application/json`. Weitere Informationen zu gültigen Inhaltstypen finden Sie unter Nutzlastformat für Tabellenspeichervorgänge.
`Content-Length`	Erforderlich. Die Länge des Anforderungstexts.
`x-ms-client-request-id`	Optional. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem Zeichenlimit von 1 Kibibyte (KiB) bereit, der beim Konfigurieren der Protokollierung in den Protokollen aufgezeichnet wird. Es wird dringend empfohlen, diesen Header zu verwenden, um clientseitige Aktivitäten mit Anforderungen zu korrelieren, die der Server empfängt. Weitere Informationen finden Sie unter Überwachen von Azure Table Storage.

Anforderungstext

Der Insert Or Merge Entity Vorgang sendet die Entität, die als Entitätssatz OData eingefügt werden soll. Dieser Entitätssatz kann entweder eine Atom- oder JSON-Nutzlast sein. Weitere Informationen finden Sie unter Einfügen und Aktualisieren von Entitäten.

Hinweis

JSON ist das empfohlene Nutzlastformat und das einzige Format, das für Version 2015-12-11 und höher unterstützt wird.

Antwort

Die Antwort enthält den HTTP-Statuscode und einen Satz von Antwortheadern.

Statuscode

Bei einem erfolgreichen Vorgang wird der Statuscode 204 (No Content) zurückgegeben. Informationen zu status-Codes finden Sie unter Status- und Fehlercodes und Tabellenspeicherfehlercodes.

Antwortheader

Die Antwort enthält die folgenden Header. Die Antwort kann auch zusätzliche HTTP-Standardheader enthalten. Alle Standardheader entsprechen der HTTP/1.1-Protokollspezifikation.

Antwortheader	BESCHREIBUNG
`ETag`	Der `ETag` für die Entität.
`x-ms-request-id`	Identifiziert eindeutig die Anforderung, die gestellt wurde, und kann für die Problembehandlung der Anforderung verwendet werden. Weitere Informationen finden Sie unter Problembehandlung für API-Vorgänge.
`x-ms-version`	Gibt die Version von Table Storage an, die zum Ausführen der Anforderung verwendet wird. Dieser Header wird für Anforderungen zurückgegeben, die für Version 2009-09-19 und höher erfolgen.
`Date`	Ein UTC-Datums-/Uhrzeitwert, der die Uhrzeit angibt, zu der die Antwort initiiert wurde. Der Dienst generiert diesen Wert.
`x-ms-client-request-id`	Kann verwendet werden, um Anforderungen und entsprechende Antworten zu behandeln. Der Wert dieses Headers entspricht dem Wert des `x-ms-client-request-id` Headers, wenn er in der Anforderung vorhanden ist. Der Wert ist höchstens 1.024 sichtbare ASCII-Zeichen. Wenn der `x-ms-client-request-id` Header in der Anforderung nicht vorhanden ist, ist er in der Antwort nicht vorhanden.

Antworttext

Keine.

Authorization

Der Kontobesitzer kann diesen Vorgang ausführen. Darüber hinaus kann dies jeder benutzer mit einer freigegebenen Zugriffssignatur tun, die über die Berechtigung zum Ausführen dieses Vorgangs verfügt.

Beispielanforderung und -antwort

Die folgenden Beispiele zeigen Beispielanforderungen, die JSON- und Atom-Feeds verwenden.

Hinweis

JSON ist das empfohlene Nutzlastformat und das einzige Format, das für Version 2015-12-11 und höher unterstützt wird.

JSON (Version 2013-08-15 und höher)

Es folgt eine Beispielanforderung und -antwort, die JSON verwendet.

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

Die Anforderung wird mit den folgenden Headern gesendet;

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

Die Anforderung wird mit dem folgenden JSON-Text gesendet:

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

Nachdem die Anforderung gesendet wurde, wird die folgende Antwort zurückgegeben:

  
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

Atomvorschub (Versionen vor 11.12.2015)

Es folgt eine Beispielanforderung und -antwort, die Atom verwendet:

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

Die Anforderung wird mit den folgenden Headern gesendet;

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

Die Anforderung wird mit dem folgenden XML-Text gesendet:

<?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>

Nachdem die Anforderung gesendet wurde, wird die folgende Antwort zurückgegeben:

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

Hinweise

Der Insert Or Merge Entity Vorgang verwendet das MERGE Verb. Sie müssen den Vorgang mit der Version 2011-08-18 oder höher aufrufen. Darüber hinaus wird bei diesem Vorgang der Header nicht verwendet If-Match . Durch diese Attribute unterscheidet sich dieser Vorgang vom Update Entity-Vorgang, beide Vorgänge enthalten jedoch den gleichen Anforderungstext.

Wenn Sie den Insert Or Merge Entity Vorgang zum Zusammenführen einer Entität verwenden, werden alle Eigenschaften der vorherigen Entität beibehalten, wenn die Anforderung sie nicht definiert oder enthält. Eigenschaften mit einem null Wert werden ebenfalls beibehalten.

Wenn Sie den Insert or Merge Entity Vorgang aufrufen, müssen Sie Werte für die PartitionKey Systemeigenschaften und RowKey angeben. Zusammen bilden diese Eigenschaften den Primärschlüssel und müssen innerhalb der Tabelle eindeutig sein.

Sowohl die PartitionKey Werte als RowKey auch müssen Zeichenfolgenwerte sein. Jeder Schlüsselwert kann bis zu 64 KiB groß sein. Wenn Sie einen ganzzahligen Wert für den Schlüsselwert verwenden, sollten Sie die ganze Zahl in eine Zeichenfolge mit fester Breite konvertieren. Dies liegt daran, dass sie kanonisch sortiert sind. Konvertieren Sie beispielsweise den Wert 1 in, um 0000001 eine ordnungsgemäße Sortierung sicherzustellen.

Um eine Eigenschaft explizit einzugeben, geben Sie den entsprechenden OData Typ an, indem Sie das m:type Attribut innerhalb der Eigenschaftendefinition im Atom-Feed festlegen. Weitere Informationen zum Eingeben von Eigenschaften finden Sie unter Einfügen und Aktualisieren von Entitäten.

Jede Anwendung, die eine HTTP MERGE Anforderung autorisieren und senden kann, kann eine Entität einfügen oder aktualisieren.

Informationen zum Ausführen von Batchupervorgängen finden Sie unter Durchführen von Entitätsgruppentransaktionen.

Weitere Informationen

Autorisieren von Anforderungen an Azure Storage
Festlegen der OData-Datendienstversionsheader
Einfügen und Aktualisieren von Entitäten
Status- und Fehlercodes
Tabellenspeicherfehlercodes