Infoga eller ersätt entitet

Artikel
06/27/2023

Åtgärden Insert Or Replace Entity ersätter en befintlig entitet eller infogar en ny entitet om den inte finns i tabellen. Eftersom den här åtgärden kan infoga eller uppdatera en entitet kallas den även för en upsert-åtgärd .

Förfrågan

Du kan skapa begäran på Insert Or Replace Entity följande sätt. HTTPS rekommenderas. Ersätt följande värden med dina egna:

myaccount med namnet på ditt lagringskonto
mytable med namnet på tabellen
myPartitionKey och myRowKey med namnet på partitionsnyckeln och radnyckeln för entiteten som ska uppdateras

Metod	URI för förfrågan	HTTP-version
`PUT`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Emulerad lagringstjänst

När du gör en begäran mot den emulerade lagringstjänsten anger du emulatorns värdnamn och Azure Table Storage-porten som 127.0.0.1:10002, följt av det emulerade lagringskontonamnet.

Metod	URI för förfrågan	HTTP-version
`PUT`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Table Storage i Storage-emulatorn skiljer sig från Azure Table Storage på flera olika sätt. Mer information finns i Skillnader mellan Storage-emulatorn och Azure Storage-tjänsterna.

URI-parametrar

Du kan ange följande ytterligare parameter i begärande-URI:n.

Parameter	Beskrivning
`timeout`	Valfritt. Parametern `timeout` uttrycks i sekunder. Mer information finns i Ange tidsgränser för Table Storage-åtgärder.

Begärandehuvuden

I följande tabell beskrivs obligatoriska och valfria begärandehuvuden.

Begärandehuvud	Beskrivning
`Authorization`	Krävs. Anger auktoriseringsschema, kontonamn och signatur. Mer information finns i Auktorisera begäranden till Azure Storage.
`Date` eller `x-ms-date`	Krävs. Anger Coordinated Universal Time (UTC) för begäran. Mer information finns i Auktorisera begäranden till Azure Storage.
`x-ms-version`	Krävs. Måste anges till 2011-08-18 eller senare. Anger vilken version av åtgärden som ska användas för den här begäran. Mer information finns i Versionshantering för Azure Storage-tjänsterna.
`Content-Type`	Krävs. Anger nyttolastens innehållstyp. Möjliga värden är `application/atom+xml` och `application/json`. Mer information om giltiga innehållstyper finns i Nyttolastformat för Table Storage-åtgärder.
`Content-Length`	Krävs. Längden på begärandetexten.
`x-ms-client-request-id`	Valfritt. Tillhandahåller ett klientgenererat, täckande värde med en teckengräns på 1 kibibyte (KiB) som registreras i loggarna när loggningen har konfigurerats. Vi rekommenderar starkt att du använder det här huvudet för att korrelera aktiviteter på klientsidan med begäranden som servern tar emot. Mer information finns i Övervaka Azure Table Storage.

Begärandetext

Åtgärden Insert Or Replace Entity skickar entiteten som ska infogas som en entitetsuppsättning OData . Den här entitetsuppsättningen kan vara antingen en JSON eller en Atom-feed. Mer information finns i Infoga och uppdatera entiteter.

Anteckning

JSON är det rekommenderade nyttolastformatet och är det enda format som stöds för version 2015-12-11 och senare.

Svarsåtgärder

Svaret innehåller en HTTP-statuskod och en uppsättning svarshuvuden.

Statuskod

En lyckad åtgärd returnerar statuskoden 204 (inget innehåll). Information om statuskoder finns i Status- och felkoder och Tabelllagringsfelkoder.

Svarshuvuden

Svaret innehåller följande rubriker. Svaret kan också innehålla ytterligare standard-HTTP-huvuden. Alla standardhuvuden överensstämmer med HTTP/1.1-protokollspecifikationen.

Svarsrubrik	Description
`ETag`	För `ETag` entiteten.
`x-ms-request-id`	Identifierar unikt den begäran som gjordes och kan användas för att felsöka begäran. Mer information finns i Felsöka API-åtgärder.
`x-ms-version`	Anger vilken version av Table Storage som används för att köra begäran. Det här huvudet returneras för begäranden mot version 2009-09-19 och senare.
`Date`	Ett UTC-datum/tid-värde som anger den tid då svaret initierades. Tjänsten genererar det här värdet.
`x-ms-client-request-id`	Kan användas för att felsöka begäranden och motsvarande svar. Värdet för det här huvudet är lika med värdet för `x-ms-client-request-id` huvudet, om det finns i begäran. Värdet är högst 1 024 synliga ASCII-tecken. `x-ms-client-request-id` Om rubriken inte finns i begäran visas den inte i svaret.

Själva svaret

Inga.

Auktorisering

Kontoägaren kan utföra den här åtgärden. Dessutom kan alla med en signatur för delad åtkomst som har behörighet att utföra den här åtgärden göra det.

Exempel på begäran och svar

I följande exempel visas exempelbegäranden som använder JSON- och Atom-feeds.

Anteckning

JSON är det rekommenderade nyttolastformatet och är det enda format som stöds för version 2015-12-11 och senare.

JSON (version 2013-08-15 och senare)

Följande är en exempelbegäran och ett svar som använder JSON.

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

Begäran skickas med följande rubriker:

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

Begäran skickas med följande JSON-brödtext:

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

När begäran har skickats returneras följande svar:

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

Atomfeed (versioner före 2015-12-11)

Följande är en exempelbegäran och ett svar som använder Atom.

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

Begäran skickas med följande rubriker:

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

Begäran skickas med följande XML-brödtext:

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

När begäran har skickats returneras följande svar:

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

Kommentarer

Åtgärden Insert Or Replace Entity använder If-Match inte huvudet. Du måste anropa den här åtgärden med hjälp av versionen 2011-08-18 eller senare. Dessa attribut skiljer den här åtgärden från åtgärden Uppdatera entitet .

Om du använder åtgärden Insert Or Replace Entity för att ersätta en entitet tas alla egenskaper från den tidigare entiteten bort, om den nya entiteten inte definierar dem. Egenskaper med ett null värde tas också bort.

När du anropar Insert or Replace Entity åtgärden måste du ange värden för systemegenskaperna PartitionKey och RowKey . Tillsammans utgör dessa egenskaper primärnyckeln och måste vara unika i tabellen.

PartitionKey Både värdena och RowKey måste vara strängvärden. Varje nyckelvärde kan vara upp till 64 KiB i storlek. Om du använder ett heltalsvärde för nyckelvärdet bör du konvertera heltal till en sträng med fast bredd. Detta beror på att de är kanoniskt sorterade. Konvertera till exempel värdet 1 till 0000001för att säkerställa korrekt sortering.

Om du uttryckligen vill skriva en egenskap anger du lämplig OData datatyp genom att ange m:type attributet i egenskapsdefinitionen i Atom-feeden. Mer information om hur du skriver egenskaper finns i Infoga och uppdatera entiteter.

Alla program som kan auktorisera och skicka en HTTP PUT begäran kan infoga eller ersätta en entitet.

Information om hur du utför batch-upsert-åtgärder finns i Utföra entitetsgrupptransaktioner.

Se även

Auktorisera begäranden till Azure Storage
Ange versionshuvuden för OData-datatjänsten
Infoga och uppdatera entiteter
Status- och felkoder
Felkoder för Table Storage