Gerir recursos do Azure Cosmos DB para NoSQL com a CLI do Azure
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 contentores 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 estão disponíveis na Referência da CLI do Azure. Também pode encontrar mais exemplos em exemplos da CLI do Azure para o Azure Cosmos DB, incluindo como criar e gerir contas, bases de dados e contentores do Azure Cosmos DB para MongoDB, Gremlin, Cassandra e API para Tabela.
Pré-requisitos
Utilize o ambiente bash no Azure Cloud Shell. Para obter mais informações, veja Início Rápido do 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, veja Como executar a CLI do Azure num contentor 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 início de sessão, veja Iniciar sessão com a CLI do Azure.
Quando lhe for pedido, 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 a utilizar o Azure Cloud Shell, a versão mais recente já está instalada.
Para exemplos da CLI do Azure para outras APIs, veja Exemplos da CLI para Cassandra, Exemplos da CLI para a API para MongoDB, Exemplos da CLI para Gremlin, Exemplos da CLI para Tabela
Importante
Não é possível mudar o nome dos recursos do Azure Cosmos DB, uma vez que isto viola a forma como o Azure Resource Manager funciona com URIs de recursos.
Azure Cosmos DBAccounts
As secções seguintes demonstram como gerir a conta do Azure Cosmos DB, incluindo:
- Criar uma conta do Azure Cosmos DB
- Adicionar ou remover regiões
- Ativar escritas em várias regiões
- Definir prioridade de ativação pós-falha regional
- Ativar a ativação pós-falha gerida pelo serviço
- Acionar ativação pós-falha manual
- Listar chaves de conta
- Listar chaves de conta só de leitura
- Listar cadeias de ligação
- Regenerar 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 E.U.A. Oeste e E.U.A. Leste:
Importante
O nome da conta do Azure Cosmos DB tem de estar em minúsculas e ter menos de 44 carateres.
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 pode adicionar ou remover regiões locations
em simultâneo e alterar outras propriedades de uma conta do Azure Cosmos DB. A modificação das regiões tem de ser efetuada como uma operação separada do que qualquer outra alteração ao recurso da conta.
Nota
Este comando permite-lhe adicionar e remover regiões, mas não lhe permite modificar prioridades de ativação pós-falha ou acionar uma ativação pós-falha manual. Veja Definir prioridade de ativação pós-falha e Acionar ativação pós-falha manual.
Dica
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. A quantidade de tempo que esta operação demora dependerá da quantidade de dados armazenados na conta. Se estiver em curso uma operação de dimensionamento de débito assíncrono , a operação de aumento vertical de débito será colocada em pausa e será retomada automaticamente quando a operação de adicionar/remover região estiver 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
Ativar várias regiões de escrita
Ativar escritas 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 ativação pós-falha
Definir a prioridade de ativação pós-falha para uma conta do Azure Cosmos DB configurada para ativação pós-falha gerida 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'
Ativar a ativação pós-falha gerida 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
Acionar ativação pós-falha manual
Atenção
Alterar a região com prioridade = 0 acionará uma ativação pós-falha manual para uma conta do Azure Cosmos DB. Qualquer outra alteração de prioridade não acionará uma ativação pós-falha.
Nota
Se executar uma operação de ativação pós-falha manual enquanto uma operação de dimensionamento de débito assíncrono estiver em curso, a operação de aumento vertical de débito será colocada em pausa. Será retomada automaticamente quando a operação de ativação pós-falha estiver 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 só de leitura
Obter chaves só de 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 ligação
Obtenha as cadeias de ligação de 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 chave de conta
Regenerar 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 secções seguintes demonstram como gerir a base de dados do Azure Cosmos DB, incluindo:
- Criar uma base de dados
- Criar uma base de dados com débito partilhado
- Migrar uma base de dados para o débito de dimensionamento automático
- Alterar débito da base de dados
- Impedir que uma base de dados seja eliminada
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 uma base de dados com débito partilhado
Crie uma base de dados do Azure Cosmos DB com débito partilhado.
resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
throughput=400
az cosmosdb sql database create \
-a $accountName \
-g $resourceGroupName \
-n $databaseName \
--throughput $throughput
Migrar uma base de dados para o débito 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 débito da base de dados
Aumente o débito de uma base 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 uma base de dados seja eliminada
Coloque um bloqueio de eliminação de recursos do Azure numa base de dados para impedir que seja eliminado. Esta funcionalidade requer que a conta do Azure Cosmos DB seja alterada por SDKs do plano de dados. Para saber mais, veja Impedir alterações dos SDKs. Os bloqueios de recursos do Azure também podem impedir que um recurso seja alterado ao especificar um ReadOnly
tipo de bloqueio. Para uma base de dados do Azure Cosmos DB, pode ser utilizada para impedir que o débito seja alterado.
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
Contentor do Azure Cosmos DB
As secções seguintes demonstram como gerir o contentor do Azure Cosmos DB, incluindo:
- Criar um contentor
- Criar um contentor com dimensionamento automático
- Criar um contentor com o TTL ativado
- Criar um contentor com uma política de índice personalizada
- Alterar débito do contentor
- Migrar um contentor para o débito de dimensionamento automático
- Impedir que um contentor seja eliminado
Criar um contentor
Crie um contentor do Azure Cosmos DB com política de índice predefinida, 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 contentor com dimensionamento automático
Crie um contentor do Azure Cosmos DB com política de índice predefinida, chave de partição e RU/s de dimensionamento automático 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 contentor com TTL
Crie um contentor do Azure Cosmos DB com o TTL ativado.
# 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 contentor com uma política de índice personalizada
Crie um contentor 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 débito de contentor
Aumente o débito de um contentor 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 contentor para o débito 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 contentor seja eliminado
Coloque um bloqueio de eliminação de recursos do Azure num contentor para impedir que seja eliminado. Esta funcionalidade requer que a conta do Azure Cosmos DB seja alterada pelos SDKs do plano de dados. Para saber mais, veja impedir alterações de SDKs. Os bloqueios de recursos do Azure também podem impedir que um recurso seja alterado ao especificar um ReadOnly
tipo de bloqueio. Para um contentor do Azure Cosmos DB, os bloqueios podem ser utilizados para impedir que o débito ou qualquer outra propriedade seja alterado.
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
Passos seguintes
Para obter mais informações sobre a CLI do Azure, consulte: