Wstawianie lub zastępowanie jednostki

Operacja zastępuje istniejącą jednostkę lub wstawia nową jednostkę, Insert Or Replace Entity 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 Insert Or Replace Entity może zostać skonstruowane w następujący sposób. Protokół HTTPS jest zalecany. Zastąp następujące wartości własnymi wartościami:

  • myaccount na nazwę konta magazynu

  • mytable na nazwę tabeli

  • myPartitionKey i myRowKey z nazwą klucza partycji i kluczem 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 Storage Service

Podczas tworzenia żądania względem emulowanej usługi magazynu określ nazwę hosta emulatora i port usługi Table Jako 127.0.0.1:10002, a następnie emulowana nazwa 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 Service w emulatorze magazynu różni się od usługi Windows® Azure™ Table na kilka sposobów. Aby uzyskać więcej informacji, zobacz Differences Between the Storage Emulator and Azure Storage Services (Różnicemiędzy usługami Azure Storage Emulator i Azure Storage Services).

Parametry identyfikatora URI

W żądaniu URI można określić następujące dodatkowe parametry.

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

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 Ustawienie Wymagane musi mieć wartość 2011-08-18 lub nowszą. Określa wersję operacji do użycia dla tego żądania. Aby uzyskać więcej informacji, zobacz Versioning for the Azure Storage Services (Wersjeusług Azure Storage Services).
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 o prawidłowych typach zawartości, zobacz Format ładunku dla operacji usługi Table Service.
Content-Length Wymagane. Długość treści żądania.
x-ms-client-request-id Opcjonalny. Zapewnia wygenerowaną przez klienta nieprzezroczystą wartość z limitem znaków 1 KiB, który jest rejestrowany w dziennikach analizy po włączeniu rejestrowania analizy magazynu. Używanie tego nagłówka jest wysoce zalecane do korelowania działań po stronie klienta z żądaniami odebranymi przez serwer. Aby uzyskać więcej informacji, zobacz About Storage Analytics Logging and Azure Logging: Using Logs to Track Storage Requests (Informacje o rejestrowaniu usługi Azure Analytics i rejestrowaniu na platformie Azure: używanie dzienników do śledzenia Storage żądań).

Treść żądania

Operacja wysyła jednostkę do wstawienia jako zestaw jednostek OData, który może być kanałem informacyjnym Insert Or Replace Entity 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 wersjach 2015-12-11 i nowszych.

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 tabel.

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 Ten nagłówek unikatowo identyfikuje żądanie, które zostało wykonane, i może służyć do rozwiązywania problemów z żądaniem. Aby uzyskać więcej informacji, zobacz Troubleshooting API Operations (Rozwiązywanie problemów z operacjami interfejsu API).
x-ms-version Wskazuje wersję usługi Table Service używaną do wykonania żądania. Ten nagłówek jest zwracany w przypadku żądań względem wersji 2009-09-19 i nowszych.
Date Wartość daty/czasu UTC wygenerowana przez usługę, która wskazuje czas, o której została zainicjowana odpowiedź.
x-ms-client-request-id Ten nagłówek 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, jeśli jest obecny w żądaniu, a wartość jest co najwyżej 1024 widocznych znaków x-ms-client-request-id ASCII. Jeśli nagłówek x-ms-client-request-id nie jest obecny w żądaniu, ten nagłówek nie będzie obecny w odpowiedzi.

Treść odpowiedzi

Brak.

Autoryzacja

Tę operację może wykonać właściciel konta i każda osoba mająca sygnaturę dostępu współdzielonych, która ma uprawnienia do wykonania tej operacji.

Przykładowe żądanie i odpowiedź

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

Uwaga

Format JSON jest zalecanym formatem ładunku i jest jedynym obsługiwanym formatem w wersjach 2015-12-11 i nowszych.

JSON (wersje 2013-08-15 i nowsze)

Poniżej przedstawiono przykładowe żądanie i odpowiedź przy użyciu danych 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 jest zwracana 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ź z użyciem atomów.

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 jest zwracana 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 nie używa nagłówka If-Match i musi być wywoływana przy użyciu wersji Insert Or Replace Entity 2011-08-18 lub nowszej. Te atrybuty odróżniają tę operację od operacji Aktualizuj jednostkę.

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

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

Wartości i muszą być wartościami ciągu; każda wartość klucza może mieć rozmiar PartitionKey RowKey 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, ponieważ są one sortowane kanonicznie. Na przykład należy przekonwertować wartość na 1 , aby zapewnić prawidłowe 0000001 sortowanie.

Aby jawnie wpisać właściwość, określ odpowiedni typ danych OData, ustawiając atrybut w definicji właściwości w m:type 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 wysłać żądanie HTTP PUT, może wstawić lub zastąpić jednostkę.

Aby uzyskać informacje o wykonywaniu operacji upsert wsadowych, zobacz Performing Entity Group Transactions (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 Service