管理 Azure Cosmos 帐户

本文介绍了如何管理你的 Azure Cosmos DB 帐户。 你将了解如何设置多宿主功能、添加或删除区域、配置多个写入区域,以及设置故障转移优先级。

创建数据库帐户

Azure 门户

  1. 在新浏览器窗口中,登录到 Azure 门户

  2. 选择“创建资源” > “数据库” > “Azure Cosmos DB”。

    Azure 门户“数据库”窗格

  3. 在“创建 Azure Cosmos DB 帐户”页上,输入新 Azure Cosmos DB 帐户的基本设置。

    设置 说明
    订阅 订阅 选择要用于此 Azure Cosmos DB 帐户的 Azure 订阅。
    资源组 新建

    然后输入在 ID 中提供的同一唯一名称
    选择“新建”。 然后输入帐户的新资源组名称。 为简单起见,可以使用与 ID 相同的名称。
    帐户名 输入唯一的名称 输入标识此 Azure Cosmos DB 帐户的唯一名称。 由于 documents.azure.cn 字符串将追加到所提供的 ID 后面以创建 URI,因此,请使用唯一的 ID。

    ID 只能包含小写字母、数字和连字符 (-) 字符。 它的长度必须介于 3 到 31 个字符之间。
    API Core(SQL) API 确定要创建的帐户的类型。 Azure Cosmos DB 提供两种 API:适用于文档数据库的 Core(SQL) 和适用于文档数据库的 MongoDB。 目前,你必须为每种 API 创建单独的帐户。

    之所以选择 Core(SQL) 是因为本文将使用 SQL 语法创建文档数据库并进行查询。

    详细了解 SQL API
    位置 选择离用户最近的区域 选择用于托管 Azure Cosmos DB 帐户的地理位置。 使用离用户最近的位置,使他们能够以最快的速度访问数据。

    选择“查看 + 创建”。 可以跳过“网络”和“标记”部分。

    Azure Cosmos DB 的“新建帐户”页

  4. 创建帐户需要几分钟时间。 等待门户中显示“祝贺你!已创建 Azure Cosmos DB 帐户”页。

    Azure 门户“通知”窗格

Azure CLI

# Create an account
az cosmosdb create --name <Azure Cosmos account name> --resource-group <Resource Group Name>

配置多宿主客户端

.NET SDK v2

ConnectionPolicy policy = new ConnectionPolicy
    {
        ConnectionMode = ConnectionMode.Direct,
        ConnectionProtocol = Protocol.Tcp,
        UseMultipleWriteLocations = true
    };
policy.SetCurrentLocation("China North");

// Pass the connection policy with the preferred locations on it to the client.
DocumentClient client = new DocumentClient(new Uri(this.accountEndpoint), this.accountKey, policy);

.NET SDK v3(预览版)

CosmosConfiguration config = new CosmosConfiguration("endpoint", "key");
config.UseCurrentRegion("China North");
CosmosClient client = new CosmosClient(config);

Java 异步 SDK

ConnectionPolicy policy = new ConnectionPolicy();
policy.setUsingMultipleWriteLocations(true);
policy.setPreferredLocations(Collections.singletonList(region));

AsyncDocumentClient client =
    new AsyncDocumentClient.Builder()
        .withMasterKeyOrResourceToken(this.accountKey)
        .withServiceEndpoint(this.accountEndpoint)
        .withConsistencyLevel(ConsistencyLevel.Eventual)
        .withConnectionPolicy(policy).build();

Node.js/JavaScript/TypeScript SDK

const connectionPolicy: ConnectionPolicy = new ConnectionPolicy();
connectionPolicy.UseMultipleWriteLocations = true;
connectionPolicy.PreferredLocations = [region];

const client = new CosmosClient({
  endpoint: config.endpoint,
  auth: { masterKey: config.key },
  connectionPolicy,
  consistencyLevel: ConsistencyLevel.Eventual
});

Python SDK

connection_policy = documents.ConnectionPolicy()
connection_policy.UseMultipleWriteLocations = True
connection_policy.PreferredLocations = [region]

client = cosmos_client.CosmosClient(self.account_endpoint, {'masterKey': self.account_key}, connection_policy, documents.ConsistencyLevel.Session)

在数据库帐户中添加/删除区域

Azure 门户

  1. 导航到你的 Azure Cosmos DB 帐户,打开“全局复制数据”菜单。

  2. 若要添加区域,请在地图上选择带有 + 标签且与你所需的区域对应的六边形。 若要添加某个区域,请选择“+ 添加区域”选项,然后从下拉菜单中选择一个区域。

  3. 若要删除区域,请选择带对号的蓝色六边形以从地图中清除一个或多个区域。 或者选择右侧位于区域旁边的“废纸篓”(🗑) 图标。

  4. 若要保存更改,请选择“确定”。

    添加或删除区域菜单

在单区域写入模式下,不能删除写入区域。 必须先故障转移到另一区域,然后才能删除当前的写入区域。

在多区域写入模式下,如果你至少具有一个区域,则可以添加或删除任何区域。

Azure CLI

# Given an account created with 1 region like so
az cosmosdb create --name <Azure Cosmos account name> --resource-group <Resource Group name> --locations 'chinaeast=0'

# Add a new region by adding another region to the list
az cosmosdb update --name <Azure Cosmos account name> --resource-group <Resource Group name> --locations 'chinaeast=0 chinanorth=1'

# Remove a region by removing a region from the list
az cosmosdb update --name <Azure Cosmos account name> --resource-group <Resource Group name> --locations 'chinanorth=0'

配置多个写入区域

Azure 门户

创建数据库帐户时,请确保启用“多区域写入”设置。

Azure Cosmos 帐户创建屏幕截图

Azure CLI

az cosmosdb create --name <Azure Cosmos account name> --resource-group <Resource Group name> --enable-multiple-write-locations true

Resource Manager 模板

以下 JSON 代码是 Azure 资源管理器模板的一个示例。 可以使用它部署采用有限过期一致性策略的 Azure Cosmos DB 帐户。 最大过期时间间隔设置为 5 秒。 可以容忍的过期请求的最大数量设置为 100。 若要了解资源管理器模板的格式和语法,请参阅资源管理器

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "name": {
            "type": "String"
        },
        "location": {
            "type": "String"
        },
        "locationName": {
            "type": "String"
        },
        "defaultExperience": {
            "type": "String"
        }
    },
    "resources": [
        {
            "type": "Microsoft.DocumentDb/databaseAccounts",
            "kind": "GlobalDocumentDB",
            "name": "[parameters('name')]",
            "apiVersion": "2015-04-08",
            "location": "[parameters('location')]",
            "tags": {
                "defaultExperience": "[parameters('defaultExperience')]"
            },
            "properties": {
                "databaseAccountOfferType": "Standard",
                "consistencyPolicy": {
                    "defaultConsistencyLevel": "BoundedStaleness",
                    "maxIntervalInSeconds": 5,
                    "maxStalenessPrefix": 100
                },
                "locations": [
                    {
                        "id": "[concat(parameters('name'), '-', parameters('location'))]",
                        "failoverPriority": 0,
                        "locationName": "[parameters('locationName')]"
                    }
                ],
                "isVirtualNetworkFilterEnabled": false,
                "enableMultipleWriteLocations": true,
                "virtualNetworkRules": [],
                "dependsOn": []
            }
        }
    ]
}

为 Azure Cosmos DB 帐户启用手动故障转移

Azure 门户

  1. 导航到你的 Azure Cosmos DB 帐户,打开“全局复制数据”菜单。

  2. 在菜单顶部,选择“手动故障转移”。

    “复制多区域数据”菜单

  3. 在“手动故障转移”菜单上,选择你的新写入区域。 选中相应的复选框,以指示你了解此选项会更改你的写入区域。

  4. 若要触发故障转移,请选择“确定”。

    手动故障转移门户菜单

Azure CLI

# Given your account currently has regions with priority like so: 'chinaeast=0 chinanorth=1'
# Change the priority order to trigger a failover of the write region
az cosmosdb update --name <Azure Cosmos account name> --resource-group <Resource Group name> --locations 'chinaeast=1 chinanorth=0'

为 Azure Cosmos DB 帐户启用自动故障转移

Azure 门户

  1. 在 Azure Cosmos DB 帐户中,打开“全局复制数据”窗格。

  2. 在窗格顶部选择“自动故障转移”。

    “复制多区域数据”菜单

  3. 在“自动故障转移”窗格中,确保将“启用自动故障转移”设置为“开”。

  4. 选择“保存”。

    自动故障转移门户菜单

也可在此菜单上设置自动故障转移优先级。

Azure CLI

# Enable automatic failover on account creation
az cosmosdb create --name <Azure Cosmos account name> --resource-group <Resource Group name> --enable-automatic-failover true

# Enable automatic failover on an existing account
az cosmosdb update --name <Azure Cosmos account name> --resource-group <Resource Group name> --enable-automatic-failover true

# Disable automatic failover on an existing account
az cosmosdb update --name <Azure Cosmos account name> --resource-group <Resource Group name> --enable-automatic-failover false

为 Azure Cosmos DB 帐户设置故障转移优先级

Azure 门户

  1. 在 Azure Cosmos DB 帐户中,打开“全局复制数据”窗格。

  2. 在窗格顶部选择“自动故障转移”。

    “复制多区域数据”菜单

  3. 在“自动故障转移”窗格中,确保将“启用自动故障转移”设置为“开”。

  4. 若要修改故障转移优先级,请将鼠标指针悬停在读取区域上,并通过在行左侧出现的三个点拖动读取区域。

  5. 选择“保存”。

    自动故障转移门户菜单

不能在此菜单上修改写入区域。 若要手动更改写入区域,必须执行手动故障转移。

Azure CLI

az cosmosdb failover-priority-change --name <Azure Cosmos account name> --resource-group <Resource Group name> --failover-policies 'chinaeast=0 chinanorth=2 chinaeast2=1'

后续步骤

了解如何管理 Azure Cosmos DB 中的一致性级别和数据冲突。 请参阅以下文章: