Udostępnij za pośrednictwem

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ń dostępnych w interfejsie wiersza polecenia usługi Azure Cosmos DB są dostępne w dokumentacji dotyczącej interfejsu wiersza polecenia platformy Azure. Więcej przykładów można również 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 bazy danych Cassandra, przykłady interfejsu wiersza polecenia dla interfejsu API dla bazy danych MongoDB, przykłady interfejsu wiersza 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 sposób działania usługi Azure Resource Manager z identyfikatorami URI zasobów.

Konta usługi Azure Cosmos DB

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 przy użyciu 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 zawierać mniej 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 ani zmieniać innych właściwości konta usługi Azure Cosmos DB. Modyfikowanie regionów musi być wykonywane jako oddzielna operacja niż jakakolwiek inna zmiana zasobu konta.

Uwaga

To polecenie umożliwia dodawanie i usuwanie regionów, ale nie pozwala na modyfikowanie priorytetów trybu failover lub wyzwalanie ręcznego trybu failover. Zobacz Ustawianie priorytetu trybu failover i Wyzwalanie ręcznego przejścia w tryb failover.

Napiwek

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 trwa operacja skalowania przepływności asynchronicznej, 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

Uwaga

Zmiana regionu o priorytcie = 0 spowoduje wyzwolenie ręcznego przejścia 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 kont

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

Uzyskiwanie 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 parametry 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 pokazano, jak zarządzać bazą danych usługi Azure Cosmos DB, w tym:

Utwórz bazę 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 autoskalowania

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

Zapobieganie usuwaniu bazy danych

Umieść blokadę usuwania zasobów platformy Azure w bazie danych, aby zapobiec jego usunięciu. Ta funkcja wymaga zablokowania konta usługi Azure Cosmos DB przed zmianą 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, określając typ 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 jednostkami 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 konta usługi Azure Cosmos DB przed zmianą 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, określając typ blokady ReadOnly . W przypadku kontenera usługi Azure Cosmos DB blokady mogą służyć do zapobiegania zmianie przepływności lub jakiejkolwiek 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: