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

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

• Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.

  

• Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.

  • Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.

  • Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.

  • Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

• 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

Contas do Azure Cosmos DB

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

• Criar uma conta do BD Cosmos do Azure
• Adicionar ou remover regiões
• Habilitar gravações de várias regiões
• Definir prioridade de failover regional
• Habilitar o failover gerenciado pelo serviço
• Disparar failover manual
• Listar chaves de conta
• Listar chaves de conta somente leitura
• Cadeias de caracteres de conexão de lista
• Regenerar a chave de conta

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:

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.

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

# 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
• Criar um banco de dados com taxa de transferência compartilhada
• Migrar um banco de dados para taxa de transferência de dimensionamento automático
• Alterar a taxa de transferência de bancos de dados
• Impedir que um banco de dados seja excluído

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
• Criar um contêiner com dimensionamento automático
• Criar um contêiner com TTL habilitado
• Criar um contêiner com a política de índice personalizada
• Alterar a taxa de transferência do contêiner
• Migrar um contêiner para taxa de transferência de dimensionamento automático
• Impedir que um contêiner seja excluído

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:

• Instalar a CLI do Azure.
• Referência à CLI do Azure
• Mais exemplos da CLI do Azure para o Azure Cosmos DB