快速入门:使用 .NET 和 Azure Cosmos DB 生成表 API 应用

本快速入门介绍如何使用 .NET 和 Azure Cosmos DB 表 API,通过克隆 GitHub 中的示例来生成应用。 此外,本快速入门还介绍了如何创建 Azure Cosmos DB 帐户,以及如何在基于 Web 的 Azure 门户中使用数据资源管理器创建表和实体。 Azure Cosmos DB 由 世纪互联 提供,是多个区域分布的多模型数据库服务。 可快速创建和查询文档、键/值数据库,所有这些都受益于 Azure Cosmos DB 核心的多个区域分布和水平缩放功能。

先决条件

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

Note

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

创建数据库帐户

Important

需创建新的适用于公开发表版表 API SDK 的表 API 帐户。 在预览期间创建的表 API 帐户不受公开发布版 SDK 的支持。

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

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

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

    设置 建议的值 说明
    ID 输入唯一名称 输入标识此 Azure Cosmos DB 帐户的唯一名称。 由于 documents.azure.cn 将追加到所提供的 ID 后面以创建 URI,因此,请使用唯一但可识别的 ID。

    ID 只能包含小写字母、数字和连字符 (-) 字符,并且必须包含 3 到 50 个字符。
    API Azure 表 API 确定要创建的帐户的类型。 Azure Cosmos DB 提供了三种 API,用以满足应用程序的需求:SQL(文档数据库)、MongoDB(文档数据库)和 Azure 表,每个目前都需要单独的帐户。

    选择“Azure 表”,因为在本快速入门中,将创建一个使用表 API 的表。

    详细了解表 API
    订阅 输入上面在 ID 中提供的同一唯一名称 选择要用于此 Azure Cosmos DB 帐户的 Azure 订阅。
    资源组 与 ID 相同的值 输入帐户的新资源组名称。 为简单起见,可以使用与 ID 相同的名称。
    位置 选择离用户最近的区域 选择要在其中托管 Azure Cosmos DB 帐户的地理位置。 使用离用户最近的位置,使他们能够以最快的速度访问数据。
    启用异地冗余 留空 这将在第二个(配对)区域中创建数据库的复制版本。 将此项留空。
    固定到仪表板 选择 选中此框,以便将新的数据库帐户添加到门户仪表板以便于访问。

    然后单击“创建” 。

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

  4. 创建帐户需要几分钟时间。 在创建帐户过程中,门户会显示“部署 Azure Cosmos DB”磁贴。

    Azure 门户“通知”窗格

    创建帐户后,会显示“祝贺你!已创建 Azure Cosmos DB 帐户”页。

添加表

现在可以在 Azure 门户中使用数据资源管理器工具来创建数据库和表。

  1. 依次单击“数据资源管理器” > “新建表”。

    此时,最右侧将显示“添加表”区域,可能需要向右滚动才能看到。

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

  2. 在“添加表”页上,输入新表的设置。

    设置 建议的值 说明
    表 ID sample-table 新表的 ID。 表名称与数据库 ID 的字符要求相同。 数据库名称的长度必须为 1 到 255 个字符,不能包含 / \ # ? 或尾随空格。
    存储容量 固定 (10 GB) 将值更改为“固定(10GB)”。 此值是数据库的存储容量。
    吞吐量 400 RU 将吞吐量更改为每秒 400 个请求单位 (RU/s)。 如果想要减少延迟,以后可以增加吞吐量。

    单击 “确定”

    数据资源管理器将显示新的数据库和表。

    显示新的数据库和集合的 Azure 门户数据资源管理器

添加示例数据

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

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

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

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

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

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

克隆示例应用程序

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

  1. 打开诸如 git bash 之类的 git 终端窗口,并使用 cd 命令更改为相应的示例应用程序安装文件夹。

    cd "C:\git-samples"
    
  2. 运行下列命令,克隆示例存储库。 此命令在计算机上创建示例应用程序的副本。

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

更新连接字符串

现在返回到 Azure 门户,获取连接字符串信息,并将其复制到应用。 这样,应用程序就可以与托管的数据库进行通信。

  1. Azure 门户中,单击“连接字符串”。

    使用屏幕右侧的复制按钮复制“主连接字符串”。

    在“连接字符串”窗格中查看并复制“主连接字符串”

  2. 在 Visual Studio 中打开 App.config 文件。

  3. 取消注释第 8 行的 StorageConnectionString 并注释掉第 7 行的 StorageConnectionString,因为本教程不使用存储模拟器。 第 7 行和第 8 行现在应如下所示:

    <!--key="StorageConnectionString" value="UseDevelopmentStorage=true;" />-->
    <add key="StorageConnectionString" value="DefaultEndpointsProtocol=https;AccountName=[AccountName];AccountKey=[AccountKey]" />
    
  4. 将“主连接字符串”值从门户粘贴到第 8 行的 StorageConnectionString 值中。 粘贴引号内的字符串。

    Important

    如果终结点使用 documents.azure.cn,则意味着帐户为预览版帐户,需创建适用于公开发布版表 API SDK 的新的表 API 帐户

    第 8 行现在应类似于:

    <add key="StorageConnectionString" value="DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=txZACN9f...==;TableEndpoint=https://<account name>.documents.azure.cn;EndpointSuffix=core.chinacloudapi.cn" />
    
  5. 保存 App.config 文件。

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

生成并部署应用

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

  2. 在 NuGet“浏览”框中,键入 Microsoft.Azure.CosmosDB.Table

  3. 安装结果中显示的 Microsoft.Azure.CosmosDB.Table 库。 这会安装 Azure Cosmos DB 表 API 包以及所有依赖项。

  4. 打开 BasicSamples.cs,向第 30 行和第 52 行添加断点。

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

    控制台窗口显示,正在将表数据添加到 Azure Cosmos DB 中的新表数据库。

    如果遇到有关依赖项的错误,请参阅故障排除

    遇到第一个断点时,请回到 Azure 门户中的数据资源管理器,展开演示* 表,然后单击“实体”。 右侧的“实体”选项卡显示已添加的新实体。请注意,用户的电话号码为 425-555-0101。

  6. 关闭数据资源管理器中的“实体”选项卡。

  7. 继续运行应用,直到下一个断点。

    遇到该断点时,切换回门户,再次单击“实体”以打开“实体”选项卡,此时可以看到电话号码已更新为 425-555-0105。

  8. 回到控制台窗口,按 CTRL + C 终止应用的执行。

    现在可以回到数据资源管理器来添加或修改实体,以及查询数据。

在 Azure 门户中查看 SLA

在 Azure 门户中监视帐户中资源的吞吐量、存储空间、可用性、延迟和一致性。 让我们快速了解一下这些指标。

  1. 在导航菜单中单击“指标”。

    Azure 门户中的指标

  2. 单击每个选项卡,以便了解 Azure Cosmos DB 提供的指标。

    Azure Cosmos DB 服务级别协议 (SLA) 关联的每个图表都提供了一行,显示是否违反了任何 SLA。 Azure Cosmos DB 通过此套指标使监视 SLA 的操作更透明。

    Azure Cosmos DB 指标套件

清理资源

如果不打算继续使用此应用,请按照以下步骤删除本快速入门中创建的所有资源,以免产生任何费用:

  1. 在 Azure 门户中,选择最左侧的“资源组”。

    Azure 门户中的指标

  2. 在资源组列表中,选择创建的资源组,然后单击“删除资源组”。

  3. 键入要删除的资源组名称,然后单击“删除”。

后续步骤

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