Sdílet prostřednictvím

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. 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. Další příklady najdete také v ukázkách Azure CLI pro službu Azure Cosmos DB, včetně postupu při vytváření a správě účtů, databází a kontejnerů Azure Cosmos DB pro MongoDB, Gremlin, Cassandra a API for Table.

Požadavky

  • 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 nelze přejmenovat, protože to porušuje způsob, jakým Azure Resource Manager funguje 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ě:

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 malými a méně než 44 znaky.

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:

Oblasti nemůžete přidávat ani odebírat locations současně 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 priority převzetí služeb při selhání nebo aktivovat ruční převzetí služeb při selhání. Viz Nastavení priority převzetí služeb při selhání a ruční převzetí služeb při selhání triggerem.

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

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 škálování asynchronní propustnosti, operace vertikálního navýšení kapacity propustnosti se pozastaví. 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íčů úč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

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

Seznam připojovací řetězec

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řit databázi

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 na propustnost automatického škálování

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 služby Azure Cosmos DB od změny pomocí sad SDK roviny dat. Další informace najdete v tématu zabránění změnám ze sad 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řte kontejner Azure Cosmos DB s výchozími zásadami indexu, 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

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ření kontejneru pomocí hodnoty 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ření kontejneru pomocí vlastních zásad indexu

Vytvořte kontejner Azure Cosmos DB pomocí vlastních zásad indexu, prostorového indexu, složeného indexu, klíče 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 propustnost automatického škálování

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 služby Azure Cosmos DB od změny pomocí sad SDK roviny dat. Další informace najdete v tématu zabránění změnám ze sad 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: