Format ładunku dla operacji usługi Table Service

  • Artykuł

Interfejs API REST usługi Table Service obsługuje formaty ATOM i JSON jako formaty ładunków OData. Chociaż protokół ATOM jest obsługiwany dla wszystkich wersji usług Azure Storage, protokół JSON jest obsługiwany tylko w wersji 2013-08-15 i nowszych.

  • Format JSON jest zalecanym formatem ładunku. Format JSON jest obsługiwany w wersji 2013-08-15 i nowszych. Musisz użyć formatu JSON w wersji 2015-12-11 lub nowszej.

  • Program ATOM jest obsługiwany w wersjach starszych niż 2015-12-11.

Uwaga

Następujące operacje interfejsu API REST nie są interfejsami API OData i obecnie nie obsługują formatu JSON: Pobieranie listy ACL tabel, ustawianie listy ACL tabel, pobieranie właściwości usługi table service i ustawianie właściwości usługi Table Service.

Aby określić format JSON lub ATOM, określ odpowiednie wartości dla Content-Type nagłówków i Accept (opisane poniżej). Zwróć uwagę na następujące ograniczenia:

  • Nagłówek Content-Type jest wymagany dla wszystkich żądań zawierających ładunek OData.

  • Accept Jeśli nagłówek nie zostanie podany, typ zawartości odpowiedzi zostanie domyślnie ustawiona na application/atom+xml.

  • Określenie parametru $format URI zastępuje wartość określoną w nagłówku Accept żądania, gdy wersja usługi danych OData jest ustawiona na 3.0. Zobacz Ustawianie nagłówków wersji usługi danych OData , aby uzyskać szczegółowe informacje o wersji usługi OData.

Aby określić format ładunku, ustaw Content-Type nagłówki żądań i Accept zgodnie z poniższą tabelą:

Format ładunku Nagłówek typu zawartości Zaakceptuj nagłówek Wersja usługi Data Service (wersja interfejsu API REST) Obsługiwane interfejsy API
Atom application/atom+xml application/atom+xml 1.0 (dowolna wersja)

2.0 (2011-08-18 lub nowszy)

3.0 (2013-08-15 lub nowszy)		 Tabele zapytań

Createtable

Usuń tabelę

Wykonywanie zapytań o jednostki

Wstaw jednostki

Wstawianie lub scalanie jednostki

Wstawianie lub zastępowanie jednostki

Aktualizowanie jednostki

Scal jednostkę

Usuwanie jednostki
JSON application/json application/json;odata=nometadata

application/json;odata=minimalmetadata

application/json;odata=fullmetadata

Aby uzyskać szczegółowe informacje, zobacz sekcję Format JSON poniżej.		 3.0 (2013-08-15 lub nowszy) Tabele zapytań

Createtable

Usuń tabelę

Wykonywanie zapytań o jednostki

Wstaw jednostki

Wstawianie lub scalanie jednostki

Wstawianie lub zastępowanie jednostki

Aktualizowanie jednostki

Scal jednostkę

Usuwanie jednostki
XML application/xml application/xml Nie dotyczy Uzyskiwanie listy ACL tabel

Ustawianie listy ACL tabel

Pobieranie właściwości usługi Table Service

Ustawianie właściwości usługi Table Service

Format JSON (application/json) (wersje 2013-08-15 i nowsze)

OData rozszerza format JSON, definiując ogólne konwencje dla tych par nazwa-wartość, podobnie jak w powyższym formacie ATOM. OData definiuje zestaw adnotacji kanonicznych dla informacji sterujących, takich jak identyfikatory, typ i łącza. Aby uzyskać szczegółowe informacje na temat formatu JSON, zobacz Wprowadzenie do formatu JSON.

Kluczową zaletą korzystania z formatu JSON OData jest to, że przewidywalne części ładunku można pominąć, aby zmniejszyć rozmiar ładunku. Aby odtworzyć te dane na końcu odbierania, wyrażenia są używane do obliczania brakujących łączy, informacji o typie i danych sterujących. Aby kontrolować, co zostanie pominięte z ładunku, istnieją trzy poziomy, które można określić jako część nagłówka Accept :

  • application/json;odata=nometadata

  • application/json;odata=minimalmetadata

  • application/json;odata=fullmetadata

Następujące adnotacje ODATA są obsługiwane przez usługę Azure Table:

  • odata.metadata: adres URL metadanych kolekcji, jednostki, wartości pierwotnej lub dokumentu usługi.

  • odata.id: identyfikator jednostki, który jest zazwyczaj adresem URL zasobu.

  • odata.editlink: link używany do edytowania/aktualizowania wpisu, jeśli jednostka jest aktualizowana, a odata.id nie reprezentuje adresu URL, którego można użyć do edytowania jednostki.

  • odata.type: nazwa typu obiektu zawierającego.

  • odata.etag: Element ETag jednostki.

  • PropertyName@odata.type, dla właściwości niestandardowych: nazwa typu właściwości docelowej.

  • PropertyName@odata.type, dla właściwości systemowych (tjPrimaryKey. właściwości , RowKeyi Timestamp ): nazwa typu właściwości docelowej.

Informacje zawarte na każdym poziomie zostały podsumowane w poniższej tabeli:

Annotations odata=fullmetadata odata=minimalmetadata odata=nometadata
odata.metadata Tak Tak Nie
odata.id Tak Nie Nie
odata.editlink Tak Nie Nie
odata.type Tak Nie Nie
odata.etag Tak Nie Nie
PropertyName@odata.type dla właściwości niestandardowych Tak Tak Nie
PropertyName@odata.type dla właściwości systemowych Tak Nie Nie

Typy właściwości w kanale informacyjnym JSON

Adnotacja odata.type jest używana w formacie OData JSON w celu określenia typu właściwości otwierania. Ta adnotacja jest obecna, gdy spełnione są wszystkie poniższe warunki:

  • Poziom kontrolki JSON jest ustawiony na odata=minimalmetadata wartość lub odata=fullmetadata, zgodnie z opisem w sekcji Format JSON .

  • Właściwość jest właściwością niestandardową. Należy pamiętać, że w przypadku tabel platformy Azure tylko PartitionKeywłaściwości , RowKeyi Timestamp są właściwościami systemu, a informacje o typie są deklarowane w elemecie $metadata. Adnotacja typu dla tych właściwości jest obecna tylko wtedy, gdy poziom kontrolki jest ustawiony na odata=fullmetadatawartość . Aby uzyskać więcej informacji, zobacz Understanding the Table Service Data Model (Omówienie modelu danych usługi Table Service).

  • Nie można określić typu właściwości za pomocą heurystyki wykrywania typów podsumowanych w poniższej tabeli.

Typ Edm Wymagana adnotacja odata.type Typ JSON
Edm.Binary Tak Ciąg
Edm.Boolean Nie Literały
Edm.DateTime Tak Ciąg
Edm.Double Nie Numeryczne (zawiera punkt dziesiętny)
Edm.Guid Tak Ciąg
Edm.Int32 Nie Numeryczne (nie zawiera przecinka dziesiętnego)
Edm.Int64 Tak Ciąg
Edm.String Nie Ciąg
n/d Nie Null

Usługa Table Service nie utrwala null wartości właściwości. Podczas pisania jednostki null można określić wartość z adnotacją odata.type lub bez niej, a każda właściwość z wartością null jest obsługiwana tak, jakby żądanie nie zawierało tej właściwości. Null wartości właściwości nigdy nie są zwracane podczas wykonywania zapytań o jednostki.

W przypadku pliku Edm.Double wartości NaNInfinity i -Infinity są reprezentowane w formacie JSON przy użyciu typu String, a adnotacja odata.type jest wymagana. Usługa Table Service nie obsługuje ujemnej wersji pliku NaN, a w formacie JSON nie rozróżnia wartości dodatnich i ujemnych (traktuje jako -0.00.0).

Następująca jednostka JSON zawiera przykład dla każdego z ośmiu różnych typów właściwości:

{  
  "PartitionKey":"mypartitionkey",  
  "RowKey":"myrowkey",  
  "DateTimeProperty@odata.type":"Edm.DateTime",  
  "DateTimeProperty":"2013-08-02T17:37:43.9004348Z",  
  "BoolProperty":false,  
  "BinaryProperty@odata.type":"Edm.Binary",  
  "BinaryProperty":"AQIDBA==",  
  "DoubleProperty":1234.1234,  
  "GuidProperty@odata.type":"Edm.Guid",  
  "GuidProperty":"4185404a-5818-48c3-b9be-f217df0dba6f",  
  "Int32Property":1234,  
  "Int64Property@odata.type":"Edm.Int64",  
  "Int64Property":"123456789012",  
  "StringProperty":"test"  
}

Ponieważ PartitionKey właściwości i RowKey są właściwościami systemu, co oznacza, że wszystkie wiersze tabeli muszą definiować te właściwości, adnotacja typu nie jest wyświetlana w jednostce. Te właściwości są wstępnie zdefiniowane jako typ Edm.String. Jednak inne właściwości są właściwościami niestandardowymi i dlatego zawierają informacje o typie odpowiadającym jednemu z obsługiwanych typów pierwotnych w powyższej tabeli.

Przykłady:

Poniższy przykładowy wpis OData przedstawia format JSON wysłany jako żądanie wstawienia jednostki do usługi Azure Table Storage (zobacz Wstawianie jednostki , aby uzyskać szczegółowe informacje na temat operacji wstawiania):

{  
  "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,  
  "NumOfOrders@odata.type":"Edm.Int64",  
  "NumOfOrders":"255",  
  "PartitionKey":"mypartitionkey",  
  "RowKey":"myrowkey1",  
}

Gdy klient wysyła zapytanie do zestawu jednostek w usłudze Azure Table Storage, usługa odpowiada za pomocą ładunku JSON (zobacz Query Entities (Jednostki zapytań ), aby uzyskać szczegółowe informacje na temat operacji zapytania. Kanał informacyjny może zawierać jeden z trzech poziomów informacji: brak metadanych, minimalnych metadanych lub pełnych metadanych. W poniższych przykładach pokazano każdy rodzaj:

Brak metadanych:

{  
  "value":[  
    {  
      "PartitionKey":"Customer03",  
      "RowKey":"Name",  
      "Timestamp":"2013-08-09T18:55:48.3402073Z",  
      "CustomerSince":"2008-10-01T15:25:05.2852025Z",  
    }  
}

Minimalne metadane:

{  
  "odata.metadata":"https://myaccount.table.core.windows.net/$metadata#Customers,  
  "value":[  
    {  
      "PartitionKey":"Customer03",  
      "RowKey":"Name",  
      "Timestamp":"2013-08-09T18:55:48.3402073Z",  
      "CustomerSince@odata.type":"Edm.DateTime",  
      "CustomerSince":"2008-10-01T15:25:05.2852025Z",  
    }  
}

Pełne metadane:

{  
  "odata.metadata":"https://myaccount.table.core.windows.net/$metadata#Customers",  
  "value":[  
    {  
      "odata.type":"myaccount.Customers",  
      "odata.id":"https://myaccount.table.core.windows.net/Customers(PartitionKey='Customer03',RowKey='Name')",  
      "odata.etag":"W/\"0x5B168C7B6E589D2\"",  
      "odata.editLink":"Customers(PartitionKey='Customer03',RowKey='Name')",  
      "PartitionKey":"Customer03,  
      "RowKey":"Name",  
      "Timestamp@odata.type":"Edm.DateTime",  
      "Timestamp":"2013-08-09T18:55:48.3402073Z",  
      "CustomerSince@odata.type":"Edm.DateTime",  
      "CustomerSince":"2008-10-01T15:25:05.2852025Z",  
    }  
}

Aby dowiedzieć się więcej na temat formatu OData JSON, zobacz specyfikację formatu OData JSON w wersji 4.0 w połączeniu ze specyfikacją [MS-ODATAJSON]: OData Protocol JSON Format Standards Support Document (Obsługa standardów formatu OData Protocol JSON).

Format atomu (tylko application/atom+xml) (wersje wcześniejsze niż 2015-12-11)

Atom to format dokumentu opartego na formacie XML, który opisuje kolekcje powiązanych informacji, nazywanych źródłami danych. Kanały informacyjne składają się z wielu elementów, znanych jako wpisy. AtomPub definiuje dodatkowe konstrukcje formatu dla wpisów i źródeł danych, dzięki czemu zasoby, które reprezentują, mogą być łatwo podzielone na kategorie, pogrupowane, edytowane i odnalezione. Jednak ponieważ atom nie definiuje sposobu kodowania danych strukturalnych za pomocą źródeł danych, OData definiuje zestaw konwencji do reprezentowania danych strukturalnych w kanale informacyjnym Atom w celu umożliwienia transferów zawartości ustrukturyzowanej przez usługi oparte na protokole OData.

Na przykład poniższy przykładowy wpis OData demonstruje format Atom wysłany za pośrednictwem żądania wstawienia jednostki do usługi Azure Table Storage przy użyciu interfejsu API REST (zobacz Wstawianie jednostki , aby uzyskać szczegółowe informacje na temat operacji wstawiania):

<?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 />  
  <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>

Gdy klient wysyła zapytanie do zestawu jednostek w usłudze Table Storage, usługa odpowiada za pomocą kanału informacyjnego Atom, który jest kolekcją wpisów Atom (zobacz Jednostki zapytań , aby uzyskać szczegółowe informacje na temat operacji zapytania):

<?xml version="1.0" encoding="utf-8" standalone="yes"?>  
<feed 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" xmlns="https://www.w3.org/2005/Atom">  
  <title type="text">Customers</title>  
  <id>https://myaccount.table.core.windows.net/Customers</id>  
  <link rel="self" title="Customers" href="Customers" />  
  <entry m:etag="W/"0x5B168C7B6E589D2"">  
  <id>https://myaccount.table.core.windows.net/Customers(PartitionKey='Customer03',RowKey='Name')</id>  
    <title type="text"></title>  
    <updated>2008-10-01T15:26:13Z</updated>  
    <author>  
      <name />  
    </author>  
    <link rel="edit" title="Customers" href="Customers (PartitionKey='Customer03',RowKey='Name')" />  
    <category term="myaccount.Customers" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />  
    <content type="application/xml">  
      <m:properties>  
        <d:PartitionKey>Customer03</d:PartitionKey>  
        <d:RowKey>Name</d:RowKey>        <d:CustomerSince m:type="Edm.DateTime">2008-10-01T15:25:05.2852025Z</d:CustomerSince>  
      </m:properties>  
    </content>  
  </entry>  
</feed>

Typy właściwości w kanale informacyjnym atomów

Typy danych właściwości są definiowane przez specyfikację protokołu OData. Nie wszystkie typy danych zdefiniowane przez specyfikację są obsługiwane przez usługę Table Service. Aby uzyskać informacje o obsługiwanych typach danych i sposobie mapowania ich na typy środowiska uruchomieniowego języka wspólnego (CLR), zobacz Understanding the Table Service Data Model (Opis modelu danych usługi Table Service).

Właściwość może być określona z jawnym typem danych lub bez tego typu. Jeśli typ zostanie pominięty, właściwość zostanie automatycznie utworzona jako typ Edm.Stringdanych .

Jeśli właściwość jest tworzona z jawnym typem, zapytanie zwracające jednostkę zawiera ten typ w kanale informacyjnym Atom, aby w razie potrzeby określić typ istniejącej właściwości. Znajomość typu właściwości jest ważna podczas tworzenia zapytania, które filtruje dla tej właściwości. Aby uzyskać więcej informacji, zobacz Wykonywanie zapytań dotyczących tabel i jednostek.

Dla Double właściwości wartości NaN, INFi -INF są używane w Atom, aby wskazać, że nie jest to liczba, nieskończoność dodatnia i nieskończoność ujemna, odpowiednio. Formularze Infinity i -Infinity są również akceptowane. Usługa Table Service nie obsługuje negatywnej wersji programu NaN. W formacie Atom rozróżnia dodatnie i ujemne zero.

Zobacz też

Ustawianie nagłówków wersji usługi danych OData
Przechowywanie wersji dla usług Azure Storage
Pojęcia dotyczące usługi Table service