Verwalten von Ressourcen für die Core (SQL)-API von Azure Cosmos mit der Azure CLI

GILT FÜR: SQL-API

Der folgende Leitfaden erläutert die gängigen Befehle zum Automatisieren der Verwaltung Ihrer Azure Cosmos DB-Konten und -Container mithilfe von Azure CLI. Referenzseiten für alle CLI-Befehle für Azure Cosmos DB sind in der Referenz zur Azure CLI verfügbar. Weitere Beispiele finden Sie auch in Azur CLI-Beispiele für Azure Cosmos DB, einschließlich der Erstellung und Verwaltung von Cosmos DB-Konten, Datenbanken und Containern für MongoDB, Gremlin, Cassandra und die Tabellen-API.

Voraussetzungen

• Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Azure Cloud Shell-Schnellstart: Bash.

  

• Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, 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. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.

  • Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden 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 das Upgrade auf die aktuelle Version durchzuführen.

• Für diesen Artikel ist mindestens Version 2.22.1 der Azure CLI erforderlich. Bei Verwendung von Azure Cloud Shell ist die aktuelle Version bereits installiert.

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

Wichtig

Azure Cosmos DB-Ressourcen können nicht umbenannt werden, da dies gegen die Funktionsweise von Azure Resource Manager mit Ressourcen-URIs verstößt.

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
• Festlegen der Priorität beim Regionsfailover
• 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 SQL-API und Sitzungskonsistenz für die Regionen „USA, Westen“ und „USA, Osten“:

Wichtig

Der Name des Azure Cosmos-Kontos muss in Kleinbuchstaben geschrieben sein und weniger als 44 Zeichen umfassen.

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-Konto mit zwei Regionen, fügen Sie eine Region hinzu, und entfernen Sie eine Region.

Hinweis

Sie können nicht gleichzeitig Regionselemente vom Typ locations hinzufügen oder entfernen und andere Eigenschaften für ein Azure Cosmos-Konto ändern. Die Anpassung von Regionen muss getrennt von anderen Änderungen an der Kontoressource vorgenommen werden.

Hinweis

Mit diesem Befehl können Sie Regionen hinzufügen und entfernen, aber weder Failoverprioritäten anpassen noch ein manuelles Failover auslösen. Weitere Informationen finden Sie unter Festlegen der Failoverpriorität und Auslösen eines manuellen Failovers.

Tipp

Wenn eine neue Region hinzugefügt wird, müssen alle Daten vollständig repliziert und in die neue Region committet werden, bevor die Region als verfügbar markiert wird. Wie lange dieser Vorgang dauert, hängt davon ab, wie viele Daten in dem Konto gespeichert werden. Wenn ein asynchroner Durchsatzskalierungsvorgang ausgeführt wird, wird der Vorgang zum horizontalen Hochskalieren des Durchsatzes angehalten und automatisch fortgesetzt, sobald der Vorgang zum Hinzufügen/Entfernen von Regionen abgeschlossen ist.

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 Cosmos-Konto

# Update an Azure Cosmos 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-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'

Aktivieren des dienstseitig 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

Achtung

Wenn die Priorität einer Region in „0“ geändert wird, wird ein manuelles Failover für ein Azure Cosmos-Konto ausgelöst. Bei anderen Prioritätsänderungen wird kein Failover ausgelöst.

Hinweis

Wenn Sie einen manuellen Failovervorgang ausführen, während ein asynchroner Durchsatzskalierungsvorgang aktiv ist, wird der Vorgang zum horizontalen Hochskalieren des Durchsatzes angehalten. Er wird automatisch fortgesetzt, sobald der Failovervorgang abgeschlossen 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)

# 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

Rufen Sie alle Schlüssel für ein Cosmos-Konto ab.

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

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

Auflisten schreibgeschützter Kontoschlüssel

Rufen Sie schreibgeschützte Schlüssel für ein Cosmos-Konto ab.

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

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

Auflisten von Verbindungszeichenfolgen

Rufen Sie die Verbindungszeichenfolgen für ein Cosmos-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

Generieren Sie einen neuen Schlüssel für ein Cosmos-Konto erneut.

# 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 Cosmos-Datenbank.

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

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

Erstellen einer Datenbank mit gemeinsam genutztem Durchsatz

Erstellen Sie eine Cosmos-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 Sie den Durchsatz einer Cosmos-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 Cosmos-Konto für Änderungen durch Datenebenen-SDKs 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 Cosmos-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
• Migrieren eines Containers zum automatisch skalierten Durchsatz
• Verhindern des Löschens eines Containers

Erstellen eines Containers

Erstellen Sie einen Cosmos-Container mit standardmäßiger Indexrichtlinie, Partitionsschlüssel und einem Durchsatz von 400 RU/s.

# Create a SQL API 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 Sie einen Cosmos-Container mit standardmäßiger Indexrichtlinie, Partitionsschlüssel und einem automatisch skalierten Durchsatz von 4000 RU/s.

# Create a SQL API 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

Erstellen eines Containers mit Gültigkeitsdauer

Erstellen Sie einen Cosmos-Container mit aktivierter Gültigkeitsdauer.

# Create an Azure Cosmos 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 Sie einen Cosmos-Container mit einer benutzerdefinierten Indexrichtlinie, einem räumlichen Index, einem zusammengesetzten Index, einem Partitionsschlüssel und einem Durchsatz von 400 RU/s.

# Create a SQL API 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 Sie den Durchsatz eines Cosmos-Containers 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 Cosmos-Konto für Änderungen durch Datenebenen-SDKs 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 einen Cosmos-Container kann damit eine Änderung des Durchsatzes oder einer anderen Eigenschaft verhindert werden.

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
• Zusätzliche Azure CLI-Beispiele für Azure Cosmos DB