Gérer les ressources Azure Cosmos DB for NoSQL à l’aide de l'interface Azure CLI

S’APPLIQUE À : NoSQL

Le guide suivant décrit les commandes courantes permettant d’automatiser la gestion de vos comptes, bases de données et conteneurs Azure Cosmos DB à l’aide de l’interface Azure CLI. Des pages d’informations de référence pour toutes les commandes Azure Cosmos DB CLI sont disponibles dans les Informations de référence sur Azure CLI. Vous trouverez également des exemples dans Exemples Azure CLI pour Azure Cosmos DB, notamment sur la création et la gestion de comptes, bases de données et conteneurs Azure Cosmos DB pour MongoDB, Gremlin, Cassandra et l’API pour Table.

Prérequis

• Utilisez l’environnement Bash dans Azure Cloud Shell. Pour plus d’informations, consultez Démarrage rapide pour Bash dans Azure Cloud Shell.

  

• Si vous préférez exécuter les commandes de référence de l’interface de ligne de commande localement, installez l’interface Azure CLI. Si vous exécutez sur Windows ou macOS, envisagez d’exécuter Azure CLI dans un conteneur Docker. Pour plus d’informations, consultez Guide pratique pour exécuter Azure CLI dans un conteneur Docker.

  • Si vous utilisez une installation locale, connectez-vous à Azure CLI à l’aide de la commande az login. Pour finir le processus d’authentification, suivez les étapes affichées dans votre terminal. Pour connaître les autres options de connexion, consultez Se connecter avec Azure CLI.

  • Lorsque vous y êtes invité, installez l’extension Azure CLI lors de la première utilisation. Pour plus d’informations sur les extensions, consultez Utiliser des extensions avec Azure CLI.

  • Exécutez az version pour rechercher la version et les bibliothèques dépendantes installées. Pour effectuer une mise à niveau vers la dernière version, exécutez az upgrade.

• Cet article nécessite la version 2.22.1 ou ultérieure d’Azure CLI. Si vous utilisez Azure Cloud Shell, la version la plus récente est déjà installée.

Pour obtenir des exemples d’interface Azure CLI destinés à d’autres API, consultez Exemples d’interface CLI pour Cassandra, Exemples d’interface CLI pour l’API pour MongoDB, Exemples d’interface CLI pour Gremlin, Exemples d’interface CLI pour Table

Important

Les ressources Azure Cosmos DB ne peuvent pas être renommées, car cela enfreint les règles de traitement des URI de ressources par Azure Resource Manager.

Azure Cosmos DBAccounts

Les sections suivantes montrent comment gérer le compte Azure Cosmos DB, et notamment :

• Création d’un compte Azure Cosmos DB
• Ajouter ou supprimer des régions
• Activer les écritures multirégions
• Définir la priorité de basculement régionale
• Activer le basculement géré par le service
• Déclencher un basculement manuel
• Répertorier les clés de compte
• Répertorier les clés de compte en lecture seule
• Répertorier les chaînes de connexion
• Régénérer la clé de compte

Création d’un compte Azure Cosmos DB

Créez un compte Azure Cosmos DB avec API pour NoSQL, cohérence de session dans les régions USA Ouest et USA Est :

Important

Le nom du compte Azure Cosmos DB doit être en minuscules et comporter moins de 44 caractères.

resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount' #needs to be lower case and less than 44 characters

az cosmosdb create \
    -n $accountName \
    -g $resourceGroupName \
    --default-consistency-level Session \
    --locations regionName='West US' failoverPriority=0 isZoneRedundant=False \
    --locations regionName='East US' failoverPriority=1 isZoneRedundant=False

Ajouter ou supprimer des régions

Créez un compte Azure Cosmos DB avec deux régions, ajoutez une région et supprimez-en une.

Notes

Vous ne pouvez pas ajouter ou supprimer simultanément des régions locations et changer d’autres propriétés pour un compte Azure Cosmos DB. La modification des régions doit être effectuée en tant qu’opération distincte de toute autre modification apportée à la ressource de compte.

Notes

Cette commande vous permet d’ajouter ou de supprimer des régions, mais ne vous permet pas de modifier des priorités de basculement ni de déclencher un basculement manuel. Consultez Définir la priorité de basculement et Déclencher un basculement manuel.

Conseil

Quand une nouvelle région est ajoutée, toutes les données doivent être entièrement répliquées et validées dans la nouvelle région pour que celle-ci soit marquée comme disponible. Le temps nécessaire à cette opération dépend de la quantité de données stockées dans le compte. Si une opération de mise à l’échelle du débit asynchrone est en cours, l’opération de mise à l’échelle du débit est suspendue et reprend automatiquement une fois l’opération d’ajout ou de suppression de région terminée.

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'

# Create an account with 2 regions
az cosmosdb create --name $accountName --resource-group $resourceGroupName \
    --locations regionName="West US" failoverPriority=0 isZoneRedundant=False \
    --locations regionName="East US" failoverPriority=1 isZoneRedundant=False

# Add a region
az cosmosdb update --name $accountName --resource-group $resourceGroupName \
    --locations regionName="West US" failoverPriority=0 isZoneRedundant=False \
    --locations regionName="East US" failoverPriority=1 isZoneRedundant=False \
    --locations regionName="South Central US" failoverPriority=2 isZoneRedundant=False

# Remove a region
az cosmosdb update --name $accountName --resource-group $resourceGroupName \
    --locations regionName="West US" failoverPriority=0 isZoneRedundant=False \
    --locations regionName="East US" failoverPriority=1 isZoneRedundant=False

Activer plusieurs régions d'écriture

Activer les écritures sur plusieurs régions pour un compte Azure Cosmos DB

# Update an Azure Cosmos DB account from single write region to multiple write regions
resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'

# Get the account resource id for an existing account
accountId=$(az cosmosdb show -g $resourceGroupName -n $accountName --query id -o tsv)

az cosmosdb update --ids $accountId --enable-multiple-write-locations true

Définir la priorité de basculement

Définir la priorité de basculement d'un compte Azure Cosmos DB configuré pour le basculement géré par le service

# Assume region order is initially 'West US'=0 'East US'=1 'South Central US'=2 for account
resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'

# Get the account resource id for an existing account
accountId=$(az cosmosdb show -g $resourceGroupName -n $accountName --query id -o tsv)

# Make South Central US the next region to fail over to instead of East US
az cosmosdb failover-priority-change --ids $accountId \
    --failover-policies 'West US=0' 'South Central US=1' 'East US=2'

Activer le basculement géré par le service

# Enable service-managed failover on an existing account
resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'

# Get the account resource id for an existing account
accountId=$(az cosmosdb show -g $resourceGroupName -n $accountName --query id -o tsv)

az cosmosdb update --ids $accountId --enable-automatic-failover true

Déclencher un basculement manuel

Attention

La modification de la région avec Priority = 0 déclenchera un basculement manuel pour un compte Azure Cosmos DB. Tout autre changement de priorité ne déclenche pas de basculement.

Notes

Si vous effectuez une opération de basculement manuel alors qu’une opération de mise à l’échelle du débit asynchrone est en cours, cette dernière est suspendue. Elle reprend automatiquement une fois l’opération de basculement terminée.

# Assume region order is initially 'West US=0' 'East US=1' 'South Central US=2' for account
resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'

# Get the account resource id for an existing account
accountId=$(az cosmosdb show -g $resourceGroupName -n $accountName --query id -o tsv)

# Trigger a manual failover to promote East US 2 as new write region
az cosmosdb failover-priority-change --ids $accountId \
    --failover-policies 'East US=0' 'South Central US=1' 'West US=2'

Lister toutes clés de compte

Obtenez toutes les clés pour un compte Azure Cosmos DB.

# List all account keys
resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'

az cosmosdb keys list \
   -n $accountName \
   -g $resourceGroupName

Répertorier les clés de compte en lecture seule

Obtenez les clés en lecture seule pour un compte Azure Cosmos DB.

# List read-only account keys
resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'

az cosmosdb keys list \
    -n $accountName \
    -g $resourceGroupName \
    --type read-only-keys

Répertorier les chaînes de connexion

Obtenez les chaînes de connexion pour un compte Azure Cosmos DB.

# List connection strings
resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'

az cosmosdb keys list \
    -n $accountName \
    -g $resourceGroupName \
    --type connection-strings

Régénérer la clé de compte

Regénérez une nouvelle clé pour un compte Azure Cosmos DB.

# Regenerate secondary account keys
# key-kind values: primary, primaryReadonly, secondary, secondaryReadonly
az cosmosdb keys regenerate \
    -n $accountName \
    -g $resourceGroupName \
    --key-kind secondary

Base de données Azure Cosmos DB

Les sections suivantes montrent comment gérer la base de données Azure Cosmos DB, et notamment de :

• Créer une base de données
• Créer une base de données avec débit partagé
• Migrer le débit d’une base de données vers la mise à l’échelle automatique
• Modifier le débit de la base de données
• Empêcher la suppression d’une base de données

Création d'une base de données

Crée une base de données Azure Cosmos DB.

resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'

az cosmosdb sql database create \
    -a $accountName \
    -g $resourceGroupName \
    -n $databaseName

Créer une base de données avec débit partagé

Créez une base de données Azure Cosmos DB avec débit partagé.

resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
throughput=400

az cosmosdb sql database create \
    -a $accountName \
    -g $resourceGroupName \
    -n $databaseName \
    --throughput $throughput

Migrer le débit d’une base de données vers la mise à l’échelle automatique

resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'

# Migrate to autoscale throughput
az cosmosdb sql database throughput migrate \
    -a $accountName \
    -g $resourceGroupName \
    -n $databaseName \
    -t 'autoscale'

# Read the new autoscale max throughput
az cosmosdb sql database throughput show \
    -g $resourceGroupName \
    -a $accountName \
    -n $databaseName \
    --query resource.autoscaleSettings.maxThroughput \
    -o tsv

Modifier le débit de la base de données

Augmentez le débit d’une base de données Azure Cosmos DB de 1000 RU/s.

resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
newRU=1000

# Get minimum throughput to make sure newRU is not lower than minRU
minRU=$(az cosmosdb sql database throughput show \
    -g $resourceGroupName -a $accountName -n $databaseName \
    --query resource.minimumThroughput -o tsv)

if [ $minRU -gt $newRU ]; then
    newRU=$minRU
fi

az cosmosdb sql database throughput update \
    -a $accountName \
    -g $resourceGroupName \
    -n $databaseName \
    --throughput $newRU

Empêcher la suppression d’une base de données

Placez un verrou de suppression de ressource Azure sur une base de données pour empêcher sa suppression. Cette fonctionnalité nécessite de verrouiller le compte Azure Cosmos DB afin qu’il ne puisse pas être modifié par les Kits de développement logiciel (SDK) de plan de données. Pour plus d’informations, consultez Prévention des modifications par les Kits de développement logiciel (SDK). Les verrous de ressources Azure peuvent également empêcher la modification d’une ressource en spécifiant un type de verrou ReadOnly. Pour une base de données Azure Cosmos DB, ils peuvent être utilisés pour empêcher la modification du débit.

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'

lockType='CanNotDelete' # CanNotDelete or ReadOnly
databaseParent="databaseAccounts/$accountName"
databaseLockName="$databaseName-Lock"

# Create a delete lock on database
az lock create --name $databaseLockName \
    --resource-group $resourceGroupName \
    --resource-type Microsoft.DocumentDB/sqlDatabases \
    --lock-type $lockType \
    --parent $databaseParent \
    --resource $databaseName

# Delete lock on database
lockid=$(az lock show --name $databaseLockName \
        --resource-group $resourceGroupName \
        --resource-type Microsoft.DocumentDB/sqlDatabases \
        --resource $databaseName \
        --parent $databaseParent \
        --output tsv --query id)
az lock delete --ids $lockid

Conteneur Azure Cosmos DB

Les sections suivantes montrent comment gérer le conteneur Azure Cosmos DB, et notamment de :

• Créer un conteneur
• Créer un conteneur avec mise à l’échelle automatique
• Créer un conteneur avec durée de vie (TTL) activée
• Créer un conteneur avec stratégie d’index personnalisée
• Modifier le débit d’un conteneur
• Migrer le débit d’un conteneur vers la mise à l’échelle automatique
• Empêcher la suppression d’un conteneur

Créez un conteneur.

Créez un conteneur Azure Cosmos DB avec la stratégie d'index, la clé de partition et le débit de 400 RU/s par défaut.

# Create a API for NoSQL container
resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
containerName='container1'
partitionKey='/myPartitionKey'
throughput=400

az cosmosdb sql container create \
    -a $accountName -g $resourceGroupName \
    -d $databaseName -n $containerName \
    -p $partitionKey --throughput $throughput

Créer un conteneur avec mise à l’échelle automatique

Créez un conteneur Azure Cosmos DB avec la stratégie d’index, la clé de partition et le débit avec mise à l’échelle automatique de 4000 RU/s par défaut.

# Create a API for NoSQL container
resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
containerName='container1'
partitionKey='/myPartitionKey'
maxThroughput=4000

az cosmosdb sql container create \
    -a $accountName -g $resourceGroupName \
    -d $databaseName -n $containerName \
    -p $partitionKey --max-throughput $maxThroughput

Créer un conteneur avec durée de vie (TTL)

Créer un conteneur Azure Cosmos DB avec TTL activé.

# Create an Azure Cosmos DB container with TTL of one day
resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
containerName='container1'

az cosmosdb sql container update \
    -g $resourceGroupName \
    -a $accountName \
    -d $databaseName \
    -n $containerName \
    --ttl=86400

Créer un conteneur avec stratégie d'index personnalisée

Créez un conteneur Azure Cosmos DB avec stratégie d'index personnalisée, index spatial, index composite, clé de partition et débit de 400 RU/s.

# Create a API for NoSQL container
resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
containerName='container1'
partitionKey='/myPartitionKey'
throughput=400

# Generate a unique 10 character alphanumeric string to ensure unique resource names
uniqueId=$(env LC_CTYPE=C tr -dc 'a-z0-9' < /dev/urandom | fold -w 10 | head -n 1)

# Define the index policy for the container, include spatial and composite indexes
idxpolicy=$(cat << EOF
{
    "indexingMode": "consistent",
    "includedPaths": [
        {"path": "/*"}
    ],
    "excludedPaths": [
        { "path": "/headquarters/employees/?"}
    ],
    "spatialIndexes": [
        {"path": "/*", "types": ["Point"]}
    ],
    "compositeIndexes":[
        [
            { "path":"/name", "order":"ascending" },
            { "path":"/age", "order":"descending" }
        ]
    ]
}
EOF
)
# Persist index policy to json file
echo "$idxpolicy" > "idxpolicy-$uniqueId.json"


az cosmosdb sql container create \
    -a $accountName -g $resourceGroupName \
    -d $databaseName -n $containerName \
    -p $partitionKey --throughput $throughput \
    --idx @idxpolicy-$uniqueId.json

# Clean up temporary index policy file
rm -f "idxpolicy-$uniqueId.json"

Modifier le débit d’un conteneur

Augmentez le débit d’un conteneur Azure Cosmos DB de 1000 RU/s.

resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
containerName='container1'
newRU=1000

# Get minimum throughput to make sure newRU is not lower than minRU
minRU=$(az cosmosdb sql container throughput show \
    -g $resourceGroupName -a $accountName -d $databaseName \
    -n $containerName --query resource.minimumThroughput -o tsv)

if [ $minRU -gt $newRU ]; then
    newRU=$minRU
fi

az cosmosdb sql container throughput update \
    -a $accountName \
    -g $resourceGroupName \
    -d $databaseName \
    -n $containerName \
    --throughput $newRU

Migrer le débit d’un conteneur vers la mise à l’échelle automatique

resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
containerName='container1'

# Migrate to autoscale throughput
az cosmosdb sql container throughput migrate \
    -a $accountName \
    -g $resourceGroupName \
    -d $databaseName \
    -n $containerName \
    -t 'autoscale'

# Read the new autoscale max throughput
az cosmosdb sql container throughput show \
    -g $resourceGroupName \
    -a $accountName \
    -d $databaseName \
    -n $containerName \
    --query resource.autoscaleSettings.maxThroughput \
    -o tsv

Empêcher la suppression d’un conteneur

Placez un verrou de suppression de ressource Azure sur un conteneur pour empêcher sa suppression. Cette fonctionnalité nécessite de verrouiller le compte Azure Cosmos DB afin qu’il ne puisse pas être modifié par les Kits de développement logiciel (SDK) de plan de données. Pour plus d’informations, consultez Prévention des modifications par les Kits de développement logiciel (SDK). Les verrous de ressources Azure peuvent également empêcher la modification d’une ressource en spécifiant un type de verrou ReadOnly. Pour un conteneur Azure Cosmos DB, les verrouillages peuvent être utilisés pour empêcher la modification du débit ou de toute autre propriété.

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
containerName='container1'

lockType='CanNotDelete' # CanNotDelete or ReadOnly
databaseParent="databaseAccounts/$accountName"
containerParent="databaseAccounts/$accountName/sqlDatabases/$databaseName"
containerLockName="$containerName-Lock"

# Create a delete lock on container
az lock create --name $containerLockName \
    --resource-group $resourceGroupName \
    --resource-type Microsoft.DocumentDB/containers \
    --lock-type $lockType \
    --parent $containerParent \
    --resource $containerName

# Delete lock on container
lockid=$(az lock show --name $containerLockName \
        --resource-group $resourceGroupName \
        --resource-type Microsoft.DocumentDB/containers \
        --resource-name $containerName \
        --parent $containerParent \
        --output tsv --query id)
az lock delete --ids $lockid

Étapes suivantes

Pour plus d’informations sur l’interface Azure CLI, consultez :

• Installation de l’interface de ligne de commande Azure
• Référence de ligne de Commande
• Autres exemples Azure CLI pour Azure Cosmos DB