Entitások lekérdezése

Cikk
02/03/2024

A Query Entities művelet lekérdezi egy tábla entitásait, és tartalmazza a és $select a $filter beállításokat.

Kérés

A lekérdezési lehetőséget használó kérésekhez a $select 2011-08-18-es vagy újabb verziót kell használnia. Emellett a és MaxDataServiceVersion a DataServiceVersion fejlécet értékre kell állítani.2.0

A leképezés használatához a kérést a 2013-08-15-es vagy újabb verzióval kell elvégeznie. A DataServiceVersion és MaxDataServiceVersion a fejlécet értékre 3.0kell állítani. További információ: Az OData-adatszolgáltatás verziófejléceinek beállítása.

A kérést az Query Entities alábbiak szerint hozhatja létre. A HTTPS használatát javasoljuk. Cserélje le a myaccount kifejezést a tárfiók nevére, a mytable helyére pedig a tábla nevét.

Metódus	Kérés URI-ja	HTTP-verzió
`GET`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='<partition-key>',RowKey='<row-key>')?$select=<comma-separated-property-names>` `https://myaccount.table.core.windows.net/mytable()?$filter=<query-expression>&$select=<comma-separated-property-names>`	HTTP/1.1

A lekérdezni kívánt entitás címe különböző űrlapokat ölthet a kérelem URI-ján. További információ: Táblák és entitások lekérdezése.

Emulált tárolási szolgáltatás URI-ja

Amikor kérést küld az emulált tárolási szolgáltatásra, adja meg az emulátor gazdagépnevét és a table szolgáltatás portját a következőként: 127.0.0.1:10002. Kövesse ezeket az információkat az emulált tárfiók nevével.

Metódus	Kérés URI-ja	HTTP-verzió
`GET`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='<partition-key>',RowKey='<row-key>')?$select=<comma-separated-property-names>` `http://127.0.0.1:10002/devstoreaccount1/mytable()?$filter=<query-expression>?$select=<comma-separated-property-names>`	HTTP/1.1

A Storage Emulator Table szolgáltatása többféleképpen különbözik az Azure Table Storage-tól. További információ: A storage emulátor és az Azure Storage-szolgáltatások közötti különbségek.

URI-paraméterek

A Query Entities művelet támogatja az OData protokoll specifikációja által meghatározott lekérdezési beállításokat.

Kérésfejlécek

Az alábbi táblázat a szükséges és nem kötelező kérelemfejléceket ismerteti:

Kérelem fejléce	Leírás
`Authorization`	Kötelező. Megadja az engedélyezési sémát, a fióknevet és az aláírást. További információ: Kérelmek engedélyezése az Azure Storage-ba.
`Date` vagy `x-ms-date`	Kötelező. Megadja a kérés egyezményes világidő (UTC) formátumban kifejezett időpontját. További információ: Kérelmek engedélyezése az Azure Storage-ba.
`x-ms-version`	Választható. A kérelemhez használandó művelet verzióját adja meg. További információ: Az Azure Storage-szolgáltatások verziószámozása.
`Accept`	Választható. Megadja a válasz hasznos adatának elfogadott tartalomtípusát. Lehetséges értékek: - `application/atom+xml` (csak 2015-12-11 előtti verziók) - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` További információ: A Table Storage-műveletek hasznos adatformátuma.
`x-ms-client-request-id`	Választható. Ügyfél által generált, átlátszatlan értéket biztosít egy 1 kibibyte (KiB) karakterkorláttal, amelyet a naplózás konfigurálásakor rögzít a naplókban. Javasoljuk, hogy ezt a fejlécet használva korrelálja az ügyféloldali tevékenységeket a kiszolgáló által kapott kérésekkel.

A kérés törzse

Nincsenek.

Mintakérés

Request Syntax:  
GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince  HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-12-11  
x-ms-date: Mon, 27 Jun 2016 15:25:14 GMT  
Authorization: SharedKeyLite myaccount:<some key>  
Accept: application/json;odata=nometadata  
Accept-Charset: UTF-8  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx

Reagálás

A válasz tartalmaz egy HTTP-állapotkódot, egy válaszfejléceket és egy választörzset.

Állapotkód

A sikeres művelet a 200 -os állapotkódot adja vissza (OK).

Az állapotkódokkal kapcsolatos információkért lásd: Állapot- és hibakódok és Table Storage-hibakódok.

Válaszfejlécek

A műveletre adott válasz a következő fejléceket tartalmazza. A válasz további szabványos HTTP-fejléceket is tartalmazhat. Minden szabványos fejléc megfelel a HTTP/1.1 protokoll specifikációjának.

Válaszfejléc	Description
`x-ms-continuation-NextPartitionKey` `x-ms-continuation-NextRowKey`	Azt jelzi, hogy: – A visszaadandó entitások száma meghaladja az 1000-et. – Túllépte a kiszolgáló időtúllépési időközét. – A rendszer eléri a kiszolgálóhatárt, ha a lekérdezés olyan adatokat ad vissza, amelyek több kiszolgáló között oszlanak meg. További információ a folytatási jogkivonatok használatáról: Lekérdezési időtúllépés és lapozás.
`x-ms-request-id`	Egyedileg azonosítja a végrehajtott kérést. Segítségével elháríthatja a kérést. További információ: API-műveletek hibaelhárítása.
`x-ms-version`	A Table Storage azon verzióját jelzi, amelyet a kérés végrehajtásához használtak. Ez a fejléc lesz visszaadva a 2009-09-19-es és újabb verzióval kapcsolatos kérésekhez.
`Date`	UTC dátum/idő érték, amely azt az időpontot jelzi, amikor a szolgáltatás elküldte a választ.
`Content-Type`	A hasznos adat tartalomtípusát jelzi. A fejléc értéke a kérelemfejléc értékétől `Accept` függ. Lehetséges értékek: - `application/atom+xml` (csak 2015-12-11 előtti verziók) - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` Az érvényes tartalomtípusokról további információt a Table Storage-műveletek hasznos adatformátuma című témakörben talál.
`x-ms-client-request-id`	A kérések és a megfelelő válaszok hibaelhárítására használható. A fejléc értéke megegyezik a `x-ms-client-request-id` fejléc értékével, ha az szerepel a kérelemben, és az érték legfeljebb 1024 látható ASCII-karakterből áll. Ha a `x-ms-client-request-id` fejléc nincs jelen a kérelemben, ez a fejléc nem lesz jelen a válaszban.

Mintaválasz

Response Status:  
HTTP/1.1 200 OK  
  
Response Headers:  
Content-Type: application/json  
x-ms-request-id: 87f178c0-44fe-4123-a4c1-96c8fa6d9654  
Date: Mon, 27 Jun 2016 15:25:14 GMT  
x-ms-version: 2015-12-11  
Connection: close

Választörzs

A Query Entities művelet egy táblában lévő entitások listáját adja vissza OData-entitáskészletként. Az entitások listája A kérelem fejlécétől függően Accept JSON-formátumban vagy Atom-hírcsatornában található.

Megjegyzés

Hasznos adatformátumként a JSON-t javasoljuk. Ez az egyetlen támogatott formátum a 2015-12-11-es és újabb verziókhoz.

JSON (2013-08-15-es és újabb verziók)

Íme egy mintakérés URI-ja egy Query Entities művelethez egy ügyféltáblán:

GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince

A válasz hasznos adatai a JSON-ban metaadatok nélkül:

{  
   "value":[  
      {  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

A válasz hasznos adatai a JSON-ban, minimális metaadatokkal:

{  
   "odata.metadata":"https://myaccount.table.core.windows.net/$metadata#Customers",  
   "value":[  
      {  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince@odata.type":"Edm.DateTime",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

A válasz hasznos adatai a JSON-ban a teljes metaadatokkal:

{  
   "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=Customer',RowKey='Name')",  
         "odata.etag":"W/\"0x5B168C7B6E589D2\"",  
         "odata.editLink":"Customers(PartitionKey=Customer',RowKey='Name')",  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp@odata.type":"Edm.DateTime",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince@odata.type":"Edm.DateTime",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

Atom-hírcsatorna (2015-12-11 előtti verziók)

Íme egy mintakérés URI-ja egy Query Entities művelethez egy ügyféltáblán:

GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince

Íme egy Atom-mintaválasz a Query Entities művelethez:

<?xml version="1.0" encoding="UTF-8"?>  
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xml:base="https://myaccount.table.core.windows.net">  
   <id>https://myaccount.table.core.windows.net/Customers</id>  
   <title type="text">Customers</title>  
   <updated>2013-08-22T00:50:32Z</updated>  
   <link rel="self" title="Customers" href="Customers" />  
   <entry m:etag="W/"0x5B168C7B6E589D2"">  
      <id>https://myaccount.table.core.windows.net/Customers(PartitionKey='Customer',RowKey='Name')</id>  
      <category term="myaccount.Customers" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />  
      <link rel="edit" title="Customers" href="Customers(PartitionKey='Customer',RowKey='Name')" />  
      <title />  
      <updated>2013-08-22T00:50:32Z</updated>  
      <author>  
         <name />  
      </author>  
      <content type="application/xml">  
         <m:properties>  
            <d:PartitionKey>Customer</d:PartitionKey>  
            <d:RowKey>Name</d:RowKey>  
            <d:Timestamp m:type="Edm.DateTime">2013-08-22T00:20:16.3134645Z</d:Timestamp>  
            <d:CustomerSince m:type="Edm.DateTime">2008-10-01T15:25:05.2852025Z</d:CustomerSince>  
         </m:properties>  
      </content>  
   </entry>  
</feed>

Engedélyezés

Ezt a műveletet a fióktulajdonos és bárki végrehajthatja, aki rendelkezik a művelet végrehajtásához engedéllyel rendelkező közös hozzáférésű jogosultságkóddal.

Megjegyzések

A Table Storage-lekérdezések egyszerre legfeljebb 1000 entitást adhatnak vissza, és legfeljebb öt másodpercig futtathatók. A válasz olyan egyéni fejléceket tartalmaz, amelyek folytatási jogkivonatokat tartalmaznak az alábbi esetekben:

Az eredményhalmaz több mint 1000 entitást tartalmaz.
A lekérdezés nem fejeződött be öt másodpercen belül.
A lekérdezés átlépi a partíció határát.

A folytatási jogkivonatokkal további kéréseket hozhat létre a következő adatoldalhoz. További információ a folytatási jogkivonatokról: Lekérdezés időtúllépése és tördelése.

Megjegyzés

Ha folytatási jogkivonatokat tartalmazó további kéréseket küld, mindenképpen adja át az eredeti URI-t a kérésen. Ha például egy , $selectvagy $top lekérdezési lehetőséget adott meg $filteraz eredeti kérés részeként, adja meg ezt a beállítást a későbbi kérésekhez. Ellenkező esetben előfordulhat, hogy a későbbi kérések váratlan eredményeket adnak vissza.

Ebben $top az esetben a lekérdezési beállítás határozza meg az oldalankénti eredmények maximális számát. Nem adja meg az eredmények maximális számát a teljes válaszkészletben.

További információ: Táblák és entitások lekérdezése.

A lekérdezési lehetőséget használó $select leképezési kérelmeknél a verziónak 2011-08-18-18-nak vagy újabbnak kell lennie. A visszaadott tulajdonságok maximális száma 255. A válasz törzse tartalmazza az összes előre jelzett tulajdonságot, még akkor is, ha a tulajdonságok nem részei a visszaadott entitásnak.

Ha például a kérelem olyan tulajdonságot tartalmaz, amelyet a kivetített entitás nem tartalmaz, a hiányzó tulajdonság null attribútummal lesz megjelölve. Az előző mintaválasz törzse tartalmazza a Address tulajdonságot, amely nem része a kivetített entitásnak. A tulajdonság értéke tehát null: <d:Address m:null="true" />.

A lekérdezés ütemezésére és feldolgozására vonatkozó kérelem teljes időtartama 30 másodperc. Ez az összeg tartalmazza a lekérdezés végrehajtásához szükséges öt másodpercet.

Vegye figyelembe, hogy a lekérdezési kifejezés jobb oldalán konstansnak kell lennie. A kifejezés jobb oldalán lévő tulajdonságra nem hivatkozhat. A lekérdezési kifejezések felépítésével kapcsolatos részletekért lásd: Lekérdezési táblák és entitások.

A lekérdezési kifejezések nem tartalmazhatnak null értékeket. A következő karaktereket kell kódolni, ha lekérdezési sztringben használja őket:

Perjel (/)
Kérdőjel (?)
Kettőspont (:)
At sign (@)
Ampersand (&)
Egyenlőségjel (=)
Pluszjel (+)
Vessző (,)
Dollárjel ($)

A HTTP-kérések GET engedélyezésére és küldésére jogosult bármely alkalmazás lekérdezheti egy tábla entitásait.

A Table Storage LINQ-n keresztüli támogatott lekérdezési műveleteiről további információt a Table Storage-hoz támogatott lekérdezési operátorok és a LINQ-lekérdezések a Table Storage-on történő írása című témakörben talál.

Lásd még

Table Storage-hibakódok
Kérések engedélyezése az Azure Storage-nak
Állapot- és hibakódok
Table Storage-erőforrások kezelése
Táblák és entitások lekérdezése
Az OData-adatszolgáltatás verziófejléceinek beállítása
Entitás beszúrása
Entitás frissítése
Entitás törlése