Wykonywanie zapytań o dokumenty
W kolekcji można wykonywać zapytania dotyczące dowolnych dokumentów JSON, wykonując wpis względem zasobu "colls" w usłudze Cosmos DB. Składnia sql usługi Cosmos DB udostępnia operatory zapytań hierarchicznych, relacyjnych i przestrzennych do wykonywania zapytań i dokumentów projektu. Aby uzyskać więcej informacji na temat wykonywania zapytań dotyczących zasobów w usłudze Cosmos DB, zobacz wykonywanie zapytań dotyczących zasobów.
Żądanie
| Metoda | Identyfikator URI żądania | Opis |
|---|---|---|
| Post | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs | Pamiętaj, że {databaseaccount} jest nazwą konta usługi Cosmos DB utworzonego w ramach subskrypcji. wartość {db-id} to wygenerowana przez użytkownika nazwa/identyfikator bazy danych, a nie identyfikator wygenerowany przez system (rid). wartość {coll-id} jest nazwą kolekcji. |
Nagłówki
Zobacz Typowe nagłówki żądań REST usługi Azure Cosmos DB dla nagłówków , które są używane przez wszystkie żądania usługi Cosmos DB.
| Nagłówek | Wymagany | Typ | Opis |
|---|---|---|---|
| x-ms-documentdb-isquery | Wymagane | Wartość logiczna | Musi mieć ustawioną wartość True wskazującą, że post jest zapytaniem. |
| Typ zawartości | Wymagane | Ciąg | Ciąg, który musi być ustawiony na wartość application/query+json. |
| x-ms-max-item-count | Opcjonalne | Liczba | Liczba całkowita wskazująca maksymalną liczbę elementów do zwrócenia na stronę. Zapytania będą zwracać nie więcej niż określoną liczbę elementów na stronę, ale mogą być mniejsze w zależności od warstwy wydajności kolekcji i ich rozmiarów. Można określić wartość x-ms-max-item-count z -1, aby umożliwić usłudze określenie optymalnej liczby elementów. Jest to zalecana wartość konfiguracji dla x-ms-max-item-count. |
| x-ms-continuation | Opcjonalne | Ciąg | Token ciągu zwracany dla zapytań i operacji źródła danych odczytu, jeśli jest więcej wyników do odczytania. Klienci mogą pobrać następną stronę wyników, ponownie przesyłając żądanie z nagłówkiem żądania x-ms-continuation ustawionym na tę wartość. |
| x-ms-documentdb-query-enablecrosspartition | Opcjonalne | Wartość logiczna | Jeśli kolekcja jest podzielona na partycje, musi to być ustawione na wartość True, aby zezwolić na wykonywanie w wielu partycjach. Zapytania filtrujące względem pojedynczego klucza partycji lub kolekcji z jedną partycją nie muszą ustawiać nagłówka. |
| x-ms-consistency-level | Opcjonalne | Ciąg | Jest to przesłonięcia na poziomie spójności. Prawidłowe wartości to: Silna, Powiązana, Sesja lub Ostateczna (w kolejności od najsilniejszych do najsłabszych). Przesłonięcia muszą być takie same lub słabsze niż skonfigurowany poziom spójności konta. |
| x-ms-session-token | Opcjonalne | Ciąg | Token ciągu używany ze spójnością na poziomie sesji. Klienci muszą powtórzyć najnowszą wartość odczytu tego nagłówka podczas żądań odczytu w celu zapewnienia spójności sesji. |
Ważne
Dla nagłówka Content-Type NIE dołączaj zestawu znaków (tj. "application/query+json; charset-utf-8"). Nagłówek musi być dokładnie taki, jak pokazano powyżej.
Treść
| Właściwość | Wymagany | Typ | Opis |
|---|---|---|---|
| Kwerendy | Wymagane | Ciąg | Zawiera tekst zapytania SQL. Aby uzyskać informacje na temat gramatyki, zobacz Gramatyka SQL. |
| parameters | Wymagane | Tablica | Tablica wartości parametrów dla zapytania. |
{
"query": "SELECT * FROM Families f WHERE f.id = @id AND f.Address.City = @city",
"parameters": [
{
"name": "@id",
"value": "AndersenFamily"
},
{
"name": "@city",
"value": "Seattle"
}
]
}
Reakcja
Zwraca tablicę dokumentów pasujących do żądanego zapytania.
Nagłówki
Zobacz Typowe nagłówki odpowiedzi REST usługi Azure Cosmos DB dla nagłówków zwracanych przez wszystkie odpowiedzi usługi Cosmos DB. Ważne nagłówki odpowiedzi to:
| Właściwość | Typ | Opis |
|---|---|---|
| x-ms-continuation | Ciąg | Zwraca token, aby pobrać więcej wyników z operacji. Klient może ponownie przesłać żądanie za pomocą nagłówka żądania x-ms-continuation zawierającego tę wartość, aby wznowić wykonywanie. |
| x-ms-request-charge | Liczba | Liczba jednostek żądań używanych przez operację. |
Kody stanu
W poniższej tabeli wymieniono typowe kody stanu zwracane przez tę operację. Aby uzyskać pełną listę kodów stanu, zobacz Kody stanu HTTP.
| Kod stanu HTTP | Opis |
|---|---|
| 200 OK | Operacja zakończyła się pomyślnie. |
| 400 Nieprawidłowe żądanie | Określone żądanie zostało określone z nieprawidłową składnią SQL lub brakuje wymaganych nagłówków. |
Treść
| Właściwość | Opis |
|---|---|
| _Rid | Jest to system wygenerowany identyfikator zasobu dla kolekcji, w której znajdują się dokumenty. |
| _Liczba | Jest to liczba dokumentów zwracanych przez operację listy. |
| Dokumenty | Tablica dokumentów zwróconych przez operację. |
Właściwości dokumentu
| Właściwość | Opis |
|---|---|
| id | Jest to unikatowa nazwa, która identyfikuje dokument, tj. żadne dwa dokumenty nie mogą współdzielić tego samego identyfikatora. Identyfikator nie może przekraczać 255 znaków. |
| <custom> | Dowolny kod JSON zdefiniowany przez użytkownika. |
| _Rid | Jest to właściwość wygenerowana przez system. Identyfikator zasobu (_rid) to unikatowy identyfikator, który jest również hierarchiczny dla stosu zasobów w modelu zasobów. Jest on używany wewnętrznie do umieszczania zasobu dokumentu i nawigacji po nim. |
| _Ts | Jest to właściwość wygenerowana przez system. Określa ostatni zaktualizowany znacznik czasu zasobu. Wartość jest znacznikiem czasu. |
| _Własny | Jest to właściwość wygenerowana przez system. Jest to unikatowy adresowy identyfikator URI zasobu. |
| _Etag | Jest to właściwość wygenerowana przez system, która określa tag zasobu wymagany do optymistycznej kontroli współbieżności. |
| _Załączniki | Jest to właściwość wygenerowana przez system, która określa ścieżkę adresową zasobu załączników. |
{
"_rid": "1KtjAImkcgw=",
"Documents": [
{
"id": "AndersenFamily",
"LastName": "Andersen",
"Parents": [
{
"FamilyName": null,
"FirstName": "Thomas"
},
{
"FamilyName": null,
"FirstName": "Mary Kay"
}
],
"Children": [
{
"FamilyName": null,
"FirstName": "Henriette Thaulow",
"Gender": "female",
"Grade": 5,
"Pets": [
{
"GivenName": "Fluffy"
}
]
}
],
"Address": {
"State": "WA",
"County": "King",
"City": "Seattle"
},
"IsRegistered": true,
"_rid": "1KtjAImkcgwBAAAAAAAAAA==",
"_self": "dbs/1KtjAA==/colls/1KtjAImkcgw=/docs/1KtjAImkcgwBAAAAAAAAAA==/",
"_etag": "\"00003200-0000-0000-0000-56f9e84d0000\"",
"_ts": 1459218509,
"_attachments": "attachments/"
}
],
"_count": 1
}
Przykład
POST https://querydemo.documents.azure.com/dbs/1KtjAA==/colls/1KtjAImkcgw=/docs HTTP/1.1
x-ms-continuation:
x-ms-documentdb-isquery: True
x-ms-documentdb-query-enablecrosspartition: True
x-ms-date: Tue, 29 Mar 2016 02:28:32 GMT
authorization: type%3dmaster%26ver%3d1.0%26sig%3drOlOhFh9plfC0ggZfmHtS3XepVitiIRsd6i1d9PnuW8%3d
Cache-Control: no-cache
User-Agent: Microsoft.Azure.Documents.Client/1.6.0.0
x-ms-version: 2015-12-16
Accept: application/json
Content-Type: application/query+json
Host: querydemo.documents.azure.com
Cookie: x-ms-session-token#0=604; x-ms-session-token=604
Content-Length: 170
Expect: 100-continue
{
"query": "SELECT * FROM Families f WHERE f.id = @id AND f.Address.City = @city",
"parameters": [
{
"name": "@id",
"value": "AndersenFamily"
},
{
"name": "@city",
"value": "Seattle"
}
]
}
HTTP/1.1 201 Created
Cache-Control: no-store, no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Content-Type: application/json
Server: Microsoft-HTTPAPI/2.0
Strict-Transport-Security: max-age=31536000
x-ms-last-state-change-utc: Fri, 25 Mar 2016 22:39:02.501 GMT
etag: "00003200-0000-0000-0000-56f9e84d0000"
x-ms-resource-quota: documentSize=10240;documentsSize=10485760;collectionSize=10485760;
x-ms-resource-usage: documentSize=0;documentsSize=1;collectionSize=1;
x-ms-schemaversion: 1.1
x-ms-alt-content-path: dbs/testdb/colls/testcoll
x-ms-quorum-acked-lsn: 602
x-ms-current-write-quorum: 3
x-ms-current-replica-set-size: 4
x-ms-request-charge: 12.38
x-ms-serviceversion: version=1.6.52.5
x-ms-activity-id: 856acd38-320d-47df-ab6f-9761bb987668
x-ms-session-token: 0:603
Set-Cookie: x-ms-session-token#0=603; Domain=querydemo.documents.azure.com; Path=/dbs/1KtjAA==/colls/1KtjAImkcgw=
Set-Cookie: x-ms-session-token=603; Domain=querydemo.documents.azure.com; Path=/dbs/1KtjAA==/colls/1KtjAImkcgw=
x-ms-gatewayversion: version=1.6.52.5
Date: Tue, 29 Mar 2016 02:28:30 GMT
{
"id": "AndersenFamily",
"LastName": "Andersen",
"Parents": [
{
"FamilyName": null,
"FirstName": "Thomas"
},
{
"FamilyName": null,
"FirstName": "Mary Kay"
}
],
"Children": [
{
"FamilyName": null,
"FirstName": "Henriette Thaulow",
"Gender": "female",
"Grade": 5,
"Pets": [
{
"GivenName": "Fluffy"
}
]
}
],
"Address": {
"State": "WA",
"County": "King",
"City": "Seattle"
},
"IsRegistered": true,
"_rid": "1KtjAImkcgwBAAAAAAAAAA==",
"_self": "dbs/1KtjAA==/colls/1KtjAImkcgw=/docs/1KtjAImkcgwBAAAAAAAAAA==/",
"_etag": "\"00003200-0000-0000-0000-56f9e84d0000\"",
"_ts": 1459218509,
"_attachments": "attachments/"
}