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

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 voor 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 ziet u hoe u het Azure Cosmos DB-account beheert, waaronder:

• Azure Cosmos DB-account maken
• Regio's toevoegen of verwijderen
• Schrijfbewerkingen in meerdere regio's inschakelen
• Regionale failoverprioriteit instellen
• Door de service beheerde failover inschakelen
• Handmatige failover activeren
• Accountsleutels vermelden
• Alleen-lezen accountsleutels weergeven
• Lijst met verbindingsreeks s
• Accountsleutel opnieuw genereren

Een Azure Cosmos DB-account maken

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

Belangrijk

De naam van het Azure Cosmos DB-account moet uit kleine letters en 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 geen regio's locations tegelijk 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 een 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 kost, is afhankelijk van hoeveel gegevens in het account worden opgeslagen. Als er een asynchrone doorvoerschaalbewerking wordt uitgevoerd, wordt de bewerking voor het omhoog schalen van doorvoer onderbroken en wordt deze automatisch hervat wanneer de regiobewerking voor toevoegen/verwijderen 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 de 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

Let op

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

Notitie

Als u een handmatige failoverbewerking uitvoert terwijl 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

Haal alle sleutels voor een Azure Cosmos DB-account op.

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

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

Alleen-lezen accountsleutels weergeven

Haal alleen-lezensleutels op 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

Haal de verbindingsreeks s voor een Azure Cosmos DB-account op.

# 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 maken met gedeelde doorvoer
• Een database migreren naar doorvoer automatisch 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 maken met gedeelde doorvoer

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 naar doorvoer automatisch 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 Azure-resourcevergrendeling op een database om te voorkomen dat deze wordt verwijderd. Voor deze functie moet het Azure Cosmos DB-account worden vergrendeld om te worden gewijzigd door SDK's voor gegevensvlakken. Zie voor meer informatie het voorkomen van wijzigingen van SDK's. 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 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 van 4000 automatisch schalen.

# 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, 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 Azure-resourcevergrendeling op een container om te voorkomen dat deze wordt verwijderd. Voor deze functie moet het Azure Cosmos DB-account worden vergrendeld om te worden gewijzigd door SDK's voor gegevensvlakken. Zie voor meer informatie het voorkomen van wijzigingen van SDK's. 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-CLI installeren
• Azure CLI-referentie
• Meer Azure CLI-voorbeelden voor Azure Cosmos DB