Wykonywanie zapytań dotyczących zasobów usługi Azure Cosmos DB przy użyciu interfejsu API REST

Usługa Azure Cosmos DB to usługa globalnie dystrybuowanej, wielomodelowej bazy danych z obsługą wielu interfejsów API. W tym artykule opisano sposób używania interfejsu REST do wykonywania zapytań dotyczących zasobów przy użyciu interfejsu API SQL.

Jak mogę wykonywać zapytania dotyczące zasobu przy użyciu interfejsu REST?

Aby wykonać zapytanie SQL dla zasobu, wykonaj następujące czynności:

• Wykonaj metodę POST względem ścieżki zasobu przy użyciu formatu JSON z właściwością query ustawioną na ciąg zapytania SQL i właściwość "parameters" ustawioną na tablicę opcjonalnych wartości parametrów.
• x-ms-documentdb-isquery Ustaw nagłówek na True.
• Content-Type Ustaw nagłówek na application/query+json.

Aby zapoznać się z przykładem pokazującym, jak wykonać zapytanie SQL w zasobie przy użyciu platformy .NET, zobacz REST z przykładu platformy .NET.

Przykład

Poniżej przedstawiono przykładową operację zapytania REST dotyczącą zasobów dokumentów. W tym przykładzie chcemy znaleźć wszystkie dokumenty, które mają wartość "Don" jako autor.

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

Szczegóły żądania

Metoda	Identyfikator URI żądania
POST	Wymagane. Typ uwierzytelniania i token podpisu. Dla tej operacji jest dozwolony tylko token klucza głównego. Aby uzyskać więcej informacji, zobacz Access Control na temat zasobów usługi Cosmos DB.

Nagłówki żądań

Poniższa tabela zawiera typowe nagłówki używane do wykonywania operacji zapytań.

Nagłówek standardowy	Opis
Autoryzacja	Wymagane. Typ uwierzytelniania i token podpisu. Dla tej operacji jest dozwolony tylko token klucza głównego. Aby uzyskać więcej informacji, zobacz Access Control na temat zasobów usługi Cosmos DB.
Typ zawartości	Wymagane. Musi być ustawiona na wartość application/query+json.
Zaakceptowanie	Opcjonalnie. W tej chwili usługa Cosmos DB zawsze zwraca ładunek odpowiedzi w standardowym formacie JSON. Klient musi mieć możliwość akceptowania treści odpowiedzi w standardowym formacie JSON.
User-Agent	Opcjonalnie. Agent użytkownika wykonujący żądanie. Zalecany format to {nazwa agenta użytkownika}/{wersja}. Na przykład zestaw SDK platformy .NET interfejsu API SQL ustawia ciąg User-Agent na Wartość Microsoft.Document.Client/1.0.0.0.

Nagłówek niestandardowy	Opis
x-ms-date	Wymagane. Data żądania określona w RFC 1123. Format daty jest wyrażony na przykład w uniwersalnym czasie koordynowanym (UTC). Pt, 08 Kwi 2015 03:52:31 GMT.
x-ms-documentdb-isquery	Wymagane. Ta właściwość musi być ustawiona na wartość true.
x-ms-max-item-count	Opcjonalnie. Aby stronicować zestaw wyników, ustaw ten nagłówek na maksymalną liczbę elementów, które mają być zwracane z powrotem na jednej stronie.
x-ms-kontynuacja	Opcjonalnie. Aby przejść do następnej strony elementów, ustaw ten nagłówek na token kontynuacji dla następnej strony.
x-ms-version	Opcjonalnie. Wersja usługi REST usługi Cosmos DB. Najnowsza wersja jest używana, gdy nagłówek nie jest podany. Aby uzyskać więcej informacji, zobacz Dokumentacja interfejsu API REST usługi Azure Cosmos DB.
x-ms-documentdb-query-enable-scan	Opcjonalnie. Użyj skanowania indeksu, aby przetworzyć zapytanie, jeśli właściwa ścieżka indeksu typu jest niedostępna.
x-ms-session-token	Opcjonalnie. Token sesji dla żądania. Służy do spójności sesji.
x-ms-partition-key	Opcjonalnie. Jeśli zostanie określony, zapytanie jest wykonywane tylko w dokumentach, które pasują do wartości klucza partycji w nagłówku.
x-ms-documentdb-query-enablecrosspartition	Opcjonalnie. Musi być ustawiona wartość true dla wszystkich zapytań, które nie filtrują względem pojedynczego klucza partycji. Zapytania filtrujące względem pojedynczej wartości klucza partycji będą wykonywane tylko dla jednej partycji, nawet jeśli jest ona ustawiona na wartość true.
x-ms-documentdb-populatequerymetrics	Opcjonalnie. Aby zwracać metryki zapytań, należy ustawić wartość na True

Treść żądania

Treść żądania powinna być prawidłowym dokumentem JSON zawierającym zapytanie SQL i parametry. Jeśli dane wejściowe są źle sformułowane lub nieprawidłowa składnia SQL, operacja kończy się niepowodzeniem z błędem 400 Nieprawidłowe żądanie.

Otrzymasz również 400 złych żądań, jeśli nie można obsłużyć zapytania przez bramę.

Właściwość	Opis
query	Wymagane. Ciąg zapytania SQL dla zapytania. Aby uzyskać więcej informacji, zobacz Dokumentacja składni SQL usługi Azure Cosmos DB.
parameters	Wymagane. Tablica parametrów JSON określona jako pary wartości nazw. Tablica parametrów może zawierać od zera do wielu parametrów. Każdy parametr musi mieć następujące wartości:name: nazwę parametru. Nazwy parametrów muszą być prawidłowymi literałami ciągów i zaczynają się od znaku "@". wartość: wartość parametru. Może być dowolną prawidłową wartością JSON (ciąg, liczba, obiekt, tablica, wartość logiczna lub null).

Przykład żądania

Poniższy przykład tworzy sparametryzowane żądanie SQL z parametrem ciągu dla @authorelementu .

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

Aby uzyskać więcej informacji na temat zapytań SQL, zobacz Zapytania SQL dla usługi Azure Cosmos DB.

Szczegóły odpowiedzi

Poniżej przedstawiono typowe kody stanu zwracane przez tę operację. Aby uzyskać informacje o kodach stanu błędów, zobacz Kody stanu HTTP dla usługi Azure Cosmos DB.

Kod	Opis
200 OK	Operacja zakończyła się pomyślnie.
400 Nieprawidłowe żądanie	Składnia instrukcji SQL jest niepoprawna.
401 Brak autoryzacji	Nie ustawiono nagłówka Authorization lub x-ms-date . Błąd 401 jest również zwracany, gdy nagłówek autoryzacji jest ustawiony na nieprawidłowy token autoryzacji.
403 Zabronione	Token autoryzacji wygasł.
404 Nie znaleziono	Kolekcja nie jest już zasobem. Na przykład zasób mógł zostać usunięty.

Nagłówki odpowiedzi

Ta operacja zwraca następujące typowe nagłówki. Mogą być zwracane dodatkowe standardowe i typowe nagłówki.

Nagłówek standardowy	Opis
Typ zawartości	Typ zawartości to application/json. Usługa Cosmos DB zawsze zwraca treść odpowiedzi w standardowym formacie JSON.
Data	Data i godzina operacji odpowiedzi. Ten format daty/godziny jest zgodny z formatem godziny daty [RFC1123] wyrażonym w formacie UTC.

Nagłówek niestandardowy	Opis
x-ms-item-count	Liczba elementów zwróconych przez operację.
x-ms-continuation	Jest to nieprzezroczysty ciąg zwracany, gdy zapytanie ma potencjalnie więcej elementów do pobrania. Kontynuacja x-ms może być uwzględniona w kolejnych żądaniach jako nagłówek żądania w celu wznowienia wykonywania zapytania.
x-ms-request-charge	Jest to liczba jednostek żądania (RU) używanych przez operację. Aby uzyskać więcej informacji na temat jednostek żądań, zobacz Request Units in Azure Cosmos DB (Jednostki żądań w usłudze Azure Cosmos DB).
x-ms-activity-id	Jest to unikatowy identyfikator operacji. Może służyć do śledzenia wykonywania żądań usługi Cosmos DB.
x-ms-session-token	Token sesji, który ma być używany dla kolejnych żądań. Służy do spójności sesji.

Treść odpowiedzi

Treść odpowiedzi dla operacji zapytania składa się z _rid zasobu nadrzędnego zasobu, którego dotyczy zapytanie, oraz tablicy zasobów zawierającej właściwości zasobu dla projekcji i zaznaczenia. Jak pokazano na przykładzie, jeśli zapytanie zostało wykonane na ścieżce dokumentacji kolekcji z _rid XP0mAJ3H-AA=, odpowiedź będzie następująca:

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

Właściwość	Opis
_Rid	Identyfikator zasobu dla kolekcji używanej w zapytaniu.
_Liczba	Liczba zwróconych elementów.
Tablica zasobów	Tablica zawierająca wyniki zapytania.

Kompilowanie treści żądania zapytania

Żądanie zapytania musi być prawidłowym dokumentem JSON zawierającym właściwość zapytania zawierającą prawidłowy ciąg zapytania SQL i właściwość parameters zawierającą tablicę parametrów opcjonalnych. Każdy parametr powinien mieć właściwość name i value parametrów, które są określone w zapytaniu. Nazwy parametrów muszą zaczynać się od znaku "@". Wartości mogą być dowolnymi prawidłowymi wartościami JSON — ciągami, liczbami całkowitymi, wartościami logicznymi i wartościami null.

Prawidłowe jest określenie tylko podzestawu parametrów określonych w tekście zapytania . Wyrażenia odwołujące się do tych nieokreślonych parametrów będą obliczane jako niezdefiniowane. Prawidłowe jest również określenie dodatkowych parametrów, które nie są używane w tekście zapytania .

Poniżej przedstawiono kilka przykładów prawidłowych żądań zapytań. Na przykład następujące zapytanie ma jeden parametr @id.

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

Poniższy przykład zawiera dwa parametry: jeden z wartością ciągu, a drugi z wartością całkowitą.

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

W poniższym przykładzie użyto parametrów w klauzuli SELECT, a także właściwości dostępnej za pośrednictwem nazwy parametru jako parametru.

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

Kwerendy, których nie można obsłużyć przez bramę

Żadne zapytanie wymagające stanu między kontynuacjami nie może być obsługiwane przez bramę. Obejmuje to następujące działania:

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

Zapytania, które mogą być obsługiwane przez bramę, obejmują:

• Proste projekcje
• Filtry

Gdy zostanie zwrócona odpowiedź dla zapytania, którego nie można obsłużyć przez bramę, będzie ona zawierać kod stanu 400 (BadRequest) i następujący komunikat:

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

Stronicowanie wyników zapytania

Żądania zapytań obsługują stronicowanie za pośrednictwem nagłówków żądań x-ms-max-item-count i x-ms-continuation . Nagłówek x-ms-max-item-count określa maksymalną liczbę wartości, które mogą być zwracane przez wykonanie zapytania. Może to być od 1 do 1000 i jest skonfigurowane z wartością domyślną 100.

Zapytania będą zwracać od zera do maksymalnej określonej wartości x-ms-max-item-count z wyników wykonywania. Wynik zapytania zawiera nagłówek x-ms-item-count , który określa rzeczywistą liczbę dokumentów zwracanych przez zapytanie. Jeśli istnieją dodatkowe wyniki, które można pobrać z zapytania, odpowiedź zawiera niepustą wartość nagłówka x-ms-continuation .

Klienci mogą pobierać kolejne strony wyników, powtarzając nagłówek x-ms-continuation jako kolejne żądanie. Aby odczytać wszystkie wyniki, klienci muszą powtórzyć ten proces, dopóki nie zostanie zwrócona pusta kontynuacja x-ms .

Wykonania zapytań usługi Cosmos DB są bezstanowe po stronie serwera i można je wznowić w dowolnym momencie przy użyciu nagłówka x-ms-continuation . Wartość x-ms-continuation używa ostatnio przetworzonego identyfikatora zasobu dokumentu (_rid) do śledzenia postępu wykonywania. W związku z tym, jeśli dokumenty zostaną usunięte i ponownie wstawione między pobieraniem stron, dokumenty mogą być potencjalnie wykluczone z dowolnych partii zapytań. Jednak zachowanie i format nagłówka x-ms-continuation mogą ulec zmianie w przyszłej aktualizacji usługi.

Zobacz też

• Azure Cosmos DB
• Azure Cosmos DB — interfejs SQL API
• Zestawy SDK interfejsu API SQL usługi Azure Cosmos DB
• Przykład REST z platformy .NET