Gestire le risorse di Azure Cosmos DB for NoSQL usando l'interfaccia della riga di comando di Azure

SI APPLICA A: NoSQL

La guida seguente illustra i comandi comuni per automatizzare la gestione degli account, dei database e dei contenitori di Azure Cosmos DB usando l'interfaccia della riga di comando di Azure. Per tutti i comandi dell'interfaccia della riga di comando di Azure Cosmos DB sono disponibili pagine di riferimento in Informazioni di riferimento sull'interfaccia della riga di comando di Azure. Altri esempi sono disponibili in Esempi dell'interfaccia della riga di comando di Azure Cosmos DB, incluse le procedure per creare e gestire gli account, i database e i contenitori di Azure Cosmos DB per MongoDB, Gremlin, Cassandra e API per Table.

Prerequisiti

• Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Avvio rapido su Bash in Azure Cloud Shell.

  

• Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.

  • Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Accedere tramite l'interfaccia della riga di comando di Azure.

  • Quando richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare le estensioni con l'interfaccia della riga di comando di Azure.

  • Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.

• Questo articolo richiede la versione 2.22.1 o successiva dell'interfaccia della riga di comando di Azure. Se si usa Azure Cloud Shell, la versione più recente è già installata.

Per gli esempi dell'interfaccia della riga di comando di Azure relativi ad altre API, vedere Esempi dell'interfaccia della riga di comando per Cassandra, Esempi dell'interfaccia della riga di comando per l'API per MongoDB, Esempi dell'interfaccia della riga di comando per Gremlin, Esempi dell'interfaccia della riga di comando per Tabella

Importante

Le risorse di Azure Cosmos DB non possono essere rinominate perché violano il funzionamento di Azure Resource Manager con gli URI delle risorse.

Account Azure Cosmos DB

Le sezioni seguenti illustrano come gestire l'account Azure Cosmos DB:

• Creare un account di Azure Cosmos DB
• Aggiungere o rimuovere aree
• Abilitare scritture in più aree
• Impostare la priorità di failover a livello di area
• Abilitare il failover gestito dal servizio
• Attivare un failover manuale
• Elencare le chiavi dell'account
• Elencare le chiavi dell'account di sola lettura
• Elencare le stringhe di connessione
• Rigenerare una chiave dell'account

Creare un account Azure Cosmos DB

Creare un account Azure Cosmos DB con API per NoSQL e coerenza della sessione nelle aree Stati Uniti occidentali e Stati Uniti orientali:

Importante

Il nome dell'account Azure Cosmos DB deve essere minuscolo e con meno di 44 caratteri.

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

Aggiungere o rimuovere aree

Creare un account Azure Cosmos DB con due aree, aggiungere un'area e rimuovere un'area.

Nota

Non è possibile aggiungere o rimuovere simultaneamente aree locations e cambiare l'ordine delle proprietà per un account Azure Cosmos DB. La modifica delle aree deve essere eseguita come operazione distinta rispetto a qualsiasi altra modifica apportata alla risorsa dell'account.

Nota

Questo comando consente di aggiungere e rimuovere aree, ma non di modificare le priorità di failover o attivare un failover manuale. Vedere Impostare la priorità di failover e Attivare un failover manuale.

Suggerimento

Quando viene aggiunta una nuova area, occorre eseguire la replica completa e il commit di tutti i dati nella nuova area prima che l'area venga contrassegnata come disponibile. La quantità di tempo necessaria per questa operazione dipenderà dalla quantità di dati archiviati nell'account. Se è in corso un'operazione asincrona di ridimensionamento della velocità effettiva, l'operazione di aumento della velocità effettiva verrà sospesa e riprenderà automaticamente al termine dell'operazione di aggiunta/rimozione dell'area.

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

Abilitare più aree di scrittura

Abilitare le scritture in più aree per un account 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

Configurare la priorità failover

Impostare la priorità di failover per un account Azure Cosmos DB configurato per il failover gestito dal servizio

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

Abilitare il failover gestito dal servizio

# 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

Attivare un failover manuale

Attenzione

La modifica dell'area con priorità = 0 attiverà un failover manuale per un account Azure Cosmos DB. Qualsiasi altra modifica della priorità non attiverà un failover.

Nota

Se si esegue un'operazione di failover manuale mentre è in corso un'operazione asincrona di ridimensionamento della velocità effettiva, l'operazione di aumento della velocità effettiva verrà sospesa. Riprenderà automaticamente al termine dell'operazione di failover.

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

Elencare le chiavi dell'account

Ottenere tutte le chiavi per un account Azure Cosmos DB.

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

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

Elencare le chiavi dell'account di sola lettura

Ottenere le chiavi di sola lettura per un account Azure Cosmos DB.

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

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

Elencare le stringhe di connessione

Ottenere le stringhe di connessione per un account Azure Cosmos DB.

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

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

Rigenerare una chiave dell'account

Rigenerare una nuova chiave per un account 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

Database Azure Cosmos DB

Le sezioni seguenti illustrano come gestire il database Azure Cosmos DB:

• Creare un database
• Creare un database con velocità effettiva condivisa
• Eseguire la migrazione di un database per sfruttare la scalabilità automatica della velocità effettiva
• Modificare la velocità effettiva del database
• Impedire l'eliminazione di un database

Creazione di un database

Crea un database di Azure Cosmos DB.

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

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

Creare un database con velocità effettiva condivisa

Creare un database Azure Cosmos DB con velocità effettiva condivisa.

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

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

Eseguire la migrazione di un database per sfruttare la scalabilità automatica della velocità effettiva

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

Modificare la velocità effettiva del database

Aumentare la velocità effettiva di un database di Azure Cosmos DB di 1000 UR/sec.

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

Impedire l'eliminazione di un database

Inserire un blocco di eliminazione delle risorse di Azure in un database per impedirne l'eliminazione. Questa funzionalità richiede che l'account Azure Cosmos DB venga modificato dagli SDK del piano dati. Per altre informazioni, vedere Impedire modifiche dagli SDK. I blocchi delle risorse di Azure possono anche impedire che una risorsa venga modificata specificando un tipo di blocco ReadOnly. Per un database di Azure Cosmos DB, può essere usato per impedire la modifica della velocità effettiva.

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

Contenitore Azure Cosmos DB

Le sezioni seguenti illustrano come gestire il contenitore Azure Cosmos DB:

• Creare un contenitore
• Creare un contenitore con scalabilità automatica
• Creare un contenitore con TTL abilitato
• Creare un contenitore con un criterio di indicizzazione personalizzato
• Modificare la velocità effettiva del contenitore
• Eseguire la migrazione di un contenitore per sfruttare la scalabilità automatica della velocità effettiva
• Impedire l'eliminazione di un contenitore

Creazione di un contenitore

Creare un contenitore di Azure Cosmos DB con criteri di indice predefiniti, chiave di partizione e UR/sec pari a 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

Creare un contenitore con scalabilità automatica

Creare un contenitore di Azure Cosmos DB con criteri di indice predefiniti, chiave di partizione e UR/sec di scalabilità automatica pari a 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

Creare un contenitore con TTL

Creare un contenitore Azure Cosmos DB con TTL abilitato.

# 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

Creare un contenitore con criteri di indice personalizzati

Creare un contenitore Azure Cosmos DB con criteri di indice personalizzati, un indice spaziale, un indice composito, una chiave di partizione e UR/sec di 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"

Modificare la velocità effettiva del contenitore

Aumentare la velocità effettiva di un contenitore Azure Cosmos DB di 1000 UR/sec.

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

Eseguire la migrazione di un contenitore per sfruttare la scalabilità automatica della velocità effettiva

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

Impedire l'eliminazione di un contenitore

Inserire un blocco di eliminazione delle risorse di Azure in un contenitore per impedirne l'eliminazione. Questa funzionalità richiede che l'account Azure Cosmos DB venga modificato dagli SDK del piano dati. Per altre informazioni, vedere Impedire modifiche dagli SDK. I blocchi delle risorse di Azure possono anche impedire che una risorsa venga modificata specificando un tipo di blocco ReadOnly. Per un contenitore Azure Cosmos DB, è possibile usare i blocchi per impedire la modifica della velocità effettiva o di qualsiasi altra proprietà.

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

Passaggi successivi

Per altre informazioni sull'interfaccia della riga di comando di Azure, vedere:

• Installazione dell'interfaccia della riga di comando di Azure
• Informazioni di riferimento sull'interfaccia della riga di comando di Azure
• Altri esempi di interfaccia della riga di comando di Azure per Azure Cosmos DB