VERTRIEB: 1-800-867-1380

Nutzlastformat für Tabellendienstvorgänge

Letzte Aktualisierung: April 2015

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 die Versionen 2013-08-15 und höher unterstützt.

noteHinweis
Die folgenden REST-API-Vorgänge sind keine OData-APIs und unterstützen derzeit kein JSON: Get Table ACL, Set Table ACL, Get Table Service Properties und Festlegen von Tabellendiensteigenschaften.

Um das ATOM- oder JSON-Format festzulegen, geben Sie die entsprechenden Werte für den Content-Type-Header und den Accept-Header (unten beschrieben) an. 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 über die OData-Dienstversion finden Sie unter Festlegen der Header für die OData-Datendienstversion.

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

 

Nutzlastformat Content-Type-Header Accept-Header Datendienstversion (REST-API-Version) Unterstützte APIs

Atom

application/atom+xml

application/atom+xml

1.0 (beliebige Version)

2,0 (18.08.11 oder höher)

3,0 (15.08.2013 oder höher)

QueryTables

CreateTable

Delete Table

Query Entities

Insert Entities

Insert Or Merge Entity

Insert Or Replace Entity

Entität aktualisieren

Merge Entity

Delete Entity

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

Delete Table

Query Entities

Insert Entities

Insert Or Merge Entity

Insert Or Replace Entity

Entität aktualisieren

Merge Entity

Delete Entity

XML

application/xml

application/xml

Nicht zutreffend

Get Table ACL

Set Table ACL

Get Table Service Properties

Festlegen von Tabellendiensteigenschaften

Atom ist ein XML-basiertes Dokumentformat, das eine Sammlung verwandter Informationen, die so genannten Feeds, beschreibt. Feeds setzen sich aus einer Reihe von Elementen zusammen, die als Einträge bezeichnet werden. Mit AtomPub werden zusätzliche Formatkonstrukte für Einträge und Feeds definiert, sodass die durch sie dargestellten Ressourcen einfach kategorisiert, gruppiert, bearbeitet und ermittelt werden können. Da Atom jedoch nicht definiert, wie strukturierte Daten in Feeds codiert werden, definiert OData einen Satz von Konventionen für die Darstellung strukturierter Daten in einem Atom-Feed, um Übertragungen strukturierter Daten mit auf OData basierenden Diensten zu ermöglichen.

Durch den folgenden OData-Beispieleintrag wird das Atom-Format veranschaulicht, das in einer Anforderung übermittelt wird, um eine Entität mithilfe der REST-API in den Azure-Tabellenspeicher einzufügen (ausführliche Informationen zum Einfügevorgang finden Sie unter Insert 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="http://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 Entitätenmenge vom Tabellenspeicher abfragt, antwortet der Dienst mit einem Atom-Feed, der alle gesammelten Atom-Einträge umfasst (Details zum Abfragevorgang finden Sie unter Query Entities):

<?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="http://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/&quot;0x5B168C7B6E589D2&quot;">
  <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>

Datentypen von Eigenschaften werden in der OData-Protokollspezifikation definiert. Nicht alle von der Spezifikation definierten Datentypen werden vom Tabellendienst unterstützt. Weitere Informationen zu den unterstützten Datentypen und wie diese den CLR-Typen (Common Language Runtime) zugeordnet sind, finden Sie unter Grundlegendes zum Tabellendienst-Datenmodell.

Eine Eigenschaft kann mit oder ohne einen expliziten Datentyp angegeben werden. Wird der Typ nicht angegeben, wird die Eigenschaft automatisch mit dem Datentyp Edm.String erstellt.

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.

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 über das 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 normalerweise der Ressourcen-URL entspricht.

  • 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

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 Tabellendienst-Datenmodell.

  • 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

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, die folglich Typinformationen enthalten, die einem der unterstützten primitiven Typen in der vorangehenden Tabelle entsprechen.

Im folgenden Beispiel für einen OData-Eintrag wird das JSON-Format veranschaulicht, das als Anforderung zum Einfügen einer Entität an den Azure-Tabellenspeicher gesendet wird (Details zum Einfügevorgang finden Sie unter Insert 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",
}

Wenn ein Client eine Entitätenmenge vom Azure-Tabellenspeicher abfragt, reagiert der Dienst mit einer JSON-Nutzlast (Details zum Abfragevorgang finden Sie unter Query Entities). 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 Spezifikation zu OData JSON-Format Version 4.0 und im [MS-ODATAJSON]: Begleitdokument zu den JSON-Formatstandards des OData-Protokolls.

Siehe auch

Fanden Sie dies hilfreich?
(1500 verbleibende Zeichen)
Vielen Dank für Ihr Feedback.
Anzeigen:
© 2015 Microsoft