Power Query SDK 概述

项目
10/05/2023

Power Query SDK 是一组旨在帮助你创建 Power Query 连接器的工具。这些连接器通常称为自定义连接器或 Power Query 扩展。

使用自定义连接器，你可以创建新数据源或自定义和扩展现有源。常见用例包括：

为 REST API 创建业务分析师易用视图。
为 Power Query 通过现有连接器（例如 OData 服务或 ODBC 驱动程序）支持的源提供品牌。
对 SaaS 产品/服务实施 OAuth v2 身份验证流程。
显示数据源的有限视图或筛选视图以提高可用性。
使用 ODBC 驱动程序为数据源启用 DirectQuery。

安装 Power Query SDK

目前有以下两个版本的 Power Query SDK 可用：

Visual Studio Power Query SDK：2017 年以 Visual Studio 2017 和 2019 扩展形式发布。
Visual Studio Code Power Query SDK（预览版）：2022 年发布，这是推荐的创建 Power Query 连接器的新方法。

我们鼓励所有开发人员安装和使用新发布的 Visual Studio Code Power Query SDK（预览版），因为，此版本将来最终会成为默认的 SDK。

Visual Studio Power Query SDK

执行以下步骤来安装 Visual Studio Power Query SDK：

从 Visual Studio Marketplace 中安装 Power Query SDK。
创建新数据连接器项目。
定义连接器逻辑。
构建项目以生成扩展文件。

预览功能。

Visual Studio Code Power Query SDK（预览版）

注意

自 2022 年 9 月起，新 Visual Studio Code Power Query SDK 目前以公共预览版形式提供。

从 Visual Studio Marketplace 的 Visual Studio Code 部分中安装新的 Visual Studio Code Power Query SDK。选择安装以安装此 SDK。

连接器开发流程

虽然你可以使用 Visual Studio Code 或 Visual Studio Power Query SDK，但两者都使用类似的过程在高级别开发连接器。

以下部分简要介绍使用 SDK 创建 Power Query 连接器的最常见过程。

创建一个新扩展

创建新项目 (Visual Studio Power Query SDK) 或新工作区 (Visual Studio Code Power Query SDK) 时，首先使用以下核心文件：

连接器定义文件 (<connectorName>.pq)
查询文件 (<connectorName>.query.pq)
字符串资源文件 (resources.resx)
用于创建图标的各种大小的 PNG 文件

你的连接器定义文件将从空数据源说明开始。可以从有关处理数据访问的文章中详细了解 Power Query SDK 上下文中的数据源。

测试

Power Query SDK 提供基本查询执行功能，允许你测试扩展，而不必切换到 Power BI Desktop。

查询测试文件

除了具有扩展文件之外，数据连接器项目还可以具有查询文件 (name.query.pq)。此文件可用于在 Visual Studio 内运行测试查询。查询评估将自动包含你的扩展代码，而不必注册 .pqx 文件，从而允许你调用或测试扩展代码中的任何共享函数。

此查询文件可以包含单个表达式（例如 HelloWorld.Contents()）、let 表达式（如 Power Query 将生成的内容）或节文档。

构建和部署

生成项目会生成 .mez 文件或扩展名文件。

Power Query 扩展捆绑在 ZIP 文件中，并被提供 .mez 文件扩展名。在运行时，Power BI Desktop 从 [Documents]\Microsoft Power BI Desktop\Custom Connectors 中加载扩展。

注意

数据连接器项目不支持将扩展文件复制到 [Documents]\Microsoft Power BI Desktop\Custom Connectors 目录中的自定义生成后步骤。如果这是你想要执行的操作，则你可能需要使用第三方扩展。

扩展在 M 节文档中定义。节文档的格式与 Power Query 中生成的查询文档的格式略有不同。你从 Power Query 导入的代码通常需要修改以适应节文档，但更改很小。应注意的节文档差异包括：

它们以节声明（例如 section HelloWorld;）开头。
每个表达式都以分号（例如，a = 1; 或 b = let c = 1 + 2 in c;）结尾。
所有函数和变量除非被标记为共享，否则它们都是节文档的局部变量。共享函数对其他查询/函数可见，可以被视为扩展的导出（即，可从 Power Query 中调用它们）。

可以在 M 语言规范中找到关于 M 节文档的详细信息。

数据连接器的分布

Power Query 连接器可用于 Power BI Desktop 或 Power Query Online 体验，例如 Power BI 数据流、Power BI 数据市场和其他体验。

Power BI Desktop

Power BI Desktop 用户可以按照以下步骤使用 Power Query 自定义连接器：

将扩展文件 (.mez or.pqx) 复制到 [Documents]/Power BI Desktop/Custom Connectors 中。
在 Power BI Desktop 中，选择文件>选项和设置>选项>安全性>数据扩展下面的（不推荐）允许任何扩展加载（不显示验证或警告）选项。
重启 Power BI Desktop。

Power BI Desktop 将在重启时自动加载扩展。

或者，作为数据源和连接器的所有者，可以将连接器提交到 Power Query 连接器认证计划，以便每次发布时它随 Power BI Desktop 一起提供。

Power Query Online

注意

Power Query 团队正在努力在 Power Query Online 体验中启用所有 Power Query 认证连接器。

Power Query Online 体验中仅显示 Power Query 认证连接器。若要详细了解 Power Query 连接器认证计划，请转到 Power Query 连接器认证。