使用 .NET SDK 为 Azure Cosmos DB 中的 SQL API 构建自定义 API

• 下载 AzureCosmosDBAPIs.zip - 1.2 MB

引言

本文是我之前文章 将数据从 SQL Server 迁移到 Azure Cosmos DB 的延续，因为本文中使用的大部分数据已经填充到数据库中。

在本文中，我将简要介绍使用 .NET SDK 为 SQL API 进行客户端开发以在 Azure Cosmos DB 上执行操作。本文不涉及其他客户端 Azure Cosmos DB API，如表 API、MongoDB API、Gremlin API。阅读本文后，我希望开发人员能够直接复制代码并进行调整，然后将其用于他们的任务中。

背景

Azure Cosmos DB 发展迅速。

• 2010 年至 2014 年，它是内部的 Microsoft DocumentDB 服务
• 2014 年 8 月，Azure DocumentDB 预览版发布，具有基于无模式 JSON 的 SQL 语法、可调吞吐量、索引、一致性等功能。
• 2015 年 4 月，Azure DocumentDB 正式发布
• 从那时起，不断添加新功能，如地理空间支持、地理复制、分区集合、对 MongoDB (BSON) 的有线支持等。

当我谈到 Azure Cosmos DB 时，很多人会问我什么是 No-SQL，为什么要考虑 No-SQL，还有哪些其他的 No-SQL 技术等等。所以，让我们从非常高层次的理解开始。原因是我想详细介绍 .NET API，而不是通过在这里给出更多关于 SQL 与 No-SQL 等的笔记来使其变得枯燥乏味。

什么是 No-SQL？

我立即想到的第一件事是，它是无模式的。这到底意味着什么呢？在同一个数据库中，你可以拥有文档、表、图、列式数据模型等等。另一个关键是，它能够实现几乎无限的存储和吞吐量（前提是你拥有适当的设置）。

为什么要考虑 No-SQL？

这是一个我面临的非常棘手的问题。考虑您想要处理的数据的体量、速度和多样性。大多数时候，我们对体量和速度感到满意，但当我们开始考虑数据多样性时，此时我们会考虑使用无模式选项，这又倾向于 No-SQL。

还有哪些其他的 No-SQL 技术？

除了 (Azure) Cosmos DB 之外，市场上还有许多来自不同供应商的技术，其中与 (Azure) Cosmos DB 竞争的有 Mongo DB、Cassandra、Amazon Dynamo DB、Orient DB、Arrango DB 等。每种都有其自身的优点和局限性。您可以深入了解每种技术，并根据您的需求选择并推荐合适的方案。我之所以选择 Azure Cosmos DB，是因为它的许多功能让我和我的客户都满意，例如弹性可伸缩的吞吐量和存储、多区域复制、使用熟悉的 SQL 语法进行即席查询等。

从高层次来看，如果我需要比较 **关系型数据库** 和 **No-SQL 数据库**，那么下面是它们的区别：

1. 关系型数据库：数据以行和列的形式表示。No-SQL 数据库：数据以文档和属性的形式表示。
2. 关系型数据库：它是强类型模式。No-SQL 数据库：无模式。
3. 关系型数据库：高度规范化。No-SQL 数据库：通常是非规范化。

必备组件

• IDE：您可以使用 VS Code 或最新版本的 VS。在本文中，使用的是 VS 2017 企业版。
• Azure Cosmos DB 模拟器：Azure Cosmos DB 模拟器提供了一个本地环境，用于模拟 Azure Cosmos DB 服务以进行开发。使用 Azure Cosmos DB 模拟器，您可以在本地开发和测试您的应用程序，而无需创建 Azure 订阅或产生任何费用。我推荐使用它，因为它是免费的，并且具有您在 Azure 门户上的 Azure Cosmos DB 中可以执行的所有相同功能。当您对应用程序在 Azure Cosmos DB 模拟器中的运行方式感到满意时，您可以切换到使用云中的 Azure Cosmos DB 帐户。Azure Cosmos DB 模拟器可以在此处找到 (https://docs.microsoft.com/en-us/azure/cosmos-db/local-emulator)。
• 掌握 C# 知识。
• Azure Cosmos DB 中的集合和文档。我已经创建了数据，如果您也想创建数据，请遵循我的文章：https://codeproject.org.cn/Articles/1266054/Migrate-Data-from-SQL-Server-to-Azure-Cosmos-DB

Azure 资源模型

Azure Cosmos DB 资源模型的结构如下。

• Azure 账户
  • 数据库
    • 集合
      • Documents
        • 资源/数据
        • 附件（可选）
      • 存储过程
      • 触发器
      • 用户定义函数
    • 用户
      • 权限

我们将按照上述资源模型创建 API（存储过程、触发器和用户定义函数不在此讨论范围）。

Azure 账户的创建在 Azure 门户上完成，我们不会考虑它，此外，我们将使用 Azure Cosmos DB 模拟器和 VS 进行所有必要的 API 操作。

在 Azure Cosmos DB 中进行的每项操作中，有一个主要因素需要考虑。它被称为“吞吐量”。吞吐量衡量的是在特定时间内可以处理的请求数量。必须预配吞吐量，以确保您的 Cosmos 数据库始终拥有足够的系统资源，以达到或超过 Azure Cosmos DB SLA。所有数据库操作的成本都由 Cosmos DB 进行标准化，并以请求单位 (RU) 表示。每个 Azure Cosmos DB 响应头都会显示请求的 RU 费用。每个 API 都有自己的一组数据库操作，从简单的点读取和写入到复杂的查询。每个数据库操作都会根据操作的复杂性消耗系统资源。

正如我之前的文章中所讨论的，让我向您简要介绍一下 Azure Cosmos DB 中的“分区”。Azure Cosmos DB 通过分区实现弹性扩展。分区是物理的固定容量数据桶。Cosmos DB 集合由多个分区组成。这些是集合的逻辑资源。分区托管分区键。分区键是哈希值，它决定了存储每个项目的物理分区。在考虑分区键时，您需要考虑事务中查询的边界以及性能没有瓶颈，因为分区是数据桶，如果分区键设置不正确，那么在分区之间遍历将导致性能问题。

另一个与性能相关的重要概念是数据复制，它通过交钥匙式全球分发完成。设置完成后，我们还可以设置一致性级别。我将让您在 Microsoft Docs 上探索更多相关内容。

Azure Cosmos DB 中的每个资源都具有以下属性：

• id：用户定义的唯一标识符。它应该是字符串。
• _rid：自动生成的资源 ID。
• _ts：自动生成的时间戳（上次更新）纪元值。
• _etag：自动生成的 GUID。用于乐观并发。
• _self：自动生成的资源 URI 路径。这在使用 Azure Cosmos DB 的 SQL API 时非常有用。
• _attachments：资源附件的 URI 路径后缀。

您可以在 Azure Cosmos DB 中编写大多数 T-SQL 运算符和函数。而创建 API 的唯一基础类是 DocumentClient。我们使用 DocumentClient 类中的方法来处理每一个 API。另一个类是 UriFactory。UriFactory 是一个辅助类，用于帮助创建与 Azure Cosmos DB 服务中的 DocumentClient 实例一起使用所需的各种 Uri。

从高层次来看，在 Azure Cosmos DB 中执行任何操作只有 2 个步骤：

1. 通过提供连接字符串（端点和密钥）创建 DocumentClient 实例。
2. 利用 .NET SDK for SQL API 的任务并行库，调用方法以访问资源。

创建应用程序（API）

理论说得够多了。阅读上面的细节我也要觉得无聊了😉。让我们开始创建 API。

1. 打开 VS Studio 并创建一个 .NET Core 2.1 控制台应用程序。尽管不需要 .NET Core 应用程序，但我希望使用最新的技术。
    
2. 完成后，将解决方案命名为 AzureCosmosDBAPIs，将项目命名为 APIs。
    
3. 将以下 NuGet 包添加到项目中：
   1. Microsoft.Azure.DocumentDB.Core
   2. Microsoft.Extensions.Configuration
   3. Microsoft.Extensions.Configuration.FileExtensions
   4. Microsoft.Extensions.Configuration.Json
4. 添加应用程序设置文件。我添加了 applicationsetttings.json 作为应用程序设置。在其中添加两个键，它们将包含 Azure Cosmos DB 的连接设置。applicationsetting.json 应该如下所示：
   
   
   我使用了 Azure CosmosDB 模拟器的端点和主键值。如果要连接到 Azure 门户，则需要从门户设置这些值。
    
5. 添加一个名为 AppConfig.cs 的类。该类用于从上面创建的文件中读取应用程序设置值。该类使用 .NET Core 的方式从配置文件中读取应用程序设置值。AppConfig.cs 应该如下所示：
   
    
6. 将名为 DatabaseOperations.cs 的类添加到 csproject。该类将包含可以在特定数据库上执行的所有必要操作，例如数据库的创建等。有 3 个方法：
   1. ViewDatabaseDetails：这将提供 Azure Cosmos DB 中的数据库列表。
   2. CreateDatabase：这将在 Azure Cosmos DB 中创建一个数据库。它有一个重载方法，该方法将数据库名称作为参数。
   3. DeleteDatabase：这将在 Azure Cosmos DB 中删除一个数据库。它有一个重载方法，该方法将数据库名称作为参数。
   4. DatabaseOperations 类及其方法应如下所示：
      
      
       
7. 将名为 CollectionOperations.cs 的类添加到 csproject。该类包含可以在数据库中的特定集合上执行的所有必要操作，例如集合的创建等。
   1. ViewCollectionsInDatabase：这将提供 Azure Cosmos DB 中数据库中集合的列表。
   2. GetCollection：这将从 Azure Cosmos DB 的数据库中获取特定的集合。该类还有另一个方法 FindDocumentCollection，它也将从数据库中获取特定的集合。
   3. CreateCollection：这将在 Azure Cosmos DB 的数据库中创建一个集合。
   4. DeleteCollection：这将从 Azure Cosmos DB 的数据库中删除一个集合。
   5. DisplayCollectionProperties：它将显示数据库中集合的属性。
   6. CollectionOperations 类应如下所示：
      
      
       
8. 将名为 DocumentOperations.cs 的类添加到 csproject。该类包含可以在集合中的特定文档上执行的所有 CRUD 方法，例如文档的创建等。
   1. 该类中有多个方法用于创建文档：
      1. 使用 JSON 字符串创建文档 (CreateDocumentUsingJson)
      2. 使用 POCO 对象创建文档 (CreateDocumentUsingPocoObject)。您可以通过添加重载方法来扩展此方法，该方法可以接受第三个参数为 POCO 类并相应地创建文档。
   2. 该类中有多个用于获取文档的方法：
      1. 获取集合中的所有文档并显示结果 (GetAllDocumentsAndDisplayResults)
      2. 获取集合中特定部门的所有文档并显示结果 (GetAllDocumentsForASpecificDepartmentAndDisplayResults)
   3. UpdateEmployeeDetails：此方法将更新文档。
   4. 删除文档可以通过两种方式完成：
      1. 按员工姓名删除 (DeleteEmployeeByEmployeeName)
      2. 按 ID 删除 (DeleteEmployeeById)
   5. DocumentOperations 类应如下所示：
      
      .
9. 将名为 UsersAndPermissionsOperations.cs 的类添加到 csproject。该类将包含在数据库和集合中对用户和用户权限执行的所有 CRUD 操作。用户在数据库级别创建，用户权限授予集合。User 的类型为 Microsoft.Azure.Documents.User 和 Microsoft.Azure.Documents.Permission。
   1. GetAllUsers 将获取数据库中的所有用户
   2. GetuserDetailsByUserId 将从数据库中获取特定用户的详细信息
   3. ViewUsers 将用于在控制台上显示信息。此方法将调用 ViewUser 以显示用户详细信息
   4. CreateUser 将在数据库中创建用户
   5. DeleteUser 将从数据库中删除用户
   6. ViewPermissionsForAUser 将显示特定用户的用户权限。此方法将调用 ViewPermission 以在控制台上显示用户权限
   7. CreatePermission 将为资源（集合）的用户创建权限
   8. 有两种重载方法用于删除权限：
      1. 一种方法将接受用户对象和权限 ID。
      2. 另一种方法将接受用户对象和权限对象。
   9. UsersAndPermissionsOperations.cs 应如下所示：
      
      
10. 在 Program.cs 中，已调用所有上述方法。我已将它们全部注释掉。您可以根据需要取消注释并验证其功能。Program.cs 应该如下所示：
    
    

您的下一步

1. 我故意省略了创建新数据库并在其中创建新集合等操作。
2. 可以使用 UriFactory 类来操作资源。