Vložit nebo sloučit entitu

Článek
08/05/2023

Operace Insert Or Merge Entity aktualizuje existující entitu nebo vloží novou entitu, pokud v tabulce neexistuje. Vzhledem k tomu, že tato operace může vložit nebo aktualizovat entitu, označuje se také jako operace upsert .

Žádost

Požadavek můžete vytvořit Insert Or Merge Entity následujícím způsobem. Doporučuje se https. Následující hodnoty nahraďte vlastními hodnotami:

myaccount s názvem vašeho účtu úložiště
mytable s názvem tabulky
myPartitionKey a myRowKey s názvem klíče oddílu a klíče řádku pro entitu, která se má aktualizovat.

Metoda	Identifikátor URI žádosti	Verze PROTOKOLU HTTP
`MERGE`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Služba emulovaného úložiště

Když vytvoříte požadavek na službu emulovaného úložiště, zadejte název hostitele emulátoru a port služby Azure Table Storage jako 127.0.0.1:10002 následovaný názvem emulovaného účtu úložiště.

Metoda	Identifikátor URI žádosti	Verze PROTOKOLU HTTP
`MERGE`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Table Storage v emulátoru úložiště se liší od Služby Azure Table Storage několika způsoby. Další informace najdete v tématu Rozdíly mezi emulátorem úložiště a službami Azure Storage.

Parametry identifikátoru URI

V identifikátoru URI požadavku můžete zadat následující další parametr.

Parametr	Popis
`timeout`	Nepovinný parametr. Parametr `timeout` je vyjádřen v sekundách. Další informace najdete v tématu Nastavení časových limitů pro operace služby Table Storage.

Hlavičky požadavku

Následující tabulka popisuje požadované a volitelné hlavičky požadavků.

Hlavička požadavku	Popis
`Authorization`	Povinná hodnota. Určuje schéma autorizace, název účtu a podpis. Další informace najdete v tématu Autorizace požadavků do služby Azure Storage.
`Date` nebo `x-ms-date`	Povinná hodnota. Určuje formát UTC (Coordinated Universal Time). Další informace najdete v tématu Autorizace požadavků do služby Azure Storage.
`x-ms-version`	Povinná hodnota. Musí být nastavená na 2011-08-18 nebo novější. Určuje verzi operace, která se má použít pro tento požadavek. Další informace najdete v tématu Správa verzí pro služby Azure Storage.
`Content-Type`	Povinná hodnota. Určuje typ obsahu datové části. Možné hodnoty jsou `application/atom+xml` a `application/json`. Další informace o platných typech obsahu najdete v tématu Formát datové části pro operace table storage.
`Content-Length`	Povinná hodnota. Délka textu požadavku.
`x-ms-client-request-id`	Nepovinný parametr. Poskytuje klientem vygenerovanou neprůselnou hodnotu s limitem počtu znaků 1 kibibajt (KiB), který je zaznamenán v protokolech při konfiguraci protokolování. Důrazně doporučujeme použít tuto hlavičku ke korelaci aktivit na straně klienta s požadavky, které server přijímá. Další informace najdete v tématu Monitorování služby Azure Table Storage.

Text požadavku

Operace Insert Or Merge Entity odešle entitu, která má být vložena jako sada OData entit. Touto sadou entit může být datová část Atom nebo JSON. Další informace najdete v tématu Vložení a aktualizace entit.

Poznámka

Doporučený formát datové části je JSON, který je jediným podporovaným formátem pro verzi 2015-12-11 a novější.

Odpověď

Odpověď obsahuje stavový kód HTTP a sadu hlaviček odpovědi.

Stavový kód

Úspěšná operace vrátí stavový kód 204 (No Content). Informace o stavových kódech najdete v tématech Stavové kódy a kódy chyb a Kódy chyb služby Table Storage.

Hlavičky odpovědi

Odpověď obsahuje následující hlavičky. Odpověď může také obsahovat další standardní hlavičky HTTP. Všechny standardní hlavičky odpovídají specifikaci protokolu HTTP/1.1.

Hlavička odpovědi	Description
`ETag`	Hodnota `ETag` pro entitu.
`x-ms-request-id`	Jednoznačně identifikuje požadavek, který byl proveden, a lze ho použít k řešení potíží s požadavkem. Další informace najdete v tématu Řešení potíží s operacemi rozhraní API.
`x-ms-version`	Označuje verzi služby Table Storage použitou ke spuštění požadavku. Tato hlavička se vrátí pro požadavky provedené ve verzi 2009-09-19 a novější.
`Date`	Hodnota data a času UTC, která označuje čas, kdy byla odpověď zahájena. Tato služba vygeneruje tuto hodnotu.
`x-ms-client-request-id`	Dá se použít k řešení potíží s požadavky a odpovídajícími odpověďmi. Hodnota této hlavičky se rovná hodnotě `x-ms-client-request-id` hlavičky, pokud je v požadavku. Hodnota je maximálně 1 024 viditelných znaků ASCII. Pokud hlavička `x-ms-client-request-id` v požadavku není, nebude v odpovědi.

Text odpovědi

Žádné

Autorizace

Tuto operaci může provést vlastník účtu. Kromě toho to může udělat každý, kdo má sdílený přístupový podpis, který má oprávnění k provedení této operace.

Ukázkový požadavek a odpověď

Následující příklady ukazují ukázkové požadavky, které používají informační kanály JSON a Atom.

Poznámka

Doporučený formát datové části je JSON, který je jediným podporovaným formátem pro verzi 2015-12-11 a novější.

JSON (verze 2013-08-15 a novější)

Následuje ukázkový požadavek a odpověď, které používají JSON.

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

Požadavek se odešle s následujícími hlavičkami:

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

Požadavek se odešle s následujícím textem JSON:

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

Po odeslání požadavku se vrátí následující odpověď:

  
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

Informační kanál Atom (verze starší než 2015-12-11)

Následuje ukázkový požadavek a odpověď, která používá Atom:

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

Požadavek se odešle s následujícími hlavičkami:

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

Požadavek se odešle s následujícím textem XML:

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

Po odeslání požadavku se vrátí následující odpověď:

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

Poznámky

Operace Insert Or Merge Entity používá sloveso MERGE . Operaci musíte volat pomocí verze 2011-08-18 nebo novější. Kromě toho tato operace nepoužívá hlavičku If-Match . Tyto atributy odlišují tuto operaci od Update Entity operace, i když text požadavku je pro obě operace stejný.

Pokud operaci použijete Insert Or Merge Entity ke sloučení entity, zachovají se všechny vlastnosti z předchozí entity, pokud je požadavek nedefinuje nebo neobsahuje. Vlastnosti s hodnotou se null také zachovají.

Při volání Insert or Merge Entity operace je nutné zadat hodnoty pro PartitionKey systémové vlastnosti a RowKey . Tyto vlastnosti společně tvoří primární klíč a musí být v rámci tabulky jedinečné.

PartitionKey Hodnoty i RowKey musí být řetězcové. Každá hodnota klíče může mít velikost až 64 KiB. Pokud jako hodnotu klíče používáte celočíselnou hodnotu, měli byste celé číslo převést na řetězec s pevnou šířkou. Je to proto, že jsou seřazené kanonicky. Pokud chcete například zajistit správné řazení, převeďte hodnotu 1 na 0000001 .

Pokud chcete explicitně zadat vlastnost, zadejte příslušný OData typ nastavením atributu m:type v definici vlastnosti v informačním kanálu Atom. Další informace o zadávání vlastností najdete v tématu Vkládání a aktualizace entit.

Entitu HTTP MERGE může vložit nebo aktualizovat libovolná aplikace, která může autorizovat a odeslat požadavek.

Informace o provádění dávkových operací upsertu najdete v tématu Provádění transakcí skupin entit.

Viz také

Autorizace požadavků do Služby Azure Storage
Nastavení hlaviček verzí datové služby OData
Vkládání a aktualizace entit
Stavové kódy a kódy chyb
Kódy chyb služby Table Storage