Dotazování prostředků Azure Cosmos DB pomocí rozhraní REST API

Článek
08/05/2023

Azure Cosmos DB je globálně distribuovaná databáze pro více modelů s podporou několika rozhraní API. Tento článek popisuje, jak pomocí rozhraní REST dotazovat prostředky pomocí rozhraní SQL API.

Návody dotazovat prostředek pomocí rozhraní REST?

Pokud chcete provést dotaz SQL na prostředek, postupujte takto:

Spusťte metodu pro cestu k prostředku pomocí json s query vlastností nastavenou POST na řetězec dotazu SQL a vlastností parameters nastavenou na pole volitelných hodnot parametrů.
x-ms-documentdb-isquery Nastavte záhlaví na True.
Content-Type Nastavte záhlaví na application/query+json.

Ukázku, jak provést dotaz SQL na prostředek pomocí .NET, najdete v tématu REST z .NET Sample.

Příklad

Níže je příklad operace dotazu REST na prostředky dokumentů. V tomto příkladu bychom chtěli najít všechny dokumenty, které mají jako autora "Don".

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": []  
}

Podrobnosti o požadavcích

Metoda	Identifikátor URI žádosti
POST	Povinné. Typ ověřování a token podpisu. Pro tuto operaci je povolený pouze token hlavního klíče. Další informace najdete v tématu Access Control o prostředcích cosmos DB.

Hlavičky požadavku

Následující tabulka obsahuje běžné hlavičky používané k provádění operací dotazů.

Standardní hlavička	Popis
Autorizace	Povinné. Typ ověřování a token podpisu. Pro tuto operaci je povolený pouze token hlavního klíče. Další informace najdete v tématu Access Control o prostředcích cosmos DB.
Typ obsahu	Povinné. Musí být nastavená na application/query+json.
Přijetí	Volitelné. V tuto chvíli Cosmos DB vždy vrací datovou část odpovědi ve standardním formátu JSON. Klient musí být schopný přijmout text odpovědi ve standardním formátu JSON.
User-Agent	Volitelné. Uživatelský agent, který provádí požadavek. Doporučený formát je {user agent name}/{version}. Sada SQL API .NET SDK například nastaví řetězec User-Agent na Microsoft.Document.Client/1.0.0.0.

Vlastní hlavička	Popis
x-ms-date	Povinné. Datum žádosti uvedené v DOKUMENTU RFC 1123. Formát data je vyjádřen například v koordinovaném univerzálním čase (UTC). Fri, 08 Apr 2015 03:52:31 GMT.
x-ms-documentdb-isquery	Povinné. Tato vlastnost musí být nastavena na hodnotu true.
x-ms-max-item-count	Volitelné. Pokud chcete procházet sadu výsledků dotazu, nastavte toto záhlaví na maximální počet položek, které se mají vrátit zpět na jednu stránku.
x-ms-continuation	Volitelné. Pokud chcete přejít na další stránku položek, nastavte toto záhlaví na pokračovací token pro další stránku.
x-ms-version	Volitelné. Verze služby REST Cosmos DB. Nejnovější verze se použije, když hlavička není k dispozici. Další informace najdete v tématu Referenční informace k rozhraní REST API služby Azure Cosmos DB.
x-ms-documentdb-query-enable-scan	Volitelné. Pokud není k dispozici správná cesta k indexu typu, použijte prohledávání indexu ke zpracování dotazu.
x-ms-session-token	Volitelné. Token relace pro požadavek. Používá se pro konzistenci relací.
x-ms-partition-key	Volitelné. Pokud je zadaný, dotaz se spustí pouze u dokumentů, které odpovídají hodnotě klíče oddílu v hlavičce.
x-ms-documentdb-query-enablecrosspartition	Volitelné. Musí být nastavena na hodnotu true pro všechny dotazy, které nefiltrují klíč jednoho oddílu. Dotazy, které filtrují hodnotu jednoho klíče oddílu, se spustí pouze pro jeden oddíl, i když je nastavená hodnota true.
x-ms-documentdb-populatequerymetrics	Volitelné. Aby bylo možné vracet metriky dotazů, musí být nastavená na `True` hodnotu .

Text požadavku

Text požadavku by měl být platný dokument JSON obsahující dotaz a parametry SQL. Pokud je vstup poškozený nebo neplatná syntaxe SQL, operace s chybou 400 Chybný požadavek selže.

Pokud brána nemůže obsluhovat dotaz, zobrazí se také chybný požadavek 400.

Vlastnost	Popis
query	Povinné. Řetězec dotazu SQL pro dotaz. Další informace najdete v tématu Referenční informace k syntaxi SQL služby Azure Cosmos DB.
parameters	Povinné. Pole JSON s parametry zadanými jako páry hodnoty názvu Pole parametrů může obsahovat od nuly až po mnoho parametrů. Každý parametr musí mít následující hodnoty:name: název parametru. Názvy parametrů musí být platné řetězcové literály a začínat na @. value: hodnota parametru. Může to být libovolná platná hodnota JSON (řetězec, číslo, objekt, pole, logická hodnota nebo hodnota null).

Vlastnost

Popis

query

Povinné. Řetězec dotazu SQL pro dotaz. Další informace najdete v tématu Referenční informace k syntaxi SQL služby Azure Cosmos DB.

parameters

Povinné. Pole JSON s parametry zadanými jako páry hodnoty názvu Pole parametrů může obsahovat od nuly až po mnoho parametrů. Každý parametr musí mít následující hodnoty:name: název parametru. Názvy parametrů musí být platné řetězcové literály a začínat na @. value: hodnota parametru. Může to být libovolná platná hodnota JSON (řetězec, číslo, objekt, pole, logická hodnota nebo hodnota null).

Příklad požadavku

Následující příklad vytvoří parametrizovaný požadavek SQL s řetězcovým parametrem pro @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"}  
    ]  
}

Další informace o dotazech SQL najdete v tématu Dotazy SQL pro Službu Cosmos DB.

Podrobnosti odpovědi

Níže jsou uvedené běžné stavové kódy vrácené touto operací. Informace o stavových kódech chyb najdete v tématu Stavové kódy HTTP pro službu Azure Cosmos DB.

Kód	Popis
200 Ok	Operace je úspěšná.
400 – Chybný požadavek	Syntaxe příkazu SQL je nesprávná.
401 – Neautorizováno	Hlavička Authorization nebo x-ms-date není nastavená. 401 se také vrátí, pokud je hlavička Autorizace nastavena na neplatný autorizační token.
403 – Zakázáno	Platnost autorizačního tokenu vypršela.
404 – Nenalezeno	Kolekce už není prostředkem. Prostředek mohl být například odstraněn.

Hlavičky odpovědi

Tato operace vrátí následující běžné hlavičky. Můžou se vrátit další standardní a běžné hlavičky.

Standardní záhlaví	Popis
Typ obsahu	Typ obsahu je application/json. Cosmos DB vždy vrací text odpovědi ve standardním formátu JSON.
Date (Datum)	Datum a čas operace odpovědi. Tento formát data a času odpovídá formátu [RFC1123] data a času vyjádřenému v UTC.

Vlastní hlavička	Popis
x-ms-item-count	Počet položek vrácených operací.
x-ms-continuation	Jedná se o neprůsvný řetězec vrácený v případě, že dotaz obsahuje potenciálně více položek, které se mají načíst. Pokračování x-ms je možné zahrnout do následných požadavků jako hlavičku požadavku pro obnovení provádění dotazu.
x-ms-request-charge	Jedná se o počet jednotek žádostí (RU) spotřebovaných operací. Další informace o jednotkách žádostí najdete v tématu Jednotky žádostí ve službě Azure Cosmos DB.
x-ms-activity-id	Jedná se o jedinečný identifikátor operace. Dá se použít k trasování provádění požadavků Cosmos DB.
x-ms-session-token	Token relace, který se má použít pro následné požadavky. Používá se pro konzistenci relací.

Text odpovědi

Tělo odpovědi pro operaci dotazu se skládá z _rid nadřazeného prostředku dotazovaného prostředku a pole prostředků obsahující vlastnosti prostředku pro projekci a výběr. Pokud byl dotaz proveden v cestě docs kolekce s _rid XP0mAJ3H-AA=, odpověď by byla následující:

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

Vlastnost	Popis
_Zbavit	ID prostředku pro kolekci použitou v rámci dotazu
_Počet	Počet vrácených položek
Pole prostředků	Pole obsahující výsledky dotazu.

Sestavení textu požadavku dotazu

Požadavek dotazu musí být platný dokument JSON obsahující vlastnost dotazu , která obsahuje platný řetězec dotazu SQL a vlastnost parameters , která obsahuje pole volitelných parametrů. Každý parametr by měl mít vlastnost název a hodnotu parametrů, které jsou zadané v dotazu. Názvy parametrů musí začínat znakem @. Hodnoty můžou být libovolné platné hodnoty JSON – řetězce, celá čísla, logické hodnoty a hodnoty null.

Je platné zadat pouze podmnožinu parametrů zadanou v textu dotazu . Výrazy, které odkazují na tyto neurčené parametry, se vyhodnotí jako nedefinované. Je také platné zadat další parametry, které se nepoužívají v textu dotazu .

Některé příklady platných žádostí o dotazy jsou uvedené níže. Například následující dotaz má jeden parametr @id.

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

Následující příklad obsahuje dva parametry, jeden s řetězcovou hodnotou a druhý s celočíselnou hodnotou.

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

Následující příklad používá parametry v klauzuli SELECT a vlastnost přístupnou prostřednictvím názvu parametru jako parametr.

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

Dotazy, které nemůže obsluhovat brána

Brána nemůže obsluhovat žádný dotaz, který vyžaduje stav napříč pokračováními. Sem patří:

TOP
ORDER BY
OFFSET LIMIT
Agregace
DISTINCT
GROUP BY

Mezi dotazy, které může brána obsluhovat, patří:

Jednoduché projekce
Filtry

Když se vrátí odpověď na dotaz, který brána nemůže obsluhovat, bude obsahovat stavový kód 400 (BadRequest) a následující zprávu:

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

Stránkování výsledků dotazu

Žádosti o dotazy podporují stránkování prostřednictvím hlaviček požadavků x-ms-max-item-count a x-ms-continuation . Hlavička x-ms-max-item-count určuje maximální počet hodnot, které může spuštění dotazu vrátit. Tato hodnota může být mezi 1 a 1000 a je nakonfigurovaná s výchozí hodnotou 100.

Dotazy se vrátí od nuly až po maximální zadané hodnoty x-ms-max-item-count z výsledků provádění. Výsledek dotazu obsahuje hlavičku x-ms-item-count , která určuje skutečný počet dokumentů vrácených dotazem. Pokud se z dotazu dají načíst další výsledky, bude odpověď obsahovat neprázdnou hodnotu pro hlavičku x-ms-continuation .

Klienti můžou načíst další stránky výsledků tak, že jako další požadavek zopakují hlavičku x-ms-continuation . Aby bylo možné číst všechny výsledky, klienti musí tento proces opakovat, dokud se nevrátí prázdné pokračování x-ms.

Spouštění dotazů Cosmos DB je na straně serveru bezstavové a je možné je kdykoli obnovit pomocí hlavičky x-ms-continuation . Hodnota x-ms-continuation používá ID naposledy zpracovaného prostředku dokumentu (_rid) ke sledování průběhu provádění. Proto pokud jsou dokumenty odstraněny a znovu vloženy mezi načtením stránek, mohou být dokumenty potenciálně vyloučeny z jakékoli dávky dotazu. Chování a formát hlavičky x-ms-continuation se však může v budoucí aktualizaci služby změnit.

Sdílet prostřednictvím