Vložit nebo nahradit entitu

Článek
06/27/2023

Operace Insert Or Replace Entity nahradí 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 Replace 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
`PUT`	`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
`PUT`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Table Storage v emulátoru úložiště se od Azure Table Storage liší 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 Replace Entity odešle entitu, která má být vložena jako sada OData entit. Tato sada entit může být buď json, nebo informační kanál Atom. 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 (bez obsahu). 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.

PUT 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žívají Atom.

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

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 Replace Entity nepoužívá hlavičku If-Match . Tuto operaci musíte volat pomocí verze 2011-08-18 nebo novější. Tyto atributy odlišují tuto operaci od operace Aktualizovat entitu .

Pokud operaci použijete Insert Or Replace Entity k nahrazení entity, odeberou se všechny vlastnosti z předchozí entity, pokud je nová entita nedefinuje. Odeberou se null také vlastnosti s hodnotou.

Při volání Insert or Replace Entity operace je nutné zadat hodnoty pro PartitionKey vlastnosti systému 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é. PartitionKey a RowKey může mít velikost až 1024 znaků. Pokud pro 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 kanonicky seřazené. Například převeďte hodnotu 1 na 0000001, aby se zajistilo správné řazení.

Pokud chcete explicitně zadat vlastnost, zadejte příslušný OData datový 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 Vložení a aktualizace entit.

Entitu může vložit nebo nahradit libovolná HTTP PUT aplikace, která může autorizovat a odeslat žádost.

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

Viz také

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

Sdílet prostřednictvím