Köra frågor mot Azure Cosmos DB-resurser med hjälp av REST-API:et

  • Artikel

Azure Cosmos DB är en globalt distribuerad databas för flera datamodeller som har stöd för flera API:er. Den här artikeln beskriver hur du använder REST för att fråga efter resurser med hjälp av SQL-API:et.

Hur gör jag för att fråga en resurs med hjälp av REST?

Utför en SQL-fråga på en resurs genom att göra följande:

  • Kör en POST metod mot en resurssökväg med JSON med query egenskapen inställd på SQL-frågesträngen och egenskapen "parameters" inställd på matrisen med valfria parametervärden.
  • x-ms-documentdb-isquery Ange rubriken till True.
  • Content-Type Ange rubriken till application/query+json.

Ett exempel som visar hur du utför en SQL-fråga på en resurs med hjälp av .NET finns i REST från .NET-exempel.

Exempel

Nedan visas ett exempel på en REST-frågeåtgärd för dokumentresurser. I det här exemplet vill vi hitta alla dokument som har "Don" som författare.

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

Information om förfrågningar

Metod URI för förfrågan
INLÄGG Krävs. Autentiseringstyp och signaturtoken. Endast huvudnyckeltoken tillåts för den här åtgärden. Mer information finns i Access Control på Cosmos DB-resurser.

Rubriker för begäran

Följande tabell innehåller de vanliga rubriker som används för att utföra frågeåtgärder.

Standardrubrik Beskrivning
Auktorisering Krävs. Autentiseringstyp och signaturtoken. Endast huvudnyckeltoken tillåts för den här åtgärden. Mer information finns i Access Control på Cosmos DB-resurser.
Innehållstyp Krävs. Måste anges till application/query+json.
Godkänn Valfritt. För tillfället returnerar Cosmos DB alltid svarsnyttolasten i JSON-standardformat. Klienten måste kunna acceptera svarstexten i JSON-standardformat.
User-Agent Valfritt. Användaragenten som utför begäran. Det rekommenderade formatet är {user agent name}/{version}. Sql API .NET SDK anger till exempel User-Agent strängen till Microsoft.Document.Client/1.0.0.0.
Anpassat sidhuvud Beskrivning
x-ms-date Krävs. Datumet för begäran enligt vad som anges i RFC 1123. Datumformatet uttrycks till exempel i Coordinated Universal Time (UTC). Fre, 08 apr 2015 03:52:31 GMT.
x-ms-documentdb-isquery Krävs. Den här egenskapen måste vara inställd på true.
x-ms-max-item-count Valfritt. Om du vill bläddra igenom en resultatuppsättning anger du det maximala antalet objekt som ska returneras på en enda sida.
x-ms-fortsättning Valfritt. Om du vill gå till nästa sida med objekt anger du den här rubriken till fortsättningstoken för nästa sida.
x-ms-version Valfritt. Versionen av Cosmos DB REST-tjänsten. Den senaste versionen används när rubriken inte anges. Mer information finns i REST API-referens för Azure Cosmos DB.
x-ms-documentdb-query-enable-scan Valfritt. Använd en indexgenomsökning för att bearbeta frågan om rätt indexsökväg av typen inte är tillgänglig.
x-ms-session-token Valfritt. Sessionstoken för begäran. Används för sessionskonsekvens.
x-ms-partition-key Valfritt. Om det anges körs frågan endast på dokument som matchar partitionsnyckelvärdet i huvudet.
x-ms-documentdb-query-enablecrosspartition Valfritt. Måste anges till true för alla frågor som inte filtrerar mot en enda partitionsnyckel. Frågor som filtrerar mot ett enda partitionsnyckelvärde körs endast mot en enda partition, även om detta är inställt på true.
x-ms-documentdb-populatequerymetrics Valfritt. Måste anges till True för att kunna returnera frågemått

Begärandetext

Begärandetexten ska vara ett giltigt JSON-dokument som innehåller SQL-frågan och parametrarna. Om indata är felaktigt eller ogiltig SQL-syntax misslyckas åtgärden med felet 400 Felaktig begäran.

Du får också en 400 felaktig begäran om en fråga inte kan hanteras av gatewayen.

Egenskap Beskrivning
query Krävs. SQL-frågesträngen för frågan. Mer information finns i SQL-syntaxreferens för Azure Cosmos DB.
parametrar Krävs. En JSON-matris med parametrar som anges som namnvärdepar. Parametermatrisen kan innehålla från noll till många parametrar. Varje parameter måste ha följande värden:namn: namnet på parametern. Parameternamn måste vara giltiga strängliteraler och börja med @. värde: värdet för parametern. Kan vara ett giltigt JSON-värde (sträng, tal, objekt, matris, booleskt eller null).

Exempel på begäran

I följande exempel görs en parametriserad SQL-begäran med en strängparameter för @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"}  
    ]  
}

Mer information om SQL-frågor finns i SQL-frågor för Azure Cosmos DB.

Svarsinformation

Följande är vanliga statuskoder som returneras av den här åtgärden. Information om felstatuskoder finns i HTTP-statuskoder för Azure Cosmos DB.

Kod Beskrivning
200 Ok Åtgärden har slutförts.
400 – Felaktig begäran Syntaxen för SQL-instruktionen är felaktig.
401 – Ej behörig Huvudet Authorization (Auktorisering ) eller x-ms-date har inte angetts. 401 returneras också när auktoriseringshuvudet är inställt på en ogiltig auktoriseringstoken.
403 – Förbjuden Auktoriseringstoken har upphört att gälla.
404 – Hittades inte Samlingen är inte längre en resurs. Resursen kan till exempel ha tagits bort.

Svarsrubriker

Den här åtgärden returnerar följande vanliga rubriker. Det kan finnas ytterligare standardhuvuden och vanliga huvuden som returneras.

Standardrubrik Beskrivning
Innehållstyp Innehållstypen är application/json. Cosmos DB returnerar alltid svarstexten i JSON-standardformat.
Datum Datum/tid för svarsåtgärden. Det här datumtidsformatet överensstämmer med datumtidsformatet [RFC1123] uttryckt i UTC.
Anpassat sidhuvud Beskrivning
x-ms-item-count Antalet objekt som returneras av åtgärden.
x-ms-continuation Det är en täckande sträng som returneras när frågan har potentiellt fler objekt som ska hämtas.

X-ms-continuation kan inkluderas i efterföljande begäranden som ett begärandehuvud för att återuppta körningen av frågan.
x-ms-request-charge Det är antalet enheter för programbegäran (RU) som förbrukas av åtgärden. Mer information om enheter för programbegäran finns i Enheter för programbegäran i Azure Cosmos DB.
x-ms-activity-id Det är en unik identifierare för åtgärden. Den kan användas för att spåra körning av Cosmos DB-begäranden.
x-ms-session-token Sessionstoken som ska användas för efterföljande begäranden. Används för sessionskonsekvens.

Svarstext

Svarstexten för frågeåtgärden består av _rid av den överordnade resursen för resursen som efterfrågas och resursmatrisen som innehåller resursegenskaperna för projektionen och markeringen. Enligt exemplet skulle svaret vara följande om en fråga utfördes på docs-sökvägen för samlingen med en _rid XP0mAJ3H-AA=:

{"_rid":" XP0mAJ3H-AA=","Documents":   [  ….  ….   ],"_count":10}
Egenskap Beskrivning
_Bli Resurs-ID:t för den samling som används i frågan.
_Räkna Antalet returnerade objekt.
Resursmatris Matrisen som innehåller frågeresultatet.

Skapa frågeförfrågningstexten

Frågebegäran måste vara ett giltigt JSON-dokument som innehåller en frågeegenskap som innehåller en giltig SQL-frågesträng och en parameteregenskap som innehåller en matris med valfria parametrar. Varje parameter ska ha en namn - och värdeegenskap för parametrar som anges i frågan. Parameternamn måste börja med tecknet "@". Värden kan vara giltiga JSON-värden – strängar, heltal, booleska värden och nullvärden.

Det är giltigt att endast ange en delmängd av parametrarna som anges i frågetexten . Uttryck som refererar till dessa ospecificerade parametrar utvärderas till odefinierad. Det är också giltigt att ange ytterligare parametrar som inte används i frågetexten .

Några exempel på giltiga frågebegäranden visas nedan. Följande fråga har till exempel en enda parameter @id.

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

I följande exempel finns två parametrar, en med ett strängvärde och en annan med ett heltalsvärde.

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

I följande exempel används parametrar i SELECT-satsen, samt en egenskap som nås via parameternamnet som en parameter.

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

Frågor som inte kan hanteras av gateway

Alla frågor som kräver tillstånd över fortsättningar kan inte hanteras av gatewayen. Du måste bland annat:

  • TOPP
  • ORDNA EFTER
  • FÖRSKJUTNINGSGRÄNS
  • Aggregeringar
  • DISTINKTA
  • GROUP BY

Frågor som kan hanteras av gatewayen är:

  • Enkla projektioner
  • Filter

När ett svar returneras för en fråga som inte kan hanteras av gatewayen innehåller det statuskoden 400 (BadRequest) och följande meddelande:

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

Sidnumrering av frågeresultat

Frågebegäranden stöder sidnumrering via huvudena x-ms-max-item-count och x-ms-continuation. Rubriken x-ms-max-item-count anger det maximala antalet värden som kan returneras av frågekörningen. Detta kan vara mellan 1 och 1 000 och konfigureras med standardvärdet 100.

Frågor returneras från noll upp till det högsta angivna x-ms-max-item-count-värdet från resultatet av körningen. Frågeresultatet innehåller ett x-ms-item-count-huvud som anger det faktiska antalet dokument som returneras av frågan. Om det finns ytterligare resultat som kan hämtas från frågan innehåller svaret ett värde som inte är tomt för rubriken x-ms-continuation .

Klienter kan hämta efterföljande sidor med resultat genom att upprepa rubriken x-ms-continuation som en annan begäran. För att kunna läsa alla resultat måste klienterna upprepa den här processen tills en tom x-ms-continuation returneras.

Cosmos DB-frågekörningar är tillståndslösa på serversidan och kan återupptas när som helst med huvudet x-ms-continuation . Värdet x-ms-continuation använder det senast bearbetade dokumentresurs-ID:t (_rid) för att spåra körningsförloppet. Om dokument tas bort och infogas på nytt mellan hämtningen av sidor kan dokumenten därför eventuellt uteslutas från någon av frågebatcherna. Beteendet och formatet för rubriken x-ms-continuation kan dock ändras i en framtida tjänstuppdatering.

Se även