Partilhar via

Migrar contêineres não particionados para contêineres particionados

  • Artigo

APLICA-SE A: NoSQL

O Azure Cosmos DB dá suporte à criação de contêineres sem uma chave de partição. Atualmente, você pode criar contêineres não particionados usando a CLI do Azure e os SDKs do Azure Cosmos DB (.NET, Java, NodeJs) que têm uma versão menor ou igual a 2.x. Não é possível criar contêineres não particionados usando o portal do Azure. No entanto, esses contêineres não particionados não são elásticos e têm capacidade de armazenamento fixa de 20 GB e limite de taxa de transferência de 10K RU/s.

Os contêineres não particionados são herdados e você deve migrar os contêineres não particionados existentes para contêineres particionados para dimensionar o armazenamento e a taxa de transferência. O Azure Cosmos DB fornece um mecanismo definido pelo sistema para migrar seus contêineres não particionados para contêineres particionados. Este documento explica como todos os contêineres não particionados existentes são migrados automaticamente para contêineres particionados. Você pode aproveitar o recurso de migração automática somente se estiver usando a versão V3 dos SDKs em todos os idiomas.

Nota

Atualmente, não é possível migrar o Azure Cosmos DB MongoDB e a API para contas Gremlin usando as etapas descritas neste documento.

Migrar contêiner usando a chave de partição definida pelo sistema

Para dar suporte à migração, o Azure Cosmos DB fornece uma chave de partição definida pelo sistema nomeada /_partitionkey em todos os contêineres que não têm uma chave de partição. Não é possível alterar a definição da chave de partição depois que os contêineres são migrados. Por exemplo, a definição de um contêiner que é migrado para um contêiner particionado será a seguinte:

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

Depois que o contêiner for migrado, você poderá criar documentos preenchendo a _partitionKey propriedade junto com as outras propriedades do documento. A _partitionKey propriedade representa a chave de partição dos seus documentos.

Escolher a chave de partição certa é importante para utilizar a taxa de transferência provisionada de forma otimizada. Para obter mais informações, consulte como escolher um artigo de chave de partição.

Nota

Você pode aproveitar a chave de partição definida pelo sistema somente se estiver usando a versão mais recente/V3 dos SDKs em todos os idiomas.

O exemplo a seguir mostra um código de exemplo para criar um documento com a chave de partição definida pelo sistema e ler esse documento:

Representação JSON do documento

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

Para obter o exemplo completo, consulte o repositório GitHub de exemplos .NET.

Migrar os documentos

Embora a definição de contêiner seja aprimorada com uma propriedade de chave de partição, os documentos dentro do contêiner não são migrados automaticamente. O que significa que o caminho da propriedade /_partitionKey da chave de partição do sistema não é adicionado automaticamente aos documentos existentes. Você precisa reparticionar os documentos existentes lendo os documentos que foram criados sem uma chave de partição e reescrevê-los de volta com _partitionKey propriedade nos documentos.

Aceder a documentos que não têm uma chave de partição

Os aplicativos podem acessar os documentos existentes que não têm uma chave de partição usando a propriedade especial do sistema chamada "PartitionKey.None", este é o valor dos documentos não migrados. Você pode usar essa propriedade em todas as operações CRUD e de consulta. O exemplo a seguir mostra um exemplo para ler um único documento do NonePartitionKey.

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

Compatibilidade com SDKs

A versão mais antiga dos SDKs do Azure Cosmos DB, como V2.x.x e V1.x.x, não oferece suporte à propriedade de chave de partição definida pelo sistema. Portanto, quando você lê a definição de contêiner de um SDK mais antigo, ela não contém nenhuma definição de chave de partição e esses contêineres se comportarão exatamente como antes. Os aplicativos criados com a versão mais antiga dos SDKs continuam a funcionar com aplicativos não particionados como estão, sem alterações.

Se um contêiner migrado for consumido pela versão mais recente/V3 do SDK e você começar a preencher a chave de partição definida pelo sistema nos novos documentos, não poderá mais acessar (ler, atualizar, excluir, consultar) esses documentos dos SDKs mais antigos.

Problemas conhecidos

Consultar a contagem de itens que foram inseridos sem uma chave de partição usando o SDK V3 pode envolver maior consumo de taxa de transferência

Se você consultar a partir do SDK V3 para os itens que são inseridos usando V2 SDK, ou os itens inseridos usando o V3 SDK com PartitionKey.None parâmetro, a consulta de contagem pode consumir mais RU/s se o PartitionKey.None parâmetro for fornecido no FeedOptions. Recomendamos que você não forneça o PartitionKey.None parâmetro se nenhum outro item for inserido com uma chave de partição.

Se novos itens forem inseridos com valores diferentes para a chave de partição, consultar essas contagens de itens passando a chave apropriada não FeedOptions terá problemas. Depois de inserir novos documentos com chave de partição, se você precisar consultar apenas a contagem de documentos sem o valor da chave de partição, essa consulta poderá novamente incorrer em RU/s mais altos, semelhante às coleções particionadas regulares.

Próximos passos