使用 Azure CLI 为 Azure Cosmos 帐户添加区域、更改故障转移优先级、触发故障转移Add regions, change failover priority, trigger failover for an Azure Cosmos account using Azure CLI

备注

在 Azure China 中使用 Azure CLI 2.0 之前,请首先运行 az cloud set -n AzureChinaCloud 更改云环境。Before you can use Azure CLI 2.0 in Azure China, please run az cloud set -n AzureChinaCloud first to change the cloud environment. 如果要切换回全局 Azure,请再次运行 az cloud set -n AzureCloudIf you want to switch back to Global Azure, run az cloud set -n AzureCloud again.

选择在本地安装并使用 CLI 时,本主题要求运行 Azure CLI 2.9.1 或更高版本。When you choose to install and use the CLI locally, this topic requires that you are running the Azure CLI version 2.9.1 or later. 运行 az --version 即可查找版本。Run az --version to find the version. 如果需要进行安装或升级,请参阅安装 Azure CLIIf you need to install or upgrade, see Install Azure CLI.

示例脚本Sample script

此脚本演示三个操作。This script demonstrates three operations.

  • 将区域添加到现有 Azure Cosmos 帐户。Add a region to an existing Azure Cosmos account.
  • 更改区域故障转移优先级(适用于使用自动故障转移的帐户)Change regional failover priority (applies to accounts using automatic failover)
  • 触发从主要区域到次要区域的手动故障转移(适用于使用手动故障转移的帐户)Trigger a manual failover from primary to secondary regions (applies to accounts with manual failover)

备注

更改其他属性时,无法在 Cosmos 帐户上添加和删除区域操作。Add and remove region operations on a Cosmos account cannot be done while changing other properties.

备注

此示例演示了如何使用 SQL (Core) API 帐户,但这些操作在 Cosmos DB 中的所有数据库 API 中都是相同的。This sample demonstrates using a SQL (Core) API account but these operations are identical across all database APIs in Cosmos DB.

#!/bin/bash

# Sign in the Azure China Cloud
az cloud set -n AzureChinaCloud
az login

# This sample shows the following:
# Add regions to an existing Cosmos account
# Change regional failover priority (applies to accounts using automatic failover)
# Trigger a manual failover from primary to secondary region (applies to accounts with manual failover)

# Note: Azure Comos accounts cannot include updates to regions with changes to other properties in the same operation

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

# Resource group and Cosmos account variables
resourceGroupName="Group-$uniqueId"
location='chinanorth2'
accountName="cosmos-$uniqueId" #needs to be lower case

# Create a resource group
az group create -n $resourceGroupName -l $location

# Create a Cosmos DB account with default values
# Use appropriate values for --kind or --capabilities for other APIs
az cosmosdb create -n $accountName -g $resourceGroupName

read -p "Press any key to add additional regions to this account"
az cosmosdb update \
    -n $accountName \
    -g $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

read -p "Press any key to change the failover priority"
# Make China East the next region to fail over to instea of China East 2
az cosmosdb failover-priority-change \
    -n $accountName \
    -g $resourceGroupName \
    --failover-policies 'China North 2=0' 'China East=1' 'China East 2=2' 

read -p "Press any key to trigger a manual failover by changing region 0"
# Initiate a manual failover and promote China East 2 as primary write region
az cosmosdb failover-priority-change \
    -n $accountName \
    -g $resourceGroupName \
    --failover-policies 'China East 2=0' 'China North 2=1' 'China East=2'

清理部署Clean up deployment

运行脚本示例后,可以使用以下命令删除资源组以及与其关联的所有资源。After the script sample has been run, the following command can be used to remove the resource group and all resources associated with it.

az group delete --name $resourceGroupName

脚本说明Script explanation

此脚本使用以下命令。This script uses the following commands. 表中的每条命令均链接到特定于命令的文档。Each command in the table links to command specific documentation.

CommandCommand 注释Notes
az group createaz group create 创建用于存储所有资源的资源组。Creates a resource group in which all resources are stored.
az cosmosdb createaz cosmosdb create 创建 Azure Cosmos DB 帐户。Creates an Azure Cosmos DB account.
az cosmosdb updateaz cosmosdb update 更新 Azure Cosmos DB 帐户(添加或删除区域)。Updates an Azure Cosmos DB account (add or remove region).
az cosmosdb failover-priority-changeaz cosmosdb failover-priority-change 在 Azure Cosmos DB 帐户上更新故障转移优先级或触发故障转移。Update failover priority or trigger failover on an Azure Cosmos DB account.
az group deleteaz group delete 删除资源组,包括所有嵌套的资源。Deletes a resource group including all nested resources.

后续步骤Next steps

有关 Azure Cosmos DB CLI 的详细信息,请参阅 Azure Cosmos DB CLI 文档For more information on the Azure Cosmos DB CLI, see Azure Cosmos DB CLI documentation.

可以在 Azure Cosmos DB CLI GitHub 存储库中找到所有 Azure Cosmos DB CLI 脚本示例。All Azure Cosmos DB CLI script samples can be found in the Azure Cosmos DB CLI GitHub Repository.