Verwalten von Azure Cosmos DB for NoSQL-Ressourcen mit der Azure CLI

Das folgende Handbuch beschreibt allgemeine Befehle zum Automatisieren der Verwaltung Ihrer Azure Cosmos DB-Konten, Datenbanken und Container mit Azure CLI. Referenzseiten für alle CLI-Befehle für Azure Cosmos DB sind in der Referenz zur Azure CLI verfügbar.

Voraussetzungen

• Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter "Erste Schritte mit Azure Cloud Shell".

  

• Wenn Sie CLI-Referenzbefehle lieber lokal ausführen möchten, installieren Sie die Azure CLI. Wenn Sie mit Windows oder macOS arbeiten, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.

  • Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Um den Authentifizierungsprozess abzuschließen, führen Sie die schritte aus, die in Ihrem Terminal angezeigt werden. Weitere Anmeldeoptionen finden Sie unter Authentifizieren bei Azure mithilfe der Azure CLI.

  • Wenn Sie dazu aufgefordert werden, installieren Sie die Azure CLI-Erweiterung bei der ersten Verwendung. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden und Verwalten von Erweiterungen mit der Azure CLI.

  • Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um auf die neueste Version zu aktualisieren.

• Für diesen Artikel ist mindestens Version 2.22.1 der Azure CLI erforderlich. Wenn Sie Azure Cloud Shell verwenden, ist die neueste Version bereits installiert.

Azure CLI-Beispiele für andere APIs finden Sie unter CLI-Beispiele für Cassandra, CLI-Beispiele für die API für MongoDB, CLI-Beispiele für Gremlin und CLI-Beispiele für Table.

Azure Cosmos DB-Konten

In den folgenden Abschnitten erfahren Sie, wie Sie Azure Cosmos DB-Konten verwalten. Dabei lernen Sie u. a. Folgendes:

• Erstellen eines Azure Cosmos DB-Kontos
• Hinzufügen oder Entfernen von Regionen
• Aktivieren von Schreibvorgängen in mehreren Regionen
• Priorität der regionalen Ausfallüberbrückung festlegen
• Aktivieren des dienstseitig verwalteten Failovers
• Auslösen eines manuellen Failovers
• Auflisten von Kontoschlüsseln
• Auflisten schreibgeschützter Kontoschlüssel
• Verbindungszeichenfolgen auflisten
• Erneutes Generieren eines Kontoschlüssels

Erstellen eines Azure Cosmos DB-Kontos

Erstellen Sie ein Azure Cosmos DB-Konto mit API für NoSQL und Sitzungskonsistenz für die Regionen „USA, Westen“ und „USA, Osten“:

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

Hinzufügen oder Entfernen von Regionen

Erstellen Sie ein Azure Cosmos DB-Konto mit zwei Regionen, fügen Sie eine Region hinzu, und entfernen Sie eine Region.

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

Aktivieren mehrerer Schreibregionen

Aktivieren von Schreibvorgängen in mehreren Regionen für ein Azure Cosmos DB-Konto

# 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

Festlegen der Failoverpriorität

Festlegen der Failoverpriorität für ein Azure Cosmos DB-Konto, das für dienstseitig verwaltete Failover konfiguriert ist

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

Aktivierung des vom Dienst verwalteten Failovers

# 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

Auslösen eines manuellen Failovers

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

Auflisten aller Kontoschlüssel

Ruft alle Schlüssel für ein Azure Cosmos DB-Konto ab.

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

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

Auflisten schreibgeschützter Kontoschlüssel

Erhalten Sie schreibgeschützte Schlüssel für ein Azure Cosmos DB-Konto.

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

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

Auflisten von Verbindungszeichenfolgen

Ruft die Verbindungszeichenfolgen für ein Azure Cosmos DB-Konto ab.

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

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

Erneutes Generieren eines Kontoschlüssels

Generiert erneut einen neuen Schlüssel für ein Azure Cosmos DB-Konto.

# Regenerate secondary account keys
# key-kind values: primary, primaryReadonly, secondary, secondaryReadonly
az cosmosdb keys regenerate \
    -n $accountName \
    -g $resourceGroupName \
    --key-kind secondary

Azure Cosmos DB-Datenbank

In den folgenden Abschnitten erfahren Sie, wie Sie Azure Cosmos DB-Datenbanken verwalten. Dabei lernen Sie u. a. Folgendes:

• Erstellen einer Datenbank
• Erstellen einer Datenbank mit gemeinsam genutztem Durchsatz
• Migrieren einer Datenbank zum automatisch skalierten Durchsatz
• Ändern des Durchsatzes einer Datenbank
• Verhindern des Löschens einer Datenbank

Erstellen einer Datenbank

Erstellen Sie eine Azure Cosmos DB-Datenbank.

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

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

Erstellen einer Datenbank mit geteiltem Durchsatz

Erstellen einer Azure Cosmos DB-Datenbank mit gemeinsam genutztem Durchsatz

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

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

Migrieren einer Datenbank zum automatisch skalierten Durchsatz

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

Ändern des Durchsatzes einer Datenbank

Erhöhen des Durchsatzes einer Azure Cosmos DB-Datenbank um 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

Verhindern des Löschens einer Datenbank

Legen Sie eine Sperre für das Löschen von Azure-Ressourcen für eine Datenbank fest, um ein Löschen der Datenbank zu verhindern. Diese Funktion erfordert, dass das Azure Cosmos DB-Konto für Änderungen durch SDKs auf Datenebene gesperrt wird. Weitere Informationen finden Sie unter Verhindern von Änderungen aus SDKs. Mit Azure-Ressourcensperren kann auch verhindert werden, dass eine Ressource geändert wird. Legen Sie dazu den Sperrentyp ReadOnly fest. Für eine Azure Cosmos DB-Datenbank kann damit eine Änderung des Durchsatzes verhindert werden.

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

Azure Cosmos DB-Container

In den folgenden Abschnitten erfahren Sie, wie Sie Azure Cosmos DB-Container verwalten. Dabei lernen Sie u. a. Folgendes:

• Container erstellen
• Erstellen eines Containers mit Autoskalierung
• Erstellen eines Container mit aktivierter Gültigkeitsdauer
• Erstellen eines Containers mit benutzerdefinierter Indexrichtlinie
• Ändern des Containerdurchsatzes
• Einen Container zur automatischen Skalierung des Durchsatzes migrieren
• Verhindern des Löschens eines Containers

Einen Container erstellen

Erstellen eines Azure Cosmos DB-Containers mit standardmäßiger Indexrichtlinie, Partitionsschlüssel und einem Durchsatz von 400 RU/s

# 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

Erstellen eines Containers mit Autoskalierung

Erstellen eines Azure Cosmos DB-Containers mit standardmäßiger Indexrichtlinie, Partitionsschlüssel und Autoskalierung auf 4.000 RU/s

# 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

Container mit TTL erstellen

Erstellen eines Azure Cosmos DB-Containers mit aktivierter TTL

# 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

Erstellen eines Containers mit benutzerdefinierter Indexrichtlinie

Erstellen eines Azure Cosmos DB-Containers mit einer benutzerdefinierten Indexrichtlinie, einem räumlichen Index, einem zusammengesetzten Index, einem Partitionsschlüssel und einem Durchsatz von 400 RU/s

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

Ändern des Containerdurchsatzes

Erhöhen des Durchsatzes eines Azure Cosmos DB-Container um 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

Migrieren eines Containers zum automatisch skalierten Durchsatz

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

Verhindern des Löschens eines Containers

Legen Sie eine Sperre für das Löschen von Azure-Ressourcen für einen Container fest, um ein Löschen des Containers zu verhindern. Diese Funktion erfordert, dass das Azure Cosmos DB-Konto für Änderungen durch SDKs auf Datenebene gesperrt wird. Weitere Informationen finden Sie unter Verhindern von Änderungen aus SDKs. Mit Azure-Ressourcensperren kann auch verhindert werden, dass eine Ressource geändert wird. Legen Sie dazu den Sperrentyp ReadOnly fest. Bei einem Azure Cosmos DB-Container kann eine Sperre eine Änderung des Durchsatzes oder einer anderen Eigenschaft verhindern.

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

Nächste Schritte

Weitere Informationen zur Azure CLI finden Sie in:

• Installieren der Azure-Befehlszeilenschnittstelle
• Azure-CLI-Referenz