Esecuzione di query sulle risorse di Azure Cosmos DB con l'API REST

Azure Cosmos DB è un database multimodello distribuito a livello globale con supporto per più API. Questo articolo descrive come usare REST per eseguire query sulle risorse usando l'API SQL.

Come si esegue una query su una risorsa usando REST?

Per eseguire una query SQL su una risorsa, eseguire le operazioni seguenti:

• Eseguire un POST metodo su un percorso di risorsa usando JSON con la query proprietà impostata sulla stringa di query SQL e la proprietà "parameters" impostata sulla matrice di valori dei parametri facoltativi.
• Impostare l'intestazione x-ms-documentdb-isquery su True.
• Impostare l'intestazione Content-Type su application/query+json.

Per un esempio che illustra come eseguire una query SQL su una risorsa con .NET, vedere REST from .NET Sample (REST from .NET Sample).

Esempio

Di seguito è riportato un esempio di operazione di query REST su risorse documento. In questo esempio si desidera trovare tutti i documenti che contengono "Don" come autore.

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

Dettagli delle richieste

Metodo	URI richiesta
POST	Obbligatorio. Tipo di autenticazione e token di firma. Per questa operazione è consentito solo il token della chiave master. Per altre informazioni, vedere Controllo di accesso sulle risorse di Cosmos DB.

Intestazioni richiesta

La tabella seguente contiene le intestazioni comuni usate per eseguire operazioni di query.

Intestazione standard	Descrizione
Autorizzazione	Obbligatorio. Tipo di autenticazione e token di firma. Per questa operazione è consentito solo il token della chiave master. Per altre informazioni, vedere Controllo di accesso sulle risorse di Cosmos DB.
Content-Type	Obbligatorio. Deve essere impostata su application/query+json.
Accettare	Facoltativo. Al momento, Cosmos DB restituisce sempre il payload della risposta in formato JSON standard. Il client deve essere in grado di accettare il corpo della risposta nel formato JSON standard.
User-Agent	Facoltativo. Agente utente che esegue la richiesta. Il formato consigliato è {user agent name}/{version}. Ad esempio, l'SDK .NET dell'API SQL imposta la stringa User-Agent su Microsoft.Document.Client/1.0.0.0.

Intestazione personalizzata	Descrizione
x-ms-date	Obbligatorio. Data della richiesta, come specificato in RFC 1123. Il formato della data è espresso nell'ora UTC (Coordinated Universal Time), ad esempio. Ven, 08 aprile 2015 03.52.31 GMT.
x-ms-documentdb-isquery	Obbligatorio. Questa proprietà deve essere impostata su true.
x-ms-max-item-count	Facoltativo. Per scorrere un set di risultati, impostare questa intestazione sul numero massimo di elementi da restituire in una singola pagina.
x-ms-continuation	Facoltativo. Per passare alla pagina di elementi successiva, impostare questa intestazione per il token di continuazione per la pagina successiva.
x-ms-version	Facoltativo. Versione del servizio REST di Cosmos DB. Quando l'intestazione non è specificata, si usa la versione più recente. Per altre informazioni, vedere Informazioni di riferimento sull'API REST di Azure Cosmos DB.
x-ms-documentdb-query-enable-scan	Facoltativo. Usare l'analisi degli indici per elaborare la query se il percorso di indice del tipo corretto non è disponibile.
x-ms-session-token	Facoltativo. Token di sessione per la richiesta. Usato per la coerenza della sessione.
x-ms-partition-key	Facoltativo. Se specificato, la query viene eseguita solo su documenti che corrispondono al valore della chiave di partizione nell'intestazione.
x-ms-documentdb-query-enablecrosspartition	Facoltativo. Deve essere impostato su true per tutte le query che non filtrano in base a una singola chiave di partizione. Le query che filtrano in base a un singolo valore della chiave di partizione verranno eseguite su una sola partizione anche se è impostata su true.
x-ms-documentdb-populatequerymetrics	Facoltativo. Deve essere impostato su True per restituire le metriche delle query

Corpo della richiesta

Il corpo della richiesta deve essere un documento JSON valido contenente la query e i parametri SQL. Se l'input è una sintassi SQL non corretta o non valida, l'operazione ha esito negativo e restituisce l'errore 400 (Richiesta non valida).

Si otterrà anche una richiesta 400 non valida se non è possibile gestire una query dal gateway.

Proprietà	Descrizione
query	Obbligatorio. Stringa di query SQL per la query. Per altre informazioni, vedere Informazioni di riferimento sulla sintassi SQL di Azure Cosmos DB.
parametri	Obbligatorio. Una matrice JSON di parametri specificati come coppie nome/valore. La matrice di parametri può contenere da zero a molti parametri. Ogni parametro deve avere i seguenti valori:name: il nome del parametro. I nomi dei parametri devono essere valori letterale stringa e iniziare con ‘@’.value: il valore del parametro. Possono essere valori JSON validi (stringa, numero, oggetto, matrice, valore booleano o null).

Esempio di richiesta

Nell'esempio seguente viene eseguita una richiesta SQL con parametri con un parametro stringa per @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"}  
    ]  
}  

Per altre informazioni sulle query SQL, vedere Query SQL per Azure Cosmos DB.

Dettagli della risposta

Di seguito sono riportati i codici di stato comuni restituiti dall'operazione. Per informazioni sui codici di stato degli errori, vedere Codici di stato HTTP per Azure Cosmos DB.

Codice	Descrizione
200 Ok	L'operazione è riuscita.
400 - Richiesta non valida	La sintassi dell'istruzione SQL non è corretta.
401 - Non autorizzato	Non è stata impostata l'intestazione Authorization o x-ms-date. Il codice 401 viene restituito anche quando l'intestazione Authorization è impostata su un token di autorizzazione non valido.
403 - Accesso negato	Il token di autorizzazione è scaduto.
404 - Non trovato	La raccolta non è più una risorsa. Ad esempio, è possibile che la risorsa sia stata eliminata.

Intestazioni della risposta

Questa operazione restituisce le seguenti intestazioni comuni. È possibile che vengano restituite altre intestazioni comuni e standard.

Intestazione standard	Descrizione
Content-Type	Il valore di Content-Type è application/json. Cosmos DB restituisce sempre il corpo della risposta in formato JSON standard.
Data	Data e ora dell'operazione di risposta. Il formato di data/ora è conforme al formato di data/ora della [RFC1123], espresso in UTC.

Intestazione personalizzata	Descrizione
x-ms-item-count	Numero di elementi restituiti dall'operazione.
x-ms-continuation	Si tratta di una stringa opaca restituita quando la query contiene potenzialmente più elementi da recuperare. È possibile includere x-ms-continuation nelle richieste successive come intestazione della richiesta di ripresa dell'esecuzione della query.
x-ms-request-charge	È il numero di unità richiesta utilizzate dall'operazione. Per altre informazioni sulle unità richiesta, vedere Unità richiesta in Azure Cosmos DB.
x-ms-activity-id	È un identificatore univoco per l'operazione. Può essere usato per tracciare l'esecuzione delle richieste di Cosmos DB.
x-ms-session-token	Token di sessione da usare per le richieste successive. Usato per la coerenza della sessione.

Corpo della risposta

Il corpo della risposta per l'operazione di query è costituito dall'ID risorsa (_rid) della risorsa padre della risorsa su cui viene eseguita la query e dalla matrice di risorse contenente le proprietà delle risorse per la proiezione e la selezione. Come nell'esempio, se una query è stata eseguita sul percorso docs della raccolta con un valore _rid XP0mAJ3H-AA=, la risposta sarà la seguente:

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

Proprietà	Descrizione
_rid	ID risorsa per la raccolta utilizzata all'interno della query.
_Conteggio	Numero di elementi restituiti.
Resource array	Matrice contenente i risultati della query.

Compilazione del corpo della richiesta di query

La richiesta di query deve essere un documento JSON valido contenente una proprietà query che include una stringa di query SQL e una proprietà parameters che include una matrice di parametri facoltativi. Ogni parametro deve avere una proprietà name e una proprietà value per i parametri specificati nella query. I nomi di parametri devono iniziare con il carattere “@”. I valori possono essere qualsiasi valore JSON valido come stringhe, interi, booleani e Null.

È valido specificare solo un subset di parametri specificati nel testo della query . Le espressioni che fanno riferimento a questi parametri non specificati restituiranno undefined. È anche possibile specificare parametri aggiuntivi che non vengono usati nel testo di query.

Di seguito sono illustrati alcuni esempi di richieste di query valide. Ad esempio, la query seguente ha un singolo parametro @id.

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

L'esempio seguente include due parametri, uno con un valore di stringa e un altro con un valore Integer.

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

L'esempio seguente usa i parametri in una clausola SELECT, oltre a una proprietà accessibile tramite il nome di parametro come parametro.

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

Query che non possono essere gestite dal gateway

Qualsiasi query che richiede lo stato tra le continuazioni non può essere gestita dal gateway. ad esempio:

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

Le query che possono essere gestite dal gateway includono:

• Proiezioni semplici
• Filtri

Quando viene restituita una risposta per una query che non può essere servita dal gateway, conterrà il codice di stato 400 (BadRequest) e il messaggio seguente:

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

Paginazione dei risultati della query

Le richieste di query supportano la paginazione tramite le intestazioni x-ms-max-item-count e x-ms-continuation request. L'intestazione x-ms-max-item-count specifica il numero massimo di valori che possono essere restituiti dall'esecuzione della query. Può essere un numero compreso tra 1 e 1000 ed è configurato con un valore predefinito pari a 100.

Dai risultati dell'esecuzione le query restituiranno un valore compreso tra zero e il valore massimo specificato per x-ms-max-item-count. Il risultato della query include un'intestazione x-ms-item-count che specifica il numero effettivo di documenti restituiti dalla query. Se sono presenti altri risultati recuperabili dalla query, la risposta includerà un valore non vuoto per l'intestazione x-ms-continuation.

I client sono in grado di recuperare pagine successive di risultati mediante la ripetizione dell'intestazione x-ms-continuation come altra richiesta. Per leggere i risultati, i client devono ripetere questo processo finché non verrà restituita un'intestazione x-ms-continuation vuota.

Le esecuzioni di query di Cosmos DB sono senza stato sul lato server e possono essere riprese in qualsiasi momento usando l'intestazione x-ms-continuation . Il valore x-ms-continuation usa l'ultimo ID risorsa del documento elaborato (_rid) per tenere traccia dello stato di esecuzione. Pertanto, se i documenti vengono eliminati e reinseriti tra il recupero di pagine, i documenti potrebbero essere potenzialmente esclusi da uno dei batch di query. È tuttavia possibile che il comportamento dell'intestazione x-ms-continuation venga modificato in un futuro aggiornamento del servizio.

Vedere anche

• Azure Cosmos DB
• API SQL Azure Cosmos DB
• SDK dell'API SQL di Azure Cosmos DB
• Esempio REST da .NET