你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 Power BI 可视化 Azure Cosmos DB 数据

适用范围： NoSQL

本文介绍需要执行哪些步骤才能将 Azure Cosmos DB 数据连接到 Power BI Desktop。

可以使用以下选项之一从 Power BI Desktop 连接到 Azure Cosmos DB：

• 使用 Microsoft Fabric 中的镜像将 Azure Cosmos DB 数据复制到 Fabric OneLake。 对数据库所做的任何更改都会近乎实时地自动同步到 Fabric OneLake，而不会影响源数据库的性能或使用资源单元 (RU)。

  然后，Power BI 报表可以使用 DirectLake 模式直接从 OneLake 访问数据。 借助 Fabric 中 Power BI 中增强的 Copilot 功能，可以利用生成式 AI 来获取关键业务见解。

• 使用 Azure Synapse Link 生成 Power BI 报表，而不会影响事务工作负载的性能或成本，也不需要创建 ETL 管道。

  可以使用 DirectQuery 或 导入模式。 借助 DirectQuery，可以使用 Azure Cosmos DB 帐户中的实时数据生成仪表板/报表，而无需将数据导入或复制到 Power BI。

• 使用 Power BI 的 Azure Cosmos DB 连接器将 Power BI Desktop 连接到 Azure Cosmos DB 帐户。 此选项仅在导入模式下可用，将会消耗为事务工作负载分配的 RU。

注意

在 Power BI Desktop 中创建的报表可以发布到 PowerBI.com。 无法从 PowerBI.com 执行 Azure Cosmos DB 数据的直接提取。

先决条件

在按照此 Power BI 教程中的说明操作之前，请确保已拥有对以下资源的访问权限：

• 下载最新版本的 Power BI Desktop。

• 创建 Azure Cosmos DB 数据库帐户并将数据添加到 Azure Cosmos DB 容器。

要在 PowerBI.com 中共享报表，必须在 PowerBI.com 中拥有帐户。 若要了解有关 Power BI 和 Power BI Pro 的详细信息，请参阅 https://powerbi.microsoft.com/pricing。

让我们开始吧

使用 Microsoft Fabric 中的镜像生成 BI 报表

可近乎实时地对现有 Azure Cosmos DB 容器启用镜像，并基于此数据生成 BI 报表/仪表板。 有关 Fabric 和镜像入门的说明，请访问 Azure Cosmos DB 的镜像教程。

使用 Azure Synapse Link 生成 BI 报表

只需在 Azure Cosmos DB 门户中单击几下鼠标，就能在现有 Azure Cosmos DB 容器上启用 Azure Synapse Link 并为此数据生成 BI 报表。 Power BI 将使用直接查询模式连接到 Azure Cosmos DB，允许你查询实时 Azure Cosmos DB 数据，且不影响事务工作负载。

若要生成 Power BI 报表/仪表板，请执行以下操作：

1. 登录到 Azure 门户，导航到 Azure Cosmos DB 帐户。

2. 从“集成”部分，打开“Power BI”窗格，然后选择“开始”。

   注意

   目前，此选项仅针对 API for NoSQL 帐户提供。 可以直接在 Synapse 无服务器 SQL 池中创建 T-SQL 视图，并为 Azure Cosmos DB for MongoDB 生成 BI 仪表板。 有关详细信息，请参阅使用 Power BI 和无服务器 Synapse SQL 池通过 Synapse 分析 Azure Cosmos DB 数据。

3. 在“启用 Azure Synapse Link”选项卡中，可以从“为此帐户启用 Azure Synapse Link”部分在帐户上启用 Synapse Link。 如果你的帐户已启用 Synapse Link，则你看不到此选项卡。必须先完成此步骤，才能开始在容器上启用 Synapse Link。

   注意

   启用 Azure Synapse Link 会产生成本影响。 有关更多详细信息，请参阅 Azure Synapse Link 定价部分。

4. 接下来，从“为容器启用 Azure Synapse 链接”部分选择启用 Synapse Link 所需的容器。

   • 如果已经在某些容器上启用了 Synapse Link，则会看到容器名称旁边的复选框已选中。 可以根据要在 Power BI 中可视化的数据选择性地取消选择它们。

   • 如果未启用 Synapse Link，你可以在现有容器上启用此功能。

     如果任何容器上正在启用 Synapse Link，则不会包含来自这些容器的数据。 应稍后返回到此选项卡，并在启用容器时导入数据。

   

5. 根据容器中的数据量，启用 Synapse Link 可能需要一段时间。 若要了解详细信息，请参阅在现有容器上启用 Synapse Link 一文。

   可以在门户中检查进度，如以下屏幕所示。 当进度达到 100% 时，容器便启用了 Synapse Link。

   

6. 从“选择工作区”选项卡中，选择 Azure Synapse Analytics 工作区，然后选择“下一步”。 此步骤将在 Synapse Analytics 中为前面选择的容器自动创建 T-SQL 视图。 有关将 Azure Cosmos DB 连接到 Power BI 所需的 T-SQL 视图的详细信息，请参阅准备视图一文。

   注意

   Azure Cosmos DB 容器属性将在 T-SQL 视图中表示为列，其中包含深度嵌套的 JSON 数据。 这是 BI 仪表板的快速入门数据。 这些视图将在 Synapse 工作区/数据库中显示；你还可以在 Synapse 工作区中使用这些视图来完成数据探索、数据科学、数据工程等任务。请注意，高级方案可能需要更复杂的视图或微调这些视图，以提高性能。 有关详细信息， 请参阅使用 Synapse 无服务器 SQL 池时 Synapse Link 的最佳做法一文。

7. 可以选择现有工作区，也可以创建新工作区。 若要选择现有工作区，请提供“订阅”、“工作区”和“数据库”详细信息。 Azure 门户将使用你的 Microsoft Entra 凭据自动连接到 Synapse 工作区并创建 T-SQL 视图。 确保你对此工作区具有“Synapse 管理员”权限。

   

8. 接下来，选择“下载 .pbids”以下载 Power BI 数据源文件。 打开下载的文件。 其中包含所需的连接信息。打开 Power BI Desktop。

   

9. 现在，可以从 Power BI Desktop 连接到 Azure Cosmos DB 数据。 将显示与每个容器中的数据对应的 T-SQL 视图列表。

   例如，以下屏幕显示车队数据。 可以加载此数据进行进一步分析，或在加载前转换这些数据。

   

10. 现在，可以使用 Azure Cosmos DB 的分析数据开始生成报表。 数据复制到分析存储后，对数据的任何更改都会反映在报表中，这通常会在几分钟内发生。

使用 Power BI 连接器生成 BI 报表

注意

目前，仅 Azure Cosmos DB for NoSQL 和 API for Gremlin 帐户支持使用 Power BI 连接器连接 Azure Cosmos DB。

1. 运行 Power BI Desktop。

2. 可以“获取数据” 、查看“最近使用的源” 或直接从“欢迎”屏幕“打开其他报表” 。 单击右上角的“X”以关闭屏幕。 显示 Power BI Desktop 的“报表” 视图。

   

3. 选择“主页” 功能区，并单击“获取数据” 。 应出现“获取数据” 窗口。

4. 单击“Azure”，选择“Azure Cosmos DB (Beta)”，并单击“连接”。

   

5. 在“预览连接器”页中，单击“继续” 。 此时会显示“Azure Cosmos DB”窗口。

6. 如下所示指定想要从其中检索数据的 Azure Cosmos DB 帐户终结点 URL，并单击“确定” 。 要使用自己的帐户，可以从 Azure 门户的“密钥”边栏选项卡的 URI 框中取得 URL 。 可选：你可以提供数据库名称、集合名称，也可以使用导航器来选择数据库和集合以标识数据来源。

7. 如果是首次连接到此终结点，则会提示输入帐户密钥。 若使用自己的帐户，请从 Azure 门户的“只读密钥” 边栏选项卡中的“主密钥” 框中取得密钥。 输入相应的密钥，然后单击“连接” 。

   我们建议在生成报表时使用只读密钥。 这可防止主密钥不必要地暴露于潜在的安全风险中。 可以从 Azure 门户的密钥边栏选项卡获取只读密钥。

8. 帐户成功连接后，将出现“导航器”窗格 。 “导航器” 会在帐户下显示数据库的列表。

9. 单击并展开报表数据的来源数据库。 现在，选择包含要检索的数据的集合。

   预览窗格显示“记录” 项的列表。 文档在 Power BI 中表示为一种“记录” 类型。 同样，文档内部的嵌套 JSON 块也是“记录” 。 要以列形式查看属性文档，请单击灰色按钮，该按钮带有两个方向相反的箭头，用于表示记录扩展。 它位于容器名称右侧，在同一预览窗格中。

10. 可以在 Power BI Desktop 报表视图中开始创建报表来将数据可视化。 可以通过将字段拖放到“报表” 画布中来创建报表。

11. 可通过两种方式刷新数据：临时刷新和按计划刷新。 只需单击“立即刷新”即可刷新数据。 有关计划刷新选项的详细信息，请查看 Power BI 文档。

已知问题和限制

• 对于分区的 Cosmos DB 容器，如果查询还包含分区键上的筛选器（WHERE 子句），则具有聚合函数的 SQL 查询将向下传递到 Cosmos DB。 如果聚合查询不包含分区键上的筛选器，则连接器将执行聚合。

• 如果在应用 TOP 或 LIMIT 后调用聚合函数，则连接器不会向下传递聚合函数。 Cosmos DB 在处理查询时处理 TOP 操作。 例如，在以下查询中，在子查询中应用 TOP，而将聚合函数应用于该结果集的顶部：

  SELECT COUNT(1) FROM (SELECT TOP 4 * FROM EMP) E

• 如果在聚合函数中提供了 DISTINCT，则连接器不会在聚合函数中提供 DISTINCT 子句时将聚合函数向下传递到 Cosmos DB。 聚合函数中存在时，Cosmos DB SQL API 不支持 DISTINCT。

• 对于 SUM 聚合函数，如果 SUM 中的任何参数是字符串、布尔值或 null，则 Cosmos DB 将返回未定义的结果集。 但是，如果有 null 值，连接器会将查询传递给 Cosmos DB，这样就会作为 SUM 计算的一部分，要求数据源将 null 值替换为零。

• 对于 AVG 聚合函数，如果 SUM 中的任何参数是字符串、布尔值或 null，则 Cosmos DB 将返回未定义的结果集。 连接器会公开连接属性，以禁用将 AVG 聚合函数向下传递给 Cosmos DB，以防需要替代此默认 Cosmos DB 行为。 禁用 AVG 向下传递时，不会将其向下传递到 Cosmos DB，连接器将处理执行 AVG 聚合操作本身。 有关详细信息，请转到高级选项中的“启用 AVERAGE 函数向下传递”。

• 连接器当前不支持具有大型分区键的 Azure Cosmos DB 容器。

• 由于服务器限制，对以下语法禁用聚合向下传递：

  • 当查询未筛选分区键或分区键筛选器在 WHERE 子句的顶层将 OR 运算符与另一个谓词一起使用时。

  • 当查询有一个或多个分区键出现在 WHERE 子句中的 IS NOT NULL 子句中时。

• V2 连接器不支持复杂的数据类型，如数组、对象和分层结构。 对于这些场景，建议使用 [Azure Cosmos DB 的 Fabric 镜像]（/articles/cosmos-db/analytics-and-business-intelligence-overview.md 功能）。

• V2 连接器使用前 1,000 个文档的采样来得出推断的架构。 仅更新文档的一部分时，不建议将其用于架构演变场景。 例如，包含数千个文档的容器中某个文档的新添加属性可能不会包含在推断的架构中。 对于这些场景，我们建议使用适用于 Azure Cosmos DB 的 Fabric 镜像功能。

• 目前，V2 连接器不支持对象属性中的非字符串值。

• 由于服务器限制，对以下语法禁用筛选器向下传递：

• 在 WHERE 子句中引用包含一个或多个聚合列的查询时。

后续步骤

• 有关 Power BI 的详细信息，请参阅 Power BI 入门。
• 若要了解有关 Azure Cosmos DB 的详细信息，请参阅 Azure Cosmos DB 文档登陆页。