Hasznos adatformátum táblaszolgáltatás-műveletekhez

A Table service REST API OData hasznos adatformátumként támogatja az ATOM és a JSON formátumot. Bár az ATOM protokoll az Azure Storage-szolgáltatások minden verziójához támogatott, a JSON protokoll csak a 2013-08-15-ös és újabb verziók esetében támogatott.

  • A JSON az ajánlott hasznos adatformátum. A JSON-t a 2013-08-15-ös és újabb verziók támogatják. A JSON-t a 2015-12-11-es és újabb verzióval kell használnia.

  • Az ATOM a 2015-12-11-nél korábbi verziók esetében támogatott.

Megjegyzés

A következő REST API-műveletek nem OData API-k, és jelenleg nem támogatják a JSON-t: Table ACL lekérése, Tábla ACL beállítása, Táblaszolgáltatás tulajdonságainak lekérése és Táblaszolgáltatás tulajdonságainak beállítása.

A JSON- vagy ATOM-formátum megadásához adja meg a és Accept a fejlécek Content-Type megfelelő értékeit (alább). Vegye figyelembe a következő korlátozásokat:

  • Az Content-Type OData hasznos adatokat tartalmazó összes kérelem fejlécére szükség van.

  • Ha a Accept fejléc nincs megadva, akkor a válasz tartalomtípusa alapértelmezés szerint a következő lesz: application/atom+xml.

  • $format Az URI paraméter megadása felülbírálja a kérelem fejlécében Accept megadott értéket, ha az OData adatszolgáltatás verziója 3.0-ra van állítva. Az OData-szolgáltatás verziójával kapcsolatos részletekért lásd : Az OData-adatszolgáltatás verziófejléceinek beállítása .

A hasznos adatformátum megadásához állítsa be a és Accept a Content-Type kérelem fejlécét az alábbi táblázat szerint:

Hasznos adatformátum Tartalomtípus fejléce Fejléc elfogadása Data Service-verzió (REST API-verzió) Támogatott API-k
Atom application/atom+xml application/atom+xml 1.0 (Bármely verzió)

2.0 (2011-08-18 vagy újabb)

3.0 (2013-08-15 vagy újabb)
Lekérdezéstáblák

CreateTable

Tábla törlése

Lekérdezési entitások

Entitások beszúrása

Entitás beszúrása vagy egyesítése

Entitás beszúrása vagy cseréje

Entitás frissítése

Entitás egyesítése

Entitás törlése
JSON application/json application/json;odata=nometadata

application/json;odata=minimalmetadata

application/json;odata=fullmetadata

Részletekért lásd az alábbi JSON-formátum szakaszt.
3.0 (2013-08-15 vagy újabb) Lekérdezéstáblák

CreateTable

Tábla törlése

Lekérdezési entitások

Entitások beszúrása

Entitás beszúrása vagy egyesítése

Entitás beszúrása vagy cseréje

Entitás frissítése

Entitás egyesítése

Entitás törlése
XML application/xml application/xml N/A Tábla ACL-ének lekérése

Tábla ACL-ének beállítása

Táblaszolgáltatás tulajdonságainak lekérése

Táblaszolgáltatás tulajdonságainak beállítása

JSON formátum (alkalmazás/json) (2013-08-15-ös és újabb verziók)

Az OData kibővíti a JSON formátumot, és általános konvenciókat határoz meg ezekhez a név-érték párokhoz, a fent leírt ATOM formátumhoz hasonlóan. Az OData a vezérlőinformációkhoz ( például azonosítókhoz, típusokhoz és hivatkozásokhoz) használható, canonical annotations halmazt definiál. A JSON formátummal kapcsolatos részletekért lásd: A JSON bemutatása.

Az OData JSON-formátumának fő előnye, hogy a hasznos adat kiszámítható részei elhagyhatók a hasznos adat méretének csökkentése érdekében. Ha ezeket az adatokat a fogadó végponton szeretné újrakonfigurálni, a kifejezések a hiányzó hivatkozások kiszámítására, az adatok beírására és az adatok vezérlésére szolgálnak. A hasznos adatból kihagyott adatok szabályozásához három szint adható meg a Accept fejléc részeként:

  • application/json;odata=nometadata

  • application/json;odata=minimalmetadata

  • application/json;odata=fullmetadata

Az Azure Table szolgáltatás a következő ODATA-megjegyzéseket támogatja:

  • odata.metadata: Gyűjtemény, entitás, primitív érték vagy szolgáltatásdokumentum metaadat-URL-címe.

  • odata.id: Az entitás azonosítója, amely általában az erőforrás URL-címe.

  • odata.editlink: A bejegyzés szerkesztéséhez/frissítéséhez használt hivatkozás, ha az entitás frissíthető, és a odata.id nem jelöl olyan URL-címet, amely az entitás szerkesztéséhez használható.

  • odata.type: A tartalmazó objektum típusneve.

  • odata.etag: Az entitás ETagje.

  • PropertyName@odata.typeegyéni tulajdonságok esetén: A megcélzott tulajdonság típusneve.

  • PropertyName@odata.typerendszertulajdonságok (azaz a PrimaryKey, RowKeyés Timestamp tulajdonságok) esetében: A megcélzott tulajdonság típusneve.

Az egyes szintekben szereplő információk összegzése a következő táblázatban történik:

Annotations odata=fullmetadata odata=minimalmetadata odata=nometadata
odata.metadata Igen Igen Nem
odata.id Igen Nem Nem
odata.editlink Igen Nem Nem
odata.type Igen Nem Nem
odata.etag Igen Nem Nem
PropertyName@odata.type egyéni tulajdonságokhoz Igen Igen Nem
PropertyName@odata.type rendszertulajdonságok esetén Igen Nem Nem

Tulajdonságtípusok egy JSON-hírcsatornában

A odata.type széljegyzet OData JSON formátumban van használva a megnyitott tulajdonság típusának meghatározásához. Ez a megjegyzés akkor jelenik meg, ha az alábbi feltételek teljesülnek:

  • A JSON-vezérlő szintje vagy odata=fullmetadataértékre odata=minimalmetadata van állítva a JSON Formátum szakaszban leírtak szerint.

  • A tulajdonság egy egyéni tulajdonság. Vegye figyelembe, hogy az Azure-táblák esetében csak a , RowKeya és Timestamp a PartitionKeytulajdonságok rendszertulajdonságok, és típusadataik deklarálva vannak a rendszerben$metadata. Ezeknek a tulajdonságoknak a típusjegyzete csak akkor jelenik meg, ha a vezérlő szintje a következőre odata=fullmetadatavan állítva: . További információ: A table service adatmodell ismertetése.

  • A tulajdonság típusa nem határozható meg az alábbi táblázatban összefoglalt típusészlelési heurisztika alapján.

Edm típusa odata.type annotation required JSON-típus
Edm.Binary Igen Sztring
Edm.Boolean No Literálok
Edm.DateTime Igen Sztring
Edm.Double No Numerikus (tizedesvesszőt tartalmaz)
Edm.Guid Igen Sztring
Edm.Int32 No Numerikus (nem tartalmaz tizedesvesszőt)
Edm.Int64 Igen Sztring
Edm.String Nem Sztring
n.a. No Null

A Table szolgáltatás nem őriz meg null értékeket a tulajdonságokhoz. Entitás írásakor megadhat egy null értéket odata.type típusú széljegyzettel vagy anélkül, és az értékekkel rendelkező null összes tulajdonságot úgy kezeli a rendszer, mintha a kérelem nem tartalmazta volna ezt a tulajdonságot. Null az entitások lekérdezése során a rendszer soha nem ad vissza tulajdonságértékeket.

Az Edm.Double esetében a és -Infinity az értékeket NaNInfinity a JSON-ban kell ábrázolni a típus Stringhasználatával, és egy odata.type jegyzetre van szükség. A Table szolgáltatás nem támogatja a NaNnegatív verzióját, és JSON formátumban nem tesz különbséget a pozitív és a negatív nulla között (úgy kezeli -0.0 , mint 0.0).

A következő JSON-entitás a nyolc különböző tulajdonságtípusra mutat példát:

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

Mivel PartitionKey és RowKey rendszertulajdonságok, ami azt jelenti, hogy minden táblasornak definiálnia kell ezeket a tulajdonságokat, a típusjegyzetük nem jelenik meg az entitásban. Ezek a tulajdonságok előre definiálva vannak típusként Edm.String. A többi tulajdonság azonban egyéni tulajdonságok, ezért a fenti táblázat egyik támogatott primitív típusának megfelelő típusinformációkat tartalmaz.

Példák:

Az alábbi OData-mintabejegyzés bemutatja az entitás Azure Table Storage-ba való beszúrására irányuló kérésként küldött JSON-formátumot (a beszúrási művelet részleteiért lásd: Entitás beszúrása ):

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

Amikor egy ügyfél egy entitáskészletet kérdez le az Azure Table Storage-ban, a szolgáltatás JSON hasznos adattal válaszol (a lekérdezési művelet részleteiért lásd: Entitások lekérdezése ). A hírcsatorna a három információszint egyikét is tartalmazhatja: nincs metaadat, minimális metaadatok vagy teljes metaadatok. Az alábbi példák bemutatják az egyes típusokat:

Nincsenek metaadatok:

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

Minimális metaadatok:

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

Teljes metaadatok:

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

Az OData JSON formátumról további információt az OData JSON Formátum 4.0-s verziójának specifikációjában talál az [MS-ODATAJSON]: OData Protocol JSON formátumszabványok támogatási dokumentumával együtt.

Atom formátum (alkalmazás/atom+xml) (csak a 2015-12-11-nél korábbi verziók)

Az Atom egy XML-alapú dokumentumformátum, amely a kapcsolódó információk gyűjteményeit írja le, más néven hírcsatornákat. A hírcsatornák számos elemből, más néven bejegyzésekből állnak. Az AtomPub további formátumszerkezeteket határoz meg a bejegyzésekhez és a hírcsatornákhoz, hogy az általuk képviselt erőforrások könnyen kategorizálhatók, csoportosíthatók, szerkeszthetők és felderíthetők legyenek. Mivel azonban az Atom nem határozza meg, hogy a strukturált adatok hogyan legyenek kódolva a hírcsatornákkal, az OData konvenciók készletét határozza meg a strukturált adatok Atom-hírcsatornákban való ábrázolására, hogy lehetővé tegye a strukturált tartalom átvitelét az OData-alapú szolgáltatások számára.

Az alábbi OData-mintabejegyzés például egy entitás REST API-val történő Azure Table Storage-ba való beszúrására irányuló kérésen keresztül küldött Atom formátumot mutatja be (a beszúrási művelet részleteiért lásd: Entitás beszúrása ):

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

Amikor egy ügyfél lekérdez egy entitáskészletet a Table Storage-ban, a szolgáltatás atomcsatornával válaszol, amely atombejegyzések gyűjteménye (a lekérdezési művelet részleteiért lásd: Lekérdezési entitások ):

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

Tulajdonságtípusok Atom-hírcsatornában

A tulajdonság adattípusát az OData protokoll specifikációja határozza meg. A Table szolgáltatás nem támogatja a specifikáció által meghatározott összes adattípust. A támogatott adattípusokkal és a közös nyelvi futtatókörnyezeti (CLR) típusokra való leképezésük módjával kapcsolatos információkért lásd : A Table Service-adatmodell ismertetése.

Egy tulajdonság explicit adattípussal vagy anélkül is megadható. Ha a típus nincs megadva, a tulajdonság automatikusan adattípusként Edm.Stringjön létre.

Ha egy tulajdonság explicit típussal jön létre, az entitást visszaküldött lekérdezés tartalmazza ezt a típust az Atom-hírcsatornán belül, így szükség esetén meghatározhatja egy meglévő tulajdonság típusát. A tulajdonság típusának ismerete fontos egy olyan lekérdezés létrehozásakor, amely az adott tulajdonságra szűr. További információ: Táblák és entitások lekérdezése.

A tulajdonságok esetében Double a , INFés -INF értékeket NaNaz Atomban arra használjuk, hogy ne jelezze a számot, a pozitív végtelent és a negatív végtelent. Az űrlapok Infinity és -Infinity a is elfogadott. A Table szolgáltatás nem támogatja a NaNnegatív verzióját. Atom formátumban megkülönbözteti a pozitív és a negatív nullát.

Lásd még:

Az OData Data Service verziófejléceinek beállítása
Az Azure Storage-szolgáltatások verziókezelése
A Table Service szolgáltatással kapcsolatos fogalmak