Správa prostředků Azure Cosmos DB for NoSQL pomocí Azure CLI
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
Použijte prostředí Bash v Azure Cloud Shell. Další informace najdete v tématu Rychlý start pro Bash v Azure Cloud Shell.
Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, nainstalujte Azure CLI. Pokud používáte Windows nebo macOS, zvažte spuštění Azure CLI v kontejneru Docker. Další informace najdete v tématu Jak spustit Azure CLI v kontejneru Dockeru.
Pokud používáte místní instalaci, přihlaste se k Azure CLI pomocí příkazu az login. Pokud chcete dokončit proces ověřování, postupujte podle kroků zobrazených na terminálu. Další možnosti přihlášení najdete v tématu Přihlášení pomocí Azure CLI.
Po zobrazení výzvy nainstalujte rozšíření Azure CLI při prvním použití. Další informace o rozšířeních najdete v tématu Využití rozšíření v Azure CLI.
Spuštěním příkazu az version zjistěte verzi a závislé knihovny, které jsou nainstalované. Pokud chcete upgradovat na nejnovější verzi, spusťte az upgrade.
- 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
- Přidání nebo odebrání oblastí
- Povolení zápisů do více oblastí
- Nastavení priority místního převzetí služeb při selhání
- Povolení převzetí služeb při selhání spravované službou
- Aktivace ručního převzetí služeb při selhání
- Výpis klíčů účtu
- Výpis klíčů účtu jen pro čtení
- Výpis připojovacích řetězců
- Opětovné vygenerování klíče účtu
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ření databáze se sdílenou propustností
- Migrace databáze za účelem automatického škálování propustnosti
- Změna propustnosti databáze
- Zabránění odstranění databáze
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ření kontejneru s automatickým škálováním
- Vytvoření kontejneru s povolenou hodnotou TTL
- Vytvoření kontejneru s vlastními zásadami indexu
- Změna propustnosti kontejneru
- Migrace kontejneru na automatické škálování propustnosti
- Zabránění odstranění kontejneru
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: