Azure Cosmos DB:使用表 API 生成 .NET 应用程序

Azure Cosmos DB 由 Microsoft 提供,是全球分布的多模型数据库服务。 可快速创建和查询文档、键/值数据库,所有这些都受益于 Azure Cosmos DB 核心的全球分布和水平缩放功能。

本快速入门教程演示如何使用 Azure 门户创建 Azure Cosmos DB 帐户,以及如何在该帐户内创建表。 然后将编写代码来插入、更新和删除条目,以及使用 NuGet 中的新 Windows Azure 存储高级表(预览版)包运行某些查询。 此库与公共 Microsoft Azure 存储 SDK 具有相同的类和方法签名,但还具有使用表 API(预览版)连接到 Azure Cosmos DB 帐户的功能。

先决条件

如果尚未安装 Visual Studio 2017,可以下载并使用免费的 Visual Studio 2017 Community Edition。 在安装 Visual Studio 的过程中,请确保启用“Azure 开发”。

Note

如果没有 Azure 订阅,可在开始前创建一个试用帐户

创建数据库帐户

  1. 在新窗口中,登录到 Azure 门户
  2. 在左菜单中,依次单击“新建”、“数据库”,然后在“Azure Cosmos DB”下单击“创建”。

    Azure 门户的屏幕截图,其中突出显示了“更多服务”和“Azure Cosmos DB”

  3. 在“新建帐户”边栏选项卡中,为 Azure Cosmos DB 帐户指定所需的配置。

    使用 Azure Cosmos DB,可以选择以下三个编程模型之一:MongoDB、SQL (DocumentDB) 和表(键/值)。

    在本快速入门教程中,我们针对表 API 编程,因此,在填写表单时,请选择“表(键/值)”。 但如果有来自目录应用的文档数据或从 MongoDB 应用迁移的数据,请意识到 Azure Cosmos DB 可以为所有任务关键型应用程序提供高度可用的全球分布式数据库服务平台。

    使用作为指南的屏幕截图中的信息填写“新建帐户”边栏选项卡。 设置帐户时你将选择唯一的值,因此你的值不会与屏幕截图完全匹配。

    “新 Azure Cosmos DB”边栏选项卡的屏幕截图

    设置 建议的值 说明
    ID 唯一值 选择用于标识 Azure Cosmos DB 帐户的唯一名称。 documents.azure.cn 会追加到所提供的 ID 以创建 URI,因此,请使用唯一但可识别的 ID。 ID 只能包含小写字母、数字及“-”字符,且长度必须为 3 到 50 个字符。
    API 表(键/值) 在本文的后面部分中,我们针对表 API 编程。
    订阅 订阅 要用于 Azure Cosmos DB 帐户的 Azure 订阅。
    资源组 与 ID 相同的值 帐户的新资源组名称。 为简单起见,可以使用与 ID 相同的名称。
    位置 离用户最近的区域 要在其中托管 Azure Cosmos DB 帐户的地理位置。 选择离用户最近的位置,使其能够以最快的速度访问数据。
  4. 单击“创建” 以创建帐户。

  5. 在工具栏上,单击“通知”可监视部署过程。

    “部署已启动”通知

  6. 部署完成后,请从“所有资源”磁贴打开新帐户。

    “所有资源”磁贴中的 Azure Cosmos DB 帐户

添加表

现在可以使用数据资源管理器创建一个表,并将数据添加到数据库。

  1. 在 Azure 门户的导航菜单中,单击“数据资源管理器(预览版)”。
  2. 在“数据资源管理器”边栏选项卡中,单击“新建表”,并使用以下信息填写该页。

    Azure 门户中的数据资源管理器

    设置 建议的值 说明
    表 ID sample-table 新表的 ID。 表名称与数据库 ID 的字符要求相同,不能包含 /、\、#、? 或尾随空格。
    存储容量 10 GB 保留默认值。 这是数据库的存储容量。
    吞吐量 400 RU 保留默认值。 如果想要减少延迟,以后可以增加吞吐量
    RU/m 关闭 使用默认值。 可以在以后需要处理高峰工作负荷时,启用 RU/m 功能。
  3. 填写表单后,请单击“确定”。

添加示例数据

现在可以使用数据资源管理器(预览版)将数据添加到新表。

  1. 在数据资源管理器中,展开 sample-table,单击“实体”,然后单击“添加实体”。

    在 Azure 门户的数据资源管理器中创建新实体

  2. 现在请将数据添加到 PartitionKey 值框和 RowKey 值框,并单击“添加实体”。

    为新实体设置分区键和行键

    现在可以在数据资源管理器中将更多实体添加到表、编辑实体或查询数据。 使用数据资源管理器还可以缩放吞吐量,并将存储过程、用户定义的函数和触发器添加到表中。

克隆示例应用程序

现在让我们从 github 克隆表应用、设置连接字符串,并运行。 你会看到以编程方式处理数据是多么容易。

  1. 打开 git 终端窗口(例如 git bash)并使用 cd 切换到工作目录。

  2. 运行下列命令,克隆示例存储库。

    git clone https://github.com/Azure-Samples/azure-cosmos-db-table-dotnet-getting-started.git
    
  3. 然后在 Visual Studio 中打开解决方案文件。

查看代码

快速查看应用中发生的情况。 打开 Program.cs 文件,会发现以下代码行创建 Azure Cosmos DB 资源。

  • CloudTableClient 已初始化。

    CloudStorageAccount storageAccount = CloudStorageAccount.Parse(connectionString); 
    CloudTableClient tableClient = storageAccount.CreateCloudTableClient();
    
  • 如果表不存在,则创建新表。

    CloudTable table = tableClient.GetTableReference("people");
    table.CreateIfNotExists();
    
  • 创建一个新的表容器。 你会注意到,该代码非常类似于常规的 Azure 表存储 SDK。

    CustomerEntity item = new CustomerEntity()
                {
                    PartitionKey = Guid.NewGuid().ToString(),
                    RowKey = Guid.NewGuid().ToString(),
                    Email = $"{GetRandomString(6)}@contoso.com",
                    PhoneNumber = "425-555-0102",
                    Bio = GetRandomString(1000)
                };
    

更新连接字符串

现在将更新连接字符串信息,使应用能够与 Azure Cosmos DB 通信。

  1. 在 Visual Studio 中,打开 app.config 文件。

  2. Azure 门户的 Azure Cosmos DB 左侧导航菜单中,单击“连接字符串”。 然后在新窗格中单击连接字符串的复制按钮。

    在“连接字符串”窗格中查看和复制终结点和帐户密钥

  3. 将值粘贴到 app.config 文件中,充当 PremiumStorageConnectionString 的值。

    <add key="PremiumStorageConnectionString" value="DefaultEndpointsProtocol=https;AccountName=MYSTORAGEACCOUNT;AccountKey=AUTHKEY;TableEndpoint=https://COSMOSDB.documents.azure.cn" />

    可以让 StandardStorageConnectionString 保留原样。

现已使用与 Azure Cosmos DB 进行通信所需的所有信息更新应用。

运行 Web 应用

  1. 在 Visual Studio 中,右键单击解决方案资源管理器中的 PremiumTableGetStarted 项目,然后单击“管理 NuGet 包”。

  2. 在 NuGet“浏览”框中,键入 WindowsAzure.Storage-PremiumTable。

  3. 选中“包括预发行版”框。

  4. 从结果中安装“WindowsAzure.Storage-PremiumTable”库。 这会安装预览版 Azure Cosmos DB 表 API 包以及所有依赖项。 请注意,这是与 Azure 表存储所使用的 Microsoft Azure 存储包不同的 NuGet 包。

  5. 单击 Ctrl+F5 运行应用程序。

    控制台窗口会显示在表中添加、检索、查询、替换和删除的数据。 完成脚本后,按任意键关闭控制台窗口。

    快速入门的控制台输出

  6. 若要查看数据资源管理器中的新实体,请直接注释掉 program.cs 中的第 188-208 行使其不会被删除,然后再次运行示例。

    现在可以回到数据资源管理器,单击“刷新”,展开“人员”表,再单击“实体”,然后即可使用该新数据。

    数据资源管理器中的新实体

在 Azure 门户中查看 SLA

现在,应用已启动且正在运行,建议确保业务连续性并监视用户访问以确保高可用性。 可以使用 Azure 门户查看集合的可用性、延迟、吞吐量和一致性。

Azure Cosmos DB 服务级别协议 (SLA) 关联的每个图均提供一行内容,显示满足 SLA 所需的配额和实际使用情况。 这些信息可让你清楚地了解数据库性能。 门户中还提供其他指标,例如存储使用量和每分钟的请求数。

  • 在 Azure 门户的左侧窗格中,选择“监视”下的“指标”。

    包含示例数据的待办事项应用

清理资源

如果不打算继续使用此应用,请删除本快速入门教程在 Azure 门户中创建的所有资源,步骤如下:

  1. 在 Azure 门户的左侧菜单中,单击“资源组”,然后单击已创建资源的名称。
  2. 在资源组页上单击“删除”,在文本框中键入要删除的资源的名称,并单击“删除”。

后续步骤

在本快速入门教程中,已了解如何创建 Azure Cosmos DB 帐户、使用数据资源管理器创建表和运行应用。 现在可以使用表 API 进行数据查询了。