Freigeben über

Abfragen von Azure Cosmos DB-Ressourcen mithilfe der REST-API

  • Artikel

Azure Cosmos DB ist eine global verteilte Mehrmodelldatenbank mit Unterstützung für mehrere APIs. In diesem Artikel wird beschrieben, wie Sie REST verwenden, um Ressourcen mithilfe der SQL-API abzufragen.

Wie wird eine Ressource mithilfe von REST abgefragt?

Gehen Sie zum Ausführen einer SQL-Abfrage für eine Ressource wie folgt vor:

  • Führen Sie eine POST Methode für einen Ressourcenpfad mithilfe von JSON aus, wobei die query Eigenschaft auf die SQL-Abfragezeichenfolge und die Eigenschaft "parameters" auf das Array optionaler Parameterwerte festgelegt ist.
  • Legen Sie den Header x-ms-documentdb-isquery auf True fest.
  • Legen Sie den Header Content-Type auf application/query+json fest.

Ein Beispiel zum Ausführen einer SQL-Abfrage für eine Ressource mit .NET finden Sie unter REST from .NET Sample.

Beispiel

Das folgende Beispiel zeigt einen REST-Abfragevorgang für Dokumentressourcen. In diesem Beispiel sollen alle Dokumente gesucht werden, deren Autor "Don" ist.

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

Anforderungsdetails

Methode Anforderungs-URI
POST Erforderlich. Der Authentifizierungstyp und das Signaturtoken. Nur das Hauptschlüsseltoken ist für diesen Vorgang zulässig. Weitere Informationen finden Sie unter Access Control zu Cosmos DB-Ressourcen.

Anforderungsheader

Die folgende Tabelle enthält die allgemeinen Header, die für die Abfragevorgänge verwendet werden.

Standardheader Beschreibung
Autorisierung Erforderlich. Der Authentifizierungstyp und das Signaturtoken. Nur das Hauptschlüsseltoken ist für diesen Vorgang zulässig. Weitere Informationen finden Sie unter Access Control zu Cosmos DB-Ressourcen.
Content-Type Erforderlich. Muss auf "application/query+json" festgelegt werden.
Annehmen Optional: Derzeit gibt Cosmos DB die Antwortnutzlast immer im JSON-Standardformat zurück. Der Client muss den Antworttext im JSON-Standardformat akzeptieren können.
User-Agent Optional: Der Benutzer-Agent zur Ausführung der Anforderung. Das empfohlene Format ist {user agent name}/{version}. Beispielsweise legt das .NET SDK der SQL-API die User-Agent Zeichenfolge auf Microsoft.Document.Client/1.0.0.0 fest.
Benutzerdefinierter Header Beschreibung
x-ms-date Erforderlich. Das Datum der Anforderung, wie in RFC 1123 angegeben. Das Datumsformat wird beispielsweise in koordinierter Weltzeit (UTC) ausgedrückt. Fri, 08 Apr 2015 03:52:31 GMT.
x-ms-documentdb-isquery Erforderlich. Diese Eigenschaft muss auf "true" festgelegt werden.
x-ms-max-item-count Optional: Wen Sie das Resultset seitenweise anzeigen möchten, legen Sie diesen Header auf die maximale Anzahl der Elemente fest, die auf einer einzigen Seite zurückgegeben werden sollen.
x-ms-continuation Optional: Wenn Sie zur nächsten Seite mit Elementen navigieren möchten, legen Sie diesen Header auf das Fortsetzungstoken für die nächste Seite fest.
x-ms-version Optional: Die Version des Cosmos DB-REST-Diensts. Die neueste Version wird verwendet, wenn der Header nicht angegeben ist. Weitere Informationen finden Sie in der Azure Cosmos DB-REST-API-Referenz.
x-ms-documentdb-query-enable-scan Optional: Verwenden Sie einen Indexscan zum Verarbeiten der Abfrage, wenn der richtige Indexpfad des Typs nicht verfügbar ist.
x-ms-session-token Optional: Das Sitzungstoken für die Anforderung. Dieses wird aus Gründen der Sitzungskonsistenz verwendet.
x-ms-partition-key Optional: Wenn angegeben, wird die Abfrage nur für Dokumente ausgeführt, die dem Partitionsschlüsselwert im Header entsprechen.
x-ms-documentdb-query-enablecrosspartition Optional: Muss für alle Abfragen, die nicht nach einem einzelnen Partitionsschlüssel filtern, auf true festgelegt werden. Abfragen, die nach einem einzelnen Partitionsschlüsselwert filtern, werden nur für eine einzelne Partition ausgeführt, auch wenn dies auf TRUE festgelegt ist.
x-ms-documentdb-populatequerymetrics Optional: Muss auf True festgelegt werden, um Abfragemetriken zurückzugeben.

Anforderungstext

Der Anforderungstext sollte ein gültiges JSON-Dokument sein, das die SQL-Abfrage und die Parameter enthält. Wenn die Eingabe fehlerhaft ist oder ungültige SQL-Syntax verwendet wird, schlägt der Vorgang mit dem Fehler "400 Bad Request" fehl.

Sie erhalten auch eine ungültige 400-Anforderung, wenn eine Abfrage nicht vom Gateway bereitgestellt werden kann.

Eigenschaft BESCHREIBUNG
Abfrage Erforderlich. Die SQL-Abfragezeichenfolge für die Abfrage. Weitere Informationen finden Sie unter Sql-Syntaxreferenz für Azure Cosmos DB.
parameters Erforderlich. Ein JSON-Array von Parametern, die als Name-Wert-Paare angegeben werden. Das Parameterarray kann von null bis zu vielen Parametern enthalten. Jeder Parameter muss die folgenden Werte aufweisen: name: der Name des Parameters. Parameternamen müssen gültige Zeichenfolgenliterale sein und mit "@" beginnen. value: Der Wert des Parameters. Kann ein beliebiger gültiger JSON-Wert (Zeichenfolge, Zahl, Objekt, Array, boolescher Wert oder Null) sein.

Anforderungsbeispiel

Im folgenden Beispiel wird eine parametrisierte SQL-Anforderung mit einem Zeichenfolgenparameter für @authorausgeführt.

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

Weitere Informationen zu den SQL-Abfragen finden Sie unter SQL-Abfragen für Azure Cosmos DB.

Antwortdetails

Die folgenden allgemeinen Statuscodes werden von diesem Vorgang zurückgegeben. Informationen zu Fehlercodes status finden Sie unter HTTP-Statuscodes für Azure Cosmos DB.

Code Beschreibung
200 Ok Der Vorgang ist erfolgreich.
400 – Ungültige Anforderung Die Syntax der SQL-Anweisung ist falsch.
401 – Nicht autorisiert Entweder ist der Authorization- oder der x-ms-date-Header nicht festgelegt. 401 wird auch zurückgegeben, wenn der Authorization-Header auf ein ungültiges Autorisierungstoken festgelegt ist.
403 – Unzulässig Das Autorisierungstoken ist abgelaufen.
404 – Nicht gefunden Die Auflistung ist keine Ressource mehr. Beispielsweise kann die Ressource gelöscht worden sein.

Antwortheader

Dieser Vorgang gibt die folgenden allgemeinen Header zurück. Möglicherweise werden weitere standardmäßige und allgemeine Header zurückgegeben.

Standardheader Beschreibung
Content-Type Der Content-Type ist application/json. Cosmos DB gibt den Antworttext immer im JSON-Standardformat zurück.
Date Datum und Uhrzeit des Antwortvorgangs. Das Datums-/Zeitformat entspricht dem RFC 1123-Datums-/Zeitformat, ausgedrückt in UTC.
Benutzerdefinierter Header Beschreibung
x-ms-item-count Die Anzahl der vom Vorgang zurückgegebenen Elemente.
x-ms-continuation Es ist eine undurchsichtige Zeichenfolge, die zurückgegeben wird, wenn die Abfrage potenziell mehr Elemente enthält, die abgerufen werden müssen.

"x-ms-continuation" kann in nachfolgende Anforderungen als Anforderungsheader einbezogen werden, um die Ausführung der Abfrage fortzusetzen.
x-ms-request-charge Dies ist die Anzahl der Anforderungseinheiten (RU), die vom Vorgang verbraucht werden. Weitere Informationen zu Anforderungseinheiten finden Sie unter Anforderungseinheiten in Azure Cosmos DB.
x-ms-activity-id Es ist ein eindeutiger Bezeichner für den Vorgang. Sie kann zum Nachverfolgen der Ausführung von Cosmos DB-Anforderungen verwendet werden.
x-ms-session-token Das Sitzungstoken für nachfolgende Anforderungen. Dieses wird aus Gründen der Sitzungskonsistenz verwendet.

Antworttext

Der Antworttext für den Abfragevorgang besteht aus der _rid der übergeordneten Ressource der Ressource, die abgefragt wird, und dem Ressourcenarray, das die Ressourceneigenschaften für die Projektion und die Auswahl enthält. Wenn beispielsweise eine Abfrage für den docs-Pfad der Auflistung mit einer Ressourcen-ID (_rid) von "XP0mAJ3H-AA=" ausgeführt wird, lautet die Antwort wie folgt:

{"_rid":" XP0mAJ3H-AA=","Documents":   [  ….  ….   ],"_count":10}
Eigenschaft Beschreibung
_rid Die Ressourcen-ID für die Sammlung, die in der Abfrage verwendet wird.
_Count Die Anzahl der zurückgegebenen Elemente.
Resource array Das Array, das die Abfrageergebnisse enthält.

Erstellen des Abfrageanforderungstexts

Die Abfrageanforderung muss ein gültiges JSON-Dokument mit enthaltener query-Eigenschaft sein, die eine gültige SQL-Abfragezeichenfolge und eine parameters-Eigenschaft enthält, in der wiederum ein Array von optionalen Parameter enthalten ist. Jeder Parameter muss eine name- und value-Eigenschaft von Parametern aufweisen, die in der Abfrage angegeben sind. Parameternamen müssen mit dem Zeichen "@" beginnen. Mögliche Werte sind alle gültigen JSON-Werte, z. B. Zeichenfolgen, ganze Zahlen, boolesche und NULL-Werte.

Es ist gültig, nur eine Teilmenge der Parameter anzugeben, die im Abfragetext angegeben sind. Ausdrücke, die auf diese nicht angegebenen Parameter verweisen, werden als nicht definiert ausgewertet. Es ist auch zulässig, zusätzliche Parameter anzugeben, die nicht im Abfragetext verwendet werden.

Nachfolgend finden Sie einige Beispiele für gültige Abfrageanforderungen. Die folgende Abfrage verfügt beispielsweise über einen einzelnen Parameter @id.

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

Das folgende Beispiel enthält zwei Parameter, von denen ein Parameter einen String- und der andere einen Integer-Wert aufweist.

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

Im folgenden Beispiel werden Parameter in der SELECT-Klausel sowie eine Eigenschaft verwendet, auf die über den Parameternamen als Parameter zugegriffen wird.

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

Abfragen, die nicht vom Gateway bedient werden können

Jede Abfrage, die den Zustand für alle Fortsetzungen erfordert, kann nicht vom Gateway bereitgestellt werden. Dies schließt Folgendes ein:

  • TOP
  • ORDER BY
  • OFFSET LIMIT
  • Aggregate
  • DISTINCT
  • GROUP BY

Zu den Abfragen, die vom Gateway bereitgestellt werden können, gehören:

  • Einfache Projektionen
  • Filter

Wenn eine Antwort für eine Abfrage zurückgegeben wird, die nicht vom Gateway bereitgestellt werden kann, enthält sie den status Code 400 (BadRequest) und die folgende Meldung:

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

Paginierung von Abfrageergebnissen

Abfrageanforderungen unterstützen die Paginierung über die Header x-ms-max-item-count und x-ms-continuation request. Der Header x-ms-max-item-count gibt die maximale Anzahl von Werten an, die durch die Ausführung der Abfrage zurückgegeben werden können. Diese kann zwischen 1 und 1000 liegen und wird standardmäßig mit 100 konfiguriert.

Abfragen geben zwischen null und dem für x-ms-max-item-count-Werte angegebenem Höchstwert aus den Ergebnissen der Ausführung zurück. Das Abfrageergebnis umfasst einen x-ms-item-count-Header, der die tatsächliche Anzahl von Dokumenten angibt, die von der Abfrage zurückgegeben werden. Wenn zusätzliche Ergebnisse vorhanden sind, die von der Abfrage abgerufen werden könnten, dann enthält die Antwort einen nicht leeren Wert für den x-ms-continuation-Header.

Clients können nachfolgende Ergebnisseiten abrufen, indem der x-ms-continuation-Header als weitere Anforderung wiederholt wird. Um alle Ergebnisse zu lesen, müssen Clients diesen Vorgang wiederholen, bis ein leerer x-ms-continuation-Header zurückgegeben wird.

Cosmos DB-Abfrageausführungen sind serverseitig zustandslos und können jederzeit mithilfe des x-ms-continuation-Headers fortgesetzt werden. Der x-ms-continuation-Wert verwendet die zuletzt verarbeitete Dokumentressourcen-ID (_rid), um den Status der Ausführung nachzuverfolgen. Wenn Dokumente also zwischen dem Abrufen von Seiten gelöscht und erneut eingefügt werden, könnten die Dokumente möglicherweise aus einem der Abfragebatches ausgeschlossen werden. Verhalten und Format des x-ms-continuation-Headers können jedoch möglicherweise in einem zukünftigen Dienstupdate geändert werden.

Weitere Informationen