Nyttolastformat för table service-åtgärder

  • Artikel

Rest-API:et för tabelltjänsten stöder ATOM- och JSON-format som OData-nyttolastformat. ATOM-protokollet stöds för alla versioner av Azure Storage-tjänsterna, men JSON-protokollet stöds endast för version 2013-08-15 och senare.

  • JSON är det rekommenderade nyttolastformatet. JSON stöds för version 2013-08-15 och senare. Du måste använda JSON med version 2015-12-11 och senare.

  • ATOM stöds för tidigare versioner än 2015-12-11.

Anteckning

Följande REST API-åtgärder är inte OData-API:er och stöder för närvarande inte JSON: Hämta tabell-ACL, Ange tabell-ACL, Hämta tabelltjänstegenskaper och Ange egenskaper för tabelltjänsten.

Om du vill ange JSON- eller ATOM-format anger du lämpliga värden för rubrikerna Content-Type och Accept (beskrivs nedan). Observera följande begränsningar:

  • Huvudet Content-Type krävs för alla begäranden som innehåller en OData-nyttolast.

  • Accept Om rubriken inte har angetts anges som standard innehållstypen för svaret till application/atom+xml.

  • Om du anger $format URI-parametern åsidosätts värdet som anges i Accept begärandehuvudet, när OData-datatjänstens version är inställd på 3.0. Mer information om OData-tjänstversionen finns i Ange versionshuvuden för OData-datatjänsten .

Ange nyttolastformatet Content-Type genom att ange huvudena och Accept begäran enligt tabellen nedan:

Nyttolastformat Rubrik för innehållstyp Acceptera sidhuvud Data Service-version (REST API-version) API:er som stöds
Atom application/atom+xml application/atom+xml 1.0 (valfri version)

2.0 (2011-08-18 eller senare)

3.0 (2013-08-15 eller senare)		 QueryTables

CreateTable

Ta bort tabell

Fråga entiteter

Infoga entiteter

Infoga eller sammanfoga entitet

Infoga eller ersätt entitet

Uppdatera entitet

Sammanfoga entitet

Ta bort entitet
JSON application/json application/json;odata=nometadata

application/json;odata=minimalmetadata

application/json;odata=fullmetadata

Mer information finns i avsnittet JSON-format nedan.		 3.0 (2013-08-15 eller senare) QueryTables

CreateTable

Ta bort tabell

Fråga entiteter

Infoga entiteter

Infoga eller sammanfoga entitet

Infoga eller ersätt entitet

Uppdatera entitet

Sammanfoga entitet

Ta bort entitet
XML application/xml application/xml Ej tillämpligt Hämta tabell-ACL

Ange tabell-ACL

Hämta egenskaper för tabelltjänsten

Ange egenskaper för tabelltjänst

JSON-format (program/json) (versioner 2013-08-15 och senare)

OData utökar JSON-formatet genom att definiera allmänna konventioner för dessa namn/värde-par, liknande DET ATOM-format som beskrivs ovan. OData definierar en uppsättning kanoniska anteckningar för kontrollinformation, till exempel ID:n, typ och länkar. Mer information om JSON-formatet finns i Introduktion till JSON.

Den största fördelen med att använda ODatas JSON-format är att förutsägbara delar av nyttolasten kan utelämnas för att minska nyttolastens storlek. För att återskapa dessa data på mottagarsidan används uttryck för att beräkna länkar som saknas, skriva information och kontrollera data. För att styra vad som utelämnas från nyttolasten finns det tre nivåer som du kan ange som en del av Accept rubriken:

  • application/json;odata=nometadata

  • application/json;odata=minimalmetadata

  • application/json;odata=fullmetadata

Följande ODATA-anteckningar stöds av Azure Table-tjänsten:

  • odata.metadata: Metadata-URL:en för ett samlings-, entitets-, primitivvärde- eller tjänstdokument.

  • odata.id: Entitets-ID, som vanligtvis är URL:en till resursen.

  • odata.editlink: Länken som används för att redigera/uppdatera posten, om entiteten är uppdaterad och odata.id inte representerar en URL som kan användas för att redigera entiteten.

  • odata.type: Typnamnet för det innehållande objektet.

  • odata.etag: ETag för entiteten.

  • PropertyName@odata.type, för anpassade egenskaper: Typnamnet för målegenskapen.

  • PropertyName@odata.type, för systemegenskaper (t.ex.PrimaryKey egenskaperna , RowKeyochTimestamp): Typnamnet för målegenskapen.

Informationen som ingår i varje nivå sammanfattas i följande tabell:

Annotations odata=fullmetadata odata=minimalmetadata odata=nometadata
odata.metadata Ja Ja Inga
odata.id Ja Inga Inga
odata.editlink Ja Inga Inga
odata.type Ja Inga Inga
odata.etag Ja Inga Inga
PropertyName@odata.type för anpassade egenskaper Ja Ja Inga
PropertyName@odata.type för systemegenskaper Ja Inga Inga

Egenskapstyper i en JSON-feed

Kommentaren odata.type används i OData JSON-format för att fastställa typen av en öppen egenskap. Den här kommentaren finns när alla villkor nedan är uppfyllda:

  • JSON-kontrollnivån är inställd på antingen odata=minimalmetadata eller odata=fullmetadata, enligt beskrivningen i avsnittet JSON-format .

  • Egenskapen är en anpassad egenskap. Observera att för Azure-tabeller är endast PartitionKeyegenskaperna , RowKeyoch Timestamp systemegenskaper och deras typinformation deklareras i $metadata. Typanteckningen för dessa egenskaper finns bara när kontrollnivån är inställd på odata=fullmetadata. Mer information finns i Förstå datamodellen för Table Service.

  • Egenskapens typ kan inte fastställas via typidentifierings-heuristiken som sammanfattas i tabellen nedan.

Typ av Edm odata.type-anteckning krävs JSON-typ
Edm.Binary Ja Sträng
Edm.Boolean No Literaler
Edm.DateTime Ja Sträng
Edm.Double No Numeriskt (innehåller decimaltecken)
Edm.Guid Ja Sträng
Edm.Int32 No Numeriskt (innehåller inte decimaltecken)
Edm.Int64 Ja Sträng
Edm.String Inga Sträng
saknas No Null

Tabelltjänsten sparar null inte värden för egenskaper. När du skriver en entitet kan ett null värde anges med eller utan en odata.type-anteckning, och alla egenskaper med ett null värde hanteras som om begäran inte innehöll den egenskapen. Null egenskapsvärden returneras aldrig när du frågar entiteter.

För Edm.Double representeras värdena NaN, Infinity och -Infinity i JSON med hjälp av typen String, och en odata.type-anteckning krävs. Tabelltjänsten stöder inte en negativ version av NaN, och i JSON-format skiljer den inte mellan positiv och negativ noll (den behandlar -0.0 som 0.0).

Följande JSON-entitet innehåller ett exempel för var och en av de åtta olika egenskapstyperna:

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

Eftersom PartitionKey och RowKey är systemegenskaper, vilket innebär att alla tabellrader måste definiera dessa egenskaper, visas inte deras typanteckning i entiteten. Dessa egenskaper är fördefinierade som typen Edm.String. De andra egenskaperna är dock anpassade egenskaper och innehåller därför typinformation som motsvarar någon av de primitiva typer som stöds i tabellen ovan.

Exempel:

Följande OData-exempelpost visar det JSON-format som skickas som en begäran om att infoga en entitet i Azure Table Storage (se Infoga entitet för information om infogningsåtgärden):

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

När en klient frågar en uppsättning entiteter i Azure Table Storage svarar tjänsten med en JSON-nyttolast (mer information om frågeåtgärden finns i Fråga entiteter ). Feeden kan innehålla en av de tre informationsnivåerna: inga metadata, minimala metadata eller fullständiga metadata. I följande exempel visas varje typ:

Inga metadata:

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

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

Fullständiga 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",  
    }  
}

Mer information om OData JSON-format finns i OData JSON Format Version 4.0-specifikationen tillsammans med dokumentet [MS-ODATAJSON]: OData Protocol JSON Format Standards Support Document.

Atomformat (endast program/atom+xml) (versioner tidigare än 2015-12-11)

Atom är ett XML-baserat dokumentformat som beskriver samlingar med relaterad information som kallas feeds. Feeds består av ett antal objekt, så kallade poster. AtomPub definierar ytterligare formatkonstruktioner för poster och feeds så att de resurser de representerar enkelt kan kategoriseras, grupperas, redigeras och identifieras. Men eftersom Atom inte definierar hur strukturerade data kodas med feeds, definierar OData en uppsättning konventioner för att representera strukturerade data i ett Atom-flöde för att möjliggöra överföring av strukturerat innehåll av tjänster baserat på OData.

Följande OData-exempelpost visar till exempel atomformatet som skickas via en begäran om att infoga en entitet i Azure Table Storage med hjälp av REST-API:et (se Infoga entitet för mer information om infogningsåtgärden):

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

När en klient frågar en uppsättning entiteter i Table Storage svarar tjänsten med en Atom-feed, som är en samling Atom-poster (se Frågeentiteter för information om frågeåtgärden):

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

Egenskapstyper i en Atom-feed

Egenskapsdatatyper definieras av OData-protokollspecifikationen. Alla datatyper som definieras av specifikationen stöds inte av tabelltjänsten. Information om vilka datatyper som stöds och hur de mappas till CLR-typer (Common Language Runtime) finns i Förstå tabelltjänstens datamodell.

En egenskap kan anges med eller utan en explicit datatyp. Om typen utelämnas skapas egenskapen automatiskt som datatyp Edm.String.

Om en egenskap skapas med en explicit typ innehåller en fråga som returnerar entiteten den typen i Atom-feeden, så att du kan fastställa typen av en befintlig egenskap om det behövs. Det är viktigt att känna till en egenskaps typ när du skapar en fråga som filtrerar på den egenskapen. Mer information finns i Fråga tabeller och entiteter.

För Double egenskaper används värdena NaN, INFoch -INF i Atom för att indikera inte ett tal, positiv oändlighet respektive negativ oändlighet. Infinity Formulären och -Infinity accepteras också. Tabelltjänsten stöder inte en negativ version av NaN. I Atom-format skiljer det mellan positiv och negativ noll.

Se även

Ange versionshuvuden för OData-datatjänsten
Versionshantering för Azure Storage-tjänsterna
Tabelltjänst-koncept