Azure Cosmos DB-erőforrások lekérdezése a REST API használatával

Az Azure Cosmos DB egy globálisan elosztott, többmodelles adatbázis, amely számos API-t támogat. Ez a cikk azt ismerteti, hogyan kérdezhet le erőforrásokat a REST használatával az SQL API használatával.

Hogyan lekérdezni egy erőforrást a REST használatával?

Ha SQL-lekérdezést szeretne végrehajtani egy erőforráson, tegye a következőket:

Hajtson végre egy metódust POST egy erőforrás-útvonalon a JSON használatával, amelynek query tulajdonsága az SQL-lekérdezési sztringre van állítva, a "parameters" tulajdonság pedig a választható paraméterértékek tömbjére van állítva.
Állítsa a x-ms-documentdb-isquery fejlécet a következőre: True.
Állítsa a Content-Type fejlécet a következőre: application/query+json.

Ha egy SQL-lekérdezést a .NET használatával szeretne végrehajtani egy erőforráson, tekintse meg a REST from .NET Sample (REST a .NET-mintából) című témakört.

Példa

Az alábbiakban egy példa REST-lekérdezési műveletet mutatunk be a dokumentumerőforrásokon. Ebben a példában az összes olyan dokumentumot szeretnénk megtalálni, amelyben "Don" van szerzőként.

POST https://contosomarketing.documents.azure.com/dbs/XP0mAA==/colls/XP0mAJ3H-AA=/docs HTTP/1.1  
x-ms-documentdb-isquery: True  
x-ms-date: Mon, 18 Apr 2015 13:05:49 GMT  
authorization: type%3dmaster%26ver%3d1.0%26sig%3dkOU%2bBn2vkvIlHypfE8AA5fulpn8zKjLwdrxBqyg0YGQ%3d  
x-ms-version: 2015-12-16  
x-ms-query-enable-crosspartition: True  
Accept: application/json  
Content-Type: application/query+json  
Host: contosomarketing.documents.azure.com  
Content-Length: 50  

{  
    "query": "SELECT * FROM root WHERE (root.Author.id = 'Don')",  
    "parameters": []  
}

Lekérdezés részletei

Metódus	Kérés URI-ja
POST	Kötelező. A hitelesítési típus és az aláírási jogkivonat. Ehhez a művelethez csak a főkulcs-jogkivonat engedélyezett. További információ: Access Control a Cosmos DB-erőforrásokról.

Kérelemfejlécek

Az alábbi táblázat a lekérdezési műveletek végrehajtásához használt gyakori fejléceket tartalmazza.

Normál fejléc	Leírás
Engedélyezés	Kötelező. A hitelesítési típus és az aláírási jogkivonat. Ehhez a művelethez csak a főkulcs-jogkivonat engedélyezett. További információ: Access Control a Cosmos DB-erőforrásokról.
Tartalomtípus	Kötelező. Az alkalmazás/lekérdezés+json értékre kell állítani.
Elfogadás	Nem kötelező. Jelenleg a Cosmos DB mindig szabványos JSON formátumban adja vissza a válasz hasznos adatait. Az ügyfélnek el kell tudnia fogadni a válasz törzsét szabványos JSON formátumban.
User-Agent	Nem kötelező. A kérést végrehajtó felhasználói ügynök. Az ajánlott formátum a következő: {user agent name}/{version}. Az SQL API .NET SDK például a User-Agent sztringet Microsoft.Document.Client/1.0.0.0.0 értékre állítja.

Egyéni fejléc	Leírás
x-ms-date	Kötelező. A kérelem dátuma az RFC 1123-ban megadott módon. A dátumformátumot például az egyezményes világidő (UTC) fejezi ki. 2015. ápr. 08. péntek, 03:52:31 GMT.
x-ms-documentdb-isquery	Kötelező. Ezt a tulajdonságot igaz értékre kell állítani.
x-ms-max-item-count	Nem kötelező. Ha egy eredménykészleten keresztül szeretne lapozást elvégezni, állítsa ezt a fejlécet a visszaadandó elemek maximális számára egyetlen oldalon.
x-ms-folytatás	Nem kötelező. Az elemek következő lapjára való navigáláshoz állítsa be ezt a fejlécet a következő lap folytatási jogkivonatára.
x-ms-version	Nem kötelező. A Cosmos DB REST szolgáltatás verziója. A legújabb verziót akkor használja a rendszer, ha a fejléc nincs megadva. További információ: Azure Cosmos DB REST API-referencia.
x-ms-documentdb-query-enable-scan	Nem kötelező. Indexvizsgálattal feldolgozhatja a lekérdezést, ha a megfelelő típusú indexútvonal nem érhető el.
x-ms-session-token	Nem kötelező. A kérés munkamenet-jogkivonata. Munkamenet-konzisztencia esetén használatos.
x-ms-partition-key	Nem kötelező. Ha meg van adva, a lekérdezés csak olyan dokumentumokon lesz végrehajtva, amelyek megfelelnek a fejléc partíciókulcs-értékének.
x-ms-documentdb-query-enablecrosspartition	Nem kötelező. Igaz értékre kell állítani azokat a lekérdezéseket, amelyek nem szűrnek egyetlen partíciókulcsra. Az egyetlen partíciókulcs-értékre szűrő lekérdezések csak egyetlen partíción lesznek végrehajtva, még akkor is, ha ez igaz értékre van állítva.
x-ms-documentdb-populatequerymetrics	Nem kötelező. A lekérdezési metrikák visszaadásához be kell állítani a értéket `True` .

Kérelem törzse

A kérelem törzsének érvényes JSON-dokumentumnak kell lennie, amely tartalmazza az SQL-lekérdezést és a paramétereket. Ha a bemenet helytelen vagy érvénytelen SQL-szintaxissal rendelkezik, a művelet 400 hibás kérelem hibával meghiúsul.

400 hibás kérést is kap, ha az átjáró nem tudja kiszolgálni a lekérdezést.

Tulajdonság	Leírás
query	Kötelező. A lekérdezés SQL-lekérdezési sztringje. További információ: Azure Cosmos DB SQL-szintaxis referenciája.
parameters	Kötelező. Névértékpárként megadott paraméterek JSON-tömbje. A paramétertömb nullától sok paraméterig tartalmazhat. Minden paraméternek a következő értékekkel kell rendelkeznie: név: a paraméter neve. A paraméterneveknek érvényes sztringkonstansoknak kell lenniük, és "@" betűvel kell kezdődniük. érték: a paraméter értéke. Bármilyen érvényes JSON-érték lehet (sztring, szám, objektum, tömb, logikai vagy null).

Tulajdonság

Leírás

query

Kötelező. A lekérdezés SQL-lekérdezési sztringje. További információ: Azure Cosmos DB SQL-szintaxis referenciája.

parameters

Kötelező. Névértékpárként megadott paraméterek JSON-tömbje. A paramétertömb nullától sok paraméterig tartalmazhat. Minden paraméternek a következő értékekkel kell rendelkeznie: név: a paraméter neve. A paraméterneveknek érvényes sztringkonstansoknak kell lenniük, és "@" betűvel kell kezdődniük. érték: a paraméter értéke. Bármilyen érvényes JSON-érték lehet (sztring, szám, objektum, tömb, logikai vagy null).

Példa kérésre

Az alábbi példa egy paraméteres SQL-kérést készít, amelynek sztringparamétere a következő: @author.

POST https://contosomarketing.documents.azure.com/dbs/XP0mAA==/colls/XP0mAJ3H-AA=/docs HTTP/1.1  
x-ms-documentdb-isquery: True  
x-ms-date: Mon, 18 Apr 2015 13:05:49 GMT  
authorization: type%3dmaster%26ver%3d1.0%26sig%3dkOU%2bBn2vkvIlHypfE8AA5fulpn8zKjLwdrxBqyg0YGQ%3d  
x-ms-version: 2015-04-08  
Accept: application/json  
Content-Type: application/query+json  
Host: contosomarketing.documents.azure.com  
Content-Length: 50  
  
{  
    "query": "SELECT * FROM root WHERE (root.Author.id = @author)",  
    "parameters":   
    [  
        { "name": "@author", "value": "Leo Tolstoy"}  
    ]  
}

Az SQL-lekérdezésekkel kapcsolatos további információkért lásd: SQL-lekérdezések az Azure Cosmos DB-hez.

Válasz részletei

A művelet által visszaadott gyakori állapotkódok a következők. A hibaállapot-kódokkal kapcsolatos információkért lásd: HTTP-állapotkódok az Azure Cosmos DB-hez.

Kód	Leírás
200 OK	A művelet sikeres.
400 Hibás kérés	Az SQL-utasítás szintaxisa helytelen.
401 Nem engedélyezett	Nincs beállítva az Engedélyezés vagy az x-ms-date fejléc. A 401-et akkor is visszaadja a rendszer, ha az Engedélyezési fejléc érvénytelen engedélyezési jogkivonatra van beállítva.
403 – Tiltott	Az engedélyezési jogkivonat lejárt.
404 Nem található	A gyűjtemény már nem erőforrás. Előfordulhat például, hogy az erőforrás törölve lett.

Válaszfejlécek

Ez a művelet a következő gyakori fejléceket adja vissza. Előfordulhat, hogy további standard és gyakori fejléceket ad vissza.

Normál fejléc	Leírás
Tartalomtípus	A Content-Type az application/json. A Cosmos DB mindig standard JSON formátumban adja vissza a válasz törzsét.
Date	A válaszművelet dátum-ideje. Ez a dátum-idő formátum megfelel az [RFC1123] dátum időformátumának UTC-ben kifejezve.

Egyéni fejléc	Leírás
x-ms-item-count	A művelet által visszaadott elem száma.
x-ms-continuation	Ez egy átlátszatlan sztring, amelyet akkor ad vissza, ha a lekérdezésben több elem is lekérhető. Az x-ms-continuation a lekérdezés végrehajtásának folytatásához kérelemfejlécként szerepelhet a későbbi kérésekben.
x-ms-request-charge	Ez a művelet által felhasznált kérelemegységek (RU) száma. További információ a kérelemegységekről: Kérelemegységek az Azure Cosmos DB-ben.
x-ms-activity-id	Ez a művelet egyedi azonosítója. A Cosmos DB-kérések végrehajtásának nyomon követésére használható.
x-ms-session-token	A későbbi kérésekhez használandó munkamenet-jogkivonat. Munkamenet-konzisztenciához használatos.

Válasz törzse

A lekérdezési művelet választörzse a lekérdezett erőforrás szülőerőforrásának _rid, valamint a leképezés és a kijelölés erőforrás-tulajdonságait tartalmazó erőforrástömb. A példának megfelelően, ha lekérdezést hajtottak végre a gyűjtemény docs elérési útján xp0mAJ3H-AA=_rid, a válasz a következő lesz:

{"_rid":" XP0mAJ3H-AA=","Documents":   [  ….  ….   ],"_count":10}

Tulajdonság	Leírás
_Megszabadulni	A lekérdezésben használt gyűjtemény erőforrás-azonosítója.
_Számít	A visszaadott elemek száma.
Erőforrástömb	A lekérdezési eredményeket tartalmazó tömb.

A lekérdezési kérelem törzsének létrehozása

A lekérdezési kérelemnek érvényes JSON-dokumentumnak kell lennie, amely tartalmaz egy érvényes SQL-lekérdezési sztringet tartalmazó lekérdezési tulajdonságot, valamint egy paramétertulajdonságot , amely opcionális paraméterek tömbjéből áll. Minden paraméternek rendelkeznie kell a lekérdezésben megadott paraméterek név - és értéktulajdonságával . A paraméterneveknek a "@" karakterrel kell kezdődniük. Az értékek bármilyen érvényes JSON-érték lehetnek – sztringek, egész számok, logikai értékek és nullok.

A lekérdezés szövegében megadott paramétereknek csak egy részhalmazát lehet megadni. Azok a kifejezések, amelyek ezekre a nem meghatározott paraméterekre hivatkoznak, meghatározatlannak lesznek értékelve. A lekérdezés szövegében nem használt további paraméterek megadása is érvényes.

Az alábbiakban néhány példát láthat az érvényes lekérdezési kérelmekre. A következő lekérdezés például egyetlen paraméterrel @idrendelkezik.

{  
    "query": "select * from docs d where d.id = @id",   
    "parameters": [   
        {"@id": "newdoc"}   
     ]  
}

Az alábbi példában két paraméter található, az egyik sztringértékkel, a másik pedig egész számmal.

{  
    "query": "select * from docs d where d.id = @id and d.prop = @prop",   
    "parameters": [   
        {"@id": "newdoc"},  
        {"@prop": 5}   
     ]  
}

Az alábbi példa a SELECT záradékban található paramétereket, valamint egy, a paraméternéven keresztül paraméterként elért tulajdonságot használ.

{  
    "query": "select @id, d[@propName] from docs d",   
    "parameters": [   
        {"@id": "newdoc"},  
        {"@propName": "prop"}  
     ]  
}

Az átjáró által nem kiszolgálható lekérdezések

Az átjáró nem tudja kiszolgálni azokat a lekérdezéseket, amelyek folytatások közötti állapotot igényelnek. Ide tartoznak az alábbiak:

TOP
ORDER BY
OFFSET LIMIT
Összesítések
DISTINCT
GROUP BY

Az átjáró által kiszolgálható lekérdezések a következők:

Egyszerű leképezések
Szűrők

Ha olyan lekérdezésre ad vissza választ, amelyet az átjáró nem tud kiszolgálni, az a 400-ás állapotkódot (BadRequest) és a következő üzenetet fogja tartalmazni:

{"code":"BadRequest","message":"The provided cross partition query can not be directly served by the gateway. 
This is a first chance (internal) exception that all newer clients will know how to handle gracefully. 
This exception is traced, but unless you see it bubble up as an exception (which only happens on older SDK clients), 
then you can safely ignore this message.\r\nActivityId: db660ee4-350a-40e9-bc2c-99f92f2b445d, Microsoft.Azure.Documents.Common/2.2.0.0",
"additionalErrorInfo":"{\"partitionedQueryExecutionInfoVersion\":2,\"queryInfo\":{\"distinctType\":\"None\",\"top\":null,\"offset\":null,\"limit\":null,
\"orderBy\":[\"Ascending\"],\"orderByExpressions\":[\"c._ts\"],\"aggregates\":[],
\"rewrittenQuery\":\"SELECT c._rid, [{\\\"item\\\": c._ts}] AS orderByItems, 
c AS payload\\nFROM c\\nWHERE ({documentdb-formattableorderbyquery-filter})\\nORDER BY c._ts\"},
\"queryRanges\":[{\"min\":\"\",\"max\":\"FF\",\"isMinInclusive\":true,\"isMaxInclusive\":false}]}"}

Lekérdezési eredmények tördelése

A lekérdezési kérelmek az x-ms-max-item-count és az x-ms-continuation kérelemfejléceken keresztül támogatják a tördelést. Az x-ms-max-item-count fejléc határozza meg a lekérdezés végrehajtásával visszaadható értékek maximális számát. Ez 1 és 1000 között lehet, és alapértelmezés szerint 100-zal van konfigurálva.

A lekérdezések nullától a végrehajtás eredményeitől számított maximális x-ms-max-item-count értékekig térnek vissza. A lekérdezés eredménye egy x-ms-item-count fejlécet tartalmaz, amely meghatározza a lekérdezés által visszaadott dokumentumok tényleges számát. Ha további eredmények is lekérhetők a lekérdezésből, akkor a válasz egy nem üres értéket tartalmaz az x-ms-continuation fejléchez.

Az ügyfelek az x-ms-continuation fejléc ismételt kérésként való ismételt megismétlésével lekérhetik az eredmények további lapjait. Az összes eredmény olvasásához az ügyfeleknek meg kell ismételnie ezt a folyamatot, amíg egy üres x-ms-folytatást nem ad vissza.

A Cosmos DB-lekérdezések végrehajtása állapot nélküli a kiszolgáló oldalán, és bármikor folytatható az x-ms-continuation fejléc használatával. Az x-ms-continuation érték a dokumentum utolsó feldolgozott erőforrás-azonosítóját (_rid) használja a végrehajtás előrehaladásának nyomon követéséhez. Ezért ha a dokumentumokat törlik és újra beszúrják a lapok beolvasása között, akkor a dokumentumok kizárhatók bármelyik lekérdezési kötegből. Az x-ms-continuation fejléc viselkedése és formátuma azonban megváltozhat egy jövőbeli szolgáltatásfrissítésben.

Lásd még:

Last updated on 2023-08-05

Megosztás a következőn keresztül: