Управление ресурсами Azure Cosmos DB для NoSQL с помощью Azure CLI

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ: NoSQL

В этом руководстве приведены команды Azure CLI, позволяющие автоматизировать управление учетными записями, базами данных и контейнерами Azure Cosmos DB. Страницы справки для всех команд интерфейса командной строки Azure Cosmos DB доступны в справочнике по Azure CLI. Дополнительные примеры см. в статье Примеры Azure CLI для Azure Cosmos DB, включая создание учетных записей, баз данных и контейнеров Azure Cosmos DB и управление ими для MongoDB, Gremlin, Cassandra и API для таблицы.

Предварительные требования

  • Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см. в статье Краткое руководство по Bash в Azure Cloud Shell.

  • Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в разделе Запуск Azure CLI в контейнере Docker.

    • Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, приведены в статье Вход с помощью Azure CLI.

    • Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений с Azure CLI.

    • Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

  • Для работы с этой статьей требуется Azure CLI 2.22.1 или более поздней версии. Если вы используете Azure Cloud Shell, последняя версия уже установлена.

Примеры Azure CLI для других API см. в разделах Примеры CLI для Cassandra, Примеры CLI для API для MongoDB, Примеры CLI для Gremlin, Примеры CLI для таблицы.

Важно!

Ресурсы Azure Cosmos DB нельзя переименовывать, так как это нарушит конвенции работы Azure Resource Manager с URI ресурсов.

Учетные записи Azure Cosmos DB

В следующих разделах показано, как управлять учетной записью Azure Cosmos DB, в том числе:

Создание учетной записи Azure Cosmos DB

Создайте учетную запись Azure Cosmos DB с ПОМОЩЬЮ API для NoSQL и согласованности сеансов в регионах "Западная часть США" и "Восточная часть США":

Важно!

Имя учетной записи Azure Cosmos DB должно быть строчным и содержать менее 44 символов.

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

Добавление и удаление регионов

Создайте учетную запись Azure Cosmos DB с двумя регионами, добавьте регион и удалите регион.

Примечание

Нельзя одновременно добавлять или удалять регионы locations , а также изменять другие свойства учетной записи Azure Cosmos DB. Изменение регионов нужно выполнять как отдельную операцию, не объединяя ее с другими изменениями в ресурсе учетной записи.

Примечание

Кроме того, эта команда позволяет добавлять или удалять регионы, но не изменять приоритеты при отработке отказа или активировать отработку отказа вручную. Ознакомьтесь с разделами о настройке приоритетов отработки отказа и об активации отработки отказа вручную.

Совет

При добавлении нового региона все данные должны быть полностью реплицированы и зафиксированы в новом регионе, прежде чем регион будет помечен как доступный. Продолжительность операции зависит от объема данных, хранящихся в учетной записи. Если идет операция асинхронного масштабирования пропускной способности, увеличение масштаба пропускной способности будет приостановлено и автоматически возобновится после завершения операции добавления и удаления региона.

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

Включение нескольких регионов записи

Включение операций записи в нескольких регионах для учетной записи 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

Задание приоритета отработки отказа

Установка приоритета отработки отказа для учетной записи Azure Cosmos DB, настроенной для отработки отказа, управляемой службой

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

Включение отработки отказа под управлением службы

# 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

Активация отработки отказа вручную

Внимание!

Изменение региона с приоритетом = 0 приведет к запуску отработки отказа вручную для учетной записи Azure Cosmos DB. Любые другие изменения приоритета не приведут к активации отработки отказа.

Примечание

Если выполнить переход на другой ресурс вручную во время асинхронного масштабирования пропускной способности, операция масштабирования пропускной способности будет приостановлена. Она будет возобновлена автоматически после завершения операции отработки отказа.

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

Перечисление ключей учетной записи.

Получите все ключи для учетной записи Azure Cosmos DB.

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

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

Вывод ключей только для чтения для учетной записи

Получите ключи только для чтения для учетной записи Azure Cosmos DB.

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

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

Вывод строк подключения

Получите строки подключения для учетной записи Azure Cosmos DB.

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

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

Повторное создание ключей учетных записей

Повторно создайте новый ключ для учетной записи 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

База данных Azure Cosmos DB

В следующих разделах описано управление базой данных Azure Cosmos DB, включая:

Создание базы данных

Создает базу данных Azure Cosmos DB.

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

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

Создание базы данных с общей пропускной способностью

Создайте базу данных Azure Cosmos DB с общей пропускной способностью.

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

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

Перенос базы данных в среду с автомасштабированием пропускной способности

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

Изменение пропускной способности базы данных

Увеличьте пропускную способность базы данных Azure Cosmos DB на 1000 ЕЗ/с.

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

Предотвращение удаления базы данных

Установите блокировку удаления ресурса Azure для базы данных, чтобы предотвратить ее удаление. Эта функция требует блокировки учетной записи Azure Cosmos DB пакетами SDK для плоскости данных. Дополнительные сведения см. в разделе предотвращение изменений из пакетов SDK. С помощью блокировок ресурсов Azure можно также запретить изменение ресурса, указав тип блокировки ReadOnly. Для базы данных Azure Cosmos DB ее можно использовать, чтобы предотвратить изменение пропускной способности.

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

Контейнер Azure Cosmos DB

В следующих разделах описаны процедуры управления контейнером Azure Cosmos DB, включая:

Создание контейнера

Создайте контейнер Azure Cosmos DB с политикой индекса по умолчанию, ключом секции и значением 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

Создание контейнера с автомасштабированием

Создайте контейнер Azure Cosmos DB с политикой индексов по умолчанию, ключом секции и автомасштабированием ЕЗ/с 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

Создание контейнера со сроком жизни

Создайте контейнер Azure Cosmos DB с включенным сроком жизни.

# 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

Создание контейнера с настраиваемой политикой индексирования

Создайте контейнер Azure Cosmos DB с настраиваемой политикой индексов, пространственным индексом, составным индексом, ключом секции и значением 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"

Изменение пропускной способности контейнера

Увеличьте пропускную способность контейнера Azure Cosmos DB на 1000 ЕЗ/с.

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

Перенос контейнера в среду с автомасштабированием пропускной способности

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

Предотвращение удаления контейнера

Установите блокировку удаления ресурса Azure для контейнера, чтобы предотвратить его удаление. Эта функция требует блокировки учетной записи Azure Cosmos DB пакетами SDK для плоскости данных. Дополнительные сведения см. в разделе предотвращение изменений из пакетов SDK. С помощью блокировок ресурсов Azure можно также запретить изменение ресурса, указав тип блокировки ReadOnly. Для контейнера Azure Cosmos DB можно использовать блокировки, чтобы предотвратить изменение пропускной способности или любого другого свойства.

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

Дальнейшие действия

Дополнительные сведения об Azure CLI см.: