Azure Cosmos DB:使用 .NET 和 Azure 门户生成 DocumentDB API Web 应用

Azure Cosmos DB 由 世纪互联 提供,是全球分布的多模型数据库服务。 可快速创建和查询文档及键/值,这两者都受益于 Azure Cosmos DB 核心的多个区域分发和水平缩放功能。

本快速入门教程演示如何使用 Azure 门户创建 Azure Cosmos DB 帐户、文档数据库和集合。 然后,生成并部署基于 DocumentDB .NET API 构建的“待办事项列表”Web 应用,如以下屏幕截图中所示。

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

先决条件

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

Note

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

或者,可以将 Azure Cosmos DB 模拟器用于本教程,该模拟器的 URI 为 https://localhost:8081,密钥为:

C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

创建数据库帐户

  1. 在新浏览器窗口中,登录到 Azure 门户
  2. 单击“新建” > “数据库” > “Azure Cosmos DB”。

    Azure 门户“数据库”窗格

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

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

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

    之所以选择 SQL 是因为,在本快速入门中将创建可使用 SQL 语法查询并可通过 SQL API 访问的文档数据库。

    详细了解 SQL API
    订阅 订阅 选择要用于此 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 任务 输入 Tasks 作为新数据库的名称。 数据库名称必须包含 1 到 255 个字符,不能包含 /、\、#、? 或尾随空格。
    集合 ID Items 输入 Items 作为新集合的名称。 集合 ID 与数据库名称的字符要求相同。
    存储容量 固定 (10 GB) 将值更改为“固定(10GB)”。 此值是数据库的存储容量。
    吞吐量 400 RU 将吞吐量更改为每秒 400 个请求单位 (RU/s)。 存储容量必须设置为“固定(10 GB)”,才能将吞吐量设置为 400 RU/s。 如果想要减少延迟,以后可以增加吞吐量。

    单击 “确定”

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

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

添加示例数据

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

  1. 在数据资源管理器中,新数据库会显示在“集合”窗格中。 展开 Tasks 数据库,展开 Items 集合,单击“文档”,然后单击“新建文档”。

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

  2. 现在,将文档添加到具有以下结构的集合。

    {
         "id": "1",
         "category": "personal",
         "name": "groceries",
         "description": "Pick up apples and strawberries.",
         "isComplete": false
    }
    
  3. 将 json 添加到“文档”选项卡以后,即可单击“保存”。

    通过复制添加 json 数据,然后在 Azure 门户的数据资源管理器中单击“保存”

  4. 再创建并保存一个文档,在其中插入 id 属性的唯一值,并将其他属性更改为适当值。 新文档可以具有所需的任何结构,因为 Azure Cosmos DB 不对数据施加任何架构。

    现在可以在数据资源管理器中使用查询来检索数据。 默认情况下,数据资源管理器使用 SELECT * FROM c 来检索集合中的所有文档,但可以将其更改为其他 SQL 查询(例如 SELECT * FROM c ORDER BY c._ts DESC),根据时间戳按升序返回所有文档。

    还可以使用数据资源管理器创建存储过程、UDF 和触发器以执行服务器端业务逻辑和缩放吞吐量。 数据资源管理器公开 API 中提供的所有内置编程数据访问,但你可以使用它轻松访问 Azure 门户中的数据。

克隆示例应用程序

现在,让我们转到如何使用代码上来。 从 GitHub 克隆 DocumentDB API 应用,设置连接字符串,并运行该应用。 会看到以编程方式处理数据是多么容易。

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

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

    git clone https://github.com/Azure-Samples/documentdb-dotnet-todo-app.git
    
  3. 然后在 Visual Studio 中打开 todo 解决方案文件。

查看代码

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

  • 在第 78 行对 DocumentClient 进行初始化。

    client = new DocumentClient(new Uri(ConfigurationManager.AppSettings["endpoint"]), ConfigurationManager.AppSettings["authKey"]);
    
  • 在第 93 行创建一个新数据库。

    await client.CreateDatabaseAsync(new Database { Id = DatabaseId });
    
  • 在第 112 行创建一个新集合。

    await client.CreateDocumentCollectionAsync(
        UriFactory.CreateDatabaseUri(DatabaseId),
        new DocumentCollection { Id = CollectionId },
        new DocumentCollection
            {
               Id = CollectionId,
               PartitionKey = new PartitionKeyDefinition() { Paths = new Collection<string>() { "/category" } }
            },
        new RequestOptions { OfferThroughput = 1000 });
    

更新连接字符串

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

  1. Azure 门户的 Azure Cosmos DB 帐户的左侧导航栏中,单击“密钥”,然后单击“读写密钥”。 使用屏幕右侧的复制按钮将 URI 和主密钥复制到下一步的 web.config 文件中。

    在 Azure 门户的“密钥”边栏选项卡中查看并复制访问密钥

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

  3. 从门户中复制 URI 值(使用复制按钮),并在 web.config 中将其设为终结点密钥的值。

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

  4. 然后从门户复制“主密钥”的值,并在 web.config 中将其设为 authKey 的值。现已使用与 Azure Cosmos DB 进行通信所需的所有信息更新应用。

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

运行 Web 应用

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

  2. 在 NuGet“浏览”框中,键入 DocumentDB

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

  4. 单击 Ctrl+F5 运行应用程序。 你的应用会显示在浏览器中。

  5. 在浏览器中单击“新建”,并在“待办事项”应用中创建一些新任务。

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

现可返回到数据资源管理器,查看查询、修改和处理此新数据。

在 Azure 门户中查看 SLA

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

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

    Azure 门户中的指标

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

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

    Azure Cosmos DB 指标套件

清理资源

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

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

后续步骤

在本快速入门教程中,已了解如何创建 Azure Cosmos DB 帐户、使用数据资源管理器创建集合和运行 Web 应用。 现在可以将其他数据导入 Cosmos DB 帐户。