Administración de recursos de Azure Cosmos DB for NoSQL mediante la CLI de Azure

SE APLICA A: NoSQL

En la siguiente guía, se describen los comandos comunes para automatizar la administración de las cuentas, las bases de datos y los contenedores de Azure Cosmos DB mediante la CLI de Azure. Hay páginas de referencia para todos los comandos de CLI de Azure Cosmos DB disponibles en la referencia de la CLI de Azure. Para ver más ejemplos, consulte Ejemplos de la CLI de Azure para Azure Cosmos DB, que incluye ejemplos sobre cómo crear y administrar cuentas, bases de datos y contenedores de Azure Cosmos DB para MongoDB, Gremlin, Cassandra y API para Table.

Requisitos previos

• Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Inicio rápido para Bash en Azure Cloud Shell.

  

• Si prefiere ejecutar comandos de referencia de la CLI localmente, instale la CLI de Azure. Si utiliza Windows o macOS, considere la posibilidad de ejecutar la CLI de Azure en un contenedor Docker. Para más información, vea Ejecución de la CLI de Azure en un contenedor de Docker.

  • Si usa una instalación local, inicie sesión en la CLI de Azure mediante el comando az login. Siga los pasos que se muestran en el terminal para completar el proceso de autenticación. Para ver otras opciones de inicio de sesión, consulte Inicio de sesión con la CLI de Azure.

  • En caso de que se le solicite, instale las extensiones de la CLI de Azure la primera vez que la use. Para más información sobre las extensiones, consulte Uso de extensiones con la CLI de Azure.

  • Ejecute az version para buscar cuál es la versión y las bibliotecas dependientes que están instaladas. Para realizar la actualización a la versión más reciente, ejecute az upgrade.

• En este artículo se necesita la versión 2.22.1, o versiones posteriores, de la CLI de Azure. Si usa Azure Cloud Shell, ya está instalada la versión más reciente.

Para ver ejemplos de la CLI de Azure para otras API, consulte Ejemplos de la CLI para Cassandra, Ejemplos de la CLI para la API para MongoDB, Ejemplos de la CLI para Gremlin, Ejemplos de la CLI para Table.

Importante

No se puede cambiar el nombre de los recursos de Azure Cosmos DB, ya que esto infringe la forma de funcionar de Azure Resource Manager con los URI de recursos.

Cuentas de Azure Cosmos DB

En las secciones siguientes se muestra cómo administrar la cuenta de Azure Cosmos DB, por ejemplo:

• Creación de una cuenta de Azure Cosmos DB
• Agregar o quitar regiones
• Habilitación de escrituras en varias regiones
• Establecimiento de la prioridad de conmutación por error regional
• Habilitación de la conmutación por error administrada por servicio
• Desencadenamiento de una conmutación por error manual
• Enumeración de claves de cuenta
• Enumeración de claves de cuenta de solo lectura
• Enumeración de cadenas de conexión
• Regeneración de la clave de cuenta

Creación de una cuenta de Azure Cosmos DB

Cree una cuenta de Azure Cosmos DB con la API para NoSQL y la coherencia de sesión en las regiones Oeste de EE. UU. y Este de EE. UU.:

Importante

El nombre de la cuenta de Azure Cosmos DB debe estar en minúscula y tener menos de 44 caracteres.

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

Agregar o quitar regiones

Cree una cuenta de Azure Cosmos DB con dos regiones, agregue una región y quite otra.

Nota

En una cuenta de Azure Cosmos DB no es posible agregar o quitar regiones (locations) al mismo tiempo ni cambiar otras propiedades. La modificación de regiones debe realizarse como una operación independiente, nunca a la vez que otro cambio en el recurso de la cuenta.

Nota:

Este comando permite agregar y quitar regiones, pero no permite modificar las prioridades de conmutación por error ni desencadenar una conmutación por error manual. Consulte Establecimiento de la prioridad de conmutación por error y Desencadenamiento de una conmutación por error manual.

Sugerencia

Cuando se agrega una nueva región, todos los datos deben replicarse por completo y estar confirmados en la nueva región antes de que la región se marque como disponible. La cantidad de tiempo que tarde esta operación dependerá de la cantidad de datos almacenados en la cuenta. Si hay una operación asincrónica de escalado del rendimiento en curso, la operación de escalado vertical del rendimiento se pausa y se reanuda automáticamente cuando se completa la operación de agregar o quitar región.

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

Habilitar regiones de varias escrituras

Habilitación de la escritura en varias regiones en una cuenta de 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

Establecimiento de la prioridad de conmutación por error

Establecimiento de la prioridad de conmutación por error para una cuenta de Azure Cosmos DB configurada para la conmutación por error administrada por servicio

# 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'

Habilitación de la conmutación por error administrada por servicio

# 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

Desencadenamiento de una conmutación por error manual

Precaución

Al cambiar una región con una prioridad = 0, se desencadenará una conmutación por error manual para una cuenta de Azure Cosmos DB. Los restantes cambios de prioridad no desencadenarán ninguna conmutación por error.

Nota:

Si realiza una operación de conmutación por error manual mientras hay una operación asincrónica de escalado del rendimiento en curso, la operación de escalado vertical del rendimiento se pausa. Se reanuda automáticamente cuando se completa la operación de conmutación por error.

# 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'

Enumeración de todas las claves de cuenta

Obtenga todas las claves para una cuenta de Azure Cosmos DB.

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

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

Enumeración de claves de cuenta de solo lectura

Obtenga las claves de solo lectura para una cuenta de Azure Cosmos DB.

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

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

Enumeración de cadenas de conexión

Obtenga las cadenas de conexión para una cuenta de Azure Cosmos DB.

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

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

Regeneración de la clave de cuenta

Regenere una nueva clave para una cuenta de 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 datos de Azure Cosmos DB

En las siguientes secciones se muestra cómo se administra la base de datos de Azure Cosmos DB, lo que incluye:

• Creación de una base de datos
• Creación de una base de datos con capacidad de proceso compartida
• Migración de una base de datos a rendimiento de escalabilidad automática
• Cambio del rendimiento de una base de datos
• Impedir que se elimine una base de datos

Crear una base de datos

Crea una base de datos de Azure Cosmos DB.

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

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

Creación de una base de datos con capacidad de proceso compartida

Cree una base de datos de Azure Cosmos DB con rendimiento compartido.

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

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

Migración de una base de datos a rendimiento de escalabilidad automática

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

Cambio del rendimiento de una base de datos

Aumente el rendimiento de una base de datos de Azure Cosmos DB en 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

Impedir que se elimine una base de datos

Coloque un bloqueo de eliminación de recursos de Azure en una base de datos para evitar que se elimine. Esta característica requiere impedir que la cuenta de Azure Cosmos DB se modifique mediante los SDK de plano de datos. Para más información, consulte Bloqueo en los SDK de Azure Cosmos DB para evitar cambios. Los bloqueos de recursos de Azure también pueden impedir que se cambie un recurso mediante la especificación de un tipo de bloqueo ReadOnly. En una base de datos de Azure Cosmos DB, se puede usar para evitar que se cambie el rendimiento.

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

Contenedor de Azure Cosmos DB

En las siguientes secciones se muestra cómo administrar el contenedor de Azure Cosmos DB, lo que incluye:

• Creación de un contenedor
• Creación de un contenedor con escalabilidad automática
• Creación de un contenedor con TTL habilitado
• Creación de un contenedor con una directiva de índice personalizada
• Cambio del rendimiento del contenedor
• Migración de un contenedor a rendimiento de escalabilidad automática
• Impedir que se elimine un contenedor

Crear un contenedor

Cree un contenedor de Azure Cosmos DB con una directiva de índice predeterminada, una clave de partición y 400 RU/s.

# 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

Creación de un contenedor con escalabilidad automática

Cree un contenedor de Azure Cosmos DB con una directiva de índice predeterminada, una clave de partición y 4000 RU/s de escalabilidad automática.

# 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

Creación de un contenedor con TTL

Cree un contenedor de Azure Cosmos DB con TTL habilitado.

# 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

Creación de un contenedor con directiva de índice personalizada

Cree un contenedor de Azure Cosmos DB con una directiva de índice personalizada, un índice espacial, un índice compuesto, una clave de partición y 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"

Cambio del rendimiento del contenedor

Aumente el rendimiento de un contenedor de Azure Cosmos DB en 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

Migración de un contenedor a rendimiento de escalabilidad automática

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

Impedir que se elimine un contenedor

Coloque un bloqueo de eliminación de recursos de Azure en un contenedor para evitar que se elimine. Esta característica requiere impedir que la cuenta de Azure Cosmos DB se modifique mediante los SDK de plano de datos. Para más información, consulte Bloqueo en los SDK de Azure Cosmos DB para evitar cambios. Los bloqueos de recursos de Azure también pueden impedir que se cambie un recurso mediante la especificación de un tipo de bloqueo ReadOnly. En un contenedor de Azure Cosmos DB, se pueden usar bloqueos para evitar que se modifique el rendimiento o cualquier otra propiedad.

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

Pasos siguientes

Para más información sobre la CLI de Azure, consulte:

• Instalación de la CLI de Azure
• Referencia de CLI de Azure
• Más ejemplos de la CLI de Azure para Azure Cosmos DB