你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
创建文档
Azure Cosmos DB 是一种全球分布式多模型数据库，支持多个 API。 本文介绍了适用于 Azure Cosmos DB 的 SQL API。
该 Create Document 操作在集合中创建新文档。
请求
| 方法 | 请求 URI | 说明 |
|---|---|---|
| POST | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs | {databaseaccount} 是在订阅下创建的 Azure Cosmos DB 帐户的名称。 {db-id} 值是用户生成的数据库名称/ID，而不是系统生成的 ID (rid) 。 {coll-id} 值是包含文档的集合的名称。 |
标头
有关所有 Azure Cosmos DB 请求 使用的标头，请参阅常见的 Azure Cosmos DB REST 请求标头。
| 标头 | 必需 | 类型 | 说明 |
|---|---|---|---|
| x-ms-documentdb-is-upsert | 可选 | Boolean | 如果设置为 true，Cosmos DB 使用 ID (和分区键值（如果适用）创建文档) 如果不存在，则更新文档（如果存在）。 |
| x-ms-indexing-directive | 可选 | 字符串 | 可接受的值为 Include 或 Exclude。 - Include 将文档添加到索引。 - 排除 从索引中省略文档。 索引行为的默认值由集合的索引策略中的“自动”属性的值决定。 |
正文
| 属性 | 必选 | 类型 | 说明 |
|---|---|---|---|
| id | 必须 | 字符串 | 它是标识文档的唯一 ID，也就是说，任何两个文档都不应共享相同的 ID。 ID 不得超过 255 个字符。 在未指定 ID 值的情况下创建文档时，会自动添加 ID 字段。 但是，始终可以通过在请求正文中为其分配自定义值来更新 ID 值。 |
| <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 响应 返回的标头，请参阅常见的 Azure Cosmos DB REST 响应标头。
| 属性 | 类型 | 说明 |
|---|---|---|
| x-ms-request-charge | Number | 操作使用的请求单位数。 |
| x-ms-session-token | 字符串 | 用于会话级别一致性的字符串令牌。 客户端必须保存此值，并为会话一致性的后续读取请求设置此值。 |
状态代码
下表列出了此操作返回的常见状态代码。 有关状态代码的完整列表，请参阅 HTTP 状态代码。
| HTTP 状态代码 | 说明 |
|---|---|
| 201 Created | 操作成功。 |
| 400 错误的请求 | JSON 正文无效。 |
| 403 禁止访问 | 无法完成该操作，因为已达到分区的存储限制。 |
| 409 冲突 | 为新文档提供的 ID 已由现有文档获取。 |
| 413 实体太大 | 请求中的文档大小已超过允许的文档大小。 |
正文
| 属性 | 说明 |
|---|---|
| _摆脱 | 它是系统生成的属性。 资源 ID (_rid) 是一个唯一标识符，也是按资源模型上的资源堆栈分层的标识符。 它在内部用于文档资源的放置和导航。 |
| _ts | 它是 系统生成的属性。 它指定资源的上次更新时间戳。 高值是一个时间戳。 |
| _自我 | 它是系统生成的属性。 它是资源的唯一可寻址 URI。 |
| _Etag | 它是一个系统生成的属性，指定乐观并发控制所需的资源 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/"
}