Gerir recursos do Azure Cosmos DB para NoSQL com 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 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

  • 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

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

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

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: