建立文件
Azure Cosmos DB 是全域散發的多模型資料庫，並可支援多個 API。 本文涵蓋適用於 Azure Cosmos DB 的 SQL API。
作業 Create Document 會在集合中建立新檔。
要求
| 方法 | 要求 URI | Description |
|---|---|---|
| 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 要求所使用的標頭，請參閱常見的 Azure Cosmos DB REST 要求標頭 。
| 標頭 | 必要 | 類型 | Description |
|---|---|---|---|
| x-ms-documentdb-is-upsert | 選擇性 | Boolean | 如果設定為 true，Cosmos DB 會建立識別碼為 (的檔，如果適用，則為分割區索引鍵值，如果不存在，則為) ，或更新檔。 |
| x-ms-indexing-directive | 選用 | String | 可接受的值為 Include 或 Exclude。 - Include 會將檔新增至索引。 - 排除 會省略檔編制索引。 索引行為的預設值由集合的編製索引原則中的自動屬性值所決定。 |
主體
| 屬性 | 必要 | 類型 | 描述 |
|---|---|---|---|
| id | 必要 | String | 這是識別檔的唯一識別碼，也就是說，不應該有兩份檔共用相同的 識別碼。 識別碼 不能超過 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 回應所傳回的標頭，請參閱 一般 Azure Cosmos DB REST 回應標頭 。
| 屬性 | 類型 | Description |
|---|---|---|
| x-ms-request-charge | 數字 | 作業所耗用的要求單位數目。 |
| x-ms-session-token | String | 與會話層級一致性搭配使用的字串權杖。 用戶端必須儲存此值，並針對會話一致性的後續讀取要求進行設定。 |
狀態碼
下表列出此作業所傳回的常見狀態碼。 如需狀態碼的完整清單，請參閱 HTTP 狀態碼。
| HTTP 狀態碼 | Description |
|---|---|
| 201 Created | 作業成功。 |
| 400 不正確的要求 | JSON 內文無效。 |
| 403 禁止 | 作業無法完成，因為已達到分割區的儲存限制。 |
| 409 衝突 | 現有檔已取得為新檔提供的識別碼。 |
| 413 實體過大 | 文件大小已超過要求中允許的文件大小。 |
主體
| 屬性 | Description |
|---|---|
| _擺脫 | 這是系統產生的屬性。 資源識別碼 (_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/"
}