Hantera Azure Cosmos DB för NoSQL-resurser med hjälp av Azure CLI

GÄLLER FÖR: NoSQL

I följande guide beskrivs vanliga kommandon för att automatisera hanteringen av dina Azure Cosmos DB-konton, databaser och containrar med hjälp av Azure CLI. Referenssidor för alla Azure Cosmos DB CLI-kommandon är tillgängliga i Azure CLI-referensen. Du kan också hitta fler exempel i Azure CLI-exempel för Azure Cosmos DB, inklusive hur du skapar och hanterar Azure Cosmos DB-konton, databaser och containrar för MongoDB, Gremlin, Cassandra och API för table.

Förutsättningar

• Använd Bash-miljön i Azure Cloud Shell. Mer information finns i Snabbstart för Bash i Azure Cloud Shell.

  

• Om du föredrar att köra CLI-referenskommandon lokalt installerar du Azure CLI. Om du kör i Windows eller macOS kan du köra Azure CLI i en Docker-container. Mer information finns i Så här kör du Azure CLI i en Docker-container.

  • Om du använder en lokal installation loggar du in på Azure CLI med hjälp av kommandot az login. Slutför autentiseringsprocessen genom att följa stegen som visas i terminalen. Andra inloggningsalternativ finns i Logga in med Azure CLI.

  • När du uppmanas att göra det installerar du Azure CLI-tillägget vid första användning. Mer information om tillägg finns i Använda tillägg med Azure CLI.

  • Kör az version om du vill hitta versionen och de beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen kör du az upgrade.

• Den här artikeln kräver version 2.22.1 eller senare av Azure CLI. Om du använder Azure Cloud Shell är den senaste versionen redan installerad.

Azure CLI-exempel för andra API:er finns i CLI-exempel för Cassandra, CLI-exempel för API för MongoDB, CLI-exempel för Gremlin, CLI-exempel för tabell

Viktigt

Azure Cosmos DB-resurser kan inte byta namn eftersom det strider mot hur Azure Resource Manager fungerar med resurs-URI:er.

Azure Cosmos DBAccounts

Följande avsnitt visar hur du hanterar Azure Cosmos DB-kontot, inklusive:

• Skapa ett Azure Cosmos DB-konto
• Lägga till eller ta bort regioner
• Aktivera skrivningar i flera regioner
• Ange regional redundansprioritet
• Aktivera tjänsthanterad redundans
• Utlösa manuell redundans
• Lista kontonycklar
• Visa en lista över skrivskyddade kontonycklar
• Lista anslutningssträngar
• Återskapa kontonyckel

Skapa ett Azure Cosmos DB-konto

Skapa ett Azure Cosmos DB-konto med API för NoSQL, sessionskonsekvens i regionerna USA, västra och USA, östra:

Viktigt

Azure Cosmos DB-kontonamnet måste innehålla gemener och mindre än 44 tecken.

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

Lägga till eller ta bort regioner

Skapa ett Azure Cosmos DB-konto med två regioner, lägg till en region och ta bort en region.

Anteckning

Du kan inte lägga till eller ta bort regioner locations samtidigt och ändra andra egenskaper för ett Azure Cosmos DB-konto. Ändring av regioner måste utföras som en separat åtgärd än någon annan ändring av kontoresursen.

Anteckning

Med det här kommandot kan du lägga till och ta bort regioner, men du kan inte ändra redundansprioriteringar eller utlösa en manuell redundansväxling. Se Ange redundansprioritet och Utlösa manuell redundans.

Tips

När en ny region läggs till måste alla data replikeras fullständigt och checkas in i den nya regionen innan regionen markeras som tillgänglig. Hur lång tid den här åtgärden tar beror på hur mycket data som lagras i kontot. Om en asynkron dataflödesskalning pågår pausas uppskalningsåtgärden för dataflödet och återupptas automatiskt när åtgärden för att lägga till/ta bort region har slutförts.

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

Aktivera flera skrivregioner

Aktivera skrivningar i flera regioner för ett 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

Ange redundansprioritet

Ange redundansprioritet för ett Azure Cosmos DB-konto som konfigurerats för tjänsthanterad redundans

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

Aktivera tjänsthanterad redundans

# 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

Utlösa manuell redundans

Varning

Om du ändrar region med prioritet = 0 utlöses en manuell redundansväxling för ett Azure Cosmos DB-konto. Andra prioritetsändringar utlöser inte en redundansväxling.

Anteckning

Om du utför en manuell redundansväxling medan en asynkron dataflödesskalning pågår pausas uppskalningsåtgärden för dataflödet. Den återupptas automatiskt när redundansåtgärden har slutförts.

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

Visa en lista över alla kontonycklar

Hämta alla nycklar för ett Azure Cosmos DB-konto.

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

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

Visa en lista över skrivskyddade kontonycklar

Hämta skrivskyddade nycklar för ett 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

Lista anslutningssträngar

Hämta anslutningssträngarna för ett Azure Cosmos DB-konto.

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

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

Återskapa kontonyckel

Återskapa en ny nyckel för ett 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-databas

Följande avsnitt visar hur du hanterar Azure Cosmos DB-databasen, inklusive:

• Skapa en databas
• Skapa en databas med delat dataflöde
• Migrera en databas för att autoskala dataflöde
• Ändra databasdataflöde
• Förhindra att en databas tas bort

Skapa en databas

Skapa en Azure Cosmos DB-databas.

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

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

Skapa en databas med delat dataflöde

Skapa en Azure Cosmos DB-databas med delat dataflöde.

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

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

Migrera en databas för att autoskala dataflöde

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

Ändra databasdataflöde

Öka dataflödet för en Azure Cosmos DB-databas med 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

Förhindra att en databas tas bort

Placera ett borttagningslås för En Azure-resurs på en databas för att förhindra att den tas bort. Den här funktionen kräver att Azure Cosmos DB-kontot inte ändras av SDK:er för dataplanet. Mer information finns i Förhindra ändringar från SDK:er. Azure-resurslås kan också förhindra att en resurs ändras genom att ange en ReadOnly låstyp. För en Azure Cosmos DB-databas kan den användas för att förhindra att dataflödet ändras.

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

Följande avsnitt visar hur du hanterar Azure Cosmos DB-containern, inklusive:

• Skapa en container
• Skapa en container med autoskalning
• Skapa en container med TTL aktiverat
• Skapa en container med anpassad indexprincip
• Ändra containerdataflöde
• Migrera en container för att autoskala dataflöde
• Förhindra att en container tas bort

Skapa en container

Skapa en Azure Cosmos DB-container med standardindexprincip, partitionsnyckel och RU/s på 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

Skapa en container med autoskalning

Skapa en Azure Cosmos DB-container med standardindexprincip, partitionsnyckel och autoskalning av RU/s på 4 000.

# 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

Skapa en container med TTL

Skapa en Azure Cosmos DB-container med TTL aktiverat.

# 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

Skapa en container med en anpassad indexprincip

Skapa en Azure Cosmos DB-container med en anpassad indexprincip, ett rumsligt index, sammansatt index, en partitionsnyckel och RU/s på 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"

Ändra containerdataflöde

Öka dataflödet för en Azure Cosmos DB-container med 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

Migrera en container för att autoskala dataflöde

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

Förhindra att en container tas bort

Placera ett borttagningslås för En Azure-resurs på en container för att förhindra att den tas bort. Den här funktionen kräver att Azure Cosmos DB-kontot inte ändras av SDK:er för dataplanet. Mer information finns i Förhindra ändringar från SDK:er. Azure-resurslås kan också förhindra att en resurs ändras genom att ange en ReadOnly låstyp. För en Azure Cosmos DB-container kan lås användas för att förhindra att dataflöde eller andra egenskaper ändras.

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ästa steg

Mer information om Azure CLI finns i:

• Installera Azure CLI
• Azure CLI-referens
• Fler Azure CLI-exempel för Azure Cosmos DB