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. Stránky s referenčními informacemi pro všechny příkazy rozhraní příkazového řádku Azure Cosmos DB jsou k dispozici v referenčních informacích k Azure CLI.

Požadavky

• Použijte prostředí Bash v Azure Cloud Shellu. Další informace najdete v tématu Začínáme s Azure Cloud Shellem.

  

• 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 Ověřování v Azure 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 Použití a správa rozšíření pomocí 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 verzi 2.22.1 nebo novější azure CLI. Pokud používáte Azure Cloud Shell, je už nainstalovaná nejnovější verze.

Ukázky Azure CLI pro jiná rozhraní API najdete v ukázkách 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 Azure Cosmos DB nejde přejmenovat, protože to porušuje způsob, jakým Azure Resource Manager funguje s identifikátory URI prostředků.

Účty Azure Cosmos DB

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

• Vytvoření účtu služby Azure Cosmos DB
• Přidání nebo odebrání oblastí
• Povolení zápisů do více oblastí
• Nastavit prioritu regionálního selhání
• Povolení selhání spravovaného službou
• Spustit ruční přepnutí
• Výpis klíčů účtu
• Výpis klíčů účtu jen pro čtení
• Seznam připojovacích řetězců
• Znovu vygenerujte klíč účtu.

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

Vytvořte účet služby Azure Cosmos DB s rozhraním API pro NoSQL, 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 psán malými písmeny a obsahovat méně 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. Změny oblastí musí být provedeny 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 prioritu pro převzetí služeb nebo spustit ruční převzetí služeb. Viz Nastavení priority převzetí služeb při selhání a Ruční 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 se v rámci účtu ukládá. Pokud probíhá operace škálování asynchronní 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

Nastavit prioritu převzetí služeb při selhání

Nastavte prioritu převzetí služeb při selhání pro účet Azure Cosmos DB nakonfigurovaný pro spravované převzetí služeb při selhání.

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

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

# 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

Spustit manuální převzetí služeb při selhání

Upozornění

Změna oblasti s pořadím = 0 aktivuje ruční převzetí služeb pro účet služby Azure Cosmos DB. Žádná jiná změna priority nevyvolá 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á asynchronní operace škálování propustnosti, operace navýšení kapacity propustnosti se pozastaví. Obnoví se automaticky po dokončení operace převzetí služeb.

# 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íčů účtu

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

Seznam 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

Seznam připojovacích řetězců

Získejte připojovací řetězec 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

Znovu vygenerujte klíč úč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 na škálování propustnosti podle potřeby
• Změna propustnosti databáze
• Zabránění odstranění databáze

Vytvořit databázi

Vytvořte databázi 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 na automatické š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

Zvyšte propustnost 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 zámek odstranění prostředku Azure do databáze, aby se zabránilo jeho odstranění. Tato funkce vyžaduje uzamčení účtu Azure Cosmos DB, aby nemohl být změněn pomocí sad SDK datové roviny. Další informace naleznete v části prevence změn v SDK. Zámky prostředků Azure můžou také zabránit změně prostředku zadáním ReadOnly typu zámku. Pro databázi Azure Cosmos DB je možné ji 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 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 povoleným TTL
• Vytvoření kontejneru pomocí vlastních zásad indexu
• Změna propustnosti kontejneru
• Migrace kontejneru, aby se automaticky škálovala propustnost
• Zabránění odstranění kontejneru

Vytvoření kontejneru

Vytvořte kontejner 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 Azure Cosmos DB s výchozími zásadami indexu, klíčem oddílu a automatickým škálováním RU/s 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řte kontejner s TTL

Vytvořte kontejner Azure Cosmos DB s povoleným 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řte kontejner 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 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

Zvyšte propustnost kontejneru 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 zámek odstranění prostředku Azure do kontejneru, aby se zabránilo jeho odstranění. Tato funkce vyžaduje uzamčení účtu Azure Cosmos DB, aby nemohl být změněn pomocí sad SDK datové roviny. Další informace naleznete v části prevence změn v SDK. Zámky prostředků Azure můžou také zabránit změně prostředku zadáním ReadOnly typu zámku. U kontejneru Azure Cosmos DB je možné zámky použít k zabráně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:

• Instalace rozhraní příkazového řádku Azure
• Referenční informace k rozhraní příkazového řádku Azure