Compartir a través de


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

  • 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

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:

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:

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: