Запрос ресурсов Azure Cosmos DB с помощью REST API

Azure Cosmos DB — это глобально распределенная многомодельная база данных с поддержкой разных API. В этой статье описывается использование REST для запроса ресурсов с помощью API SQL.

Как выполнить запрос ресурса с помощью REST?

Чтобы выполнить запрос SQL на ресурс, выполните следующие действия.

• POST Выполните метод для пути к ресурсу, используя JSON с свойством query , для свойства задана строка SQL-запроса, а для свойства "parameters" задан массив значений необязательных параметров.
• В качестве заголовка x-ms-documentdb-isquery установите True.
• В качестве заголовка Content-Type установите application/query+json.

Пример выполнения SQL-запроса к ресурсу с помощью .NET см. в разделе Пример REST из .NET.

Пример

Ниже приведен пример операции запроса REST с ресурсами документа. В этом примере нужно найти все документы, автором которых является "Don".

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

Сведения о запросе

Заголовки запросов

В следующей таблице приведены общие заголовки, используемые для выполнения операций запроса.

Текст запроса

Текст запроса должен являться допустимым документом JSON, содержащим SQL-запрос и параметры. Если входное значение неверно сформировано или при недопустимом синтаксисе SQL происходит сбой операции с ошибкой 400 (неверный запрос).

Вы также получите 400 неверный запрос, если запрос не может быть обработан шлюзом.

Пример запроса

В следующем примере выполняется параметризованный SQL-запрос со строковым параметром для @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"}  
    ]  
}  

Дополнительные сведения о запросах SQL см. в статье SQL-запросы для Azure Cosmos DB.

Сведения об ответах

Ниже приведены типичные коды состояния, возвращаемые этой операцией. Сведения о кодах состояния ошибок см. в статье Коды состояния HTTP для Azure Cosmos DB.

Заголовки откликов

Эта операция возвращает следующие общие заголовки. Кроме того, могут быть возвращены дополнительные стандартные и общие заголовки.

Текст ответа

Текст ответа для операции запроса состоит из _rid родительского ресурса запрашиваемого ресурса и массива ресурсов, содержащего свойства ресурса для выбора и проекции. Согласно примеру, если запрос выполняется по пути к коллекции docs со свойством _rid, имеющим значение XP0mAJ3H-AA=, ответ будет выглядеть следующим образом:

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

Построение текста запроса

Запрос должен представлять собой допустимый документ JSON, включающий в себя свойство query, которое содержит допустимый SQL-запрос, и свойство parameters, содержащее массив необязательных параметров. Каждый параметр должен иметь свойства name и value для параметров, указанных в запросе. Имена параметров должны начинаться с символа "@". Значения могут быть любыми допустимыми значениями JSON: строками, целыми числами, логическими значениями и значениями null.

Допустимо указывать только подмножество параметров, указанных в тексте запроса . Выражения, ссылающиеся на эти не заданные параметры, приведут к получению результата undefined. Можно также указать дополнительные параметры, которые не используются в тексте query.

Ниже приведены некоторые примеры допустимых запросов. Например, следующий запрос имеет один параметр @id.

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

В следующем примере имеется два параметра, один со строковым значением, а другой — с целочисленным значением.

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

В следующем примере доступ к параметрам в предложении SELECT, а также к свойствам осуществляется через имя параметра в качестве параметра.

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

Запросы, которые не могут быть обработаны шлюзом

Любой запрос, требующий состояния в продолжениях, не может обслуживаться шлюзом. В том числе:

• В начало
• ORDER BY
• OFFSET LIMIT
• Статистические выражения
• DISTINCT
• GROUP BY

Ниже приведены запросы, которые могут обслуживаться шлюзом.

• Простые проекции
• Фильтры

При возврате ответа для запроса, который не может быть обработан шлюзом, он будет содержать код состояния 400 (BadRequest) и следующее сообщение:

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

Разбиение на страницы результатов запроса

Запросы поддерживают разбиение на страницы с помощью заголовков x-ms-max-item-count и x-ms-continuation request. Заголовок x-ms-max-item-count указывает максимальное количество значений, которые могут быть возвращены при выполнении запроса. Оно может иметь значение от 1 до 1000, по умолчанию — 100.

Запросы будут возвращать от нуля до указанного в x-ms-max-item-count максимального количества значений из результатов выполнения. Результат запроса содержит заголовок x-ms-item-count, который задает фактическое количество документов, возвращенных запросом. Если имеются дополнительные результаты, которые могут быть получены из запроса, то в ответ включается непустое значение для заголовка x-ms-continuation.

Клиенты могут извлекать последующие страницы с результатами, возвращая заголовок x-ms-continuation в качестве следующего запроса. Для считывания всех результатов клиентам необходимо повторять этот процесс до возвращения пустого заголовка x-ms-continuation.

Выполнение запросов Cosmos DB выполняется без отслеживания состояния на стороне сервера и может быть возобновлено в любое время с помощью заголовка x-ms-continuation . Значение x-ms-continuation использует идентификатор ресурса последнего обработанного документа (_rid) для отслеживания процесса выполнения. Поэтому при удалении и повторной вставке документов между получением страниц документы могут быть исключены из любого пакета запроса. Тем не менее поведение и формат заголовка x-ms-continuation могут измениться в будущих версиях.

См. также:

• Azure Cosmos DB
• API SQL для Azure Cosmos DB
• Пакеты SDK ДЛЯ API SQL для Azure Cosmos DB
• Пример REST из .NET