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ébenAccept
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.type
egyéni tulajdonságok esetén: A megcélzott tulajdonság típusneve.PropertyName@odata.type
rendszertulajdonságok (azaz aPrimaryKey
,RowKey
ésTimestamp
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ékreodata=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 ,
RowKey
a ésTimestamp
aPartitionKey
tulajdonsá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őreodata=fullmetadata
van á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 NaN
Infinity
a JSON-ban kell ábrázolni a típus String
használatával, és egy odata.type jegyzetre van szükség. A Table szolgáltatás nem támogatja a NaN
negatí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.String
jö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 NaN
az 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 NaN
negatí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