共用方式為

將未分割的容器移轉至已分割的容器

  • 發行項

適用於：NoSQL

Azure Cosmos DB 支援建立沒有分割區索引鍵的容器。 目前，您可以使用小於或等於 2.x 版的 Azure CLI 和 Azure Cosmos DB SDK (.NET、JAVA、NodeJs) 來建立未分割的容器。 您無法使用 Azure 入口網站建立未分割的容器。 不過，這種未分割的容器沒有彈性，固定為儲存體容量 20 GB 和輸送量限制 10K RU/秒。

未分割容器是舊版的，您應該將現有的未分割容器移轉至已分割的容器，以調整儲存體和輸送量。 Azure Cosmos DB 提供系統定義的機制，可將未分割的容器移轉至已分割的容器。 本文件說明如何將所有現有的未分割容器自動移轉至已分割的容器。 只有當您使用所有語言的 V3 版 SDK 時，才可以利用自動移轉功能。

注意

目前，您無法使用此文件件所述的步驟來移轉 Azure Cosmos DB MongoDB 和 API for Gremlin 帳戶。

使用系統定義的分割區索引鍵來遷移容器

為了支援移轉，在沒有分割區索引鍵的所有容器上，Azure Cosmos DB 提供系統定義的分割區索引鍵，名為 /_partitionkey。 移轉容器之後，您就無法變更分割區索引鍵定義。 例如，容器遷移至已分割的容器時，其定義如下所示：

{
    "Id": "CollId"
  "partitionKey": {
    "paths": [
      "/_partitionKey"
    ],
    "kind": "Hash"
  },
}

遷移容器之後，您可以建立文件，而且除了文件的其他屬性，還可加進 _partitionKey 屬性。 _partitionKey 屬性代表文件的分割區索引鍵。

為了充分利用佈建的輸送量，選擇正確的分割區索引鍵很重要。 如需詳細資訊，請參閱如何選擇分割區索引鍵一文。

注意

只有在使用最新/V3 版的 SDK 時 (所有語言)，才能利用系統定義的分割區索引鍵。

下列程式碼範例示範以系統定義的分割區索引鍵建立文件，並讀取該文件：

文件的 JSON 表示法

DeviceInformationItem = new DeviceInformationItem
{
   "id": "elevator/PugetSound/Building44/Floor1/1",
   "deviceId": "3cf4c52d-cc67-4bb8-b02f-f6185007a808",
   "_partitionKey": "3cf4c52d-cc67-4bb8-b02f-f6185007a808"
}

public class DeviceInformationItem
{
    [JsonProperty(PropertyName = "id")]
    public string Id { get; set; }

    [JsonProperty(PropertyName = "deviceId")]
    public string DeviceId { get; set; }

    [JsonProperty(PropertyName = "_partitionKey", NullValueHandling = NullValueHandling.Ignore)]
    public string PartitionKey { get {return this.DeviceId; set; }
}

CosmosContainer migratedContainer = database.Containers["testContainer"];

DeviceInformationItem deviceItem = new DeviceInformationItem() {
  Id = "1234",
  DeviceId = "3cf4c52d-cc67-4bb8-b02f-f6185007a808"
}

ItemResponse<DeviceInformationItem > response =
  await migratedContainer.CreateItemAsync<DeviceInformationItem>(
    deviceItem.PartitionKey,
    deviceItem
  );

// Read back the document providing the same partition key
ItemResponse<DeviceInformationItem> readResponse =
  await migratedContainer.ReadItemAsync<DeviceInformationItem>(
    partitionKey: deviceItem.PartitionKey,
    id: device.Id
  );

如需完整範例，請參閱 .NET 範例 GitHub 存放庫。

遷移文件

使用分割區索引鍵屬性增強容器定義時，不會自動遷移容器內的文件。 這表示系統分割區索引鍵屬性 /_partitionKey 路徑不會自動新增至現有文件。 您必須讀取未以分割區索引鍵建立的現有文件，以重新分割的文件，然後在文件中使用 _partitionKey 屬性，將文件重寫回來。

存取沒有分割區索引鍵的文件

應用程式可以使用名為 "PartitionKey.None" (此值代表未遷移的文件) 的特殊系統屬性，以存取沒有分割區索引鍵的現有文件。 您可以在所有 CRUD 和查詢作業中使用此屬性。 下列範例示範從 NonePartitionKey 讀取單一文件。

CosmosItemResponse<DeviceInformationItem> readResponse =
await migratedContainer.Items.ReadItemAsync<DeviceInformationItem>(
  partitionKey: PartitionKey.None,
  id: device.Id
);

SDK 的相容性

舊版 Azure Cosmos DB SDK (例如 V2.x.x 和 V1.x.x) 不支援系統定義的分割區索引鍵屬性。 因此，從舊版 SDK 讀取的容器定義不含任何分割區索引鍵定義，這些容器的行為一如既往。 使用舊版 SDK 建立的應用程式一成不變，仍像未分割一樣繼續運作。

如果已移轉的容器由最新/V3 版的 SDK 取用，而且您在新文件中開始填入系統定義的分割區索引鍵，則無法從舊版 SDK 存取 (讀取、更新、刪除、查詢) 這些文件。

已知問題

使用 V3 SDK 查詢未以分割區索引鍵插入的項目計數時，可能耗用較多輸送量

從 V3 SDK 查詢使用 V2 SDK 插入的項目，或使用 V3 SDK 搭配 PartitionKey.None 參數插入的項目時，如果是在 FeedOptions 中提供 PartitionKey.None 參數，則計數查詢可能耗用較多 RU/秒。 如果未以分割區索引鍵插入其他項目，建議您不要提供 PartitionKey.None 參數。

如果以分割區索引鍵的不同值來插入新項目，則在 FeedOptions 中傳入適當的索引鍵來查詢這種項目計數，就不會有任何問題。 以分割區索引鍵插入新文件之後，如果您只需要查詢沒有分割區索引鍵值的文件計數，則該查詢可能像一般分割的集合一樣，還是會耗用較多 RU/秒。

下一步