Condividi tramite

Eseguire la migrazione di contenitori non partizionati a contenitori partizionati

  • Articolo

SI APPLICA A: NoSQL

Azure Cosmos DB supporta la creazione di contenitori senza una chiave di partizione. Attualmente è possibile creare contenitori non partizionati usando l'interfaccia della riga di comando di Azure e gli SDK di Azure Cosmos DB (.NET, Java, NodeJs) con una versione inferiore o uguale a 2.x. Non è possibile creare contenitori non partizionati usando il portale di Azure. Tuttavia, tali contenitori non partizionati non sono elastici e hanno una capacità di archiviazione fissa di 20 GB e un limite di velocità effettiva di 10.000 UR/s.

I contenitori non partizionati sono legacy ed è necessario eseguire la migrazione dei contenitori non partizionati esistenti ai contenitori partizionati per dimensionare l'archiviazione e la velocità effettiva. Azure Cosmos DB offre un meccanismo definito dal sistema per la migrazione dei contenitori non partizionati ai contenitori partizionati. Questo documento illustra come viene eseguita la migrazione automatica di tutti i contenitori non partizionati esistenti in contenitori partizionati. È possibile sfruttare la funzionalità di migrazione automatica solo se si usa la versione 3 degli SDK in tutte le lingue.

Nota

Attualmente non è possibile eseguire la migrazione di Azure Cosmos DB MongoDB e API per gli account Gremlin seguendo la procedura descritta in questo documento.

Eseguire la migrazione del contenitore usando la chiave di partizione definita dal sistema

Per supportare la migrazione, Azure Cosmos DB fornisce una chiave di partizione definita dal sistema denominata /_partitionkey in tutti i contenitori che non dispongono di una chiave di partizione. Non è possibile modificare la definizione della chiave di partizione dopo la migrazione dei contenitori. Ad esempio, la definizione di un contenitore di cui viene eseguita la migrazione a un contenitore partizionato sarà la seguente:

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

Dopo la migrazione del contenitore, è possibile creare documenti popolando la proprietà _partitionKey insieme alle altre proprietà del documento. La proprietà _partitionKey rappresenta la chiave di partizione dei documenti.

La scelta della chiave di partizione corretta è importante per usare la velocità effettiva con provisioning in modo ottimale. Per altre informazioni, vedere l'articolo su come scegliere una chiave di partizione.

Nota

È possibile sfruttare la chiave di partizione definita dal sistema solo se si usa la versione più recente/V3 degli SDK in tutti i linguaggi.

L'esempio seguente illustra un codice di esempio per creare un documento con la chiave di partizione definita dal sistema e leggere il documento:

Rappresentazione JSON del 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
  );

Per l'esempio completo, vedere il repository GitHub degli esempi .NET.

Eseguire la migrazione dei documenti

Sebbene la definizione del contenitore sia migliorata con una proprietà della chiave di partizione, i documenti all'interno del contenitore non vengono migrati automaticamente. Ciò significa che il percorso della proprietà /_partitionKey della chiave di partizione di sistema non viene aggiunto automaticamente ai documenti esistenti. È necessario ripartizionare i documenti esistenti leggendo i documenti creati senza una chiave di partizione e riscrivendoli con la proprietà _partitionKey nei documenti.

Accedere ai documenti che non dispongono di una chiave di partizione

Le applicazioni possono accedere ai documenti esistenti che non dispongono di una chiave di partizione usando la proprietà di sistema speciale denominata "PartitionKey.None", ovvero il valore dei documenti non migrati. È possibile usare questa proprietà in tutte le operazioni CRUD e di query. L'esempio seguente mostra un esempio per leggere un singolo documento da NonePartitionKey.

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

Compatibilità con gli SDK

La versione precedente degli SDK di Azure Cosmos DB, ad esempio V2.x.x e V1.x.x, non supporta la proprietà della chiave di partizione definita dal sistema. Pertanto, quando si legge la definizione del contenitore da un SDK precedente, non contiene alcuna definizione della chiave di partizione e questi contenitori si comportano esattamente come in precedenza. Le applicazioni compilate con la versione precedente degli SDK continuano a funzionare con le versioni non partizionate così come sono senza modifiche.

Se un contenitore migrato viene utilizzato dalla versione più recente/V3 dell'SDK e si inizia a popolare la chiave di partizione definita dal sistema all'interno dei nuovi documenti, non è più possibile accedere (lettura, aggiornamento, eliminazione, query) a tali documenti dagli SDK precedenti.

Problemi noti

L'esecuzione di query per il conteggio degli elementi inseriti senza una chiave di partizione tramite SDK V3 può comportare un consumo di velocità effettiva superiore

Se si esegue una query dall'SDK V3 per gli elementi inseriti usando l'SDK V2 o gli elementi inseriti usando l'SDK V3 con il parametro PartitionKey.None, la query di conteggio può usare più UR/s se il parametro PartitionKey.None viene fornito in FeedOptions. È consigliabile non specificare il parametro PartitionKey.None se non vengono inseriti altri elementi con una chiave di partizione.

Se vengono inseriti nuovi elementi con valori diversi per la chiave di partizione, l'esecuzione di query per tali conteggi di elementi passando la chiave appropriata in FeedOptions non avrà problemi. Dopo aver inserito nuovi documenti con chiave di partizione, se è necessario eseguire una query solo sul numero di documenti senza il valore della chiave di partizione, tale query potrebbe comportare di nuovo un numero di UR/s superiore simile alle normali raccolte partizionate.

Passaggi successivi