Gerenciar recursos do Azure Cosmos DB for NoSQL usando a CLI do Azure

  • Artigo

APLICA-SE A: NoSQL

O guia a seguir descreve os comandos comuns para automatizar o gerenciamento de contas, os bancos de dados e os contêineres do Azure Cosmos DB usando a CLI do Azure. As páginas de referência de todos os comandos do Azure Cosmos DB CLI estão disponíveis na Referência de CLI do Azure. Você também pode encontrar mais exemplos em amostras de CLI do Azure para o Azure Cosmos DB, incluindo como criar e gerenciar contas, bancos de dados e contêineres do Azure Cosmos DB para MongoDB, Gremlin, Cassandra e API do Table.

Pré-requisitos

  • Este artigo requer a versão 2.22.1 ou posterior da CLI do Azure. Se você está usando o Azure Cloud Shell, a versão mais recente já está instalada.

Para obter exemplos da CLI do Azure para outras APIs, confira Exemplos de CLI para o Cassandra, Exemplos de CLI para a API do MongoDB, Exemplos de CLI para o Gremlin, Exemplos de CLI para o Table

Importante

Os recursos Azure Cosmos DB não podem ser renomeados, pois isso viola como o Azure Resource Manager funciona com URIs de recursos.

Contas do Azure Cosmos DB

As seguintes seções demonstram como gerenciar a conta do Azure Cosmos DB, incluindo:

Criar uma conta do Azure Cosmos DB

Crie uma conta do Azure Cosmos DB com a API para NoSQL, consistência de sessão nas regiões Oeste dos EUA e Leste dos EUA:

Importante

O nome da conta do Azure Cosmos DB deve ser em minúsculas e menor que 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

Adicionar ou remover regiões

Crie uma conta do Azure Cosmos DB com duas regiões, adicione uma região e remova uma região.

Observação

Não é possível adicionar ou remover regiões locations simultaneamente nem alterar outras propriedades de uma conta do Azure Cosmos DB. A modificação de regiões precisa ser executada como uma operação separada de qualquer outra alteração no recurso da conta.

Observação

Este comando permite adicionar e remover regiões, mas não permite modificar as prioridades de failover nem disparar um failover manual. Confira Definir prioridade de failover e Disparar failover manual.

Dica

Quando uma nova região é adicionada, todos os dados devem ser totalmente replicados e confirmados na nova região antes que a região seja marcada como disponível. O tempo para esta operação dependerá da quantidade de dados armazenados na conta. Se uma operação de dimensionamento de taxa de transferência assíncrona estiver em andamento, a operação de expansão de taxa de transferência será pausada e será retomada automaticamente quando a operação de adicionar/remover região for concluída.

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 várias regiões de gravação

Habilitar gravação em várias regiões em uma conta do 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

Definir prioridade de failover

Defina a prioridade de failover para uma conta do Azure Cosmos DB configurada para failover gerenciado pelo serviço

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

Habilitar o failover gerenciado pelo serviço

# 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

Disparar failover manual

Cuidado

Alterar a região com prioridade = 0 disparará um failover manual para uma conta do Azure Cosmos DB. Nenhuma outra alteração de prioridade disparará um failover.

Observação

Se você executar uma operação manual de failover enquanto uma operação de dimensionamento de taxa de transferência assíncrona estiver em andamento, a operação de expansão de taxa de transferência será pausada. Ela será retomada automaticamente quando a operação de failover for concluída.

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

Listar todas as chaves de conta

Liste todas as chaves para uma conta do Azure Cosmos DB.

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

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

Listar chaves de conta somente leitura

Obtenha as chaves somente leitura para uma conta do Azure Cosmos DB.

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

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

Cadeias de caracteres de conexão de lista

Liste as cadeias de conexão para uma conta do Azure Cosmos DB.

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

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

Regenerar a chave de conta

Regenere uma nova chave para uma conta do 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

Banco de Dados do Azure Cosmos DB

As seguintes seções demonstram como gerenciar o banco de dados do Azure Cosmos DB, incluindo:

Criar um banco de dados

Crie um banco de dados do Azure Cosmos DB.

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

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

Criar um banco de dados com taxa de transferência compartilhada

Crie um banco de dados do Azure Cosmos DB com taxa de transferência compartilhada.

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

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

Migrar um banco de dados para taxa de transferência de dimensionamento automático

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

Alterar taxa de transferência de bancos de dados

Aumente a taxa de transferência de um banco de dados do Azure Cosmos DB em 1.000 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 um banco de dados seja excluído

Coloque um bloqueio de exclusão de recurso do Azure em um banco de dados para impedir que ele seja excluído. Esse recurso requer que o bloqueio da conta do Azure Cosmos DB seja alterado pelos SDKs do plano de dados. Para saber mais, consulte impedindo alterações de SDKs. Os bloqueios de recursos do Azure também podem impedir que um recurso seja alterado, especificando um tipo de bloqueio ReadOnly. Para um banco de dados do Azure Cosmos DB, isso pode ser usado para impedir que a taxa de transferência seja alterada.

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

Contêiner do Azure Cosmos DB

As seguintes seções demonstram como gerenciar o contêiner do Azure Cosmos DB, incluindo:

Criar um contêiner

Crie um contêiner do Azure Cosmos DB com política de índice padrão, chave de partição e RU/s de 400.

# 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

Criar um contêiner com dimensionamento automático

Crie um contêiner do Azure Cosmos DB com política de índice padrão, chave de partição e RU/s de dimensionamento automático de 4.000.

# 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

Criar um contêiner com TTL

Crie um contêiner do Azure Cosmos DB com 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

Criar um contêiner com a política de índice personalizada

Crie um contêiner do Azure Cosmos DB com uma política de índice personalizada, um índice espacial, um índice composto, uma chave de partição e RU/s de 400.

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

Alterar a taxa de transferência do contêiner

Aumente a taxa de transferência de um contêiner do Azure Cosmos DB em 1.000 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

Migrar um contêiner para taxa de transferência de dimensionamento automático

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 um contêiner seja excluído

Coloque um bloqueio de exclusão de recurso do Azure em um contêiner para impedir que ele seja excluído. Esse recurso requer que o bloqueio da conta do Azure Cosmos DB seja alterado pelos SDKs do plano de dados. Para saber mais, consulte impedindo alterações de SDKs. Os bloqueios de recursos do Azure também podem impedir que um recurso seja alterado, especificando um tipo de bloqueio ReadOnly. Para um contêiner do Azure Cosmos DB, os bloqueios podem ser usados para impedir que a taxa de transferência ou qualquer outra propriedade seja alterada.

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

Próximas etapas

Para obter mais informações sobre a CLI do Azure, consulte: