建立集合

發行項
08/05/2023

作業 Create Collection 會在資料庫中建立新的集合。

注意

這些 API 參考文章示範如何使用 Azure Cosmos DB 資料平面 API 建立資源。透過資料平面 API，您可以設定基本選項，例如編制索引原則，資料分割索引鍵就像使用 Cosmos DB SDK 一樣。如果您需要所有 Azure Cosmos DB 資源的完整功能支援，建議您使用 Cosmos DB 資源提供者。

要求

方法	要求 URI	Description
POST	HTTPs://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls	{databaseaccount} 是您訂用帳戶下建立的 Azure Cosmos DB 帳戶名稱。 {db-id} 可以是資料庫的識別碼或_rid值。

標題

如需所有 Azure Cosmos DB 要求所使用的標頭，請參閱常見的 Azure Cosmos DB REST 要求標頭。

建構主要金鑰權杖的雜湊簽章時，ResourceType 應該是「colls」。 ResourceId 應該是 dbs/{db-id} ，其中 {db-id} 可以是資料庫的識別碼或_rid值。

屬性	必要	類型	Description
x-ms-offer-throughput	選擇性	數字	使用者為以每秒 100 個要求單位表示的集合指定手動輸送量 (RU/秒) 。最低為 400，最多 1，000，000 (或更高版本，方法是要求限制增加) 。只能指定或 `x-ms-cosmos-offer-autopilot-settings` 的 `x-ms-offer-throughput` 其中一個。這些標頭不能一起指定。
x-ms-cosmos-offer-autopilot-settings	選擇性	JSON	使用者指定的自動調整最大 RU/秒。值為具有屬性 `maxThroughput` 的 JSON。例如：`{"maxThroughput": 4000}`。只能指定或 `x-ms-cosmos-offer-autopilot-settings` 的 `x-ms-offer-throughput` 其中一個。這些標頭不能一起指定。使用自動調整時，需要 partitionKey 定義。
x-ms-offer-type	選用	String	這是已淘汰的預先定義效能等級 S1、S2 和 S3 的舊版標頭。建議您使用手動或自動調整輸送量，如上所述。

主體

屬性	必要	類型	描述
id	必要	String	使用者產生之集合的唯一名稱。沒有兩個集合可以有相同的識別碼。它是不能超過 255 個字元的字串。
indexingPolicy	選擇性	Object	這個值可用來設定檢索原則。預設會針對集合中的所有文件路徑自動檢索。
partitionKey	必要	Object	這個值是用來設定資料分割索引鍵，以便將資料分割成多個分割區。若要使用大型分割區索引鍵，請在 partitionKey 屬性中將版本指定為 2。如果 REST API 版本是 2018-12-31 或更高版本，集合必須包含 partitionKey 定義。在 2018-12-31 之前的版本中，您可以省略 partitionKey 定義，並確保輸送量介於 400 - 10，000 RU/秒之間，來建立具有手動輸送量的舊版非分割集合。為了獲得最佳效能和延展性，建議您一律設定分割區索引鍵。瞭解如何選擇良好的分割區索引鍵。

範例主體承載

{  
  "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 回應所傳回的標頭，請參閱常見的 Azure Cosmos DB REST 回應標頭。

狀態碼

下表列出此作業所傳回的常見狀態碼。如需狀態碼的完整清單，請參閱 HTTP 狀態碼。

HTTP 狀態碼	Description
201 Created	作業成功。
400 不正確的要求	JSON 內文無效。檢查是否缺少大括號或引號。
409 衝突	現有集合已採用為新集合提供的識別碼。
404，子狀態碼為 1013	集合建立作業仍在進行中。

如果您在建立集合時遇到逾時例外狀況，請執行讀取作業來驗證是否已成功建立集合。除非集合建立作業成功，否則讀取作業會擲回例外狀況。如果讀取作業擲回狀態碼為 404 的例外狀況，而子狀態碼為 1013，表示集合建立作業仍在進行中。重試讀取作業，直到您取得 200 或 201 狀態碼為止，這些程式碼會讓您知道已成功建立集合。

主體

屬性	描述
id	這是識別新集合的唯一名稱。
_擺脫	它是系統產生的屬性。資源識別碼 (_rid) 是唯一的識別碼，同時也是資源模型上資源堆疊的階層式。供內部進行放置和導覽文件資源時使用。
_Ts	它是系統產生的屬性。代表資源的上次更新時間戳記。值為時間戳記。
_自我	它是系統產生的屬性。代表資源的唯一可定址 URI。
_Etag	它是系統產生的屬性，代表開放式並行控制所需的資源 etag 。
_醫生	它是系統產生的屬性，指定檔資源的可定址路徑。
_sprocs	它是系統產生的屬性，指定預存程式 (sprocs) 資源的可定址路徑。
_觸發器	它是系統產生的屬性，指定觸發程式資源的可定址路徑。
_udfs	它是系統產生的屬性，指定使用者定義函式 (udfs) 資源的可定址路徑。
_衝突	它是系統產生的屬性，指定衝突資源的可定址路徑。在操作集合內的資源期間，如果發生衝突，使用者可以在衝突 URI 路徑上執行 GET 來檢查衝突的資源。
indexingPolicy	這是集合的索引編制原則設定。
partitionKey	這是集合的資料分割組態設定。

包含路徑底下的屬性

屬性	Description
path	索引行為套用至的路徑。索引路徑開頭為根 (/) ，且通常會以問號 (？) 萬用字元運算子結尾，表示前置詞有多個可能的值。例如，若要為 SELECT * FROM Families F WHERE F.familyName = "Andersen" 提供服務，您必須在集合的索引原則中包含 /familyName/? 在集合的索引原則中。索引路徑也可以使用 * 萬用字元運算子來指定路徑首碼底下的遞迴行為。例如，使用 /payload/* 可將 payload 屬性下的所有項目自編製索引作業中排除。
dataType	它是套用索引行為的資料類型。可以是 String、 Number、 Point、 Polygon或 LineString。布林值和 Null 會自動編制索引
kind	索引的類型。雜湊索引適用于相等比較，而範圍索引適用于相等、範圍比較和排序。空間索引適用于空間查詢。
有效位數	索引的有效位數。可以設定為 -1 表示最大有效位數，或數位介於 1-8 之間，字串則設定為 1-100。不適用於 Point、 Polygon和 LineString 資料類型。

[排除路徑] 底下的屬性

屬性	Description
path	從索引編制中排除的路徑。索引路徑開頭為根 (/) ，且通常會以 * 萬用字元運算子結尾。例如，使用 /payload/* 可將 payload 屬性下的所有項目自編製索引作業中排除。

資料分割索引鍵底下的屬性

屬性	Description
路徑	路徑陣列，用來分割集合中的資料。路徑不得包含萬用字元或尾端斜線。例如，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 RU/秒的集合。 x-ms-offer-throughput 標頭用來設定輸送量 (RU/秒) 值。它會接受最小值為 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 RU/秒， (其縮放比例介於 400 - 4000 RU/秒之間) 。 x-ms-cosmos-offer-autopilot-settings 標頭用來設定 maxThroughput 值，也就是自動調整最大 RU/秒值。它會接受至少 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
  }  
}

建立集合

要求

標題

主體

範例主體承載

回應

標題

狀態碼

主體

回應本文範例

範例 1

範例 2

另請參閱

其他資源