Share via

Formát datové části pro operace služby Table Service

  • Článek

Rozhraní REST API služby Table podporuje jako formáty datové části OData ATOM a JSON. Protokol ATOM se sice podporuje ve všech verzích služeb Azure Storage, ale protokol JSON se podporuje jenom pro verzi 2013-08-15 a novější.

  • Json je doporučený formát datové části. JSON se podporuje pro verzi 2013-08-15 a novější. Musíte použít JSON s verzí 2015-12-11 a novější.

  • ATOM se podporuje ve verzích starších než 2015-12-11.

Poznámka

Následující operace rozhraní REST API nejsou rozhraníMI OData API a v současné době nepodporují JSON: Získání seznamu ACL tabulky, nastavení seznamu ACL tabulky, získání vlastností služby Table Service a nastavení vlastností služby Table Service.

Pokud chcete zadat formát JSON nebo ATOM, zadejte příslušné hodnoty pro Content-Type hlavičky a Accept (popsané níže). Mějte na paměti následující omezení:

  • Hlavička Content-Type je povinná pro všechny požadavky, které obsahují datovou část OData.

  • Pokud hlavičku Accept nezadáte, typ obsahu odpovědi se ve výchozím nastavení nastaví na application/atom+xml.

  • Zadání parametru $format URI přepíše hodnotu zadanou v Accept hlavičce požadavku, pokud je verze datové služby OData nastavená na 3.0. Podrobnosti o verzi služby OData najdete v tématu Nastavení hlaviček verze datové služby OData.

Pokud chcete zadat formát datové části, nastavte Content-Type hlavičky a Accept žádosti podle následující tabulky:

Formát datové části Hlavička typu obsahu Přijmout hlavičku Verze datové služby (verze rozhraní REST API) Podporovaná rozhraní API
Atom application/atom+xml application/atom+xml 1.0 (libovolná verze)

2.0 (2011-08-18 nebo novější)

3.0 (2013-08-15 nebo novější)		 Tabulky dotazů

Createtable

Odstranit tabulku

Dotazování entit

Vložit entity

Vložení nebo sloučení entity

Vložení nebo nahrazení entity

Aktualizace entity

Sloučit entitu

Odstranit entitu
JSON application/json application/json;odata=nometadata

application/json;odata=minimalmetadata

application/json;odata=fullmetadata

Podrobnosti najdete níže v části Formát JSON .		 3.0 (2013-08-15 nebo novější) Tabulky dotazů

Createtable

Odstranit tabulku

Dotazování entit

Vložit entity

Vložení nebo sloučení entity

Vložení nebo nahrazení entity

Aktualizace entity

Sloučit entitu

Odstranit entitu
XML application/xml application/xml – Získání seznamu ACL tabulky

Nastavit seznam ACL tabulky

Získání vlastností služby Table Service

Nastavení vlastností služby Table Service

Formát JSON (application/json) (verze 2013-08-15 a novější)

OData rozšiřuje formát JSON definováním obecných konvencí pro tyto páry název-hodnota, podobně jako formát ATOM popsaný výše. OData definuje sadu kanonických poznámek pro informace o ovládacích prvků, jako jsou ID, typ a odkazy. Podrobnosti o formátu JSON najdete v tématu Úvod do formátu JSON.

Klíčovou výhodou použití formátu JSON pro OData je, že předvídatelné části datové části je možné vynechat, aby se snížila velikost datové části. K rekonstituci těchto dat na straně příjemce se výrazy používají k výpočtu chybějících odkazů, informací o typech a řízení dat. Pokud chcete určit, co se v datové části vynechá, můžete jako součást hlavičky Accept zadat tři úrovně:

  • application/json;odata=nometadata

  • application/json;odata=minimalmetadata

  • application/json;odata=fullmetadata

Služba Azure Table podporuje následující poznámky ODATA:

  • odata.metadata: Adresa URL metadat pro kolekci, entitu, primitivní hodnotu nebo dokument služby.

  • odata.id: ID entity, což je obecně adresa URL prostředku.

  • odata.editlink: Odkaz použitý k úpravě nebo aktualizaci položky, pokud je entita aktualizovatelná a odata.id nepředstavuje adresu URL, kterou lze použít k úpravě entity.

  • odata.type: Název typu obsahujícího objektu.

  • odata.etag: Značka ETag entity.

  • PropertyName@odata.type, pro vlastní vlastnosti: Název typu cílové vlastnosti.

  • PropertyName@odata.type, pro systémové vlastnosti (tj.PrimaryKey vlastnosti , RowKeyaTimestamp): Název typu cílové vlastnosti.

Informace zahrnuté v jednotlivých úrovních jsou shrnuté v následující tabulce:

Annotations odata=fullmetadata odata=minimalmetadata odata=nometadata
odata.metadata Ano Ano Ne
odata.id Ano Ne Ne
odata.editlink Yes No Ne
odata.type Ano No Ne
odata.etag Ano Ne Ne
PropertyName@odata.type pro vlastní vlastnosti Ano Ano No
PropertyName@odata.type pro systémové vlastnosti Ano Ne Ne

Typy vlastností v informačním kanálu JSON

Poznámka se odata.type používá ve formátu JSON OData k určení typu otevřené vlastnosti. Tato poznámka je k dispozici, pokud jsou splněny všechny následující podmínky:

  • Úroveň ovládacího prvku JSON je nastavená na nebo odata=minimalmetadataodata=fullmetadata, jak je popsáno v části Formát JSON .

  • Vlastnost je vlastní vlastnost. Všimněte si, že pro tabulky Azure jsou systémové vlastnosti pouze PartitionKeyvlastnosti , RowKeya Timestamp a informace o jejich typu jsou deklarovány v $metadata. Poznámka k typu pro tyto vlastnosti je k dispozici pouze v případě, že je úroveň ovládacího prvku nastavena na odata=fullmetadatahodnotu . Další informace najdete v tématu Principy datového modelu služby Table Service.

  • Typ vlastnosti nelze určit pomocí heuristiky detekce typů shrnuté v následující tabulce.

Typ Edm Požadovaná poznámka odata.type Typ JSON
Edm.Binary Ano Řetězec
Edm.Boolean Ne Literály
Edm.DateTime Ano Řetězec
Edm.Double Ne Číselné (obsahuje desetinnou čárku)
Edm.Guid Ano Řetězec
Edm.Int32 Ne Číselné (neobsahuje desetinnou čárku)
Edm.Int64 Ano Řetězec
Edm.String No Řetězec
Není k dispozici Ne Null

Služba Table Service neuchovává null hodnoty vlastností. Při zápisu entity null může být hodnota zadána s poznámkou odata.type nebo bez a každá vlastnost s null hodnotou je zpracována, jako by požadavek tuto vlastnost neobsahoval. Null Hodnoty vlastností se při dotazování entit nikdy nevrací.

Pro Edm.Double jsou hodnoty NaNa Infinity-Infinity reprezentovány ve formátu JSON pomocí typu Stringa vyžaduje se poznámka odata.type. Služba Table Service nepodporuje zápornou verzi objektu NaNa ve formátu JSON nerozlišuje mezi kladnou a zápornou nulou (považuje -0.00.0se za ).

Následující entita JSON poskytuje příklad pro každý z osmi různých typů vlastností:

{  
  "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"  
}

Vzhledem k tomu PartitionKey , že a RowKey jsou systémové vlastnosti, což znamená, že všechny řádky tabulky musí tyto vlastnosti definovat, jejich poznámka typu se v entitě nezobrazí. Tyto vlastnosti jsou předdefinované jako typ Edm.String. Ostatní vlastnosti jsou však vlastní vlastnosti, a proto obsahují informace o typu odpovídající jednomu z podporovaných primitivních typů ve výše uvedené tabulce.

Příklady:

Následující ukázková položka OData ukazuje formát JSON odeslaný jako požadavek na vložení entity do služby Azure Table Storage (podrobnosti o operaci vložení najdete v tématu Vložení entity ):

{  
  "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",  
}

Když se klient dotazuje na sadu entit ve službě Azure Table Storage, služba odpoví datovou částí JSON (podrobnosti o operaci dotazu najdete v tématu Dotazování entit). Informační kanál může obsahovat jednu ze tří úrovní informací: žádná metadata, minimální metadata nebo úplná metadata. Následující příklady ukazují jednotlivé druhy:

Žádná metadata:

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

Minimální metadata:

{  
  "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",  
    }  
}

Úplná metadata:

{  
  "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",  
    }  
}

Další informace o formátu OData JSON najdete ve specifikaci formátu OData JSON verze 4.0 ve spojení s dokumentem [MS-ODATAJSON]: Podpora standardů FORMÁTU JSON protokolu OData.

Formát Atom (application/atom+xml) (pouze verze starší než 2015-12-11)

Atom je formát dokumentu založený na jazyce XML, který popisuje kolekce souvisejících informací označovaných jako informační kanály. Informační kanály se skládají z řady položek, které se označují jako položky. AtomPub definuje další konstrukty formátu pro položky a informační kanály, aby prostředky, které představují, mohly být snadno kategorizovány, seskupovány, upravovány a zjištěny. Vzhledem k tomu, že Atom nedefinuje způsob kódování strukturovaných dat pomocí informačních kanálů, OData definuje sadu konvencí pro reprezentaci strukturovaných dat v informačním kanálu Atom, aby bylo možné přenášet strukturovaný obsah službami založenými na OData.

Například následující ukázková položka OData ukazuje formát Atom odeslaný prostřednictvím požadavku na vložení entity do služby Azure Table Storage pomocí rozhraní REST API (podrobnosti o operaci vložení najdete v tématu Vložení entity ):

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

Když se klient dotazuje na sadu entit ve službě Table Storage, služba odpoví informačním kanálem Atom, což je kolekce položek Atom (podrobnosti o operaci dotazu najdete v tématu Dotazování entit ):

<?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 vlastností v informačním kanálu Atom

Datové typy vlastností jsou definovány specifikací protokolu OData. Služba Table Service nepodporuje všechny datové typy definované ve specifikaci. Informace o podporovaných datových typech a o tom, jak se mapují na typy MODULU CLR (Common Language Runtime), najdete v tématu Vysvětlení datového modelu služby Table Service.

Vlastnost může být zadána s explicitním datovým typem nebo bez. Pokud je typ vynechán, vlastnost se automaticky vytvoří jako datový typ Edm.String.

Pokud je vlastnost vytvořena s explicitním typem, dotaz, který vrací entitu, zahrne tento typ v informačním kanálu Atom, abyste mohli v případě potřeby určit typ existující vlastnosti. Znalost typu vlastnosti je důležitá při vytváření dotazu, který tuto vlastnost filtruje. Další informace najdete v tématu Dotazování tabulek a entit.

Pro Double vlastnosti se hodnoty NaN, INFa -INF používají v Atomu k označení čísla, kladného nekonečna a záporného nekonečna. Formuláře Infinity a -Infinity jsou také přijímány. Služba Table Service nepodporuje zápornou verzi nástroje NaN. Ve formátu Atom rozlišuje mezi kladnou a zápornou nulou.

Viz také

Nastavení hlaviček verze datové služby OData
Správa verzí pro služby Azure Storage
Koncepty služby Table service