Migrace kontejnerů nerozdělených na dělené kontejnery

  • Článek

PLATÍ PRO: NoSQL

Azure Cosmos DB podporuje vytváření kontejnerů bez klíče oddílu. V současné době můžete vytvářet nerozdělené kontejnery pomocí Azure CLI a sad SDK služby Azure Cosmos DB (.NET, Java, NodeJs), které mají verzi menší nebo rovnou 2.x. Pomocí Azure Portal nemůžete vytvářet nerozdělené kontejnery. Tyto kontejnery, které nejsou rozdělené na oddíly, ale nejsou elastické a mají pevnou kapacitu úložiště 20 GB a limit propustnosti 10 tisíc RU/s.

Kontejnery, které nejsou rozdělené na oddíly, jsou starší verze a měli byste stávající kontejnery bez oddílů migrovat na dělené kontejnery, abyste mohli škálovat úložiště a propustnost. Azure Cosmos DB poskytuje systémem definovaný mechanismus pro migraci kontejnerů bez oddílů do dělených kontejnerů. Tento dokument vysvětluje, jak se všechny existující kontejnery bez oddílů automaticky migrují do dělených kontejnerů. Funkci automatické migrace můžete využít jenom v případě, že používáte sady SDK verze 3 ve všech jazycích.

Poznámka

V současné době není možné migrovat mongoDB a rozhraní API služby Azure Cosmos DB pro účty Gremlin pomocí kroků popsaných v tomto dokumentu.

Migrace kontejneru pomocí klíče oddílu definovaného systémem

Pro podporu migrace poskytuje Azure Cosmos DB pro všechny kontejnery, které nemají klíč oddílu, klíč /_partitionkey oddílu definovaný systémem. Po migraci kontejnerů nemůžete změnit definici klíče oddílu. Například definice kontejneru, který se migruje do děleného kontejneru, bude následující:

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

Po migraci kontejneru můžete vytvářet dokumenty naplněním _partitionKey vlastnosti spolu s ostatními vlastnostmi dokumentu. Vlastnost _partitionKey představuje klíč oddílu vašich dokumentů.

Výběr správného klíče oddílu je důležitý pro optimální využití zřízené propustnosti. Další informace najdete v článku o volbě klíče oddílu .

Poznámka

Klíč oddílu definovaný systémem můžete využít pouze v případě, že používáte nejnovější verzi sad SDK nebo v3 ve všech jazycích.

Následující příklad ukazuje ukázkový kód pro vytvoření dokumentu s klíčem oddílu definovaným systémem a přečtením tohoto dokumentu:

Reprezentace dokumentu 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
  );

Kompletní ukázku najdete v úložišti GitHubu ukázek .NET .

Migrace dokumentů

I když je definice kontejneru vylepšená o vlastnost klíče oddílu, dokumenty v rámci kontejneru se automaticky nemigrují. To znamená, že cesta k vlastnosti /_partitionKey klíče systémového oddílu se automaticky nepřidá do existujících dokumentů. Musíte předělit existující dokumenty tak, že si přečtete dokumenty vytvořené bez klíče oddílu a přepíšete je zpět pomocí _partitionKey vlastnosti v dokumentech.

Přístup k dokumentům, které nemají klíč oddílu

Aplikace můžou přistupovat k existujícím dokumentům, které nemají klíč oddílu, pomocí speciální systémové vlastnosti s názvem PartitionKey.None, což je hodnota nemigrovaných dokumentů. Tuto vlastnost můžete použít ve všech operacích CRUD a dotazování. Následující příklad ukazuje ukázku pro čtení jednoho dokumentu z NonePartitionKey.

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

Kompatibilita se sadami SDK

Starší verze sad SDK služby Azure Cosmos DB, jako jsou V2.x.x a V1.x.x, nepodporují vlastnost klíče oddílu definovanou systémem. Když tedy přečtete definici kontejneru ze starší sady SDK, neobsahuje žádnou definici klíče oddílu a tyto kontejnery se budou chovat přesně jako předtím. Aplikace, které jsou sestavené se starší verzí sad SDK, budou dál fungovat beze změn bez rozdělení na oddíly.

Pokud migrovaný kontejner využívá nejnovější verze sady SDK nebo verze 3 a v nových dokumentech začnete nasytit klíč oddílu definovaný systémem, nebudete už mít k těmto dokumentům přístup (čtení, aktualizace, odstraňování, dotazování) ze starších sad SDK.

Známé problémy

Dotazování na počet položek vložených bez klíče oddílu pomocí sady SDK v3 může zahrnovat vyšší spotřebu propustnosti.

Pokud ze sady SDK v3 zadáte dotaz na položky vložené pomocí sady SDK v2 nebo položky vložené pomocí sady SDK v3 s parametrem PartitionKey.None , může dotaz na počet spotřebovávat více RU/s, pokud PartitionKey.None je parametr zadaný v části FeedOptions. Pokud se s klíčem oddílu PartitionKey.None nevkládají žádné další položky, doporučujeme parametr nezadávat.

Pokud se vloží nové položky s různými hodnotami klíče oddílu, dotazování na tyto položky počítá předáním příslušného klíče FeedOptions nebude mít žádné problémy. Pokud se po vložení nových dokumentů s klíčem oddílu potřebujete dotazovat jenom na počet dokumentů bez hodnoty klíče oddílu, může se u daného dotazu znovu objevit vyšší počet RU/s, podobně jako u běžných dělených kolekcí.

Další kroky