使用 Visual Studio Code 的 DocumentDB 扩展连接到 Azure DocumentDB

Visual Studio Code的 DocumentDB 扩展将 Azure DocumentDB 引入编辑器。 使用此免费的开源扩展浏览文档、运行查询和管理集合，而无需离开Visual Studio Code。

在本文中，请安装扩展，使用Microsoft Entra ID或数据库凭据连接到群集，并运行第一个查询。 然后在仪表板中浏览群集，使用字段感知建议生成视觉查询，或者切换到交互式 shell 或可重用脚本。

该扩展在 Windows、macOS 和 Linux 上运行。 其查询运行时是内置的：无需安装 MongoDB Shell 或配置外部可执行文件。 由于它通过 MongoDB API 线路协议进行连接，因此还可以将其与其他 MongoDB API 兼容的数据库一起使用。

先决条件

• 一份 Azure 订阅。 如果没有 Azure 订阅，请创建一个试用帐户。

• 现有的 Azure DocumentDB 群集

  • 如果没有群集，请 创建新群集

• Visual Studio Code。
• 从开发环境到群集的网络访问。 对于公共连接，请为客户端 IP 地址 配置防火墙规则 。 对于专用连接，请使用可以访问群集专用终结点的环境。
• 登录到群集数据的一种方式：在群集上注册为用户的 Microsoft Entra 标识，或本机数据库凭据。 若要尝试该示例，需要有权创建集合并插入文档。 使用开发数据库而不是生产数据。
• 若要从扩展中浏览 Azure 中的群集，需要一个对群集资源具有读取访问权限的 Azure 帐户。 如果没有它，你仍然可以使用连接字符串进行连接。

安装和连接

从Visual Studio市场安装 DocumentDB 扩展。 或者，在 Visual Studio Code 中，在 “扩展” 视图中搜索 DocumentDB，选择 Microsoft 发布的 DocumentDB 扩展，然后选择“安装”。

然后，按照适合你的工作方式连接到你的群集：

如果连接尝试失败，请参阅 排查连接问题。

使用服务发现进行连接

服务发现会代你登录 Azure 并列出群集，因此无需在 Azure 门户中查找终结点。

1. 从活动栏中打开 DocumentDB 。 在服务发现中，选择Azure DocumentDB，并在出现提示时登录到Azure。
2. 展开订阅以显示其群集，然后展开你的群集以进行连接。
3. 选择群集支持的身份验证方法：
   • Microsoft Entra ID：选择“使用我的帐户登录”。 如果帐户属于多个租户，请选择包含群集的租户。
   • 用户名和密码：输入本机数据库用户的凭据。
4. 若要下次将群集保存在 DocumentDB 连接 中，请选择其保存图标或打开其上下文菜单并保存。

看不到群集？ 选择 筛选器条目（漏斗图标）旁边的 Azure DocumentDB，选择要显示的租户和订阅。 选择“管理凭据”（密钥图标）以登录到另一个Azure帐户或租户。 筛选器选择会在不同会话间保留。 有关详细信息，请参阅管理Azure帐户、租户和订阅（用户手册）。

从Azure资源视图进行连接

如果使用 Azure 资源扩展，Azure DocumentDB 群集也会显示在Azure视图中，与其他 Azure 资源并列显示，并按订阅、资源组或资源类型分组。

展开群集以查看其数据库和集合。 在此处打开集合视图、Query Playground 或交互式 shell。 无需创建单独的连接或复制连接字符串。

使用连接字符串进行连接

1. 在Azure 门户中，打开群集并在资源菜单中选择连接字符串。 复制连接字符串。 对于Microsoft Entra ID，请使用Microsoft Entra ID部分中的值。

2. 在Visual Studio Code中，从活动栏中打开 DocumentDB。 在 DocumentDB 连接中，选择“新建连接”，然后选择“连接字符串”并粘贴该值。

3. 选择身份验证方法：

   • Microsoft Entra ID：选择“使用我的帐户登录”以使用自己的标识。 Visual Studio Code在具有托管标识的Azure虚拟机上运行时，请选择“使用分配给此计算机的标识”或改用其他托管标识。 有关详细信息，请参阅 使用托管标识（用户手册）进行连接。
   • 用户名和密码：输入密码。 门户中的连接字符串不包含它。

   

若要在应用程序或其他工具中重复使用连接，请打开群集的上下文菜单，然后选择“ 复制连接字符串”。 计划共享字符串时，选择在不带密码的情况下复制该字符串。

浏览群集仪表板

打开群集的上下文菜单，然后选择 “群集仪表板”。 仪表板将数据库、集合和存储信息集中到一个视图中。 检查连接状态、筛选库存并打开集合，而无需展开边栏中的每个节点。

对于空群集，请选择 “新建数据库” 并将其命名为 store。 打开该数据库，选择“ 新建集合”，并命名该集合 products。 如果已有数据，请选择数据库以浏览其集合并打开要查询的集合。

更改后使用 “刷新” 更新清单。 统计信息取决于服务器报告的内容;仪表板显示快照，而不是运行操作的实时监视器。 还可以打开 shell、复制连接字符串，以及从仪表板访问集合操作。

尝试使用示例数据进行查询

已经有要浏览的集合？ 跳过示例内容，并在筛选器中使用自己的字段名称。 否则，请将这三种产品添加到您的新store.products集合中。 本文中的屏幕截图展示了该扩展在其他演示数据集下的效果。

1. 在仪表板中，选择 “打开 Shell”。 或者，在边栏中打开 products 集合的上下文菜单，然后选择 “打开交互式 Shell”。

2. 在插入示例文档之前，运行以下命令以选择 store 数据库：

   use store
   

3. 运行以下命令一次，将示例文档插入到store.products中：

   db.products.insertMany([
     { _id: "tent", name: "Trail Tent", price: 420, quantity: 140, sale: true },
     { _id: "sleeping-bag", name: "Sleeping Bag", price: 150, quantity: 118, sale: true },
     { _id: "mittens", name: "Mittens", price: 35, quantity: 121, sale: false }
   ])
   

4. 在集合视图中打开集合。 可以使用侧栏中集合旁边的 “打开集合视图” 图标，或者从仪表板打开集合。

查找所需的内容

在“集合视图”中，在 “筛选器” 中输入此表达式以查找价格超过 100 的特价商品：

{ sale: true, price: { $gt: 100 } }

将 Project 设置为 { name: 1, price: 1, _id: 0 }，将 Sort 设置为 { price: -1 }，然后选择 Find Query。 使用示例数据，结果显示“Trail Tent”和“睡袋”，按价格从高到低排序。

输入查询时，编辑器会建议你浏览的文档中的字段、相关运算符和与每个字段的类型匹配的值。 将鼠标悬停在运算符上以获取其文档。 建议使用本地收集的模式信息，而不是外部服务。

在 表、 树和 JSON 视图之间切换以检查结果。 可以创建、编辑或删除文档、导入 JSON 数据以及导出文档或查询结果。

在演练场中保存查询

当一次性查询变为想要保留的内容时，将其移动到 Query Playground。 Playground 文件使用 .documentdb.js 扩展并支持 JavaScript、聚合管道、变量和循环。

1. 打开 store 或 products 的上下文菜单，然后选择新建查询演练场。 该文件会自动连接到该群集和数据库。 在集合视图中，还可以选择“在 Playground 中打开”以将当前查找查询转到 Playground。

2. 将生成的示例替换为此聚合，以查找具有足够库存的销售项目：

   db.products.aggregate([
     { $match: { sale: true, price: { $gte: 100, $lte: 1000 }, quantity: { $gt: 50 } } },
     { $project: { _id: 0, name: 1, price: 1, quantity: 1 } },
     { $sort: { price: -1 } }
   ])
   

3. 选择“在块上方 运行 ”，或选择文件顶部的 “全部运行 ”，并在出现提示时确认。 结果显示在侧面板中。 将文件保存为 sale-products.documentdb.js 以保留脚本。

使用空白行分隔查询以独立运行它们。 如果以后的块依赖于早期块的变量，请使用“全部运行”。 通过块上方的 集合视图 和 Shell 链接，可以在另一个查询图面中继续操作，而无需手动复制代码。

腾出试验空间

想要尝试更新或删除某项而不更改原始文档？ 复制小型开发集合，然后针对副本运行试验。

1. 在 DocumentDB 连接中，为 products 打开上下文菜单，并选择 复制集合。
2. 打开目标数据库的上下文菜单，然后选择 “粘贴集合”。 可以使用同一个数据库，也可以使用另一台已连接服务器上的数据库。
3. 将新集合命名为 products-experiment。 选择 “否，仅复制文档” 进行仅数据复制，然后查看源和目标并确认。
4. 打开复制的集合，并在试验之前检查其内容。 创建一个 playground products-experiment，或更改 shell 命令以使用 db.getCollection("products-experiment")。

如果粘贴到现有集合中，向导会提供策略来在遇到重复的 _id 值时停止、跳过冲突的文档、覆盖文档或生成新的 ID。 在确认之前查看策略：发生冲突时停止不会回滚已复制的文档。

还可以使用集合复制符合条件的辅助索引，也可以从 索引 节点单独复制索引定义。 如果源包含 TTL 或唯一索引，选择是，复制索引会在确认前停止粘贴。 再次运行 粘贴收藏 并选择 “否”，仅复制文档。 复制文档后，使用 索引上下文菜单 单独复制索引。 TTL 索引可以在复制期间删除文档，而唯一索引可能会拒绝这些文档。 有关单独的索引工作流及其保护措施，请参阅 复制和粘贴集合和索引（用户手册）。

探索更多工具

最新版本添加了更多处理数据的方法，从索引管理到本地开发环境：

• 管理查询旁的索引。 在集合视图中打开 索引 以检查现有索引，并通过引导式窗体创建新索引。 使用 以 JSON 预览 查看定义，或将命令发送到 playground 或 shell。 可用的索引类型和操作取决于数据库。
• 在本地试用 DocumentDB。 在“连接”视图中的“自己的 DocumentDB”下，选择“设置 DocumentDB Local”，以进行引导式设置，并可选择示例数据。 此可选工作流需要正常工作的 Docker 引擎或 Docker Desktop 环境，而连接到 Azure DocumentDB 则不需要。 请参阅“设置 DocumentDB 本地”（用户手册）。
• 从更多环境进行连接。 服务发现还会查找 Azure Cosmos DB for MongoDB (RU) 帐户、Azure 虚拟机上的 DocumentDB、Kubernetes 和 MongoDB Atlas，因此可以在一个位置保留所有连接。 请参阅服务发现（用户手册）。

有关最新添加和修补程序，请参阅 扩展发布公告。

排除连接问题

有关详细信息，请打开 输出 面板，选择 DocumentDB，将日志级别设置为 Trace，然后再次连接。

相关内容

• 浏览适用于 Visual Studio Code 的 DocumentDB 扩展（用户手册）
• 为 Azure DocumentDB 群集配置防火墙访问
• 配置Microsoft Entra ID身份验证
• 使用 Azure DocumentDB 迁移扩展插件迁移数据