Wstawianie lub scalanie jednostki

Artykuł
08/05/2023

Operacja Insert Or Merge Entity aktualizuje istniejącą jednostkę lub wstawia nową jednostkę, jeśli nie istnieje w tabeli. Ponieważ ta operacja może wstawić lub zaktualizować jednostkę, jest również znana jako operacja upsert .

Żądanie

Żądanie można skonstruować Insert Or Merge Entity w następujący sposób. Zalecane jest użycie protokołu HTTPS. Zastąp następujące wartości własnymi:

myaccount z nazwą konta magazynu
mytable z nazwą tabeli
myPartitionKey oraz myRowKey o nazwie klucza partycji i klucza wiersza dla jednostki do zaktualizowania

Metoda	Identyfikator URI żądania	Wersja PROTOKOŁU HTTP
`MERGE`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Emulowana usługa magazynu

Po wysłaniu żądania względem emulowanej usługi magazynu określ nazwę hosta emulatora i port usługi Azure Table Storage jako 127.0.0.1:10002, a następnie nazwę emulowanego konta magazynu.

Metoda	Identyfikator URI żądania	Wersja PROTOKOŁU HTTP
`MERGE`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Usługa Table Storage w emulatorze usługi Storage różni się od usługi Azure Table Storage na kilka sposobów. Aby uzyskać więcej informacji, zobacz Różnice między emulatorem usługi Storage i usługami Azure Storage.

Parametry identyfikatora URI

W identyfikatorze URI żądania można określić następujący dodatkowy parametr.

Parametr	Opis
`timeout`	Opcjonalny. Parametr jest wyrażony `timeout` w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji usługi Table Storage.

Nagłówki żądań

W poniższej tabeli opisano wymagane i opcjonalne nagłówki żądań.

Nagłówek żądania	Opis
`Authorization`	Wymagane. Określa schemat autoryzacji, nazwę konta i podpis. Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.
`Date` lub `x-ms-date`	Wymagane. Określa dla żądania godzinę w formacie uniwersalnego czasu koordynowanego (UTC). Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.
`x-ms-version`	Wymagane. Musi być ustawiona wartość 2011-08-18 lub nowsza. Określa wersję operacji do użycia dla tego żądania. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji usług Azure Storage.
`Content-Type`	Wymagane. Określa typ zawartości ładunku. Możliwe wartości to `application/atom+xml` i `application/json`. Aby uzyskać więcej informacji na temat prawidłowych typów zawartości, zobacz Format ładunku dla operacji usługi Table Storage.
`Content-Length`	Wymagane. Długość treści żądania.
`x-ms-client-request-id`	Opcjonalny. Udostępnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem znaków 1-kibibyte (KiB), który jest rejestrowany w dziennikach podczas konfigurowania rejestrowania. Zdecydowanie zalecamy używanie tego nagłówka do korelowania działań po stronie klienta z żądaniami odbieranymi przez serwer. Aby uzyskać więcej informacji, zobacz Monitorowanie usługi Azure Table Storage.

Treść żądania

Operacja Insert Or Merge Entity wysyła jednostkę do wstawienia jako OData zestawu jednostek. Ten zestaw jednostek może być ładunkiem Atom lub JSON. Aby uzyskać więcej informacji, zobacz Wstawianie i aktualizowanie jednostek.

Uwaga

Format JSON jest zalecanym formatem ładunku i jest jedynym formatem obsługiwanym w wersji 2015-12-11 lub nowszej.

Reakcja

Odpowiedź zawiera kod stanu HTTP i zestaw nagłówków odpowiedzi.

Kod stanu

Operacja zakończona powodzeniem zwraca kod stanu 204 (No Content). Aby uzyskać informacje o kodach stanu, zobacz Kody stanu i błędów oraz Kody błędów usługi Table Storage.

Nagłówki odpowiedzi

Odpowiedź zawiera następujące nagłówki. Odpowiedź może również zawierać dodatkowe, standardowe nagłówki HTTP. Wszystkie nagłówki standardowe są zgodne ze specyfikacją protokołu HTTP/1.1.

Nagłówek odpowiedzi	Opis
`ETag`	Element `ETag` dla jednostki.
`x-ms-request-id`	Jednoznacznie identyfikuje żądanie, które zostało wykonane i może być używane do rozwiązywania problemów z żądaniem. Aby uzyskać więcej informacji, zobacz Rozwiązywanie problemów z operacjami interfejsu API.
`x-ms-version`	Wskazuje wersję usługi Table Storage używaną do uruchamiania żądania. Ten nagłówek jest zwracany dla żądań wysyłanych w wersji 2009-09-19 lub nowszej.
`Date`	Wartość daty/godziny UTC wskazująca godzinę, w której zainicjowano odpowiedź. Usługa generuje tę wartość.
`x-ms-client-request-id`	Może służyć do rozwiązywania problemów z żądaniami i odpowiadającymi im odpowiedziami. Wartość tego nagłówka jest równa wartości `x-ms-client-request-id` nagłówka, jeśli jest obecna w żądaniu. Wartość wynosi co najwyżej 1024 widoczne znaki ASCII. `x-ms-client-request-id` Jeśli nagłówek nie jest obecny w żądaniu, nie będzie on obecny w odpowiedzi.

Treść odpowiedzi

Brak.

Autoryzacja

Właściciel konta może wykonać tę operację. Ponadto każda osoba z sygnaturą dostępu współdzielonego, która ma uprawnienia do wykonania tej operacji, może to zrobić.

Przykładowe żądanie i odpowiedź

W poniższych przykładach przedstawiono przykładowe żądania używające źródeł danych JSON i Atom.

Uwaga

Format JSON jest zalecanym formatem ładunku i jest jedynym formatem obsługiwanym w wersji 2015-12-11 lub nowszej.

JSON (wersja 2013-08-15 lub nowsza)

Poniżej przedstawiono przykładowe żądanie i odpowiedź, która używa kodu JSON.

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

Żądanie jest wysyłane z następującymi nagłówkami:

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

Żądanie jest wysyłane z następującą treścią 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 wysłaniu żądania zostanie zwrócona następująca odpowiedź:

  
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

Kanał informacyjny atomów (wersje wcześniejsze niż 2015-12-11)

Poniżej przedstawiono przykładowe żądanie i odpowiedź używającą atomu:

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

Żądanie jest wysyłane z następującymi nagłówkami:

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

Żądanie jest wysyłane z następującą treścią 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 wysłaniu żądania zostanie zwrócona następująca odpowiedź:

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

Uwagi

Operacja Insert Or Merge Entity używa czasownika MERGE . Należy wywołać operację przy użyciu wersji 2011-08-18 lub nowszej. Ponadto ta operacja nie używa nagłówka If-Match . Te atrybuty odróżniają tę operację Update Entity od operacji, chociaż treść żądania jest taka sama w przypadku obu operacji.

Jeśli używasz Insert Or Merge Entity operacji do scalania jednostki, wszelkie właściwości z poprzedniej jednostki zostaną zachowane, jeśli żądanie nie zdefiniuje ani nie zawiera. Właściwości z wartością null również są zachowywane.

Podczas wywoływania Insert or Merge Entity operacji należy określić wartości właściwości PartitionKey systemu i RowKey . Razem te właściwości tworzą klucz podstawowy i muszą być unikatowe w tabeli.

PartitionKey Wartości i RowKey muszą być wartościami ciągu. Każda wartość klucza może mieć rozmiar do 64 KiB. Jeśli używasz wartości całkowitej dla wartości klucza, należy przekonwertować liczbę całkowitą na ciąg o stałej szerokości. Wynika to z tego, że są one posortowane kanonicznie. Na przykład przekonwertuj wartość 1 na 0000001 , aby zapewnić prawidłowe sortowanie.

Aby jawnie wpisać właściwość, określ odpowiedni OData typ, ustawiając m:type atrybut w definicji właściwości w kanale informacyjnym Atom. Aby uzyskać więcej informacji na temat wpisywania właściwości, zobacz Wstawianie i aktualizowanie jednostek.

Każda aplikacja, która może autoryzować i wysyłać HTTP MERGE żądanie, może wstawić lub zaktualizować jednostkę.

Aby uzyskać informacje na temat wykonywania operacji upsert wsadowych, zobacz Wykonywanie transakcji grupy jednostek.

Zobacz też

Autoryzowanie żądań do usługi Azure Storage
Ustawianie nagłówków wersji usługi danych OData
Wstawianie i aktualizowanie jednostek
Kody stanu i błędów
Kody błędów usługi Table Storage