Wstaw jednostkę

  • Artykuł

Operacja Insert Entity wstawia nową jednostkę do tabeli.

Żądanie

Żądanie można skonstruować Insert Entity w następujący sposób. Zalecane jest użycie protokołu HTTPS. Zastąp ciąg myaccount nazwą konta magazynu, a ciąg mytable nazwą tabeli.

Metoda Identyfikator URI żądania Wersja PROTOKOŁU HTTP
POST https://myaccount.table.core.windows.net/mytable HTTP/1.1

Identyfikator URI usługi magazynu emulowanego

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
POST http://127.0.0.1:10002/devstoreaccount1/mytable 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ące dodatkowe parametry.

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 Opcjonalny. 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 (wersje wcześniejsze niż 2015-12-11) 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.
Accept Opcjonalny. Określa akceptowany typ zawartości ładunku odpowiedzi. Możliwe wartości:

- application/atom+xml (wersje wcześniejsze niż 2015-12-11)
- application/json;odata=nometadata
- application/json;odata=minimalmetadata
- application/json;odata=fullmetadata

Aby uzyskać więcej informacji, zobacz Format ładunku dla operacji usługi Table Storage.
Prefer Opcjonalny. Określa, czy odpowiedź powinna zawierać wstawioną jednostkę w ładunku. Możliwe wartości to return-no-content i return-content. Aby uzyskać więcej informacji, zobacz Ustawianie nagłówka Preferuj zarządzanie echo odpowiedzi na operacje wstawiania.
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 Entity wysyła jednostkę do wstawienia jako OData jednostki, która jest ź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.

JSON (wersja 2013-08-15 i nowsze)

Oto przykładowa treść żądania JSON dla Insert Entity operacji:

{  
   "Address":"Mountain View",  
   "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":true,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey"  
}

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

Oto przykładowa treść żądania Atom dla Insert Entity operacji.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>  
<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-09-18T23:46:19.3857256Z</updated>  
  <author>  
    <name />  
  </author>  
  <id />  
  <content type="application/xml">  
    <m:properties>  
      <d:Address>Mountain View</d:Address>  
      <d:Age m:type="Edm.Int32">23</d:Age>  
      <d:AmountDue m:type="Edm.Double">200.23</d:AmountDue>  
      <d:BinaryData m:type="Edm.Binary" m:null="true" />  
      <d:CustomerCode m:type="Edm.Guid">c9da6455-213d-42c9-9a79-3e9149a57833</d:CustomerCode>  
      <d:CustomerSince m:type="Edm.DateTime">2008-07-10T00:00:00</d:CustomerSince>  
      <d:IsActive m:type="Edm.Boolean">true</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>

Reakcja

Odpowiedź zawiera kod stanu HTTP, zestaw nagłówków odpowiedzi i treść odpowiedzi.

Kod stanu

Kod stanu zależy od wartości nagłówka Prefer . Prefer Jeśli nagłówek jest ustawiony na return-no-contentwartość , operacja zakończona pomyślnie zwróci kod stanu 204 (No Content). Prefer Jeśli nagłówek nie jest określony lub jeśli jest ustawiony na return-contentwartość , operacja zakończona powodzeniem zwraca kod stanu 201 (Created). Aby uzyskać więcej informacji, zobacz Ustawianie nagłówka Preferuj zarządzanie echo odpowiedzi na operacje wstawiania.

Aby uzyskać informacje o kodach stanu, zobacz Kody stanu i błędów oraz Kody błędów usługi Table Service.

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
x-ms-request-id 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 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ść.
ETag Element ETag dla jednostki.
Preference-Applied Wskazuje, czy Prefer nagłówek żądania został uhonorowany. Jeśli odpowiedź nie zawiera tego nagłówka, Prefer nagłówek nie został uhonorowany. Jeśli ten nagłówek zostanie zwrócony, jego wartość będzie mieć wartość return-content lub return-no-content.

Aby uzyskać więcej informacji, zobacz Ustawianie nagłówka Preferuj zarządzanie echo odpowiedzi na operacje wstawiania.
Content-Type Wskazuje typ zawartości ładunku. Wartość zależy od wartości określonej dla nagłówka Accept żądania. Możliwe wartości:

- application/atom+xml
- application/json;odata=nometadata
- application/json;odata=minimalmetadata
- application/json;odata=fullmetadata

Aby uzyskać więcej informacji na temat typów zawartości, zobacz Format ładunku dla operacji usługi Table Storage.
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

Jeśli żądanie zawiera Prefer nagłówek z wartością return-no-content, nie jest zwracana żadna treść odpowiedzi. W przeciwnym razie treść odpowiedzi jest zestawem OData jednostek.

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)

Oto przykładowa odpowiedź JSON dla każdego poziomu metadanych:

Brak metadanych:

{  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey",  
   "Timestamp":"2013-08-22T01:12:06.2608595Z",  
   "Address":"Mountain View",  
   "Age":23,  
   "AmountDue":200.23,  
   "CustomerCode":"c9da6455-213d-42c9-9a79-3e9149a57833",  
   "CustomerSince":"2008-07-10T00:00:00",  
   "IsActive":true,  
   "NumberOfOrders":"255"  
}

Minimalne metadane:

{  
   "odata.metadata":"https://myaccount.table.core.windows.net/Customer/$metadata#Customers/@Element",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey",  
   "Timestamp":"2013-08-22T01:12:06.2608595Z",  
   "Address":"Mountain View",  
   "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":true,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255"  
}

Pełne metadane:

{  
   "odata.metadata":"https://myaccount.table.core.windows.net/Customer/$metadata#Customers/@Element",  
   "odata.type":"myaccount.Customers",  
   "odata.id":" https://myaccount.table.core.windows.net/Customers(PartitionKey='mypartitionkey',RowKey='myrowkey')",  
   "odata.etag":"W/\"0x5B168C7B6E589D2\"",  
   "odata.editLink":"Customers(PartitionKey='mypartitionkey',RowKey='myrowkey')",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey",  
   "Timestamp@odata.type":"Edm.DateTime",  
   "Timestamp":"2013-08-22T01:12:06.2608595Z",  
   "Address":"Mountain View",  
   "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":true,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255"  
}

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

Oto przykładowa treść odpowiedzi Atom dla Insert Entity operacji.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>  
<entry xml:base="https://myaccount.table.core.windows.net/" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" m:etag="W/"0x5B168C7B6E589D2"" xmlns="https://www.w3.org/2005/Atom">  
  <id>https://myaccount.table.core.windows.net/mytable(PartitionKey='mypartitionkey',RowKey='myrowkey1')</id>  
  <title type="text"></title>  
  <updated>2008-09-18T23:46:19.3857256Z</updated>  
  <author>  
    <name />  
  </author>  
  <link rel="edit" title="mytable" href="mytable(PartitionKey='mypartitionkey',RowKey='myrowkey1')" />  
  <category term="myaccount.Tables" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />  
  <content type="application/xml">  
    <m:properties>  
      <d:PartitionKey>mypartitionkey</d:PartitionKey>  
      <d:RowKey>myrowkey1</d:RowKey>  
      <d:Timestamp m:type="Edm.DateTime">2008-09-18T23:46:19.4277424Z</d:Timestamp>  
      <d:Address>Mountain View</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:00</d:CustomerSince>  
      <d:IsActive m:type="Edm.Boolean">true</d:IsActive>  
      <d:NumOfOrders m:type="Edm.Int64">255</d:NumOfOrders>  
    </m:properties>  
  </content>  
</entry>

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

Uwagi

Podczas wstawiania jednostki do tabeli 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. PartitionKey wartości i RowKey mogą mieć rozmiar maksymalnie 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, ponieważ są one sortowane 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.

Usługa Table Storage nie sprawia, że wartości właściwości są null trwałe. Określenie właściwości z wartością null jest równoważne pomijaniu tej właściwości w żądaniu.

Aby uzyskać informacje na temat wykonywania operacji wstawiania wsadowego, 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