管理 Azure Cosmos 帐户Manage an Azure Cosmos account

本文介绍如何使用 Azure 门户、Azure PowerShell、Azure CLI 和 Azure 资源管理器模板管理 Azure Cosmos 帐户中的各种任务。This article describes how to manage various tasks on an Azure Cosmos account using the Azure portal, Azure PowerShell, Azure CLI, and Azure Resource Manager templates.

创建帐户Create an account

Azure 门户Azure portal

  1. 登录到 Azure 门户Sign in to the Azure portal.

  2. 选择“创建资源” > “数据库” > “Azure Cosmos DB”。Select Create a resource > Databases > Azure Cosmos DB.

    Azure 门户“数据库”窗格

  3. 在“创建 Azure Cosmos DB 帐户”页上,输入新 Azure Cosmos 帐户的基本设置。On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    设置Setting Value DescriptionDescription
    订阅Subscription 订阅名称Subscription name 选择要用于此 Azure Cosmos 帐户的 Azure 订阅。Select the Azure subscription that you want to use for this Azure Cosmos account.
    资源组Resource Group 资源组名称Resource group name 选择一个资源组,或者选择“新建”,然后输入新资源组的唯一名称。Select a resource group, or select Create new, then enter a unique name for the new resource group.
    帐户名Account Name 输入唯一的名称Enter a unique name 输入标识此 Azure Cosmos 帐户的名称。Enter a name to identify your Azure Cosmos account. 由于 documents.azure.cn 字符串将追加到所提供的 ID 后面以创建 URI,因此,请使用唯一的 ID。Because documents.azure.cn is appended to the ID that you provide to create your URI, use a unique ID.

    ID 只能包含小写字母、数字和连字符 (-) 字符。The ID can only contain lowercase letters, numbers, and the hyphen (-) character. 它的长度必须介于 3 到 31 个字符之间。It must be between 3-31 characters in length.
    APIAPI Core (SQL)Core (SQL) API 确定要创建的帐户的类型。The API determines the type of account to create. Azure Cosmos DB 提供五种 API:适用于文档数据的 Core (SQL) 和 MongoDB、适用于图形数据的 Gremlin、Azure 表和 Cassandra。Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. 目前,你必须为每种 API 创建单独的帐户。Currently, you must create a separate account for each API.

    选择“Core (SQL)”,以便使用 SQL 语法创建文档数据库并进行查询。Select Core (SQL) to create a document database and query by using SQL syntax.

    详细了解 SQL APILearn more about the SQL API.
    位置Location 选择离用户最近的区域Select the region closest to your users 选择用于托管 Azure Cosmos DB 帐户的地理位置。Select a geographic location to host your Azure Cosmos DB account. 使用离用户最近的位置,使他们能够以最快的速度访问数据。Use the location that is closest to your users to give them the fastest access to the data.

    Azure Cosmos DB 的“新建帐户”页

  4. 选择“查看 + 创建”。Select Review + create. 可以跳过“网络”和“标记”部分。You can skip the Network and Tags sections.

  5. 检查帐户设置,然后选择“创建”。Review the account settings, and then select Create. 创建帐户需要几分钟时间。It takes a few minutes to create the account. 等待门户页显示“你的部署已完成”消息。Wait for the portal page to display Your deployment is complete.

    Azure 门户“通知”窗格

  6. 选择“转到资源”,转到 Azure Cosmos DB 帐户页。Select Go to resource to go to the Azure Cosmos DB account page.

    Azure Cosmos DB 帐户页

Azure CLIAzure CLI

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

# Create an account
$resourceGroupName = 'myResourceGroup'
$accountName = 'myaccountname' # must be lower case.

az cosmosdb create \
   --name $accountName \
   --resource-group $resourceGroupName \
   --kind GlobalDocumentDB \
   --default-consistency-level Session \
   --locations chinanorth=0 chinaeast=1 \
   --enable-multiple-write-locations true

Azure PowerShellAzure PowerShell

# Sign in the Azure China Cloud
Connect-AzAccount -Environment AzureChinaCloud

# Create an Azure Cosmos account for Core (SQL) API
$resourceGroupName = "myResourceGroup"
$location = "China North"
$accountName = "mycosmosaccount" # must be lower case.

$locations = @(
    @{ "locationName"="China North"; "failoverPriority"=0 },
    @{ "locationName"="China East"; "failoverPriority"=1 }
)

$consistencyPolicy = @{
    "defaultConsistencyLevel"="BoundedStaleness";
    "maxIntervalInSeconds"=300;
    "maxStalenessPrefix"=100000
}

$CosmosDBProperties = @{
    "databaseAccountOfferType"="Standard";
    "locations"=$locations;
    "consistencyPolicy"=$consistencyPolicy;
    "enableMultipleWriteLocations"="true"
}

New-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName -Location $location `
    -Name $accountName -PropertyObject $CosmosDBProperties

Azure Resource Manager 模板Azure Resource Manager template

此 Azure 资源管理器模板将为任何受支持的 API(配置有两个区域以及用于选择一致性级别、自动故障转移和多主数据库的选项)创建 Azure Cosmos 帐户。This Azure Resource Manager template will create an Azure Cosmos account for any supported API configured with two regions and options to select consistency level, automatic failover, and multi-master. 若要部署此模板,请在自述文件页创建 Azure Cosmos 帐户上,单击“部署到 Azure”To deploy this template, click on Deploy to Azure on the readme page, Create Azure Cosmos account

“部署到 Azure”Deploy to Azure

在数据库帐户中添加/删除区域Add/remove regions from your database account

Azure 门户Azure portal

  1. 登录到 Azure 门户Sign in to Azure portal.

  2. 导航到 Azure Cosmos 帐户,打开“全局复制数据”菜单 。Go to your Azure Cosmos account, and open the Replicate data globally menu.

  3. 要添加区域,请在地图上选择包含与所需区域对应的 + 标签的六边形。To add regions, select the hexagons on the map with the + label that corresponds to your desired region(s). 另外,若要添加某个区域,请选择“+ 添加区域”选项,然后从下拉菜单中选择一个区域。 Alternatively, to add a region, select the + Add region option and choose a region from the drop-down menu.

  4. 若要删除区域,请选择带对号的蓝色六边形以从地图中清除一个或多个区域。To remove regions, clear one or more regions from the map by selecting the blue hexagons with check marks. 或者选择右侧位于区域旁边的“废纸篓”(🗑) 图标。Or select the "wastebasket" (🗑) icon next to the region on the right side.

  5. 若要保存更改,请选择“确定”。 To save your changes, select OK.

    添加或删除区域菜单

在单区域写入模式下,不能删除写入区域。In a single-region write mode, you cannot remove the write region. 必须先故障转移到另一区域,然后才能删除当前的写入区域。You must fail over to a different region before you can delete the current write region.

在多区域写入模式下,如果你至少具有一个区域,则可以添加或删除任何区域。In a multi-region write mode, you can add or remove any region, if you have at least one region.

Azure CLIAzure CLI

$resourceGroupName = 'myResourceGroup'
$accountName = 'myaccountname'

# Create an account with 1 region
az cosmosdb create --name $accountName --resource-group $resourceGroupName --locations chinanorth=0

# Add a region
az cosmosdb update --name $accountName --resource-group $resourceGroupName --locations chinanorth=0 chinaeast=1

# Remove a region
az cosmosdb update --name $accountName --resource-group $resourceGroupName --locations chinanorth=0

Azure PowerShellAzure PowerShell

# Create an account with 1 region
$resourceGroupName = "myResourceGroup"
$location = "China North"
$accountName = "mycosmosaccount" # must be lower case.

$locations = @( @{ "locationName"="China North"; "failoverPriority"=0 } )
$consistencyPolicy = @{ "defaultConsistencyLevel"="Session" }
$CosmosDBProperties = @{
    "databaseAccountOfferType"="Standard";
    "locations"=$locations;
    "consistencyPolicy"=$consistencyPolicy
}
New-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName -Location $location `
    -Name $accountName -PropertyObject $CosmosDBProperties

# Add a region
$account = Get-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName -Name $accountName

$locations = @( 
    @{ "locationName"="China North"; "failoverPriority"=0 },
    @{ "locationName"="China East"; "failoverPriority"=1 } 
)

$account.Properties.locations = $locations
$CosmosDBProperties = $account.Properties

Set-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName -PropertyObject $CosmosDBProperties

# Azure Resource Manager does not wait on the resource update
Write-Host "Confirm region added before continuing..."

# Remove a region
$account = Get-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName -Name $accountName

$locations = @( @{ "locationName"="China North"; "failoverPriority"=0 } )

$account.Properties.locations = $locations
$CosmosDBProperties = $account.Properties

Set-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName -PropertyObject $CosmosDBProperties

配置多个写入区域Configure multiple write-regions

Azure 门户Azure portal

打开“全局复制数据”选项卡,选择“启用”以启用多区域写入 。Open the Replicate Data Globally tab and select Enable to enable multi-region writes. 启用多区域写入后,你的帐户当前拥有的所有读取区域将变为读取和写入区域。After you enable multi-region writes, all the read regions that you currently have on the account will become read and write regions.

Note

启用多区域写入后,无法禁用它。After you enable multi-region writes, you cannot disable it.

Azure Cosmos 帐户配置多主数据库屏幕快照

Azure CLIAzure CLI

$resourceGroupName = 'myResourceGroup'
$accountName = 'myaccountname'
az cosmosdb update --name $accountName --resource-group $resourceGroupName --enable-multiple-write-locations true

Azure PowerShellAzure PowerShell

# Update an Azure Cosmos account from single to multi-master

$account = Get-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName -Name $accountName

$account.Properties.enableMultipleWriteLocations = "true"
$CosmosDBProperties = $account.Properties

Set-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName -PropertyObject $CosmosDBProperties

Resource Manager 模板Resource Manager template

可通过部署用于创建帐户的资源管理器模板和设置 enableMultipleWriteLocations: true 来将一个帐户从单主数据库迁移到多主数据库。An account can be migrated from single-master to multi-master by deploying the Resource Manager template used to create the account and setting enableMultipleWriteLocations: true. 以下 Azure 资源管理器模板是一个极简模板,该模板会在启用单区域和多主数据库的情况下为 SQL API 部署 Azure Cosmos 帐户。The following Azure Resource Manager template is a bare minimum template that will deploy an Azure Cosmos account for SQL API with a single region and multi-master enabled.

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "name": {
            "type": "String"
        },
        "location": {
            "type": "String",
            "defaultValue": "[resourceGroup().location]"
        }
    },
    "resources": [
        {
            "type": "Microsoft.DocumentDb/databaseAccounts",
            "kind": "GlobalDocumentDB",
            "name": "[parameters('name')]",
            "apiVersion": "2015-04-08",
            "location": "[parameters('location')]",
            "tags": {},
            "properties": {
                "databaseAccountOfferType": "Standard",
                "consistencyPolicy": { "defaultConsistencyLevel": "Session" },
                "locations": [
                    {
                        "locationName": "[parameters('location')]",
                        "failoverPriority": 0
                    }
                ],
                "enableMultipleWriteLocations": true
            }
        }
    ]
}

为 Azure Cosmos 帐户启用自动故障转移Enable automatic failover for your Azure Cosmos account

借助自动故障转移选项,在某个区域不可用时,Azure Cosmos DB 可以故障转移到具有最高故障转移优先级的区域,无需用户操作。The Automatic failover option allows Azure Cosmos DB to failover to the region with the highest failover priority with no user action should a region become unavailable. 如果启用自动故障转移,则可修改区域优先级。When automatic failover is enabled, region priority can be modified. 帐户必须具有两个或更多区域以启用自动故障转移。Account must have two or more regions to enable automatic failover.

Azure 门户Azure portal

  1. 在 Azure Cosmos 帐户中,打开“全局复制数据”窗格 。From your Azure Cosmos account, open the Replicate data globally pane.

  2. 在窗格顶部选择“自动故障转移”。 At the top of the pane, select Automatic Failover.

    “多区域复制数据”菜单

  3. 在“自动故障转移”窗格中,确保将“启用自动故障转移”设置为“开”。 On the Automatic Failover pane, make sure that Enable Automatic Failover is set to ON.

  4. 选择“保存”。 Select Save.

    自动故障转移门户菜单

Azure CLIAzure CLI

# Enable automatic failover on an existing account
$resourceGroupName = 'myResourceGroup'
$accountName = 'myaccountname'

az cosmosdb update --name $accountName --resource-group $resourceGroupName --enable-automatic-failover true

Azure PowerShellAzure PowerShell

$resourceGroupName = "myResourceGroup"
$accountName = "mycosmosaccount"

$account = Get-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName

$account.Properties.enableAutomaticFailover="true";
$CosmosDBProperties = $account.Properties;

Set-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName -PropertyObject $CosmosDBProperties

为 Azure Cosmos 帐户设置故障转移优先级Set failover priorities for your Azure Cosmos account

Cosmos 帐户配置为自动故障转移后,可以更改区域的故障转移优先级。After a Cosmos account is configured for automatic failover, the failover priority for regions can be changed.

Important

帐户配置为自动故障转移后,不能修改写入区域(故障转移优先级为零)。You cannot modify the write region (failover priority of zero) when the account is configured for automatic failover. 要更改写入区域,必须禁用自动故障转移并执行手动故障转移。To change the write region, you must disable automatic failover and do a manual failover.

Azure 门户Azure portal

  1. 在 Azure Cosmos 帐户中,打开“多区域复制数据”窗格 。From your Azure Cosmos account, open the Replicate data multiple-regionally pane.

  2. 在窗格顶部选择“自动故障转移”。 At the top of the pane, select Automatic Failover.

    “多区域复制数据”菜单

  3. 在“自动故障转移”窗格中,确保将“启用自动故障转移”设置为“开”。 On the Automatic Failover pane, make sure that Enable Automatic Failover is set to ON.

  4. 若要修改故障转移优先级,请将鼠标指针悬停在读取区域上,并通过在行左侧出现的三个点拖动读取区域。To modify the failover priority, drag the read regions via the three dots on the left side of the row that appear when you hover over them.

  5. 选择“保存”。 Select Save.

    自动故障转移门户菜单

Azure CLIAzure CLI

# Assume region order is initially chinaeast=0 chinanorth=1 chinaeast2=2 on account creation
$resourceGroupName = 'myResourceGroup'
$accountName = 'myaccountname'

az cosmosdb failover-priority-change --name $accountName --resource-group $resourceGroupName --failover-policies chinaeast=0 chinaeast2=1 chinanorth=2

Azure PowerShellAzure PowerShell

# Assume account currently has regions with priority: China North = 0, China East = 1, China East 2 = 2
$resourceGroupName = "myResourceGroup"
$accountName = "myaccountname"

$failoverPolicies = @(
    @{ "locationName"="China North"; "failoverPriority"=0 },
    @{ "locationName"="China East 2"; "failoverPriority"=1 },
    @{ "locationName"="China East"; "failoverPriority"=2 }
)

Invoke-AzResourceAction -Action failoverPriorityChange `
    -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" `
    -ResourceGroupName $resourceGroupName -Name $accountName -Parameters $failoverPolicies

在 Azure Cosmos 帐户上执行手动故障转移Perform manual failover on an Azure Cosmos account

Important

Azure Cosmos 帐户必须配置为手动故障转移,才能成功执行此操作。The Azure Cosmos account must be configured for manual failover for this operation to succeed.

执行手动故障转移的过程涉及将帐户的写入区域(故障转移优先级 = 0)更改为已为该帐户配置的其他区域。The process for performing a manual failover involves changing the account's write region (failover priority = 0) to another region configured for the account.

Note

多主数据库帐户不能进行手动故障转移。Multi-master accounts cannot be manually failed over. 对于使用 Azure Cosmos SDK 的应用程序,SDK 会检测某个区域何时变为不可用,然后自动重定向到下一个最近的区域(如果在 SDK 中使用多宿主 API)。For applications using the Azure Cosmos SDK, the SDK will detect when a region becomes unavailable, then redirect automatically to the next closest region if using multi-homing API in the SDK.

Azure 门户Azure portal

  1. 导航到 Azure Cosmos 帐户,打开“全局复制数据”菜单 。Go to your Azure Cosmos account, and open the Replicate data globally menu.

  2. 在菜单顶部,选择“手动故障转移”。 At the top of the menu, select Manual Failover.

    “多区域复制数据”菜单

  3. 在“手动故障转移” 菜单上,选择你的新写入区域。On the Manual Failover menu, select your new write region. 选中相应的复选框,以指示你了解此选项会更改你的写入区域。Select the check box to indicate that you understand this option changes your write region.

  4. 若要触发故障转移,请选择“确定”。 To trigger the failover, select OK.

    手动故障转移门户菜单

Azure CLIAzure CLI

# Assume account currently has regions with priority: chinaeast=0 chinanorth=1
# Change the priority order to trigger a failover of the write region
$resourceGroupName = 'myResourceGroup'
$accountName = 'myaccountname'

az cosmosdb update --name $accountName --resource-group $resourceGroupName --locations chinanorth=0 chinaeast=1

Azure PowerShellAzure PowerShell

# Assume account currently has regions with priority: China North = 0, China East = 1
# Change the priority order to trigger a failover of the write region
$resourceGroupName = "myResourceGroup"
$accountName = "myaccountname"

$account = Get-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName

$locations = @(
    @{ "locationName"="China East"; "failoverPriority"=0 },
    @{ "locationName"="China North"; "failoverPriority"=1 }
)

$account.Properties.locations=$locations;
$CosmosDBProperties = $account.Properties;

Set-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName -PropertyObject $CosmosDBProperties

后续步骤Next steps

有关如何管理 Azure Cosmos 帐户以及数据库和容器的详细信息和示例,请阅读以下文章:For more information and examples on how to manage the Azure Cosmos account as well as database and containers, read the following articles: