使用 Azure CLI 管理 Azure Cosmos Core (SQL) API 资源

适用于: SQL API Cassandra API Gremlin API 表 API Azure Cosmos DB API for MongoDB

以下指南介绍了使用 Azure CLI 自动管理 Azure Cosmos DB 帐户、数据库和容器的常见命令。 Azure CLI 参考中收录了所有 Azure Cosmos DB CLI 命令的参考页。 还可以在针对 Azure Cosmos DB 的 Azure CLI 示例中找到更多示例,包括如何为 MongoDB、Gremlin、Cassandra 和表 API 创建和管理 Cosmos DB 帐户、数据库和容器。

先决条件

  • 如果需要,请安装 Azure CLI 来运行 CLI 参考命令。

    • 如果使用的是本地安装,请使用 az login 命令登录到 Azure CLI。 若要完成身份验证过程,请遵循终端中显示的步骤。 有关其他登录选项,请参阅登录 Azure CLI

    • 出现提示时,请在首次使用时安装 Azure CLI 扩展。 有关扩展详细信息,请参阅使用 Azure CLI 的扩展

    • 运行 az version 以查找安装的版本和依赖库。 若要升级到最新版本,请运行 az upgrade

  • 本文需要 2.22.1 或更高版本的 Azure CLI。

备注

请先运行 az cloud set -n AzureChinaCloud 更改云环境,然后才能在 Azure 中国世纪互联中使用 Azure CLI。 若要切换回 Azure 公有云,请再次运行 az cloud set -n AzureCloud

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

重要

无法重命名 Azure Cosmos DB 资源,因为这违反了 Azure 资源管理器与资源 URI 的工作方式。

Azure Cosmos 帐户

以下部分演示如何管理 Azure Cosmos 帐户,包括:

创建 Azure Cosmos DB 帐户

在“中国北部 2”和“中国东部 2”区域创建启用了 SQL API 和会话一致性的 Azure Cosmos DB 帐户:

重要

Azure Cosmos 帐户名称必须为小写且小于 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='China North 2' failoverPriority=0 isZoneRedundant=False \
    --locations regionName='China East 2' failoverPriority=1 isZoneRedundant=False

添加或删除区域

创建包含两个区域的 Azure Cosmos 帐户,添加一个区域,并删除一个区域。

备注

不能同时添加或删除区域 locations 并更改 Azure Cosmos 帐户的其他属性。 修改区域的操作必须作为单独的操作与任何其他对帐户资源的更改操作分开执行。

备注

此命令可添加和删除区域,但不可修改故障转移优先级或触发手动故障转移。 请参阅设置故障转移优先级触发手动故障转移

提示

添加新区域时,必须将所有数据完全复制并提交到新区域,然后才能将该区域标记为可用。 此操作所需的时间取决于帐户中存储的数据量。

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'

# Create an account with 2 regions
az cosmosdb create --name $accountName --resource-group $resourceGroupName \
    --locations regionName="China North 2" failoverPriority=0 isZoneRedundant=False \
    --locations regionName="China East 2" failoverPriority=1 isZoneRedundant=False

# Add a region
az cosmosdb update --name $accountName --resource-group $resourceGroupName \
    --locations regionName="China North 2" failoverPriority=0 isZoneRedundant=False \
    --locations regionName="China East 2" failoverPriority=1 isZoneRedundant=False \
    --locations regionName="China East" failoverPriority=2 isZoneRedundant=False

# Remove a region
az cosmosdb update --name $accountName --resource-group $resourceGroupName \
    --locations regionName="China North 2" failoverPriority=0 isZoneRedundant=False \
    --locations regionName="China East 2" failoverPriority=1 isZoneRedundant=False

启用多个写入区域

为 Cosmos 帐户启用多区域写入

# Update an Azure Cosmos 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 帐户设置故障转移优先级

# Assume region order is initially 'China North 2'=0 'China East 2'=1 'China East'=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 China East the next region to fail over to instead of China East 2
az cosmosdb failover-priority-change --ids $accountId \
    --failover-policies 'China North 2=0' 'China East=1' 'China East 2=2'

启用自动故障转移

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

触发手动故障转移

注意

在 priority = 0 的情况下更改区域会为 Azure Cosmos 帐户触发手动故障转移。 任何其他优先级更改都不会触发故障转移。

# Assume region order is initially 'China North 2=0' 'China East 2=1' 'China East=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 China East 2 as new write region
az cosmosdb failover-priority-change --ids $accountId \
    --failover-policies 'China East 2=0' 'China East=1' 'China North 2=2'

列出所有帐户密钥

获取 Cosmos 帐户的所有密钥。

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

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

列出只读帐户密钥

获取 Cosmos 帐户的只读密钥。

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

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

列出连接字符串

获取 Cosmos 帐户的连接字符串。

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

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

重新生成帐户密钥

重新生成 Cosmos 帐户的新密钥。

# 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 数据库,具体包括:

创建数据库

创建 Cosmos 数据库。

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

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

创建具有共享吞吐量的数据库

创建具有共享吞吐量的 Cosmos 数据库。

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

更改数据库吞吐量

将 Cosmos 数据库的吞吐量增加 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 资源删除锁置于数据库上,以防止删除该数据库。 此功能要求锁定 Cosmos 帐户,防止其被数据平面 SDK 更改。 若要了解详细信息,请参阅防止被 SDK 更改。 Azure 资源锁也可以通过指定 ReadOnly 锁类型来防止更改资源。 对于 Cosmos 数据库,可以使用该锁来防止更改吞吐量。

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 容器,具体包括:

创建容器

创建带有默认索引策略、分区键且 RU/s 为 400 的 Cosmos 容器。

# Create a SQL API 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/s 为 4000 的 Cosmos 容器。

# Create a SQL API 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 的 Cosmos 容器。

# Create an Azure Cosmos 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 的 Cosmos 容器。

# Create a SQL API 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"

更改容器吞吐量

将 Cosmos 容器的吞吐量增加 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 资源删除锁置于容器上,以防止删除该容器。 此功能要求锁定 Cosmos 帐户,防止其被数据平面 SDK 更改。 若要了解详细信息,请参阅防止被 SDK 更改。 Azure 资源锁也可以通过指定 ReadOnly 锁类型来防止更改资源。 对于 Cosmos 容器,此锁可用于防止更改吞吐量或其他任何属性。

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