Infoga eller sammanfoga entitet

Artikel
06/27/2023

Åtgärden Insert Or Merge Entity uppdaterar 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 Merge 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
`MERGE`	`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
`MERGE`	`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 Ställa in 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 loggning 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 Merge Entity skickar entiteten som ska infogas som en entitetsuppsättning OData . Den här entitetsuppsättningen kan vara antingen en Atom- eller JSON-nyttolast. 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 statuskod 204 (No Content). Information om statuskoder finns i Status- och felkoder och Tabelllagringsfelkoder.

Svarshuvuden

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

Svarsrubrik	Description
`ETag`	`ETag` för entiteten.
`x-ms-request-id`	Identifierar den begäran som gjordes unikt 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ändes för att köra begäran. Det här huvudet returneras för begäranden som görs mot version 2009-09-19 och senare.
`Date`	Ett datum-/tidsvärde för UTC 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. Om rubriken `x-ms-client-request-id` inte finns i begäran finns 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.

MERGE 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:

MERGE 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='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>

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 Merge Entity använder verbet MERGE . Du måste anropa åtgärden med hjälp av versionen 2011-08-18 eller senare. Dessutom använder If-Match inte den här åtgärden huvudet. Dessa attribut skiljer den här åtgärden från Update Entity åtgärden, även om begärandetexten är densamma för båda åtgärderna.

Om du använder åtgärden Insert Or Merge Entity för att sammanfoga en entitet behålls alla egenskaper från den tidigare entiteten, om begäran inte definierar eller inkluderar dem. Egenskaper med ett null värde behålls också.

När du anropar Insert or Merge Entity åtgärden måste du ange värden för PartitionKey - och RowKey -systemegenskaperna. 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 heltalet till en sträng med fast bredd. Detta beror på att de är kanoniskt sorterade. Konvertera till exempel värdet 1 till 0000001 för att säkerställa korrekt sortering.

Om du uttryckligen vill ange en egenskap anger du lämplig OData typ 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 MERGE begäran kan infoga eller uppdatera 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