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

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

Anforderungsheader

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

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.

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.

Antwortheader

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

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}  

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

• Azure Cosmos DB
• SQL-API für Azure Cosmos DB
• Azure Cosmos DB SQL-API-SDKs
• REST aus .NET-Beispiel