Query's uitvoeren op Azure Cosmos DB-resources met behulp van de REST API

Artikel
08/05/2023

Azure Cosmos DB is een wereldwijd gedistribueerde, multi-model databaseservice met ondersteuning voor meerdere API’s. In dit artikel wordt beschreven hoe u REST gebruikt om query's uit te voeren op resources met behulp van de SQL-API.

Hoe kan ik een query uit op een resource met behulp van REST?

Ga als volgt te werk om een SQL-query uit te voeren op een resource:

Voer een POST methode uit op basis van een resourcepad met behulp van JSON, waarbij de query eigenschap is ingesteld op de SQL-querytekenreeks en de eigenschap 'parameters' is ingesteld op de matrix met optionele parameterwaarden.
Stel de x-ms-documentdb-isquery header in op True.
Stel de Content-Type header in op application/query+json.

Zie REST from .NET Sample (REST from .NET Sample) voor een voorbeeld van het uitvoeren van een SQL-query op een resource met behulp van .NET.

Voorbeeld

Hieronder ziet u een voorbeeld van een REST-querybewerking voor documentresources. In dit voorbeeld zoeken we alle documenten met 'Don' als auteur.

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

Gedetailleerde aanvraaggegevens

Methode	Aanvraag-URI
VERZENDEN	Vereist. Het verificatietype en het handtekeningtoken. Alleen het hoofdsleuteltoken is toegestaan voor deze bewerking. Zie Access Control op Cosmos DB-resources voor meer informatie.

Aanvraagheaders

De volgende tabel bevat de algemene headers die worden gebruikt om querybewerkingen uit te voeren.

Standaardkoptekst	Beschrijving
Autorisatie	Vereist. Het verificatietype en het handtekeningtoken. Alleen het hoofdsleuteltoken is toegestaan voor deze bewerking. Zie Access Control op Cosmos DB-resources voor meer informatie.
Content-Type	Vereist. Moet worden ingesteld op application/query+json.
Accepteren	Optioneel. Op dit moment retourneert Cosmos DB altijd de nettolading van het antwoord in de standaard-JSON-indeling. De client moet de antwoordtekst in standaard JSON-indeling kunnen accepteren.
User-Agent	Optioneel. De gebruikersagent die de aanvraag uitvoert. De aanbevolen indeling is {user agent name}/{version}. De SQL API .NET SDK stelt bijvoorbeeld de User-Agent tekenreeks in op Microsoft.Document.Client/1.0.0.0.

Aangepaste koptekst	Beschrijving
x-ms-date	Vereist. De datum van de aanvraag, zoals opgegeven in RFC 1123. De datumnotatie wordt bijvoorbeeld uitgedrukt in Coordinated Universal Time (UTC). Vr, 08 apr 2015 03:52:31 GMT.
x-ms-documentdb-isquery	Vereist. Deze eigenschap moet worden ingesteld op true.
x-ms-max-item-count	Optioneel. Als u een resultatenset wilt doorlopen, stelt u deze koptekst in op het maximum aantal items dat op één pagina moet worden geretourneerd.
x-ms-continuation	Optioneel. Als u naar de volgende pagina met items wilt navigeren, stelt u deze koptekst in op het vervolgtoken voor de volgende pagina.
x-ms-version	Optioneel. De versie van Cosmos DB REST-service. De nieuwste versie wordt gebruikt wanneer de header niet is opgegeven. Zie Naslaginformatie over azure Cosmos DB REST API voor meer informatie.
x-ms-documentdb-query-enable-scan	Optioneel. Gebruik een indexscan om de query te verwerken als het juiste indexpad van het type niet beschikbaar is.
x-ms-session-token	Optioneel. Het sessietoken voor de aanvraag. Wordt gebruikt voor sessieconsistentie.
x-ms-partition-key	Optioneel. Indien opgegeven, wordt de query alleen uitgevoerd op documenten die overeenkomen met de waarde van de partitiesleutel in de header.
x-ms-documentdb-query-enablecrosspartition	Optioneel. Moet worden ingesteld op true voor query's die niet filteren op één partitiesleutel. Query's die filteren op één partitiesleutelwaarde worden uitgevoerd op slechts één partitie, zelfs als dit is ingesteld op true.
x-ms-documentdb-populatequerymetrics	Optioneel. Moet worden ingesteld op om `True` metrische querygegevens te retourneren

Aanvraagbody

De aanvraagbody moet een geldig JSON-document zijn met de SQL-query en -parameters. Als de invoer een ongeldige of ongeldige SQL-syntaxis is, mislukt de bewerking met met de fout 400 Ongeldige aanvraag.

U krijgt ook een 400 ongeldige aanvraag als een query niet kan worden uitgevoerd door de gateway.

Eigenschap	Beschrijving
query	Vereist. De SQL-queryreeks voor de query. Zie Naslaginformatie over azure Cosmos DB SQL-syntaxis voor meer informatie.
parameters	Vereist. Een JSON-matrix met parameters die zijn opgegeven als naamwaardeparen. De parametermatrix kan van nul tot veel parameters bevatten. Elke parameter moet de volgende waarden hebben:name: de naam van de parameter. Parameternamen moeten geldige letterlijke tekenreeksen zijn en beginnen met @. value: de waarde van de parameter. Kan elke geldige JSON-waarde zijn (tekenreeks, getal, object, matrix, Booleaanse waarde of null).

Eigenschap

Beschrijving

query

Vereist. De SQL-queryreeks voor de query. Zie Naslaginformatie over azure Cosmos DB SQL-syntaxis voor meer informatie.

parameters

Vereist. Een JSON-matrix met parameters die zijn opgegeven als naamwaardeparen. De parametermatrix kan van nul tot veel parameters bevatten. Elke parameter moet de volgende waarden hebben:name: de naam van de parameter. Parameternamen moeten geldige letterlijke tekenreeksen zijn en beginnen met @. value: de waarde van de parameter. Kan elke geldige JSON-waarde zijn (tekenreeks, getal, object, matrix, Booleaanse waarde of null).

Voorbeeld van aanvraag

In het volgende voorbeeld wordt een SQL-aanvraag met parameters gemaakt met een tekenreeksparameter voor @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"}  
    ]  
}

Zie SQL-query's voor Azure Cosmos DB voor meer informatie over de SQL-query's.

Antwoorddetails

Hier volgen algemene statuscodes die door deze bewerking worden geretourneerd. Zie HTTP-statuscodes voor Azure Cosmos DB voor informatie over foutstatuscodes.

Code	Beschrijving
200 Ok	De bewerking is geslaagd.
400 Ongeldige aanvraag	De syntaxis van de SQL-instructie is onjuist.
401 Onbevoegd	De header Autorisatie of x-ms-date is niet ingesteld. 401 wordt ook geretourneerd wanneer de autorisatieheader is ingesteld op een ongeldig autorisatietoken.
403 Verboden	Het autorisatietoken is verlopen.
404 Niet gevonden	De verzameling is geen resource meer. De resource kan bijvoorbeeld zijn verwijderd.

Antwoordheaders

Deze bewerking retourneert de volgende algemene headers. Er kunnen aanvullende standaard- en algemene headers worden geretourneerd.

Standaardkoptekst	Beschrijving
Content-Type	Het inhoudstype is application/json. Cosmos DB retourneert altijd de hoofdtekst van het antwoord in de standaard-JSON-indeling.
Datum	De datum/tijd van de reactiebewerking. Deze datum/tijdnotatie voldoet aan de datum/tijdnotatie [RFC1123] uitgedrukt in UTC.

Aangepaste koptekst	Beschrijving
x-ms-item-count	Het aantal items dat door de bewerking wordt geretourneerd.
x-ms-continuation	Het is een ondoorzichtige tekenreeks die wordt geretourneerd wanneer de query mogelijk meer items bevat die moeten worden opgehaald. De x-ms-continuation kan in volgende aanvragen worden opgenomen als aanvraagheader om de uitvoering van de query te hervatten.
x-ms-request-charge	Dit is het aantal aanvraageenheden (RU) dat door de bewerking wordt verbruikt. Zie Aanvraageenheden in Azure Cosmos DB voor meer informatie over aanvraageenheden.
x-ms-activity-id	Het is een unieke id voor de bewerking. Het kan worden gebruikt voor het traceren van de uitvoering van Cosmos DB-aanvragen.
x-ms-session-token	Het sessietoken dat moet worden gebruikt voor volgende aanvragen. Wordt gebruikt voor sessieconsistentie.

Hoofdtekst van antwoord

De antwoordtekst voor de querybewerking bestaat uit de _rid van de bovenliggende resource van de resource die wordt opgevraagd en de resourcematrix die de resource-eigenschappen voor de projectie en selectie bevat. Als er volgens het voorbeeld een query is uitgevoerd op het docs-pad van de verzameling met een _rid XP0mAJ3H-AA=, zou het antwoord er als volgt uitzien:

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

Eigenschap	Beschrijving
_Ontdoen	De resource-id voor de verzameling die in de query wordt gebruikt.
_Tellen	Het aantal geretourneerde items.
Resourcematrix	De matrix met de queryresultaten.

De hoofdtekst van de queryaanvraag samenstellen

De queryaanvraag moet een geldig JSON-document zijn met een queryeigenschap die een geldige SQL-queryreeks en een parametereigenschap met een matrix met optionele parameters bevat. Elke parameter moet een naam en waarde-eigenschap hebben van parameters die zijn opgegeven in de query. Parameternamen moeten beginnen met het teken '@'. Waarden kunnen geldige JSON-waarden zijn: tekenreeksen, gehele getallen, Booleaanse waarden en null-waarden.

Het is geldig om alleen een subset van parameters op te geven die zijn opgegeven in de querytekst . Expressies die verwijzen naar deze niet-opgegeven parameters, worden geëvalueerd als niet-gedefinieerd. Het is ook geldig om aanvullende parameters op te geven die niet worden gebruikt in de querytekst .

Hieronder ziet u enkele voorbeelden van geldige queryaanvragen. De volgende query heeft bijvoorbeeld één parameter @id.

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

Het volgende voorbeeld heeft twee parameters, een met een tekenreekswaarde en een andere met een geheel getal.

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

In het volgende voorbeeld worden parameters in de SELECT-component gebruikt, evenals een eigenschap die toegankelijk is via de parameternaam als parameter.

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

Query's die niet door de gateway kunnen worden uitgevoerd

Query's waarvoor een status is vereist voor voortzettingen, kunnen niet worden uitgevoerd door de gateway. Dit omvat:

BOVEN
ORDER BY
OFFSET LIMIT
Statistische functies
DISTINCT
GROUP BY

Query's die door de gateway kunnen worden uitgevoerd, zijn onder andere:

Eenvoudige projecties
Filters

Wanneer een antwoord wordt geretourneerd voor een query die niet kan worden uitgevoerd door de gateway, bevat deze de statuscode 400 (BadRequest) en het volgende bericht:

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

Paginering van queryresultaten

Queryaanvragen ondersteunen paginering via de aanvraagheaders x-ms-max-item-count en x-ms-continuation . De header x-ms-max-item-count geeft het maximum aantal waarden op dat kan worden geretourneerd door de uitvoering van de query. Dit kan tussen 1 en 1000 zijn en is geconfigureerd met een standaardwaarde van 100.

Query's retourneren van nul tot de maximaal opgegeven x-ms-max-item-count-waarden uit de resultaten van de uitvoering. Het queryresultaat bevat een x-ms-item-count-header die het werkelijke aantal documenten aangeeft dat door de query wordt geretourneerd. Als er aanvullende resultaten kunnen worden opgehaald uit de query, bevat het antwoord een niet-lege waarde voor de x-ms-continuation-header .

Clients kunnen volgende pagina's met resultaten ophalen door de x-ms-continuation-header als een andere aanvraag te echoën. Als u alle resultaten wilt lezen, moeten clients dit proces herhalen totdat een lege x-ms-continuation wordt geretourneerd.

Uitvoeringen van Cosmos DB-query's zijn staatloos aan de serverzijde en kunnen op elk gewenst moment worden hervat met behulp van de x-ms-continuation-header . De x-ms-continuation-waarde gebruikt de laatst verwerkte documentresource-id (_rid) om de voortgang van de uitvoering bij te houden. Dus als documenten worden verwijderd en opnieuw worden ingevoegd tussen het ophalen van pagina's, kunnen de documenten mogelijk worden uitgesloten van een van de querybatches. Het gedrag en de indeling van de x-ms-continuation-header kunnen echter veranderen in een toekomstige service-update.

Share via