Wstawianie lub zastępowanie jednostki

Artykuł
08/05/2023

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

Żądanie

Żądanie można skonstruować Insert Or Replace 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 z nazwą klucza partycji i klucza wiersza dla jednostki do zaktualizowania

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

Emulowana usługa magazynu

Po wysłaniu żądania względem usługi emulowanego 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
`PUT`	`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

Dla identyfikatora 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 dla 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. Zapewnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem znaków 1-kibibyte (KiB) rejestrowanym 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 Replace Entity wysyła jednostkę, która ma zostać wstawiona jako OData zestaw jednostek. Ten zestaw jednostek może być źródłem danych JSON lub Atom. Aby uzyskać więcej informacji, zobacz Wstawianie i aktualizowanie jednostek.

Uwaga

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

Reakcja

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

Kod stanu

Pomyślna operacja zwraca kod stanu 204 (Brak zawartości). 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 standardowe nagłówki są zgodne ze specyfikacją protokołu HTTP/1.1.

Nagłówek odpowiedzi	Opis
`ETag`	Element `ETag` dla jednostki.
`x-ms-request-id`	Unikatowo identyfikuje wykonane żądanie i może służyć 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 uruchomienia żądania. Ten nagłówek jest zwracany w przypadku żądań wysyłanych w wersji 2009-09-19 lub nowszej.
`Date`	Wartość daty/godziny UTC wskazująca godzinę, o 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 odpowiedziami. Wartość tego nagłówka jest równa wartości nagłówka `x-ms-client-request-id` , jeśli jest obecna w żądaniu. Wartość jest najwyżej 1024 widocznymi znakami ASCII. `x-ms-client-request-id` Jeśli nagłówek nie znajduje się 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 pokazano przykładowe żądania używające źródeł danych JSON i Atom.

Uwaga

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

JSON (wersja 2013-08-15 i nowsze)

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

PUT 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

Źródło danych Atom (wersje wcześniejsze niż 2015-12-11)

Poniżej przedstawiono przykładowe żądanie i odpowiedź, które używa atomu.

PUT 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='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 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 Replace Entity nie używa nagłówka If-Match . Tę operację należy wywołać przy użyciu wersji 2011-08-18 lub nowszej. Te atrybuty odróżniają tę operację od operacji Aktualizuj jednostkę.

Jeśli używasz Insert Or Replace Entity operacji do zastąpienia jednostki, wszystkie właściwości z poprzedniej jednostki zostaną usunięte, jeśli nowa jednostka ich nie zdefiniuje. Właściwości z wartością null są również usuwane.

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

PartitionKey Wartości i RowKey muszą być wartościami ciągów. PartitionKey wartości i RowKey mogą mieć rozmiar do 1024 znaków. 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. Dzieje się tak, ponieważ 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 danych, 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 PUT żądanie, może wstawić lub zastąpić 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

Udostępnij za pośrednictwem