Partilhar via

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

  • Artigo

APLICA-SE A: NoSQL

O guia a seguir descreve os comandos comuns para automatizar a gestão das contas, das bases de dados e dos containers do Azure Cosmos DB com a CLI do Azure. As páginas de referência para todos os comandos da CLI do Azure Cosmos DB encontram-se disponíveis em Referência da CLI do Azure. Você também pode encontrar mais exemplos em exemplos 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 for Table.

Pré-requisitos

  • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.

  • Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

    • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

    • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

    • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

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

Para exemplos de CLI do Azure para outras APIs, consulte Exemplos de CLI para Cassandra, Exemplos de CLI para API para MongoDB, Amostras de CLI para Gremlin, Amostras de CLI para Tabela

Importante

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

Azure Cosmos DBAccounts

As seções a seguir 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 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 minúsculo e ter 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

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.

Nota

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

Nota

Este comando permite adicionar e remover regiões, mas não permite modificar prioridades de failover ou acionar um failover manual. Consulte Definir prioridade de failover e Acionar failover manual.

Gorjeta

Quando é adicionada uma nova região, todos os dados têm de estar totalmente replicados e consolidados na nova região antes desta ser marcada como disponível. O tempo que esta operação demora dependerá da quantidade de dados armazenados na conta. Se uma operação de dimensionamento assíncrono de taxa de transferência estiver em andamento, a operação de expansão de taxa de transferência será pausada e 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ções em várias regiões para 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

Definir a prioridade de failover para uma conta do Azure Cosmos DB configurada para failover gerenciado por 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 failover gerenciado por 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

Acionar failover manual

Atenção

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

Nota

Se você executar uma operação de failover manual enquanto uma operação de dimensionamento assíncrono de taxa de transferência estiver em andamento, a operação de expansão de taxa de transferência será pausada. Ele será retomado 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

Obtenha 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 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

Listar cadeias de conexão

Obtenha 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 da 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

Base de dados do Azure Cosmos DB

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

Criar uma base de dados

Crie uma base 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 dimensionar automaticamente a taxa de transferência

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 a taxa de transferência do banco de dados

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

Coloque um bloqueio de exclusão de recursos do Azure em um banco de dados para impedir que ele seja excluído. Esse recurso requer o bloqueio da conta do Azure Cosmos DB de ser alterada por SDKs de plano de dados. Para saber mais, consulte Prevenção de alterações de SDKs. Os bloqueios de recursos do Azure também podem impedir que um recurso seja alterado especificando um tipo de ReadOnly bloqueio. Para um banco de dados do Azure Cosmos DB, ele 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 seções a seguir demonstram como gerenciar o contêiner do Azure Cosmos DB, incluindo:

Criar um contentor

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 escala automática de 4000.

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

Migrar um contêiner para dimensionar automaticamente a taxa de transferência

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 evitar que ele seja excluído. Esse recurso requer o bloqueio da conta do Azure Cosmos DB de ser alterada por SDKs de plano de dados. Para saber mais, consulte Prevenção de alterações de SDKs. Os bloqueios de recursos do Azure também podem impedir que um recurso seja alterado especificando um tipo de ReadOnly bloqueio. 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óximos passos

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