Créer et gérer des travaux de copie de conteneur dans Azure Cosmos DB (préversion)

  • Article

Les travaux de copie permettent de créer des copies de conteneurs dans des comptes Azure Cosmos DB.

Cet article explique comment créer, superviser et gérer des travaux de copie à l’aide de commandes Azure CLI.

Prérequis

  • Vous pouvez utiliser le portail Cloud Shell pour exécuter des commandes de copie de conteneur. Vous pouvez également exécuter les commandes localement. Vérifiez que vous avez téléchargé et installé Azure CLI sur votre machine.
  • La copie de conteneur est prise en charge uniquement dans ces régions. Vérifiez que la région d’écriture de votre compte figure dans cette liste.
  • Installez l’extension de préversion Azure Cosmos DB qui contient les commandes de copie de conteneur. 
    az extension add --name cosmosdb-preview

Définir des variables shell

Tout d’abord, définissez toutes les variables que chaque script individuel utilise.

$sourceSubId = "<source-subscription-id>" 
$destinationSubId = "<destination-subscription-id>" 
$sourceAccountRG = "<source-resource-group-name>"
$destinationAccountRG = "<destination-resource-group-name>"
$sourceAccount = "<cosmos-source-account-name>"
$destinationAccount = "<cosmos-destination-account-name>"
$jobName = ""
$sourceDatabase = ""
$sourceContainer = ""
$destinationDatabase = ""
$destinationContainer = ""

Attribuer l’autorisation de lecture

Remarque

Cette étape n’est pas nécessaire si vous copiez des données dans le même compte Azure Cosmos DB.

Lors de la copie de données d’un conteneur d’un compte vers le conteneur d’un autre compte, il est nécessaire d’accorder l’accès en lecture du conteneur source à l’identité du compte de destination pour effectuer l’opération de copie. Suivez les étapes ci-dessous pour attribuer l’autorisation de lecture requise au compte de destination.

Utilisation d’une identité managée par le système

  1. Définir le contexte de l’abonnement de destination 
    az account set --subscription $destinationSubId
  2. Ajouter une identité système sur le compte de destination 
    $identityOutput = az cosmosdb identity assign -n $destinationAccount -g $destinationAccountRG
$principalId = ($identityOutput | ConvertFrom-Json).principalId
  3. Définir l’identité par défaut sur le compte de destination 
    az cosmosdb update -n $destinationAccount -g $destinationAccountRG --default-identity="SystemAssignedIdentity"
  4. Définir le contexte de l’abonnement source 
    az account set --subscription $sourceSubId
  5. Ajouter une attribution de rôle à un compte d’utilisateur 
    # Read-only access role
$roleDefinitionId = "00000000-0000-0000-0000-000000000001" 
az cosmosdb sql role assignment create --account-name $sourceAccount --resource-group $sourceAccountRG --role-definition-id $roleDefinitionId --scope "/" --principal-id $principalId
  6. Réinitialiser le contexte de l’abonnement de destination 
    az account set --subscription $destinationSubId

Utilisation d’une identité managée affectée par l’utilisateur

  1. Attribuer une variable d’identité managée affectée par l’utilisateur 
    $userAssignedManagedIdentityResourceId = "<CompleteResourceIdOfUserAssignedManagedIdentity>"
  2. Définir le contexte de l’abonnement de destination 
    az account set --subscription $destinationSubId
  3. Ajouter une identité managée affectée par l’utilisateur sur le compte de destination 
    $identityOutput = az cosmosdb identity assign -n $destinationAccount -g $destinationAccountRG --identities $userAssignedManagedIdentityResourceId
$principalId = ($identityOutput | ConvertFrom-Json).userAssignedIdentities.$userAssignedManagedIdentityResourceId.principalId
  4. Définir l’identité par défaut sur le compte de destination 
    az cosmosdb update -n $destinationAccount -g $destinationAccountRG --default-identity=UserAssignedIdentity=$userAssignedManagedIdentityResourceId
  5. Définir le contexte de l’abonnement source 
    az account set --subscription $sourceSubId
  6. Ajouter une attribution de rôle à un compte d’utilisateur 
    $roleDefinitionId = "00000000-0000-0000-0000-000000000001"  # Read-only access role
az cosmosdb sql role assignment create --account-name $sourceAccount --resource-group $sourceAccountRG --role-definition-id $roleDefinitionId --scope "/" --principal-id $principalId
  7. Réinitialiser le contexte de l’abonnement de destination 
    az account set --subscription $destinationSubId

Créer un travail de copie

az cosmosdb copy create `
    --resource-group $destinationAccountRG `
    --job-name $jobName `
    --dest-account $destinationAccount `
    --src-account $sourceAccount `
    --dest-nosql database=$destinationDatabase container=$destinationContainer `
    --src-nosql database=$sourceDatabase container=$sourceContainer
    --mode Online

Surveiller la progression

Surveillez la progression à l’aide de la commande ci-dessous.

az cosmosdb copy show `
    --resource-group $destinationAccountRG `
    --account-name $destinationAccount `
    --job-name $jobName
  1. Nombre total : il représente le nombre total de modifications (document total + nouvelles modifications) dans le conteneur source à tout moment.
  2. Nombre traité : il représente le nombre total d’événements provenant du flux de modification du conteneur source qui ont été traités par le travail de copie.

Terminer le travail de copie

  1. Lorsque le nombre traité devient supérieur ou égal au nombre total, désactivez les mises à jour sur le conteneur source et attendez 5 à 10 minutes pour vider les modifications restantes.
  2. Exécutez l’API d’achèvement pour terminer le travail de copie et libérer des ressources de calcul, ce qui écrit également les modifications restantes (le cas échéant) dans le conteneur de destination.
    az cosmosdb copy complete `
        --resource-group $destinationAccountRG `
        --account-name $destinationAccount `
        --job-name $jobName
  1. Mettez à jour les applications clientes pour commencer à utiliser le nouveau conteneur (destination) si nécessaire.

Définir des variables shell

Tout d’abord, définissez toutes les variables que chaque script individuel utilise.

$destinationRG = "<destination-resource-group-name>"
$sourceAccount = "<cosmos-source-account-name>"
$destinationAccount = "<cosmos-destination-account-name>"
$jobName = ""
$sourceDatabase = ""
$sourceCollection = ""
$destinationDatabase = ""
$destinationCollection = ""

Créer un travail de copie

Créer un travail pour copier une collection dans un compte d’API MongoDB Azure Cosmos DB :

az cosmosdb copy create `
    --resource-group $destinationRG `
    --job-name $jobName `
    --dest-account $destinationAccount `
    --src-account $sourceAccount `
    --dest-mongo database=$destinationDatabase collection=$destinationCollection `
    --src-mongo database=$sourceDatabase collection=$sourceCollection

Remarque

--job-name doit être unique pour chaque travail au sein d’un compte.

Définir des variables shell

Tout d’abord, définissez toutes les variables que chaque script individuel utilise.

$destinationRG = "<destination-resource-group-name>"
$sourceAccount = "<cosmos-source-account-name>"
$destinationAccount = "<cosmos-destination-account-name>"
$jobName = ""
$sourceKeySpace = ""
$sourceTable = ""
$destinationKeySpace = ""
$destinationTable = ""

Créer un travail de copie

Créez un travail pour copier une table dans un compte Azure Cosmos DB for Apache Cassandra :

az cosmosdb copy create `
    --resource-group $destinationRG `
    --job-name $jobName `
    --dest-account $destinationAccount `
    --src-account $sourceAccount `
    --dest-cassandra keyspace=$destinationKeySpace table=$destinationTable `
    --src-cassandra keyspace=$sourceKeySpace table=$sourceTable

Remarque

--job-name doit être unique pour chaque travail au sein d’un compte.

Gestion des travaux de copie

Surveiller la progression d’un travail de copie

Afficher la progression et l’état d’un travail de copie :

az cosmosdb copy show `
    --resource-group $destinationAccountRG `
    --account-name $destinationAccount `
    --job-name $jobName

Répertorier tous les travaux de copie créés dans un compte

Pour répertorier tous les travaux de copie créés dans un compte :

az cosmosdb copy list `
    --resource-group $destinationAccountRG `
    --account-name $destinationAccount

Suspendre un travail de copie

Pour suspendre un travail de copie en cours, vous pouvez utiliser la commande suivante :

az cosmosdb copy pause `
    --resource-group $destinationAccountRG `
    --account-name $destinationAccount `
    --job-name $jobName

Reprendre un travail de copie

Pour rependre un travail de copie en cours, vous pouvez utiliser la commande suivante :

az cosmosdb copy resume `
    --resource-group $destinationAccountRG `
    --account-name $destinationAccount `
    --job-name $jobName

Annuler un travail de copie

Pour annuler un travail de copie en cours, vous pouvez utiliser la commande suivante :

az cosmosdb copy cancel `
    --resource-group $destinationAccountRG `
    --account-name $destinationAccount `
    --job-name $jobName

Obtenir de l’aide pour les problèmes de copie

Pour les problèmes relatifs à un travail de copie, envoyez une nouvelle demande de support à partir du portail Azure. Choisissez le type de problème « Migration de données » et le sous-type de problème « Copie de conteneur ».

Étapes suivantes

  • Pour plus d’informations sur les travaux de copie de conteneur, consultez l’article Travaux de copie.