Azure Cosmos DB voor NoSQL-resources beheren met behulp van Azure CLI

Artikel
03/09/2023

VAN TOEPASSING OP: NoSQL

In de volgende handleiding worden veelvoorkomende opdrachten beschreven voor het automatiseren van het beheer van Azure Cosmos DB-accounts, -databases en -containers, met behulp van Azure CLI. Referentiepagina's voor alle Azure Cosmos DB CLI-opdrachten zijn beschikbaar in de naslaginformatie voor Azure CLI. U vindt ook meer voorbeelden in Azure CLI-voorbeelden voor Azure Cosmos DB, waaronder het maken en beheren van Azure Cosmos DB-accounts, -databases en -containers voor MongoDB, Gremlin, Cassandra en API for Table.

Vereisten

Gebruik de Bash-omgeving in Azure Cloud Shell. Zie Quickstart voor Bash in Azure Cloud Shell voor meer informatie.
Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.
- Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met behulp van de opdracht AZ login. Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Raadpleeg Aanmelden bij Azure CLI voor aanvullende aanmeldingsopties.
- Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor meer informatie over extensies.
- Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om te upgraden naar de nieuwste versie.

Voor dit artikel is versie 2.22.1 of hoger van de Azure CLI vereist. Als u Azure Cloud Shell gebruikt, is de nieuwste versie al geïnstalleerd.

Voor Azure CLI-voorbeelden voor andere API's raadpleegt u CLI-voorbeelden voor Cassandra, CLI-voorbeelden voor API voor MongoDB, CLI-voorbeelden voor Gremlin, CLI-voorbeelden voor tabel

Belangrijk

De naam van Azure Cosmos DB-resources kan niet worden gewijzigd, omdat dit in strijd is met de werking van Azure Resource Manager met resource-URI's.

Azure Cosmos DBAccounts

In de volgende secties wordt uitgelegd hoe u het Azure Cosmos DB-account beheert, waaronder:

Azure Cosmos DB-account maken
Regio's toevoegen of verwijderen
Schrijfbewerkingen voor meerdere regio's inschakelen
Regionale failoverprioriteit instellen
Door service beheerde failover inschakelen
Handmatige failover activeren
Accountsleutels weergeven
Alleen-lezen accountsleutels weergeven
Verbindingsreeksen weergeven
Accountsleutel opnieuw genereren

Maak een Azure Cosmos DB-account

Maak een Azure Cosmos DB-account met API voor NoSQL, sessieconsistentie in de regio's VS - west en VS - oost:

Belangrijk

De naam van het Azure Cosmos DB-account moet uit kleine letters bestaan en uit minder dan 44 tekens bestaan.

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

Regio's toevoegen of verwijderen

Maak een Azure Cosmos DB-account met twee regio's, voeg een regio toe en verwijder een regio.

Notitie

U kunt niet tegelijkertijd regio's locations toevoegen of verwijderen en andere eigenschappen voor een Azure Cosmos DB-account wijzigen. Het wijzigen van regio's moet worden uitgevoerd als een afzonderlijke bewerking dan elke andere wijziging in de accountresource.

Notitie

Met deze opdracht kunt u regio's toevoegen en verwijderen, maar niet de failover-prioriteit wijzigen of een handmatige failover activeren. Zie Failoverprioriteit instellen en Handmatige failover activeren.

Tip

Wanneer een nieuwe regio wordt toegevoegd, moeten alle gegevens volledig worden gerepliceerd en in de nieuwe regio worden vastgelegd voordat de regio als beschikbaar wordt gemarkeerd. De hoeveelheid tijd die deze bewerking in beslag neemt, is afhankelijk van de hoeveelheid gegevens die zijn opgeslagen in het account. Als er een asynchrone doorvoerschaalbewerking wordt uitgevoerd, wordt de bewerking voor het omhoog schalen van doorvoer onderbroken en automatisch hervat wanneer de bewerking voor het toevoegen/verwijderen van de regio is voltooid.

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

Meerdere schrijfregio's inschakelen

Schrijfbewerkingen voor meerdere regio's inschakelen voor een Azure Cosmos DB-account

# 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

Failoverprioriteit instellen

De failoverprioriteit instellen voor een Azure Cosmos DB-account dat is geconfigureerd voor door de service beheerde 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)

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

Door service beheerde failover inschakelen

# 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

Handmatige failover activeren

Waarschuwing

Als u een regio met prioriteit = 0 wijzigt, wordt een handmatige failover geactiveerd voor een Azure Cosmos DB-account. Een andere wijziging van de prioriteit zal geen failover activeren.

Notitie

Als u een handmatige failoverbewerking uitvoert terwijl er een asynchrone doorvoerschaalbewerking wordt uitgevoerd, wordt de bewerking voor het omhoog schalen van doorvoer onderbroken. Deze wordt automatisch hervat wanneer de failoverbewerking is voltooid.

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

Alle accountsleutels weergeven

Alle sleutels voor een Azure Cosmos DB-account ophalen.

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

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

Alleen-lezen accountsleutels weergeven

Alleen-lezensleutels ophalen voor een Azure Cosmos DB-account.

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

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

Verbindingsreeksen weergeven

De verbindingsreeksen voor een Azure Cosmos DB-account ophalen.

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

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

Accountsleutel opnieuw genereren

Genereer een nieuwe sleutel voor een Azure Cosmos DB-account.

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

In de volgende secties ziet u hoe u de Azure Cosmos DB-database kunt beheren, met inbegrip van:

Een database maken
Een database met gedeelde doorvoer maken
Een database migreren om doorvoer automatisch te schalen
Databasedoorvoer wijzigen
Voorkomen dat een database wordt verwijderd

Een database maken

Hiermee maakt u een Azure Cosmos DB-database.

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

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

Een database met gedeelde doorvoer maken

Maak een Azure Cosmos DB-database met gedeelde doorvoer.

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

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

Een database migreren om doorvoer automatisch te schalen

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

Databasedoorvoer wijzigen

Verhoog de doorvoer van een Azure Cosmos DB-database met 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

Voorkomen dat een database wordt verwijderd

Plaats een vergrendeling voor het verwijderen van een Azure-resource op een database om te voorkomen dat deze wordt verwijderd. Voor deze functie moet het Azure Cosmos DB-account worden vergrendeld zodat het niet kan worden gewijzigd door gegevensvlak-SDK's. Zie Wijzigingen van SDK's voorkomen voor meer informatie. Azure-resourcevergrendelingen kunnen ook voorkomen dat een resource wordt gewijzigd door een ReadOnly vergrendelingstype op te geven. Voor een Azure Cosmos DB-database kan deze worden gebruikt om te voorkomen dat de doorvoer wordt gewijzigd.

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 de volgende secties ziet u hoe u de Azure Cosmos DB-container kunt beheren, met inbegrip van:

Een container maken
Een container maken met automatische schaalaanpassing
Een container maken waarvoor TTL is ingeschakeld
Een container maken met aangepast indexbeleid
Containerdoorvoer wijzigen
Een container migreren om doorvoer automatisch te schalen
Voorkomen dat een container wordt verwijderd

Een container maken

Maak een Azure Cosmos DB-container met standaardindexbeleid, partitiesleutel en RU/s van 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

Een container maken met automatische schaalaanpassing

Maak een Azure Cosmos DB-container met standaardindexbeleid, partitiesleutel en RU/s met automatische schaalaanpassing van 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

Een container maken met TTL

Maak een Azure Cosmos DB-container waarvoor TTL is ingeschakeld.

# 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

Een container maken met een aangepast indexbeleid

Maak een Azure Cosmos DB-container met een aangepast indexbeleid, een ruimtelijke index, een samengestelde index, een partitiesleutel en RU/s van 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"

Containerdoorvoer wijzigen

Verhoog de doorvoer van een Azure Cosmos DB-container met 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

Een container migreren om doorvoer automatisch te schalen

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

Voorkomen dat een container wordt verwijderd

Plaats een Verwijderingsvergrendeling voor Azure-resources op een container om te voorkomen dat deze wordt verwijderd. Voor deze functie moet het Azure Cosmos DB-account worden vergrendeld zodat het niet kan worden gewijzigd door gegevensvlak-SDK's. Zie Wijzigingen van SDK's voorkomen voor meer informatie. Azure-resourcevergrendelingen kunnen ook voorkomen dat een resource wordt gewijzigd door een ReadOnly vergrendelingstype op te geven. Voor een Azure Cosmos DB-container kunnen vergrendelingen worden gebruikt om te voorkomen dat doorvoer of andere eigenschappen worden gewijzigd.

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

Volgende stappen

Zie voor meer informatie over de Azure CLI:

Azure Cosmos DB voor NoSQL-resources beheren met behulp van Azure CLI

Vereisten

Azure Cosmos DBAccounts

Maak een Azure Cosmos DB-account

Regio's toevoegen of verwijderen

Meerdere schrijfregio's inschakelen

Failoverprioriteit instellen

Door service beheerde failover inschakelen

Handmatige failover activeren

Alle accountsleutels weergeven

Alleen-lezen accountsleutels weergeven

Verbindingsreeksen weergeven

Accountsleutel opnieuw genereren

Azure Cosmos DB-database

Een database maken

Een database met gedeelde doorvoer maken

Een database migreren om doorvoer automatisch te schalen

Databasedoorvoer wijzigen

Voorkomen dat een database wordt verwijderd

Azure Cosmos DB-container

Een container maken

Een container maken met automatische schaalaanpassing

Een container maken met TTL

Een container maken met een aangepast indexbeleid

Containerdoorvoer wijzigen

Een container migreren om doorvoer automatisch te schalen

Voorkomen dat een container wordt verwijderd

Volgende stappen

Aanvullende resources