Format ładunku dla operacji usługi Table Service

Interfejs API REST usługi Table Service obsługuje formaty atomów i JSON w formatach ładunków OData. Protokół ATOM jest obsługiwany dla wszystkich wersji usług Azure Storage, ale protokół JSON jest obsługiwany tylko w wersji 2013-08-15 i nowszej.

  • Zalecany format ładunku to JSON. W przypadku wersji 2013-08-15 i nowszej jest obsługiwany język JSON. Musisz używać danych JSON w wersji 2015-12-11 lub nowszej.

  • 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ą danych JSON: Uzyskiwanie listy ACL tabel,ustawianie listy ACL tabel,uzyskiwanie właściwości usługi tabel i ustawianie właściwości usługi tabel.

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

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

  • Jeśli nagłówek nie zostanie podany, typ zawartości odpowiedzi będzie Accept domyślnie mieć wartość application/atom+xml .

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

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

Format ładunku Nagłówek typu zawartości Zaakceptuj nagłówek Wersja usługi danych (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)
QueryTables

Createtable

Usuwanie tabeli

Jednostki zapytań

Wstawianie jednostek

Wstawianie lub scalanie jednostki

Wstawianie lub zastępowanie jednostki

Aktualizowanie jednostki

Scalanie jednostki

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) QueryTables

Createtable

Usuwanie tabeli

Jednostki zapytań

Wstawianie jednostek

Wstawianie lub scalanie jednostki

Wstawianie lub zastępowanie jednostki

Aktualizowanie jednostki

Scalanie jednostki

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

Ustawianie listy ACL tabel

Uzyskiwanie 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)

Rozszerzenie formatu OData w formacie JSON przez zdefiniowanie ogólnych konwencji dla tych par nazwa-wartość, podobnie jak w formacie ATOM opisanym powyżej. OData definiuje zestaw adnotacji kanonicznych dla informacji sterujących, takich jak identyfikatory, typy i linki. Aby uzyskać szczegółowe informacje o formacie JSON, zobacz Introducing JSON (Wprowadzenie do formatu JSON).

Kluczową zaletą korzystania z formatu JSON OData jest możliwość pominięcia przewidywalnych części ładunku w celu zmniejszenia rozmiaru ładunku. Aby odechcieć te dane na końcu odbierającym, wyrażenia są używane do obliczania brakujących linków, informacji o typie i danych sterujących. Aby kontrolować, co jest pomijane z ładunku, istnieją trzy poziomy, które można określić jako część Accept nagłówka:

  • 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 Service:

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

  • odata.id: identyfikator jednostki, czyli zazwyczaj adres URL zasobu.

  • odata.editlink: link używany do edytowania/aktualizowania wpisu, jeśli jednostka jest aktualizowaalna, odata.id nie reprezentuje adresu URL, który może sł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 systemu (tj., właściwości , i ): nazwa typu właściwości PrimaryKey RowKey Timestamp 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 systemu Tak Nie Nie

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

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

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

  • Właściwość jest właściwością niestandardową. Należy pamiętać, że w przypadku tabel platformy Azure tylko właściwości , i są właściwościami systemu, a informacje o ich typie PartitionKey RowKeyTimestamp deklarowane w pliku $metadata . Adnotacja typu dla tych właściwości jest obecna tylko wtedy, gdy poziom kontroli jest ustawiony na odata=fullmetadata . 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ą heurystycznych wartości heurystycznych 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 Zero

Usługa Table Service nie utrwala null wartości właściwości. Podczas pisania jednostki można określić wartość z adnotacją odata.type lub bez niej, a każda właściwość z wartością jest obsłużona tak, jakby żądanie nie zawierało null null 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 , i są reprezentowane w formacie JSON przy użyciu typu NaN Infinity , a -Infinity String adnotacja odata.type jest wymagana. Usługa Table Service nie obsługuje ujemnej wersji , a w formacie JSON nie rozróżnia zera dodatniego i ujemnego NaN (traktuje -0.0 jako 0.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 i są właściwościami systemu, co oznacza, że wszystkie wiersze tabeli muszą definiować te właściwości, ich adnotacje typu RowKey nie są wyświetlane 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ące jednem z obsługiwanych typów pierwotnych w powyższej tabeli.

Przykłady:

Poniższy przykładowy wpis OData demonstruje format JSON wysył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 Jednostki zapytania, aby uzyskać szczegółowe informacje na temat operacji zapytania). Źródło danych może zawierać jeden z trzech poziomów informacji: brak metadanych, minimalne metadane lub pełne metadane. 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 JSON protokołu OData, zobacz specyfikację OData JSON Format Version 4.0 w połączeniu z dokumentem [ MS-ODATAJSON: ] OData Protocol JSON Format Standards Support Document.

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

Atom to format dokumentu oparty na formacie XML, który opisuje kolekcje powiązanych informacji nazywanych źródłami danych. Źródła danych składają się z wielu elementów nazywanych wpisami. AtomPub definiuje dodatkowe konstrukcje formatu dla wpisów i źródeł danych, dzięki czemu zasoby, które reprezentują, mogą być łatwo kategoryzowane, grupowane, 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 transferu ustrukturyzowanej zawartości przez usługi oparte na danych OData.

Na przykład poniższy przykładowy wpis OData demonstruje format Atom wysyłany za pośrednictwem żądania wstawienia jednostki do usługi Azure Table Storage przy użyciu interfejsu API REST (zobacz Insert Entity (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ą źródła danych Atom, które jest kolekcją wpisów Atom (zobacz Jednostki zapytania, 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

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ę Tabel. Aby uzyskać informacje o obsługiwanych typach danych i mapach na typy środowiska uruchomieniowego języka wspólnego (CLR), zobacz Understanding the Table Service Data Model (Omówienie modelu danych usługi Table Service).

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

Jeśli właściwość jest tworzona za pomocą jawnego typu, zapytanie, które zwraca jednostkę, zawiera ten typ w kanale informacyjnym Atom, dzięki czemu w razie potrzeby można określić typ istniejącej właściwości. Znajomość typu właściwości jest ważna podczas konstruowania zapytania filtrowego dla tej właściwości. Aby uzyskać więcej informacji, zobacz Wykonywanie zapytań dotyczących tabel i jednostek.

W przypadku właściwości wartości , i są używane w atomie, aby nie wskazywać odpowiednio liczby, nieskończoności dodatniej i Double NaN INF -INF nieskończoności ujemnej. Formularze Infinity i są również -Infinity akceptowane. Usługa Table Service nie obsługuje negatywnej wersji programu NaN . W formacie Atom rozróżnia zero dodatnie i ujemne.

Zobacz też

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