Zarządzanie zasobami usługi Azure Cosmos DB for NoSQL przy użyciu interfejsu wiersza polecenia platformy Azure

  • Artykuł

DOTYCZY: NoSQL

W poniższym przewodniku opisano typowe polecenia służące do automatyzowania zarządzania kontami, bazami danych i kontenerami usługi Azure Cosmos DB przy użyciu interfejsu wiersza polecenia platformy Azure. Strony referencyjne dla wszystkich poleceń interfejsu wiersza polecenia usługi Azure Cosmos DB są dostępne w dokumentacji interfejsu wiersza polecenia platformy Azure. Więcej przykładów można znaleźć w przykładach interfejsu wiersza polecenia platformy Azure dla usługi Azure Cosmos DB, w tym na temat tworzenia kont, baz danych i kontenerów usługi Azure Cosmos DB dla baz danych MongoDB, Gremlin, Cassandra i interfejsu API dla tabel.

Wymagania wstępne

  • Ten artykuł wymaga wersji 2.22.1 lub nowszej interfejsu wiersza polecenia platformy Azure. W przypadku korzystania z usługi Azure Cloud Shell najnowsza wersja jest już zainstalowana.

Przykłady interfejsu wiersza polecenia platformy Azure dla innych interfejsów API można znaleźć w temacie Przykłady interfejsu wiersza polecenia dla rozwiązania Cassandra, przykłady interfejsu wiersza polecenia dla interfejsu API dla bazy danych MongoDB, przykłady interfejsuwiersza polecenia dla języka Gremlin, przykłady interfejsu wiersza polecenia dla tabeli

Ważne

Nie można zmienić nazwy zasobów usługi Azure Cosmos DB, ponieważ narusza to, jak usługa Azure Resource Manager współpracuje z identyfikatorami URI zasobów.

Azure Cosmos DBAccounts

W poniższych sekcjach pokazano, jak zarządzać kontem usługi Azure Cosmos DB, w tym:

Tworzenie konta usługi Azure Cosmos DB

Utwórz konto usługi Azure Cosmos DB za pomocą interfejsu API dla noSQL, spójności sesji w regionach Zachodnie stany USA i Wschodnie stany USA:

Ważne

Nazwa konta usługi Azure Cosmos DB musi być mała i mniejsza niż 44 znaki.

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

Add or remove regions (Dodawanie lub usuwanie regionów)

Utwórz konto usługi Azure Cosmos DB z dwoma regionami, dodaj region i usuń region.

Uwaga

Nie można jednocześnie dodawać ani usuwać regionów locations i zmieniać innych właściwości konta usługi Azure Cosmos DB. Modyfikowanie regionów musi być wykonywane jako osobna operacja niż jakakolwiek inna zmiana zasobu konta.

Uwaga

To polecenie umożliwia dodawanie i usuwanie regionów, ale nie umożliwia modyfikowania priorytetów trybu failover ani wyzwalania ręcznego przejścia w tryb failover. Zobacz Ustawianie priorytetu trybu failover i Ręczne przełączanie w tryb failover wyzwalacza.

Porada

Gdy dodawany jest nowy region, wszystkie dane muszą zostać w pełni zreplikowane i zatwierdzone w nowym regionie, zanim region zostanie oznaczony jako dostępny. Czas potrzebny na wykonanie tej operacji zależy od ilości danych przechowywanych na koncie. Jeśli operacja skalowania przepływności asynchronicznej jest w toku, operacja skalowania przepływności w górę zostanie wstrzymana i zostanie wznowiona automatycznie po zakończeniu operacji dodawania/usuwania regionu.

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

Włączanie wielu regionów zapisu

Włączanie zapisu w wielu regionach dla konta usługi 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

Ustawianie priorytetu trybu failover

Ustawianie priorytetu trybu failover dla konta usługi Azure Cosmos DB skonfigurowanego na potrzeby trybu failover zarządzanego przez usługę

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

Włączanie trybu failover zarządzanego przez usługę

# 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

Wyzwalanie ręcznego przejścia w tryb failover

Przestroga

Zmiana regionu o priorytcie = 0 spowoduje ręczne przejście w tryb failover dla konta usługi Azure Cosmos DB. Każda inna zmiana priorytetu nie spowoduje wyzwolenia trybu failover.

Uwaga

Jeśli wykonasz ręczną operację trybu failover, gdy operacja skalowania przepływności asynchronicznej jest w toku, operacja skalowania przepływności zostanie wstrzymana. Zostanie ona wznowiona automatycznie po zakończeniu operacji trybu failover.

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

Wyświetlanie listy wszystkich kluczy konta

Pobierz wszystkie klucze dla konta usługi Azure Cosmos DB.

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

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

Wyświetlanie listy kluczy kont tylko do odczytu

Pobieranie kluczy tylko do odczytu dla konta usługi Azure Cosmos DB.

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

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

Wyświetlanie listy parametrów połączenia

Pobierz parametry połączenia dla konta usługi Azure Cosmos DB.

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

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

Ponowne generowanie klucza konta

Wygeneruj ponownie nowy klucz dla konta usługi 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

Baza danych usługi Azure Cosmos DB

W poniższych sekcjach przedstawiono sposób zarządzania bazą danych usługi Azure Cosmos DB, w tym:

Tworzenie bazy danych

Tworzy bazę danych usługi Azure Cosmos DB.

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

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

Tworzenie bazy danych z udostępnioną przepływnością

Utwórz bazę danych usługi Azure Cosmos DB z udostępnioną przepływnością.

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

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

Migrowanie bazy danych do przepływności skalowania automatycznego

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

Zmienianie przepływności bazy danych

Zwiększ przepływność bazy danych usługi 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

Uniemożliwianie usunięcia bazy danych

Umieść blokadę usuwania zasobów platformy Azure w bazie danych, aby zapobiec jej usunięciu. Ta funkcja wymaga zablokowania konta usługi Azure Cosmos DB na podstawie zestawów SDK płaszczyzny danych. Aby dowiedzieć się więcej, zobacz Zapobieganie zmianom zestawów SDK. Blokady zasobów platformy Azure mogą również uniemożliwić zmianę zasobu przez określenie typu blokady ReadOnly . W przypadku bazy danych usługi Azure Cosmos DB można jej użyć, aby zapobiec zmianie przepływności.

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

Kontener usługi Azure Cosmos DB

W poniższych sekcjach pokazano, jak zarządzać kontenerem usługi Azure Cosmos DB, w tym:

Tworzenie kontenera

Utwórz kontener usługi Azure Cosmos DB z domyślnymi zasadami indeksu, kluczem partycji i jednostkami RU/s z 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

Tworzenie kontenera z autoskalowaniem

Utwórz kontener usługi Azure Cosmos DB z domyślnymi zasadami indeksu, kluczem partycji i automatycznym skalowaniem RU/s z 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

Tworzenie kontenera z użyciem czasu wygaśnięcia

Utwórz kontener usługi Azure Cosmos DB z włączonym czasem wygaśnięcia.

# 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

Tworzenie kontenera z niestandardowymi zasadami indeksu

Utwórz kontener usługi Azure Cosmos DB z niestandardowymi zasadami indeksu, indeksem przestrzennym, indeksem złożonym, kluczem partycji i wartością RU/s z 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"

Zmienianie przepływności kontenera

Zwiększ przepływność kontenera usługi 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

Migrowanie kontenera do przepływności autoskalowania

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

Zapobieganie usuwaniu kontenera

Umieść blokadę usuwania zasobów platformy Azure w kontenerze, aby zapobiec jego usunięciu. Ta funkcja wymaga zablokowania zmiany konta usługi Azure Cosmos DB przez zestawy SDK płaszczyzny danych. Aby dowiedzieć się więcej, zobacz zapobieganie zmianom z zestawów SDK. Blokady zasobów platformy Azure mogą również uniemożliwić zmianę zasobu przez określenie typu blokady ReadOnly . W przypadku kontenera usługi Azure Cosmos DB blokady mogą służyć do zapobiegania zmianie przepływności lub innej właściwości.

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

Następne kroki

Aby uzyskać więcej informacji na temat interfejsu wiersza polecenia platformy Azure, zobacz: