65.9K
CodeProject 正在变化。 阅读更多。
Home

使用 SQL API 和 Azure 门户通过 Azure Cosmos DB 构建 .NET Web 应用

Microsoft
emptyStarIconemptyStarIconemptyStarIconemptyStarIconemptyStarIcon

0/5 (0投票)

2018年12月21日

CPOL
viewsIcon

9851

本快速入门演示如何使用 Azure 门户创建 Azure Cosmos DB SQL API 帐户、文档数据库和集合。然后，你将构建和部署一个基于 SQL .NET API 的待办事项列表 Web 应用，如下图所示。

Azure Cosmos DB 是 Microsoft 的全局分布式多模型数据库服务。你可以快速创建和查询文档、键/值和图数据库，所有这些都受益于 Azure Cosmos DB 核心的全局分布式和水平扩展功能。

本快速入门演示如何使用 Azure 门户创建 Azure Cosmos DB SQL API 帐户、文档数据库和集合。然后，你将构建和部署一个基于 SQL .NET API 的待办事项列表 Web 应用，如下图所示。

必备组件

如果你尚未安装 Visual Studio 2017，可以下载并使用 **免费** 的 Visual Studio 2017 社区版。请确保在 Visual Studio 安装过程中启用 **Azure 开发**。

如果你没有 Azure 订阅，请在开始之前创建一个 免费帐户。

你可以 免费试用 Azure Cosmos DB，无需 Azure 订阅、免费且无承诺。或者，你可以使用 Azure Cosmos DB 模拟器，其 URI 为 https://:8081。主密钥在 身份验证请求 中提供。

创建数据库帐户

  1. 在新浏览器窗口中，登录 Azure 门户。

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

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

    设置 值 描述
    订阅 您的订阅 选择要用于此 Azure Cosmos DB 帐户的 Azure 订阅。
    资源组 新建

    然后输入与 ID 中提供的相同的唯一名称    		 选择新建。然后为您的帐户输入新的资源组名称。为简单起见，请使用与您的 ID 相同的名称。
    科目名称 输入唯一名称 输入一个唯一名称来标识您的 Azure Cosmos DB 帐户。由于 documents.azure.com 会附加到您提供的 ID 以创建 URI，因此请使用唯一 ID。

    ID 只能包含小写字母、数字和连字符 (-) 字符。其长度必须在 3 到 31 个字符之间。
    API Core(SQL) API 决定要创建的帐户类型。Azure Cosmos DB 提供五种 API：文档数据库的 Core (SQL)、图数据库的 Gremlin、文档数据库的 MongoDB、Azure Table 和 Cassandra。目前，你必须为每种 API 创建单独的帐户。

    选择Core(SQL)，因为在本文中您将创建一个文档数据库并使用 SQL 语法进行查询。

    详细了解 SQL API.
    Location 选择离您的用户最近的区域 选择一个托管您的 Azure Cosmos DB 帐户的地理位置。使用离您的用户最近的位置，以便他们能最快地访问数据。

    选择审查+创建。您可以跳过网络和标记部分。

  4. 帐户创建需要几分钟时间。等待门户显示恭喜！您的 Azure Cosmos DB 帐户已创建页面。

添加集合

现在可以使用 Azure 门户中的 Data Explorer 工具来创建数据库和集合。

  1. 单击 **Data Explorer** > **New Collection**。

    “**Add Collection**”区域显示在最右侧，你可能需要向右滚动才能看到它。

  2. 在“**Add collection**”页面上，输入新集合的设置。

    设置 建议值 描述
    Database id Tasks（任务） 为新数据库输入 _Tasks_ 作为名称。数据库名称必须包含 1 到 255 个字符，且不能包含 /, \\, #, ? 或尾随空格。
    Collection id Items 为你的新集合输入 _Items_ 作为名称。集合 ID 具有与数据库名称相同的字符要求。
    Partition key <your key="" partition=""> 输入一个分区键，例如 _/userid_。
    吞吐量 400 RU 将吞吐量更改为每秒 400 个请求单位 (RU/s)。如果你想减少延迟，可以在以后纵向扩展吞吐量。

    除了上述设置外，你还可以为集合选择性地添加 **Unique keys**。在本例中，我们将其留空。唯一键为开发人员提供了向数据库添加数据完整性层的能力。通过在创建集合时创建唯一键策略，可以确保每个分区键的值唯一。要了解更多信息，请参阅 Azure Cosmos DB 中的唯一键 文章。

    点击**确定**。

    Data Explorer 显示了新的数据库和集合。

添加示例数据

现在可以使用 Data Explorer 将数据添加到你的新集合中。

  1. 在 Data Explorer 中，新数据库会显示在“Collections”窗格中。展开 **Tasks** 数据库，展开 **Items** 集合，单击 **Documents**，然后单击 **New Documents**。

  2. 现在向集合添加一个具有以下结构的文档。

    {
    "id": "1",
    "category": "personal",
    "name": "groceries",
    "description": "Pick up apples and strawberries.",
    "isComplete": false
}

  3. 在“**Documents**”选项卡中添加 json 后，单击“**Save**”。

  4. 创建并保存另一个文档，在其中插入一个唯一的 `id` 属性值，并根据需要更改其他属性。你的新文档可以具有任何结构，因为 Azure Cosmos DB 对你的数据不强制执行任何架构。

查询你的数据

现在可以使用 Data Explorer 中的查询来检索和筛选你的数据。

  1. 注意，默认情况下，查询设置为 `SELECT * FROM c`。此默认查询检索并显示集合中的所有文档。

  2. 停留在“**Documents**”选项卡上，通过单击“**Edit Filter**”按钮修改查询，在查询谓词框中添加 `ORDER BY c._ts DESC`，然后单击“**Apply Filter**”。

此修改后的查询按时间戳降序排列文档，因此你的第二个文档现在排在第一个。如果你熟悉 SQL 语法，可以在此框中输入任何支持的 SQL 查询。

我们在 Data Explorer 中的工作到此结束。在继续进行代码工作之前，请注意，你还可以使用 Data Explorer 创建存储过程、UDF 和触发器来执行服务器端业务逻辑以及扩展吞吐量。Data Explorer 暴露了 API 中所有内置的程序化数据访问功能，但提供了对 Azure 门户中数据的便捷访问。

克隆示例应用程序

现在让我们切换到代码工作。让我们从 GitHub 克隆一个 SQL API 应用，设置连接字符串，然后运行它。你将看到以编程方式处理数据的简便性。

  1. 打开命令提示符，创建一个名为 git-samples 的新文件夹，然后关闭命令提示符。

    md "C:\git-samples"

  2. 打开一个 git 终端窗口（例如 git bash），并使用 `cd` 命令更改到新文件夹以安装示例应用。

    cd "C:\git-samples"

  3. 运行以下命令克隆示例存储库。此命令会在你的计算机上创建一个示例应用的副本。

    git clone https://github.com/Azure-Samples/documentdb-dotnet-todo-app.git

  4. 然后，在 Visual Studio 中打开 todo 解决方案文件。

审阅代码

此步骤是可选的。如果你有兴趣了解代码中如何创建数据库资源，可以审阅以下代码片段。否则，你可以跳到 更新连接字符串。

以下代码片段均来自 _DocumentDBRepository.cs_ 文件。

  • `DocumentClient` 在第 76 行初始化。

    client = new DocumentClient(new Uri(ConfigurationManager.AppSettings["endpoint"]), ConfigurationManager.AppSettings["authKey"]);

  • 新数据库在第 91 行创建。

    await client.CreateDatabaseAsync(new Database { Id = DatabaseId });

  • 新集合在第 110 行创建。

    await client.CreateDocumentCollectionAsync(
    UriFactory.CreateDatabaseUri(DatabaseId),
    new DocumentCollection
        {
           Id = CollectionId
        },
    new RequestOptions { OfferThroughput = 400 });

更新连接字符串

现在返回 Azure 门户以获取你的连接字符串信息，并将其复制到应用中。

  1. 在 Azure 门户中，在你的 Azure Cosmos DB 帐户的左导航栏中选择 **Keys**，然后选择 **Read-write Keys**。你将使用屏幕右侧的复制按钮将 URI 和 Primary Key 复制到下一步的 web.config 文件中。

  2. 在 Visual Studio 2017 中，打开 web.config 文件。

  3. 从门户中复制你的 URI 值（使用复制按钮），并将其设为 web.config 中 endpoint 键的值。

    <add key="endpoint" value="FILLME" />

  4. 然后从门户复制你的 PRIMARY KEY 值，并将其设为 web.config 中 authKey 的值。

    <add key="authKey" value="FILLME" />

  5. 然后更新 database 的值以匹配你之前创建的数据库的名称。你现在已将应用更新为与 Azure Cosmos DB 通信所需的所有信息。

    <add key="database" value="Tasks" />

运行 Web 应用

  1. 在 Visual Studio 中，右键单击 **Solution Explorer** 中的项目，然后选择 **Manage NuGet Packages**。

  2. 在 NuGet **Browse** 框中，键入 _DocumentDB_。

  3. 从结果中安装 **Microsoft.Azure.DocumentDB** 库。这将安装 Microsoft.Azure.DocumentDB 包以及所有依赖项。

  4. 按 CTRL + F5 运行应用程序。你的应用将在浏览器中显示。

  5. 在浏览器中选择 **Create New**，然后在你的待办事项应用中创建几个新任务。

现在你可以返回 Data Explorer，查看、查询、修改并处理这些新数据。

在 Azure 门户中审阅 SLA

帐户中资源的吞吐量、存储、可用性、延迟和一致性在 Azure 门户中进行监控。让我们快速查看这些指标。

  1. 在导航菜单中单击 **Metrics**。

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

    与 Azure Cosmos DB 服务级别协议 (SLA) 关联的每个图表都提供一条线，显示是否违反了任何 SLA。Azure Cosmos DB 通过这一系列指标使其 SLA 的监控透明化。

清理资源

如果你不打算继续使用此应用，请使用以下步骤删除此快速入门创建的所有资源，以免产生任何费用。

  1. 在 Azure 门户的左侧，选择 **Resource groups**，然后选择你创建的资源组。

    如果左侧菜单已折叠，请单击 展开它。

  2. 在新窗口中选择资源组，然后单击 **Delete resource group**。

  3. 在新窗口中，键入要删除的资源组的名称，然后单击 **Delete**。

© . All rights reserved.