Insert Or Replace Entity

Artikel
06/27/2023

Der Insert Or Replace Entity Vorgang ersetzt eine vorhandene Entität oder fügt eine neue Entität ein, wenn sie in der Tabelle nicht 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 Replace 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 zeilenschlüssels für die zu aktualisierende Entität

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

Emulierter Speicherdienst

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

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

Table Storage im Speicheremulator unterscheidet sich auf verschiedene Weise von Azure Table Storage. Weitere Informationen finden Sie unter Unterschiede zwischen dem Speicheremulator und den 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 Table Storage-Vorgä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 Table Storage-Vorgä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 in den Protokollen aufgezeichnet wird, wenn die Protokollierung konfiguriert ist. 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 Replace Entity Vorgang sendet die Entität, die als Entitätssatz OData eingefügt werden soll. Dieser Entitätssatz kann entweder ein JSON- oder ein Atom-Feed 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 (Kein Inhalt) 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`	Die `ETag` für die Entität.
`x-ms-request-id`	Identifiziert die durchgeführte Anforderung eindeutig 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 den Zeitpunkt angibt, zu dem die Antwort initiiert wurde. Der Dienst generiert diesen Wert.
`x-ms-client-request-id`	Kann zur Problembehandlung von Anforderungen und entsprechenden Antworten verwendet werden. Der Wert dieses Headers ist gleich dem Wert des `x-ms-client-request-id` Headers, wenn er in der Anforderung vorhanden ist. Der Wert beträgt 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 jeder mit einer Shared Access Signature, die über die Berechtigung zum Ausführen dieses Vorgangs verfügt, dies tun.

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.

PUT 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

Atom-Feed (Versionen vor 2015-12-11)

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

PUT 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='myrowkey1')</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 Replace Entity Vorgang verwendet nicht den If-Match Header. Sie müssen diesen Vorgang mit der Version 2011-08-18 oder höher aufrufen. Diese Attribute unterscheiden diesen Vorgang vom Vorgang Entität aktualisieren .

Wenn Sie den Insert Or Replace Entity Vorgang verwenden, um eine Entität zu ersetzen, werden alle Eigenschaften der vorherigen Entität entfernt, wenn die neue Entität sie nicht definiert. Eigenschaften mit einem null Wert werden ebenfalls entfernt.

Wenn Sie den Insert or Replace 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 0000001, um eine ordnungsgemäße Sortierung sicherzustellen.

Um eine Eigenschaft explizit einzugeben, geben Sie den entsprechenden OData Datentyp 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 PUT Anforderung autorisieren und senden kann, kann eine Entität einfügen oder ersetzen.

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