Azure CLI を使用した Azure Cosmos DB for NoSQL リソースの管理

[アーティクル]
08/15/2024

適用対象: NoSQL

次のガイドでは、Azure CLI を使用して Azure Cosmos DB のアカウント、データベース、コンテナーの管理を自動化するための共通のコマンドについて説明します。 Azure Cosmos DB CLI のすべてのコマンドのリファレンスページは、Azure CLI リファレンスで確認できます。 Azure Cosmos DB の Azure CLI サンプルにも、MongoDB、Gremlin、Cassandra、Table 用 API で Azure Cosmos DB のアカウント、データベース、コンテナーを作成し、管理する方法などを含むその他の例があります。

前提条件

Azure Cloud Shell で Bash 環境を使用します。詳細については、「Azure Cloud Shell の Bash のクイックスタート」を参照してください。
CLI リファレンスコマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。
- ローカルインストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。認証プロセスを完了するには、ターミナルに表示される手順に従います。その他のサインインオプションについては、Azure CLI でのサインインに関するページを参照してください。
- 初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。拡張機能の詳細については、Azure CLI で拡張機能を使用する方法に関するページを参照してください。
- az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。最新バージョンにアップグレードするには、az upgrade を実行します。

この記事では、Azure CLI のバージョン 2.22.1 以降が必要です。 Azure Cloud Shell を使用している場合は、最新バージョンが既にインストールされています。

他の API の Azure CLI サンプルについては、Cassandra の CLI サンプル、MongoDB 用 API の CLI サンプル、Gremlin の CLI サンプル、Table の CLI サンプルを参照してください

重要

Azure Cosmos DB リソースの名前を変更することはできません。これは、Azure Resource Manager がリソース URI と連携する方法に違反するためです。

Azure Cosmos DBAccounts

以下のセクションでは、次の内容を含む Azure Cosmos DB アカウントの管理方法について説明します。

Azure Cosmos DB アカウントの作成
リージョンの追加または削除
複数リージョンの書き込みを有効にする
リージョンのフェールオーバーの優先度を設定する
サービス管理フェールオーバーを有効にする
手動フェールオーバーをトリガーする
アカウントキーを一覧表示する
読み取り専用のアカウントキーを一覧表示する
接続文字列の一覧表示
アカウントキーを再生成する

Azure Cosmos DB アカウントを作成する

NoSQL 用 API を使用して、米国西部と米国東部のリージョンのセッション整合性で、Azure Cosmos DB アカウントを作成します。

重要

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

リージョンを追加または削除する

リージョンが 2 つある Azure Cosmos DB アカウントの作成、リージョンの追加、リージョンの削除を行います。

注意

Azure Cosmos DB アカウントに対し、リージョン locations の追加または削除と、他のプロパティの変更を同時に行うことはできません。リージョンの変更は、アカウントリソースに対する他のあらゆる変更とは別の操作として実行する必要があります。

Note

このコマンドでは、リージョンの追加および削除が可能ですが、フェールオーバー優先度を変更したり手動フェールオーバーをトリガーしたりすることはできません。フェールオーバーの優先度と手動フェールオーバーのトリガーに関する説明を参照してください。

ヒント

新しいリージョンが追加されるとき、すべてのデータが新しいリージョンに完全にレプリケートおよびコミットされるまで、リージョンには使用可能のマークが付きません。この操作にかかる時間は、アカウント内に保存されているデータの量によって変動します。非同期スループットスケーリング操作が進行中の場合、スループットのスケールアップ操作は一時停止され、リージョンの追加または削除操作が完了すると自動的に再開されます。

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 アカウントの手動フェールオーバーがトリガーされます。他の優先度を変更しても、フェールオーバーはトリガーされません。

Note

非同期スループットスケーリング操作の進行中に手動フェールオーバー操作を実行すると、スループットのスケールアップ操作は一時停止されます。フェールオーバー操作が完了すると、自動的に再開されます。

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

データベースが削除されないようにする

削除されないように、データベースに Azure リソースの削除ロックを配置します。この機能を使用するには、データプレーン SDK による Azure Cosmos DB アカウントの変更をロックする必要があります。詳細については、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 コンテナーの管理方法について説明します。

コンテナーの作成
自動スケーリングを使用してコンテナーを作成する
TTL が有効なコンテナーを作成する
カスタムインデックスポリシーを持つコンテナーの作成
コンテナーのスループットを変更する
コンテナーを自動スケーリングのスループットに移行する
コンテナーが削除されないようにする

コンテナーを作成する

既定のインデックスポリシー、パーティションキー、および 400 の秒あたりの RU を使用して Azure Cosmos DB コンテナーを作成します。

# 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

自動スケーリングを使用してコンテナーを作成する

既定のインデックスポリシー、パーティションキー、および 4000 の RU/s の自動スケーリングを使用して Azure Cosmos DB コンテナーを作成します。

# 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

TTL を使用したコンテナーを作成する

TTL を有効にして 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

カスタムインデックスポリシーを持つコンテナーを作成する

カスタムインデックスポリシー、空間インデックス、複合インデックス、パーティションキーを持ち、RU が秒あたり 400 の Azure Cosmos DB コンテナーを作成します。

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

コンテナーを自動スケーリングのスループットに移行する

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 リソースの削除ロックを配置します。この機能を使用するには、データプレーン SDK による Azure Cosmos DB アカウントの変更をロックする必要があります。詳細については、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 の詳細については、次をご覧ください。

次の方法で共有

Azure CLI を使用した Azure Cosmos DB for NoSQL リソースの管理

前提条件

Azure Cosmos DBAccounts

Azure Cosmos DB アカウントを作成する

リージョンを追加または削除する

複数の書き込みリージョンを有効にする

フェールオーバー優先度を設定する

サービス管理フェールオーバーを有効にする

手動フェールオーバーをトリガーする

すべてのアカウントキーを一覧表示する

読み取り専用のアカウントキーを一覧表示する

接続文字列の一覧表示

アカウントキーの再生成

Azure Cosmos DB データベース

データベースを作成する

共有スループットのデータベースを作成する

データベースを自動スケーリングのスループットに移行する

データベースのスループットを変更する

データベースが削除されないようにする

Azure Cosmos DB コンテナー

コンテナーを作成する

自動スケーリングを使用してコンテナーを作成する

TTL を使用したコンテナーを作成する

カスタムインデックスポリシーを持つコンテナーを作成する

コンテナーのスループットを変更する

コンテナーを自動スケーリングのスループットに移行する

コンテナーが削除されないようにする

次のステップ

フィードバック

その他のリソース

次の方法で共有

Azure CLI を使用した Azure Cosmos DB for NoSQL リソースの管理

前提条件

Azure Cosmos DBAccounts

Azure Cosmos DB アカウントを作成する

リージョンを追加または削除する

複数の書き込みリージョンを有効にする

フェールオーバー優先度を設定する

サービス管理フェールオーバーを有効にする

手動フェールオーバーをトリガーする

すべてのアカウント キーを一覧表示する

読み取り専用のアカウント キーを一覧表示する

接続文字列の一覧表示

アカウント キーの再生成

Azure Cosmos DB データベース

データベースを作成する

共有スループットのデータベースを作成する

データベースを自動スケーリングのスループットに移行する

データベースのスループットを変更する

データベースが削除されないようにする

Azure Cosmos DB コンテナー

コンテナーを作成する

自動スケーリングを使用してコンテナーを作成する

TTL を使用したコンテナーを作成する

カスタム インデックス ポリシーを持つコンテナーを作成する

コンテナーのスループットを変更する

コンテナーを自動スケーリングのスループットに移行する

コンテナーが削除されないようにする

次のステップ

フィードバック

その他のリソース

すべてのアカウントキーを一覧表示する

読み取り専用のアカウントキーを一覧表示する

アカウントキーの再生成

カスタムインデックスポリシーを持つコンテナーを作成する