Nutzlastformat für Tabellendienstvorgänge

  • Artikel

Die REST-API des Tabellendiensts unterstützt ATOM und JSON als OData-Nutzlastformate. Während das ATOM-Protokoll für alle Versionen der Azure-Speicherdienste unterstützt wird, wird das JSON-Protokoll nur für Version 2013-08-15 und höher unterstützt.

  • JSON ist das empfohlene Nutzlastformat. JSON wird für Version 2013-08-15 und höher unterstützt. Sie müssen JSON mit Version 2015-12-11 und höher verwenden.

  • ATOM wird für Versionen vor 2015-12-11 unterstützt.

Hinweis

Die folgenden REST-API-Vorgänge sind keine OData-APIs und unterstützen derzeit nicht JSON: Tabellen-ACL abrufen, Tabellen-ACL festlegen, Tabellendiensteigenschaften abrufen und Tabellendiensteigenschaften festlegen.

Um das JSON- oder ATOM-Format anzugeben, geben Sie die entsprechenden Werte für die Content-Type Header und Accept an (unten beschrieben). Beachten Sie folgende Einschränkungen:

  • Der Content-Type-Header ist für alle Anforderungen erforderlich, die eine OData-Nutzlast enthalten.

  • Wenn der Accept-Header nicht bereitgestellt wird, dann wird als Inhaltstyp der Antwort standardmäßig application/atom+xml verwendet.

  • Durch Festlegen des URI-Parameters $format überschreiben Sie den im Accept-Anforderungsheader angegebenen Wert, wenn die OData-Datendienstversion auf 3.0 festgelegt ist. Ausführliche Informationen zur OData-Dienstversion finden Sie unter Festlegen der OData Data Service-Versionsheader .

Um das Nutzlastformat anzugeben, legen Sie den Content-Type-Anforderungsheader und den Accept-Anforderungsheader gemäß der folgenden Tabelle fest:

Nutzlastformat Header „Content-Type“ Accept-Header Datendienstversion (REST-API-Version) Unterstützte APIs
Atom application/atom+xml application/atom+xml 1.0 (beliebige Version)

2.0 (18.08.2011 oder höher)

3,0 (15.08.2013 oder höher)		 QueryTables

CreateTable

Tabelle löschen

Entitäten abfragen

Insert Entities

Insert Or Merge Entity

Insert Or Replace Entity

Entität aktualisieren

Entität zusammenführen

Entität löschen
JSON application/json application/json;odata=nometadata

application/json;odata=minimalmetadata

application/json;odata=fullmetadata

Ausführliche Informationen finden Sie im Abschnitt JSON-Format unten.		 3,0 (15.08.2013 oder höher) QueryTables

CreateTable

Tabelle löschen

Entitäten abfragen

Insert Entities

Insert Or Merge Entity

Insert Or Replace Entity

Entität aktualisieren

Entität zusammenführen

Entität löschen
XML application/xml application/xml – Get Table ACL

Set Table ACL

Get Table Service Properties

Festlegen von Tabellendiensteigenschaften

JSON-Format (Anwendung/JSON) (Versionen 2013-08-15 und höher)

OData erweitert das JSON-Format, indem wie beim oben beschriebenen ATOM-Format allgemeine Konventionen für diese Name-Wert-Paare definiert werden. OData definiert einen Satz kanonischer Anmerkungen für Steuerungsinformationen wie IDs, Typen und Links. Ausführliche Informationen zum JSON-Format finden Sie unter Einführung in JSON.

Der Hauptvorteil bei der Verwendung des JSON-Formats von OData besteht darin, dass die vorhersagbaren Teile der Nutzlast ausgelassen werden können, um die Nutzlastgröße zu reduzieren. Um diese Daten auf der Empfängerseite wieder zusammenzusetzen, werden Ausdrücke zur Berechnung der fehlenden Links, Typinformationen und Steuerungsdaten verwendet. Um zu steuern, was in der Nutzlast ausgelassen wird, können Sie drei Ebenen als Teil des Accept-Headers angeben:

  • application/json;odata=nometadata

  • application/json;odata=minimalmetadata

  • application/json;odata=fullmetadata

Die folgenden ODATA-Anmerkungen werden vom Azure-Tabellendienst unterstützt:

  • odata.metadata: Die Metadaten-URL für eine Auflistung, eine Entität, einen primitiven Wert oder ein Dienstdokument.

  • odata.id: Die Entitäts-ID, die in der Regel die URL der Ressource ist.

  • odata.editlink: Der Link zum Bearbeiten/Aktualisieren des Eintrags, wenn die Entität aktualisiert werden kann und wenn die odata.id keine URL ist, die zur Bearbeitung der Entität verwendet werden kann.

  • odata.type: Der Typname des enthaltenden Objekts.

  • odata.etag: Das ETag der Entität.

  • PropertyName@odata.type bei benutzerdefinierten Eigenschaften: der Typname der Zieleigenschaft.

  • PropertyName@odata.type bei Systemeigenschaften (d. h. die Eigenschaften PrimaryKey, RowKey und Timestamp): der Typname der Zieleigenschaft.

Die auf den einzelnen Ebenen eingeschlossenen Informationen sind in der folgenden Tabelle zusammengefasst:

Annotations odata=fullmetadata odata=minimalmetadata odata=nometadata
odata.metadata Ja Ja Nein
odata.id Ja Nein Nein
odata.editlink Ja Nein Nein
odata.type Ja Nein Nein
odata.etag Ja Nein Nein
PropertyName@odata.type bei benutzerdefinierten Eigenschaften Ja Ja Nein
PropertyName@odata.type bei Systemeigenschaften Ja Nein Nein

Eigenschaftstypen in einem JSON-Feed

Die odata.type-Anmerkung wird im JSON-Format von OData verwendet, um den Typ einer offenen Eigenschaft zu ermitteln. Diese Anmerkung ist vorhanden, wenn alle folgenden Bedingungen erfüllt sind:

  • Die JSON-Steuerungsebene wird entweder auf odata=minimalmetadata oder odata=fullmetadata festgelegt, wie im Abschnitt JSON-Format erläutert.

  • Die Eigenschaft ist eine benutzerdefinierte Eigenschaft. Beachten Sie, dass bei Azure-Tabellen nur die Eigenschaften PartitionKey, RowKey und Timestamp Systemeigenschaften sind und dass ihre Typinformationen in $metadata deklariert sind. Die Typanmerkung dieser Eigenschaften ist nur vorhanden, wenn die Steuerungsebene auf odata=fullmetadata festgelegt ist. Weitere Informationen finden Sie unter Grundlegendes zum Tabellendienstdatenmodell.

  • Der Typ der Eigenschaft kann nicht mithilfe der Heuristik zur Typerkennung ermittelt werden, wie in der folgenden Tabelle zusammengefasst.

Edm-Typ odata.type-Anmerkung erforderlich JSON-Typ
Edm.Binary Ja String
Edm.Boolean Nein Literale
Edm.DateTime Ja String
Edm.Double Nein Numerisch (enthält Dezimaltrennzeichen)
Edm.Guid Ja String
Edm.Int32 Nein Numerisch (enthält keine Dezimaltrennzeichen)
Edm.Int64 Ja String
Edm.String Nein String
– Nein Null

Der Tabellendienst speichert null keine Werte für Eigenschaften. Beim Schreiben einer Entität kann ein null Wert mit oder ohne odata.type-Anmerkung angegeben werden, und jede Eigenschaft mit einem null Wert wird so behandelt, als ob die Anforderung diese Eigenschaft nicht enthält. Null Eigenschaftswerte werden nie zurückgegeben, wenn Entitäten abgefragt werden.

Für Edm.Double werden die Werte NaNund Infinity-Infinity in JSON mit dem Typ Stringdargestellt, und eine odata.type-Anmerkung ist erforderlich. Der Tabellendienst unterstützt keine negative Version von NaNund unterscheidet im JSON-Format nicht zwischen positiver und negativer Null (er behandelt -0.0 als 0.0).

Die folgende JSON-Entität stellt ein Beispiel für jeden der acht verschiedene Eigenschaftstypen bereit:

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

Da PartitionKey und RowKey Systemeigenschaften sind, d. h., sie müssen von allen Tabellenzeilen definiert werden, wird die zugehörige Typanmerkung nicht in der Entität angezeigt. Diese Eigenschaften sind als Edm.String-Typ vordefiniert. Die anderen Eigenschaften sind jedoch benutzerdefinierte Eigenschaften und enthalten daher Typinformationen, die einem der unterstützten primitiven Typen in der obigen Tabelle entsprechen.

Beispiele:

Der folgende OData-Beispieleintrag veranschaulicht das JSON-Format, das als Anforderung zum Einfügen einer Entität in Azure Table Storage gesendet wird (Details zum Einfügevorgang finden Sie unter Entität einfügen ):

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

Wenn ein Client eine Gruppe von Entitäten in Azure Table Storage abfragt, antwortet der Dienst mit einer JSON-Nutzlast (Details zum Abfragevorgang finden Sie unter Abfrageentitäten ). Der Feed kann eine der folgenden drei Informationsebenen einschließen: keine Metadaten, minimale Metadaten oder vollständige Metadaten. Die einzelnen Ebenen werden anhand der folgenden Beispiele veranschaulicht:

Keine Metadaten:

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

Minimale Metadaten:

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

Vollständige Metadaten:

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

Weitere Informationen zum OData-JSON-Format finden Sie in der OData JSON Format Version 4.0-Spezifikation in Verbindung mit dem Dokument [MS-ODATAJSON]: OData Protocol JSON Format Standards Support Document.

Atom format (application/atom+xml) (nur Versionen vor 2015-12-11)

Atom ist ein XML-basiertes Dokumentformat, das Sammlungen verwandter Informationen beschreibt, die als Feeds bezeichnet werden. Feeds setzen sich aus einer Reihe von Elementen zusammen, die als Einträge bezeichnet werden. AtomPub definiert zusätzliche Formatkonstrukte für Einträge und Feeds, damit die von ihnen dargestellten Ressourcen leicht kategorisiert, gruppiert, bearbeitet und ermittelt werden können. Da Atom jedoch nicht definiert, wie strukturierte Daten mit Feeds codiert werden, definiert OData eine Reihe von Konventionen für die Darstellung strukturierter Daten in einem Atom-Feed, um die Übertragung strukturierter Inhalte durch dienste basierend auf OData zu ermöglichen.

Der folgende OData-Beispieleintrag veranschaulicht beispielsweise das Atom-Format, das über eine Anforderung zum Einfügen einer Entität in Azure Table Storage mithilfe der REST-API gesendet wird (Details zum Einfügevorgang finden Sie unter Entität einfügen ):

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

Wenn ein Client eine Gruppe von Entitäten im Tabellenspeicher abfragt, antwortet der Dienst mit einem Atom-Feed, bei dem es sich um eine Sammlung von Atom-Einträgen handelt (Details zum Abfragevorgang finden Sie unter Abfrageentitäten ):

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

Eigenschaftstypen in einem Atom-Feed

Eigenschaftendatentypen werden durch die OData-Protokollspezifikation definiert. Nicht alle von der Spezifikation definierten Datentypen werden vom Tabellendienst unterstützt. Informationen zu den unterstützten Datentypen und deren Zuordnung zu CLR-Typen (Common Language Runtime) finden Sie unter Grundlegendes zum Tabellendienstdatenmodell.

Eine Eigenschaft kann mit oder ohne einen expliziten Datentyp angegeben werden. Wenn der Typ ausgelassen wird, wird die Eigenschaft automatisch als Datentyp Edm.Stringerstellt.

Wenn eine Eigenschaft mit einem expliziten Typ erstellt wird, enthält eine Abfrage, die die Entität zurückgibt, diesen Typ innerhalb des Atom-Feeds, sodass Sie den Typ einer vorhandenen Eigenschaft bei Bedarf bestimmen können. Sie sollten den Typ einer Eigenschaft kennen, wenn Sie eine Abfrage mit einem Filter für diese Eigenschaft erstellen. Weitere Informationen finden Sie unter Abfragen von Tabellen und Entitäten.

Für Double Eigenschaften werden die Werte NaN, INFund -INF in Atom verwendet, um keine Zahl, positive Unendlichkeit bzw. negative Unendlichkeit anzugeben. Die Formulare Infinity und -Infinity werden ebenfalls akzeptiert. Der Tabellendienst unterstützt keine negative Version von NaN. Im Atom-Format wird zwischen positiver und negativer Null unterschieden.

Weitere Informationen

Festlegen der Header für die OData-Datendienstversion
Versioning for the Azure Storage Services (Versionsverwaltung für Azure Storage-Dienste)
Konzepte des Tabellenspeicherdiensts