使用 Azure CLI 管理 Azure Cosmos DB for NoSQL 资源

2025-04-21

适用范围： NoSQL

以下指南介绍了使用 Azure CLI 自动管理 Azure Cosmos DB 帐户、数据库和容器的常见命令。 Azure CLI 参考中收录了所有 Azure Cosmos DB CLI 命令的参考页。

先决条件

在 Azure Cloud Shell 中使用 Bash 环境。有关详细信息，请参阅开始使用 Azure Cloud Shell。
如需在本地运行 CLI 参考命令，请安装 Azure CLI。如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。
- 如果使用的是本地安装，请使用 az login 命令登录到 Azure CLI。若要完成身份验证过程，请遵循终端中显示的步骤。有关其他登录选项，请参阅使用 Azure CLI 向 Azure 进行身份验证。
- 出现提示时，请在首次使用时安装 Azure CLI 扩展。有关扩展详细信息，请参阅使用和管理 Azure CLI 的扩展。
- 运行 az version 以查找安装的版本和依赖库。若要升级到最新版本，请运行 az upgrade。

本文需要 2.22.1 或更高版本的 Azure CLI。如果使用 Azure Cloud Shell，则最新版本已安装。

有关其他 API 的 Azure CLI 示例，请参阅适用于 Cassandra 的 CLI 示例、适用于 API for MongoDB 的 CLI 示例、适用于 Gremlin 的 CLI 示例、适用于 Table 的 CLI 示例

重要

无法重命名 Azure Cosmos DB 资源，因为这将违反 Azure 资源管理器对资源 URI 的使用方法。

Azure Cosmos DB 帐户

以下部分演示了如何管理 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

添加或删除区域

创建包含两个区域的 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 RU/秒。

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 容器，具体包括：

创建容器
使用自动缩放创建容器
创建启用了 TTL 的容器
使用自定义索引策略创建容器
更改容器吞吐量
迁移容器以自动缩放吞吐量
防止容器被删除

创建容器

创建带有默认索引策略、分区键和 RU/秒为 400 的 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

使用自动缩放创建容器

创建带有默认索引策略、分区键和自动缩放 RU/秒为 4000 的 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/s 为 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/秒。

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 的详细信息，请参阅：

通过