Поделиться через

Управление ресурсами 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 см. в примерах интерфейса командной строки для Cassandra, примерах CLI для API для MongoDB, примерах CLI для Gremlin, примерах CLI для таблицы

Внимание

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

Azure Cosmos DBAccounts

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

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

Создайте контейнер 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 см.: