Správa prostředků Azure Cosmos DB for NoSQL pomocí Azure CLI

  • Článek

PLATÍ PRO: NoSQL

Následující příručka popisuje běžné příkazy pro automatizaci správy účtů, databází a kontejnerů Azure Cosmos DB pomocí Azure CLI. Referenční stránky pro všechny příkazy rozhraní příkazového řádku služby Azure Cosmos DB jsou k dispozici v referenčních informacích k Azure CLI. Další příklady najdete také v ukázkách Azure CLI pro Azure Cosmos DB, včetně vytváření a správy účtů, databází a kontejnerů Azure Cosmos DB pro MongoDB, Gremlin, Cassandra a ROZHRANÍ API pro Table.

Požadavky

  • Tento článek vyžaduje azure CLI verze 2.22.1 nebo novější. Pokud používáte Azure Cloud Shell, je už nainstalovaná nejnovější verze.

Ukázky Azure CLI pro další rozhraní API najdete v tématu Ukázky rozhraní příkazového řádku pro Cassandra, Ukázky rozhraní příkazového řádku pro rozhraní API pro MongoDB, Ukázky rozhraní příkazového řádku pro Gremlin, Ukázky rozhraní příkazového řádku pro tabulku.

Důležité

Prostředky služby Azure Cosmos DB nejde přejmenovat, protože to porušuje způsob, jakým Azure Resource Manager pracuje s identifikátory URI prostředků.

Účty služby Azure Cosmos DB

Následující části ukazují, jak spravovat účet služby Azure Cosmos DB, včetně následujících:

Vytvoření účtu služby Azure Cosmos DB

Vytvořte účet služby Azure Cosmos DB s rozhraním API pro NoSQL a konzistencí relací v oblastech USA – západ a USA – východ:

Důležité

Název účtu služby Azure Cosmos DB musí být malými písmeny a musí být kratší než 44 znaků.

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

Přidání nebo odebrání oblastí

Vytvořte účet služby Azure Cosmos DB se dvěma oblastmi, přidejte oblast a odeberte oblast.

Poznámka

Nemůžete současně přidávat nebo odebírat oblasti locations a měnit další vlastnosti účtu služby Azure Cosmos DB. Úpravy oblastí se musí provést jako samostatná operace než jakákoli jiná změna prostředku účtu.

Poznámka

Tento příkaz umožňuje přidávat a odebírat oblasti, ale neumožňuje měnit priority převzetí služeb při selhání ani aktivovat ruční převzetí služeb při selhání. Viz Nastavení priority převzetí služeb při selhání a Aktivace ručního převzetí služeb při selhání.

Tip

Když se přidá nová oblast, všechna data se musí zcela replikovat a zapsat do nové oblasti, než se tato oblast označí za dostupnou. Doba trvání této operace bude záviset na tom, kolik dat je v účtu uloženo. Pokud probíhá operace asynchronního škálování propustnosti , operace vertikálního navýšení kapacity propustnosti se pozastaví a po dokončení operace přidání nebo odebrání oblasti se automaticky obnoví.

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

Povolení více oblastí zápisu

Povolení zápisů do více oblastí pro účet služby Azure Cosmos DB

# 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

Nastavení priority převzetí služeb při selhání

Nastavení priority převzetí služeb při selhání pro účet služby Azure Cosmos DB nakonfigurovaný pro převzetí služeb při selhání spravované službou

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

Povolení převzetí služeb při selhání spravované službou

# 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

Aktivace ručního převzetí služeb při selhání

Upozornění

Změna oblasti s prioritou = 0 aktivuje ruční převzetí služeb při selhání pro účet služby Azure Cosmos DB. Žádná jiná změna priority neaktivuje převzetí služeb při selhání.

Poznámka

Pokud provádíte ruční operaci převzetí služeb při selhání, zatímco probíhá operace asynchronního škálování propustnosti , pozastaví se operace vertikálního navýšení propustnosti. Po dokončení operace převzetí služeb při selhání se automaticky obnoví.

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

Výpis všech klíčů účtů

Získejte všechny klíče pro účet služby Azure Cosmos DB.

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

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

Výpis klíčů účtu jen pro čtení

Získejte klíče jen pro čtení pro účet služby Azure Cosmos DB.

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

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

Výpis připojovacích řetězců

Získejte připojovací řetězce pro účet služby Azure Cosmos DB.

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

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

Opětovné vygenerování klíče účtu

Znovu vygenerujte nový klíč pro účet služby Azure Cosmos DB.

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

Databáze Azure Cosmos DB

Následující části ukazují, jak spravovat databázi Azure Cosmos DB, včetně:

Vytvoření databáze

Vytvoří účet databáze Azure Cosmos DB.

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

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

Vytvoření databáze se sdílenou propustností

Vytvořte databázi Azure Cosmos DB se sdílenou propustností.

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

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

Migrace databáze za účelem automatického škálování propustnosti

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

Změna propustnosti databáze

Zvýšení propustnosti databáze Azure Cosmos DB o 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

Zabránění odstranění databáze

Umístěte na databázi zámek odstranění prostředku Azure, abyste zabránili jejímu odstranění. Tato funkce vyžaduje uzamčení účtu služby Azure Cosmos DB před změnou pomocí sad SDK roviny dat. Další informace najdete v tématu Zabránění změnám v sadách SDK. Zámky prostředků Azure také můžou zabránit změně prostředku zadáním ReadOnly typu zámku. U databáze Azure Cosmos DB se dá použít k zabránění změně propustnosti.

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

Kontejner služby Azure Cosmos DB

Následující části ukazují, jak spravovat kontejner Azure Cosmos DB, včetně:

Vytvoření kontejneru

Vytvořte kontejner Služby Azure Cosmos DB s výchozími zásadami indexu, klíčem oddílu a 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

Vytvoření kontejneru s automatickým škálováním

Vytvořte kontejner Služby Azure Cosmos DB s výchozími zásadami indexu, klíčem oddílu a ru/s automatického škálování s hodnotou 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

Vytvoření kontejneru s hodnotou TTL

Vytvořte kontejner Azure Cosmos DB s povolenou hodnotou 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

Vytvoření kontejneru s vlastními zásadami indexu

Vytvořte kontejner Azure Cosmos DB s vlastními zásadami indexu, prostorovým indexem, složeným indexem, klíčem oddílu a ru/s o hodnotě 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"

Změna propustnosti kontejneru

Zvýšení propustnosti kontejneru služby Azure Cosmos DB o 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

Migrace kontejneru na automatické škálování propustnosti

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

Zabránění odstranění kontejneru

Umístěte na kontejner zámek odstranění prostředku Azure, abyste zabránili jeho odstranění. Tato funkce vyžaduje uzamčení účtu služby Azure Cosmos DB před změnou pomocí sad SDK roviny dat. Další informace najdete v tématu Zabránění změnám v sadách SDK. Zámky prostředků Azure také můžou zabránit změně prostředku zadáním ReadOnly typu zámku. U kontejneru Azure Cosmos DB je možné použít zámky, které brání změně propustnosti nebo jakékoli jiné vlastnosti.

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

Další kroky

Další informace o Azure CLI najdete tady: