Создание коллекции
Операция Create Collection создает новую коллекцию в базе данных.
Примечание
В этих справочных статьях по API показано, как создавать ресурсы с помощью API плоскости данных Azure Cosmos DB. С помощью API плоскости данных можно настроить базовые параметры, такие как политика индексирования, ключи секций, так же, как в пакетах SDK для Cosmos DB. Если вам требуется полная поддержка функций для всех ресурсов Azure Cosmos DB, рекомендуется использовать поставщик ресурсов Cosmos DB.
Запрос
| Метод | Универсальный код ресурса (URI) запроса | Описание |
|---|---|---|
| POST | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls | {databaseaccount} — это имя учетной записи Azure Cosmos DB, созданной в вашей подписке. {db-id} может быть идентификатором или значением _rid для базы данных. |
Заголовки
Заголовки, используемые всеми запросами Azure Cosmos DB, см. в статье Общие заголовки запросов REST Azure Cosmos DB .
При создании хэш-подписи для маркера ключа master параметр ResourceType должен иметь значение colls. ResourceId должен иметь значение dbs/{db-id}, где {db-id} может быть идентификатором или значением _rid базы данных.
| Свойство | Обязательно | Тип | Описание |
|---|---|---|---|
| Пропускная способность x-ms-offer-throughput | Необязательно | Число | Пользователь указал пропускную способность вручную (ЕЗ/с) для коллекции, выраженной в единицах 100 единиц запросов в секунду. Минимальное значение — от 400 до 1 000 000 (или выше при запросе увеличения лимита). Необходимо указать только один из x-ms-offer-throughput или x-ms-cosmos-offer-autopilot-settings . Эти заголовки нельзя указать вместе. |
| x-ms-cosmos-offer-autopilot-settings | Необязательно | JSON | Пользователь указал максимальное значение ЕЗ/с автомасштабирования. Значением является JSON со свойством maxThroughput. Например: {"maxThroughput": 4000}.Необходимо указать только один из x-ms-offer-throughput или x-ms-cosmos-offer-autopilot-settings . Эти заголовки нельзя указать вместе. При использовании автомасштабирования требуется определение partitionKey . |
| x-ms-offer-type | Необязательно | Строка | Это устаревший заголовок для предварительно определенных уровней производительности S1, S2 и S3, которые были выведены из эксплуатации. Рекомендуется использовать пропускную способность вручную или автомасштабирование, как описано выше. |
Текст
| Свойство | Обязательно | Тип | Описание |
|---|---|---|---|
| идентификатор | Обязательно | Строка | Созданное пользователем уникальное имя коллекции. Две коллекции не могут иметь одинаковые идентификаторы. Это строка, которая не должна содержать более 255 символов. |
| indexingPolicy | Необязательно | Объект | Это значение используется для настройки политики индексирования. По умолчанию индексирование выполняется автоматически для всех путей к документу в пределах коллекции. |
| partitionKey | Обязательно | Объект | Это значение используется для настройки ключа секции, который будет использоваться для секционирования данных на несколько секций. Чтобы использовать большой ключ секции, укажите версию как 2 в свойстве partitionKey. Если REST API версии 2018-12-31 или выше, коллекция должна содержать определение partitionKey . В версиях старше 2018-12-31 можно создать устаревшую несекционированную коллекцию с пропускной способностью вручную, опустив определение partitionKey и обеспечив пропускную способность в диапазоне от 400 до 10 000 ЕЗ/с. Для оптимальной производительности и масштабируемости рекомендуется всегда задавать ключ секции. Узнайте, как выбрать подходящий ключ секции. |
Пример полезных данных текста
{
"id": "testcoll",
"indexingPolicy": {
"automatic": true,
"indexingMode": "Consistent",
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "String",
"precision": -1,
"kind": "Range"
}
]
}
]
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash",
"Version": 2
}
}
Ответ
Create Collection возвращает созданную коллекцию в виде текста ответа.
Заголовки
Заголовки, возвращаемые всеми ответами Azure Cosmos DB, см. в статье Общие заголовки ответов REST Azure Cosmos DB .
Коды состояния
В таблице ниже указаны стандартные коды состояния, возвращаемые этой операцией. Полный список кодов состояния см. в разделе Коды состояния HTTP.
| Код состояния HTTP | Описание |
|---|---|
| 201 Создано | Операция выполнена успешно. |
| 400 — недопустимый запрос | Недопустимый текст JSON. Проверьте наличие фигурных скобок и кавычек. |
| 409. Конфликт | Идентификатор, предоставленный для новой коллекции, был взят существующей коллекцией. |
| 404 с кодом дочернего состояния 1013 | Операция создания коллекции все еще выполняется. |
Если при создании коллекции возникает исключение времени ожидания, выполните операцию чтения, чтобы проверить, успешно ли создана коллекция. Операция чтения создает исключение до тех пор, пока операция создания коллекции не будет выполнена успешно. Если операция чтения создает исключение с кодом состояния 404 и кодом вложенного состояния 1013, это означает, что операция создания коллекции все еще выполняется. Повторяйте операцию чтения, пока не получите коды состояния 200 или 201. Эти коды позволяют узнать, что коллекция успешно создана.
Текст
| Свойство | Описание |
|---|---|
| идентификатор | Это уникальное имя, которое идентифицирует новую коллекцию. |
| _rid | Это свойство, созданное системой. Идентификатор ресурса (_rid) — это уникальный идентификатор, который также является иерархическим для стека ресурсов в модели ресурсов. Он используется системой для размещения и перемещения по ресурсам разрешения. |
| _Ts | Это свойство, созданное системой. Оно представляет метку времени последнего обновления ресурса. Значение — метка времени. |
| _Самостоятельно | Это свойство, созданное системой. Это уникальный адресуемый URI для ресурса. |
| _etag | Это созданное системой свойство, представляющее тег ресурса, необходимый для управления оптимистическим параллелизмом. |
| _Док | Это созданное системой свойство, указывающее адресуемый путь к ресурсу документов. |
| _sprocs | Это созданное системой свойство, указывающее адресный путь к ресурсу хранимых процедур (sprocs). |
| _Триггеры | Это сгенерируемое системой свойство, указывающее адресуемый путь к ресурсу триггеров. |
| _udfs | Это сгенерируемое системой свойство, указывающее адресуемый путь к ресурсу определяемых пользователем функций (UDFS). |
| _Конфликтов | Это созданное системой свойство, указывающее адресуемый путь ресурса конфликтов. Если во время выполнения операции с ресурсом в коллекции возникает конфликт, пользователи могут проверить конфликтующие ресурсы с помощью операции GET для пути URI конфликтов. |
| indexingPolicy | Это параметры политики индексирования для коллекции. |
| partitionKey | Это параметры конфигурации секционирования для коллекции. |
Свойства в разделе Включенные пути
| Свойство | Описание |
|---|---|
| путь | Путь, к которому применяется поведение индексирования. Пути к индексу начинаются с корневого (/) и обычно заканчиваются подстановочным оператором вопросительного знака (?), обозначая наличие нескольких возможных значений префикса. Например, чтобы обслуживать запрос SELECT * FROM Families F WHERE F.familyName = "Andersen", вам нужно включить путь индекса для /familyName/? в политике индекса коллекции. В путях индекса можно также использовать оператор подстановочного знака * для задания алгоритма пути рекурсивно по префиксу. Например, /payload/* можно использовать для исключения из индексации всего, что находится по свойству payload. |
| dataType | Это тип данных, к которому применяется поведение индексирования. Может иметь значение String, Number, Point, Polygon или LineString. Логические значения и значения NULL индексируются автоматически. |
| kind | Тип индекса. Хэш-индексы полезны для сравнения на равенство, а индексы range — для равенства, сравнения диапазонов и сортировки. Пространственные индексы полезны для пространственных запросов. |
| precision | Точность индекса. Можно задать значение -1 для максимальной точности или от 1 до 8 для числа и 1–100 для строки. Неприменимо для типов данных Point, Polygon и LineString . |
Свойства в разделе Исключенные пути
| Свойство | Описание |
|---|---|
| путь | Путь, исключенный из индексирования. Пути к индексу начинаются с корня (/) и обычно заканчиваются подстановочным оператором *. Например, /payload/* можно использовать для исключения из индексации всего, что находится по свойству payload. |
Свойства в разделе "Ключ секции"
| Свойство | Описание |
|---|---|
| paths | Массив путей, по которым можно секционировать данные в коллекции. Пути не должны содержать подстановочный знак или косую черту в конце. Например, свойство JSON AccountNumber указывается как /AccountNumber. Массив должен содержать только одно значение. |
| kind | Алгоритм, используемый для секционирования. Поддерживается только хэш. |
| version | Необязательное поле, если оно не указано, значение по умолчанию — 1. Чтобы использовать большой ключ секции, задайте для версии значение 2. Чтобы узнать больше о ключах секций, см. статью о создании коллекций с помощью ключа большой секции . |
Пример текста ответа
{
"id": "testcoll",
"indexingPolicy": {
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"kind": "Range",
"dataType": "String",
"precision": -1
},
{
"kind": "Range",
"dataType": "Number",
"precision": -1
}
]
}
],
"excludedPaths": []
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash",
"Version": 2
},
"_rid": "PD5DALigDgw=",
"_ts": 1459200611,
"_self": "dbs/PD5DAA==/colls/PD5DALigDgw=/",
"_etag": "\"00005900-0000-0000-0000-56f9a2630000\"",
"_docs": "docs/",
"_sprocs": "sprocs/",
"_triggers": "triggers/",
"_udfs": "udfs/",
"_conflicts": "conflicts/"
}
Пример 1
В следующем примере создается коллекция с пропускной способностью 400 ЕЗ/с вручную.
x-ms-offer-throughput Заголовок используется для задания значения пропускной способности (ЕЗ/с). Он принимает число с минимальным значением 400, которое увеличивается на единицы 100.
POST https://querydemo.documents.azure.com/dbs/testdb/colls HTTP/1.1
x-ms-offer-throughput: 400
x-ms.date: 04/20/2021
authorization: type%3dmaster%26ver%3d1.0%26sig%3dpDOKhfllik0BJijp5apzqHL%2bjtoFhsvdhAGE5F8%2bOiE%3d
Cache-Control: no-cache
User-Agent: contoso/1.0
x-ms-version: 2015-12-16
Accept: application/json
Host: querydemo.documents.azure.com
Content-Length: 235
Expect: 100-continue
{
"id": "testcoll",
"indexingPolicy": {
"automatic": true,
"indexingMode": "Consistent",
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "String",
"precision": -1,
"kind": "Range"
}
]
}
]
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash",
"Version": 2
}
}
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: Mon, 28 Mar 2016 20:00:12.142 GMT
etag: "00005900-0000-0000-0000-56f9a2630000"
collection-partition-index: 0
collection-service-index: 24
x-ms-schemaversion: 1.1
x-ms-alt-content-path: dbs/testdb
x-ms-quorum-acked-lsn: 9
x-ms-current-write-quorum: 3
x-ms-current-replica-set-size: 4
x-ms-request-charge: 4.95
x-ms-serviceversion: version=1.6.52.5
x-ms-activity-id: 05d0a3b5-4504-446a-96f4-bef3a3408595
x-ms-session-token: 0:10
Set-Cookie: x-ms-session-token#0=10; Domain=querydemo.documents.azure.com; Path=/dbs/PD5DAA==/colls/PD5DALigDgw=
Set-Cookie: x-ms-session-token=10; Domain=querydemo.documents.azure.com; Path=/dbs/PD5DAA==/colls/PD5DALigDgw=
x-ms-gatewayversion: version=1.6.52.5
Date: Mon, 28 Mar 2016 21:30:12 GMT
{
"id": "testcoll",
"indexingPolicy": {
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"kind": "Range",
"dataType": "String",
"precision": -1
},
{
"kind": "Range",
"dataType": "Number",
"precision": -1
}
]
}
],
"excludedPaths": []
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash"
},
"_rid": "PD5DALigDgw=",
"_ts": 1459200611,
"_self": "dbs/PD5DAA==/colls/PD5DALigDgw=/",
"_etag": "\"00005900-0000-0000-0000-56f9a2630000\"",
"_docs": "docs/",
"_sprocs": "sprocs/",
"_triggers": "triggers/",
"_udfs": "udfs/",
"_conflicts": "conflicts/"
}
Пример 2
В следующем примере создается коллекция с максимальной пропускной способностью автомасштабирования 4000 ЕЗ/с (она масштабируется от 400 до 4000 ЕЗ/с).
x-ms-cosmos-offer-autopilot-settings Заголовок используется для задания maxThroughput значения, которое является значением автомасштабирования максимального количества единиц запросов в секунду. Он принимает число не менее 4000, которое увеличивается на единицы 1000. При использовании автомасштабирования требуется определение ключа секции, как показано в следующем примере:
Примечание
Чтобы включить автомасштабирование в существующей базе данных или коллекции или переключиться с автомасштабирования на пропускную способность вручную, см. статью Замена предложения.
POST https://querydemo.documents.azure.com/dbs/testdb/colls HTTP/1.1
x-ms-cosmos-offer-autopilot-settings: {"maxThroughput": 4000}
x-ms-date: Wed, 22 Jul 2020 22:17:39 GMT
authorization: type%3dmaster%26ver%3d1.0%26sig%3dpDOKhfllik0BJijp5apzqHL%2bjtoFhsvdhAGE5F8%2bOiE%3d
Cache-Control: no-cache
User-Agent: contoso/1.0
x-ms-version: 2018-12-31
Accept: application/json
Host: querydemo.documents.azure.com
Content-Length: 235
Expect: 100-continue
{
"id": "testcoll",
"indexingPolicy": {
"automatic": true,
"indexingMode": "Consistent",
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "String",
"precision": -1,
"kind": "Range"
}
]
}
]
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash",
"Version": 2
}
}