Payload-indeling voor Table-servicebewerkingen

  • Artikel

De REST API van de Table-service ondersteunt ATOM en JSON als OData-nettoladingindelingen. Hoewel het ATOM-protocol wordt ondersteund voor alle versies van de Azure-opslagservices, wordt het JSON-protocol alleen ondersteund voor versie 2013-08-15 en hoger.

  • JSON is de aanbevolen nettoladingindeling. JSON wordt ondersteund voor versie 2013-08-15 en hoger. U moet JSON gebruiken met versie 2015-12-11 en hoger.

  • ATOM wordt ondersteund voor versies ouder dan 2015-12-11.

Notitie

De volgende REST API-bewerkingen zijn geen OData-API's en bieden momenteel geen ondersteuning voor JSON: Tabel-ACL ophalen, Tabel-ACL instellen, Eigenschappen van tabelservice ophalen en Eigenschappen van tabelservice instellen.

Als u de JSON- of ATOM-indeling wilt opgeven, geeft u de juiste waarden op voor de Content-Type headers en Accept (hieronder beschreven). Houd rekening met de volgende beperkingen:

  • De Content-Type header is vereist voor alle aanvragen die een OData-nettolading bevatten.

  • Als de Accept header niet is opgegeven, wordt het inhoudstype van het antwoord standaard ingesteld op application/atom+xml.

  • Als u de $format URI-parameter opgeeft, wordt de waarde die is opgegeven in de Accept aanvraagheader overschreven wanneer de versie van de OData-gegevensservice is ingesteld op 3.0. Zie De OData Data Service-versieheaders instellen voor meer informatie over de versie van de OData-service.

Als u de indeling van de nettolading wilt opgeven, stelt u de Content-Type aanvraagheaders en Accept in volgens de onderstaande tabel:

Payload-indeling Koptekst van inhoudstype Koptekst accepteren Data Service Version (REST API-versie) Ondersteunde API's
Atom application/atom+xml application/atom+xml 1.0 (elke versie)

2.0 (18-08-2011 of hoger)

3.0 (2013-08-15 of hoger)		 Querytables

CreateTable

Tabel verwijderen

Query-entiteiten

Entiteiten invoegen

Entiteit invoegen of samenvoegen

Entiteit invoegen of vervangen

Entiteit bijwerken

Entiteit samenvoegen

Entiteit verwijderen
JSON application/json application/json;odata=nometadata

application/json;odata=minimalmetadata

application/json;odata=fullmetadata

Zie de sectie JSON-indeling hieronder voor meer informatie.		 3.0 (2013-08-15 of hoger) Querytables

CreateTable

Tabel verwijderen

Query-entiteiten

Entiteiten invoegen

Entiteit invoegen of samenvoegen

Entiteit invoegen of vervangen

Entiteit bijwerken

Entiteit samenvoegen

Entiteit verwijderen
XML application/xml application/xml N.v.t. Tabel-ACL ophalen

Tabel-ACL instellen

Eigenschappen van tabelservice ophalen

Eigenschappen van tabelservice instellen

JSON-indeling (toepassing/json) (versies 2013-08-15 en hoger)

OData breidt de JSON-indeling uit door algemene conventies te definiëren voor deze naam-waardeparen, vergelijkbaar met de ATOM-indeling die hierboven wordt beschreven. OData definieert een set canonieke aantekeningen voor besturingsinformatie, zoals id's, type en koppelingen. Zie Inleiding tot JSON voor meer informatie over de JSON-indeling.

Het belangrijkste voordeel van het gebruik van de JSON-indeling van OData is dat de voorspelbare delen van de nettolading kunnen worden weggelaten om de grootte van de nettolading te verkleinen. Als u deze gegevens aan de ontvangende kant opnieuw wilt instellen, worden expressies gebruikt om ontbrekende koppelingen te berekenen, informatie te typen en gegevens te beheren. Als u wilt bepalen wat er uit de nettolading wordt weggelaten, zijn er drie niveaus die u kunt opgeven als onderdeel van de Accept header:

  • application/json;odata=nometadata

  • application/json;odata=minimalmetadata

  • application/json;odata=fullmetadata

De volgende ODATA-aantekeningen worden ondersteund door de Azure Table-service:

  • odata.metadata: De metagegevens-URL voor een verzameling, entiteit, primitieve waarde of servicedocument.

  • odata.id: de entiteits-id, die doorgaans de URL naar de resource is.

  • odata.editlink: de koppeling die wordt gebruikt om de vermelding te bewerken/bij te werken, als de entiteit kan worden bijgewerkt en de odata.id geen URL vertegenwoordigt die kan worden gebruikt om de entiteit te bewerken.

  • odata.type: De typenaam van het object dat het bevat.

  • odata.etag: De ETag van de entiteit.

  • PropertyName@odata.type, voor aangepaste eigenschappen: de typenaam van de doeleigenschap.

  • PropertyName@odata.type, voor systeemeigenschappen (bijvoorbeeld de PrimaryKeyeigenschappen , RowKeyen Timestamp ): de typenaam van de doeleigenschap.

De informatie in elk niveau wordt samengevat in de volgende tabel:

Annotations odata=fullmetadata odata=minimalmetadata odata=nometadata
odata.metadata Ja Ja Nee
odata.id Ja Nee Nee
odata.editlink Ja Nee Nee
odata.type Ja Nee Nee
odata.etag Ja Nee Nee
PropertyName@odata.type voor aangepaste eigenschappen Ja Ja Nee
PropertyName@odata.type voor systeemeigenschappen Ja Nee Nee

Eigenschapstypen in een JSON-feed

De odata.type aantekening wordt gebruikt in de OData JSON-indeling om het type van een open eigenschap te bepalen. Deze aantekening is aanwezig wanneer aan alle onderstaande voorwaarden is voldaan:

  • Het JSON-besturingsniveau is ingesteld op odata=minimalmetadata of odata=fullmetadata, zoals besproken in de sectie JSON-indeling .

  • De eigenschap is een aangepaste eigenschap. Houd er rekening mee dat voor Azure-tabellen alleen de PartitionKeyeigenschappen , RowKeyen Timestamp systeemeigenschappen zijn en dat hun typegegevens worden gedeclareerd in $metadata. De typeaantekening voor deze eigenschappen is alleen aanwezig wanneer het besturingselementniveau is ingesteld op odata=fullmetadata. Zie Inzicht in het tabelservicegegevensmodel voor meer informatie.

  • Het type van de eigenschap kan niet worden bepaald met de heuristiek van typedetectie die in de onderstaande tabel wordt samengevat.

Edm-type aantekening voor odata.type vereist JSON-type
Edm.Binary Ja Tekenreeks
Edm.Boolean Nee Literals
Edm.DateTime Ja Tekenreeks
Edm.Double Nee Numeriek (bevat een decimaalteken)
Edm.Guid Ja Tekenreeks
Edm.Int32 Nee Numeriek (bevat geen decimaalteken)
Edm.Int64 Ja Tekenreeks
Edm.String Nee Tekenreeks
n.v.t. Nee Null

De Tabelservice bewaart null geen waarden voor eigenschappen. Bij het schrijven van een entiteit kan een null waarde worden opgegeven met of zonder een odata.type-aantekening en wordt elke eigenschap met een null waarde verwerkt alsof de aanvraag die eigenschap niet bevat. Null eigenschapswaarden worden nooit geretourneerd bij het uitvoeren van query's op entiteiten.

Voor Edm.Double worden de waarden NaN, Infinity en -Infinity weergegeven in JSON met behulp van het type String, en is een odata.type-aantekening vereist. De Table-service biedt geen ondersteuning voor een negatieve versie van NaNen maakt in JSON-indeling geen onderscheid tussen positieve en negatieve nul (het wordt behandeld -0.0 als 0.0).

De volgende JSON-entiteit biedt een voorbeeld voor elk van de acht verschillende eigenschapstypen:

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

Omdat PartitionKey en RowKey systeemeigenschappen zijn, wat betekent dat alle tabelrijen deze eigenschappen moeten definiëren, wordt hun typeaantekening niet weergegeven in de entiteit. Deze eigenschappen zijn vooraf gedefinieerd als het type Edm.String. De andere eigenschappen zijn echter aangepaste eigenschappen en bevatten daarom typegegevens die overeenkomen met een van de ondersteunde primitieve typen in de bovenstaande tabel.

Voorbeelden:

In de volgende OData-voorbeeldvermelding ziet u de JSON-indeling die is verzonden als een aanvraag voor het invoegen van een entiteit in Azure Table Storage (zie Entiteit invoegen voor meer informatie over de invoegbewerking):

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

Wanneer een client een query uitvoert op een set entiteiten in Azure Table Storage, reageert de service met een JSON-nettolading (zie Query-entiteiten voor meer informatie over de querybewerking). De feed kan een van de drie informatieniveaus bevatten: geen metagegevens, minimale metagegevens of volledige metagegevens. In de volgende voorbeelden ziet u elk type:

Geen metagegevens:

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

Minimale metagegevens:

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

Volledige metagegevens:

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

Zie de specificatie OData JSON Format Version 4.0 in combinatie met het ondersteuningsdocument [MS-ODATAJSON]: OData Protocol JSON Format Standards Support Document voor meer informatie over de OData JSON-indeling.

Atom-indeling (toepassing/atom+xml) (alleen eerdere versies dan 11-12-2015)

Atom is een op XML gebaseerde documentindeling waarin verzamelingen gerelateerde informatie worden beschreven die feeds worden genoemd. Feeds bestaan uit een aantal items, ook wel vermeldingen genoemd. AtomPub definieert aanvullende indelingsconstructies voor vermeldingen en feeds, zodat de resources die ze vertegenwoordigen eenvoudig kunnen worden gecategoriseerd, gegroepeerd, bewerkt en gedetecteerd. Omdat Atom echter niet definieert hoe gestructureerde gegevens worden gecodeerd met feeds, definieert OData een set conventies voor het weergeven van gestructureerde gegevens in een Atom-feed om overdracht van gestructureerde inhoud door services op basis van OData mogelijk te maken.

In de volgende OData-voorbeeldvermelding ziet u bijvoorbeeld de Atom-indeling die is verzonden via een aanvraag voor het invoegen van een entiteit in Azure Table Storage met behulp van de REST API (zie Entiteit invoegen voor meer informatie over de invoegbewerking):

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

Wanneer een client een query uitvoert op een set entiteiten in Table Storage, reageert de service met een Atom-feed, een verzameling Atom-vermeldingen (zie Query-entiteiten voor meer informatie over de querybewerking):

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

Eigenschapstypen in een Atom-feed

Gegevenstypen van eigenschappen worden gedefinieerd door de OData Protocol-specificatie. Niet alle gegevenstypen die door de specificatie zijn gedefinieerd, worden ondersteund door de Table-service. Zie Understanding the Table Service Data Model (Engelstalig) voor meer informatie over de ondersteunde gegevenstypen en hoe deze worden toegewezen aan common language runtime (CLR)-typen.

Een eigenschap kan worden opgegeven met of zonder een expliciet gegevenstype. Als u het type weglaat, wordt de eigenschap automatisch gemaakt als gegevenstype Edm.String.

Als een eigenschap is gemaakt met een expliciet type, bevat een query die de entiteit retourneert dat type in de Atom-feed, zodat u indien nodig het type van een bestaande eigenschap kunt bepalen. Het is belangrijk om het type van een eigenschap te kennen wanneer u een query maakt die op die eigenschap filtert. Zie Query's uitvoeren op tabellen en entiteiten voor meer informatie.

Voor Double eigenschappen worden de waarden NaN, INF, en -INF gebruikt in Atom om respectievelijk geen getal, positieve oneindigheid en negatieve oneindigheid aan te geven. De formulieren Infinity en -Infinity worden ook geaccepteerd. De Table-service biedt geen ondersteuning voor een negatieve versie van NaN. In Atom-indeling wordt onderscheid gemaakt tussen positieve en negatieve nul.

Zie ook

De OData Data Service-versieheaders instellen
Versiebeheer voor Azure Storage Services
Concepten van Table Service