Распространенные заголовки запросов REST для Azure Cosmos DB
Следующие заголовки запросов являются общими для всех задач, которые можно выполнять с помощью API SQL:
| Заголовок | Обязательно | Тип | Описание |
|---|---|---|---|
| Авторизация | Обязательно | Строка | Маркер авторизации для запроса. Дополнительные сведения о создании допустимого маркера авторизации см. в разделе контроль доступа ресурсов Cosmos DB. |
| Content-Type | Обязательный (для PUT, PATCH и POST) | Строка | Для операций запроса POST это должно быть application/query+json. Для операций PATCH это должно быть application/json_patch+json. Для вложений необходимо задать тип Mime вложения. Дополнительные сведения о типах Mime см. в разделе Создание вложения. Для всех остальных задач должен иметь значение application/json. |
| If-Match | Необязательный (применяется только для PUT и DELETE) | Строка | Используется, чтобы сделать операцию условной для оптимистичного параллелизма. Значение должно быть значением etag ресурса. |
| If-None-Match | Необязательный (применяется только в GET) | Строка | Делает операцию условной для выполнения только в том случае, если ресурс был изменен. Значение должно быть etag ресурса. |
| If-Modified-Since | Необязательный (применяется только в GET) | Дата | Возвращает etag ресурса, измененного после указанной даты в формате RFC 1123. Игнорируется при указании параметра If-None-Match |
| User-Agent | Необязательно | Строка | Строка, указывающая агент пользователя клиента, выполняющий запрос. Рекомендуемый формат: {имя агента пользователя}/{версия}. Например, официальный пакет SDK API SQL для .NET задает строку User-Agent Microsoft.Document.Client/1.0.0.0. Настраиваемый агент пользователя может быть чем-то вроде ContosoMarketingApp/1.0.0. |
| x-ms-activity-id | Необязательно | Строка | Предоставленный клиентом идентификатор для операции, который повторяется в ответе сервера. Рекомендуемое значение — уникальный идентификатор. |
| x-ms-consistency-level | Необязательно | Строка | Уровень согласованности переопределяется для параметров чтения документов и вложений. Допустимые значения: Strong, Bounded, Session или Eventual (в порядке от сильного к самому слабому). Переопределение должно быть таким же или слабым, чем настроенный для учетной записи уровень согласованности. |
| x-ms-continuation | Необязательно | Строка | Строковый маркер, возвращаемый для запросов и операций чтения и веб-канала, если есть дополнительные результаты для чтения. Клиенты могут получить следующую страницу результатов, повторно отдав запрос с заголовком запроса x-ms-continuation, для которого задано это значение. |
| x-ms-date | Обязательно | Дата | Дата запроса в формате даты RFC 1123, выраженная в формате универсального координированного времени, например Пт, 8 Апреля 2015 03:52:31 GMT. |
| x-ms-max-item-count | Необязательно | Число | Целое число, указывающее максимальное количество возвращаемых элементов на страницу. Можно указать значение x-ms-max-item-count со значением -1, чтобы служба определяла оптимальное число элементов. Это рекомендуемое значение конфигурации для x-ms-max-item-count |
| x-ms-documentdb-partitionkey | Необязательно | Array | Значение ключа секции для запрошенной операции документа или вложения. Требуется для операций с документами и вложениями, если определение коллекции включает определение ключа секции. Это значение используется для область запроса к документам, которые соответствуют критериям ключа секции. По умолчанию это запрос к одной секции. Поддерживается в API версии 2015-12-16 и более поздних версий. В настоящее время API SQL поддерживает один ключ секции, поэтому это массив, содержащий только одно значение. |
| x-ms-documentdb-query-enablecrosspartition | Необязательно | Логическое | Если для этого заголовка задано значение true и если в запросе нет ключа секции, Azure Cosmos DB распределяет запрос между секциями. При таком распространении отдельные запросы направляются по всем секциям. Чтобы считать результаты запроса, клиентские приложения должны получить результаты из FeedResponse и проверить свойство ContinuationToken. Чтобы считывать все результаты, выполняйте итерацию данных, пока ContinuationToken не будет иметь значение null. |
| x-ms-session-token | Обязательный (только для согласованности сеанса) | Строка | Строковый токен, используемый для согласованности на уровне сеанса. Дополнительные сведения см. в разделе Использование уровней согласованности в Cosmos DB |
| x-ms-version | Обязательно | Строка | Версия службы REST Cosmos DB. Список поддерживаемых версий API см. в справочнике по REST API Azure Cosmos DB. |
| A-IM | Необязательно | Строка | Указывает запрос канала изменений . Должно быть задано значение "Добавочный веб-канал" или пропущено в противном случае. |
| x-ms-documentdb-partitionkeyrangeid | Необязательно | Число | Используется в запросах канала изменений . Идентификатор диапазона ключей разделов для считывания данных. |
| x-ms-cosmos-allow-tentative-writes | Необязательно | Логическое | Если этот заголовок имеет значение true для учетных записей Azure Cosmos, настроенных с несколькими расположениями записи, Azure Cosmos DB разрешит запись во все расположения. Запросы на запись со значением этого заголовка, равным false (или если заголовок отсутствует), завершатся ошибкой с кодом состояния ответа 403 с сообщением об ошибке "Операции записи в регионе запрещены". |
См. также: