Создание документа
Azure Cosmos DB — это глобально распределенная многомодельная база данных с поддержкой разных API. В этой статье рассматривается API SQL для Azure Cosmos DB.
Операция Create Document создает новый документ в коллекции.
Запрос
| Метод | Универсальный код ресурса (URI) запроса | Описание |
|---|---|---|
| POST | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs | {databaseaccount} — это имя учетной записи Azure Cosmos DB, созданной в вашей подписке. Значение {db-id} — это созданное пользователем имя или идентификатор базы данных, а не системный идентификатор (rid). Значение {coll-id} — это имя коллекции, содержащей документ. |
Заголовки
Заголовки, используемые всеми запросами Azure Cosmos DB, см. в статье Общие заголовки запросов REST Azure Cosmos DB .
| Заголовок | Обязательно | Тип | Описание |
|---|---|---|---|
| x-ms-documentdb-is-upsert | Необязательно | Логическое | Если задано значение true, Cosmos DB создает документ с идентификатором (и значением ключа секции, если применимо), если он не существует, или обновляет документ, если он существует. |
| x-ms-indexing-directive | Необязательно | Строка | Допустимое значение — Include или Exclude. - Include добавляет документ в индекс. - Исключение исключает документ из индексирования. По умолчанию поведение индексирования определяется значением свойства automatic в политике индексирования для коллекции. |
Текст
| Свойство | Обязательно | Тип | Описание |
|---|---|---|---|
| идентификатор | Обязательно | Строка | Это уникальный идентификатор, который идентифицирует документ, то есть два документа не должны иметь одинаковый идентификатор. Идентификатор не должен превышать 255 символов. Поле идентификатора автоматически добавляется при создании документа без указания значения идентификатора. Однако вы всегда можете обновить значение идентификатора, назначив ему пользовательское значение в тексте запроса. |
| <custom> | Обязательно | JSON | Любой определяемый пользователем элемент JSON. |
{
"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
}
Ответ
Возвращает текст созданного документа.
Заголовки
Заголовки, возвращаемые всеми ответами Azure Cosmos DB, см. в статье Общие заголовки ответов REST Azure Cosmos DB .
| Свойство | Тип | Описание |
|---|---|---|
| x-ms-request-charge | Число | Количество единиц запросов, используемых операцией. |
| x-ms-session-token | Строка | Строковый токен, используемый для согласованности на уровне сеанса. Клиенты должны сохранить это значение и задать его для последующих запросов на чтение для согласованности сеанса. |
Коды состояния
В таблице ниже указаны стандартные коды состояния, возвращаемые этой операцией. Полный список кодов состояния см. в разделе Коды состояния HTTP.
| Код состояния HTTP | Описание |
|---|---|
| 201 Создано | Операция выполнена успешно. |
| 400 — недопустимый запрос | Недопустимый текст JSON. |
| 403. Запрещено | Не удалось завершить операцию, так как достигнут предел хранилища секции. |
| 409. Конфликт | Идентификатор, предоставленный для нового документа, был взят существующим документом. |
| 413 (Сущность слишком велика) | Размер документа в запросе превышает допустимый размер документа. |
Текст
| Свойство | Описание |
|---|---|
| _Избавить | Это свойство, созданное системой. Идентификатор ресурса (_rid) — это уникальный идентификатор, который также является иерархическим для стека ресурсов в модели ресурсов. Он используется внутренне для размещения ресурса документа и перемещения по нему. |
| _Ts | Это свойство, созданное системой. Оно представляет метку времени последнего обновления ресурса. Значение — метка времени. |
| _Самостоятельно | Это свойство, созданное системой. Это уникальный адресуемый URI для ресурса. |
| _etag | Это созданное системой свойство, указывающее тег ресурса, необходимый для управления оптимистическим параллелизмом. |
| _Вложения | Это созданное системой свойство, указывающее адресуемый путь к ресурсу вложений. |
{
"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/"
}
Пример
POST https://querydemo.documents.azure.com/dbs/1KtjAA==/colls/1KtjAImkcgw=/docs HTTP/1.1
x-ms-documentdb-partitionkey: ["Andersen"]
x-ms-date: Tue, 29 Mar 2016 02:28:29 GMT
authorization: type%3dmaster%26ver%3d1.0%26sig%3d92WMAkQv0Zu35zpKZD%2bcGSH%2b2SXd8HGxHIvJgxhO6%2fs%3d
Cache-Control: no-cache
User-Agent: Microsoft.Azure.Documents.Client/1.6.0.0
x-ms-version: 2015-12-16
Accept: application/json
Host: querydemo.documents.azure.com
Cookie: x-ms-session-token#0=602; x-ms-session-token=602
Content-Length: 344
Expect: 100-continue
{
"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
}
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/"
}