TripPin 第 1 部分 - OData 服务的数据连接器

项目
05/23/2024

此多部分教程介绍如何针对 Power Query 创建新数据源扩展。本教程按顺序进行，每一课都建立在前几课创建的连接器的基础上，逐步为连接器添加新功能。

在本课中，你将：

使用 Power Query SDK 创建新的数据连接器项目
创作基本函数以从源中拉取数据
在 Power Query SDK 中测试连接器
在 Power BI Desktop 中注册连接器

创建基本 OData 连接器

在本部分中，你将创建新的数据连接器项目，提供一些基本信息，并在 Power Query SDK 中对其进行测试。

打开 Visual Studio Code。建议先创建一个新工作区，然后创建新的扩展项目。若要创建新的扩展项目，请打开资源管理器，然后在“Power Query SDK”部分选择“创建扩展项目”按钮。

选择此按钮后，系统将提示输入新项目的名称。将此新项目命名为 TripPin。

打开 TripPin.pq 文件并粘贴以下连接器定义。

section TripPin;

[DataSource.Kind="TripPin", Publish="TripPin.Publish"]
shared TripPin.Feed = Value.ReplaceType(TripPinImpl, type function (url as Uri.Type) as any);

TripPinImpl = (url as text) =>
    let
        source = OData.Feed(url)
    in
        source;

// Data Source Kind description
TripPin = [
    Authentication = [
        Anonymous = []
    ],
    Label = "TripPin Part 1 - OData"
];

// Data Source UI publishing description
TripPin.Publish = [
    Beta = true,
    Category = "Other",
    ButtonText = { "TripPin OData", "TripPin OData" }
];

此连接器定义包含：

TripPin 连接器的数据源定义记录
一条表明“隐式（匿名）”是此源的唯一身份验证类型的声明
一个具有调用 OData.Feed 的实现的函数 (TripPinImpl)
一个将参数类型设置为 Uri.Type 的共享函数 (TripPin.Feed)
数据源发布记录，允许连接器出现在 Power Query“获取数据”对话框中

打开 TripPin.query.pq 文件。将当前内容替换为对导出的函数的调用。

TripPin.Feed("https://services.odata.org/v4/TripPinService/")

在测试连接器之前，必须先生成它。为此，请转到“终端”并选择“运行生成任务...”选项（键盘快捷键 Ctrl + Shift + B）。建议选择“MakePQX”选项，但可用于生成的任一选项都应正常工作。

此操作的结果将创建新的 Bin 文件夹，其中生成的连接器存储为 TripPin.mez。

<project>.query.pq 文件用于测试扩展，而无需将其部署到 Power BI Desktop 的 bin 文件夹。使用 Power Query SDK 中提供的工具：

选择“设置凭据”选项。
选择“TripPin”作为数据源。
选择 TripPin.query.pq 文件作为查询/测试文件。
选择“匿名”作为身份验证种类。

在输出对话框中，将显示一条消息确认已为数据源设置凭据，并显示创建的每个凭据的详细信息。

注意

始终可以使用“清除所有凭据”命令清除凭据，或使用 Power Query SDK 工具中的“列出凭据”命令检查可用凭据。

现在已准备好凭据后，可以选择 TripPin.query.pq 文件，并在文档中右键单击以评估当前 Power Query 文件，或使用选项从 Power Query SDK 工具评估当前文件。

输出对话框显示了评估结果的消息，以及名为“PQTest 结果”的新窗口。

“PQTest 结果”窗口由三个选项卡组成：

输出：在网格中显示数据的预览。
摘要：常规评估详细信息，如 StartTime、EndTime、Duration、用于评估的文件、状态等。
DataSource：提供有关从种类、函数名称和路径使用的数据源的信息。

你可以在测试文件中试用几个其他 OData URL，以了解返回的其他结果。例如：

https://services.odata.org/v4/TripPinService/Me
https://services.odata.org/v4/TripPinService/GetPersonWithMostFriends()
https://services.odata.org/v4/TripPinService/People

TripPin.query.pq 文件可以包含单个语句、let 语句或完整节文档。

let
    Source = TripPin.Feed("https://services.odata.org/v4/TripPinService/"),
    People = Source{[Name="People"]}[Data],
    SelectColumns = Table.SelectColumns(People, {"UserName", "FirstName", "LastName"})
in
    SelectColumns

重要

确保在工作时始终保存文件。如果对 TripPin.pq 文件进行了更改，则应始终触发后续生成任务，以确保针对最新版本的连接器进行测试。

打开 Fiddler 以捕获 HTTP 流量，并运行查询。你应该会看到一些向 services.odata.org 提出的其他请求，这些请求由混合容器进程生成。你可能会发现，访问服务的根 URL 会导致 302 状态和重定向到较长版本的 URL。以下重定向是从基本库函数“免费”获取的另一种行为。

如果查看 URL，则需要注意的一点是，你可能会看到 SelectColumns 语句发生的查询折叠。 https://services.odata.org/v4/TripPinService/People?$select=UserName%2CFirstName%2CLastName

如果将更多转换添加到查询中，则可以查看它们如何影响生成的 URL。

务必注意此行为。即使未实施显式折叠逻辑，连接器也会从 OData.Feed 函数中继承这些功能。 M 语句可撰写 - 筛选器上下文将尽可能从一个函数流向另一个函数。这在概念上类似于连接器中使用的数据源继承其身份验证上下文和凭据的方法。在后面的课程中，你将所使用的具有本机折叠功能的 OData.Feed 替换为不具有此功能的 Web.Contents。若要获得相同级别的功能，你将需要使用 Table.View 接口并实施自己的显式折叠逻辑。

在 Power BI Desktop 中加载扩展

若要在 Power BI Desktop 中使用扩展，你需要将连接器项目的输出文件 (TripPin.mez) 复制到自定义连接器目录中。

创建 [My Documents]\Power BI Desktop\Custom Connectors 目录。
将扩展文件 (TripPin.mez) 复制到此目录。
在 Power BI Desktop 中，选中（不推荐）允许任何扩展加载（不显示验证或警告）选项（在文件>选项和设置>选项>安全性>数据扩展下面）。
重启 Power BI Desktop。
选择获取数据 > 更多，以显示获取数据对话框。

你可以通过在搜索框中键入其名称来查找扩展。

“获取数据”对话框。

选择函数名称，然后选择连接。此时将显示第三方消息 - 选择继续以继续。此时将显示函数调用对话框。输入服务的根 URL (https://services.odata.org/v4/TripPinService/)，然后选择确定。

调用函数。

由于这是你第一次访问此数据源，将收到凭据提示。检查是否选择了最短 URL，然后选择连接。

凭据提示设置为“匿名”的图像，并将级别设置设为最短 URL。

请注意，出现的不是简单的数据表，而是导航器。这是因为 OData.Feed 函数会返回具有特殊元数据的表，此外，Power Query 体验知道要将此表显示为导航表。本演练将介绍如何在将来的课程中创建和自定义自己的导航表。

选择 Me 表，然后选择转换数据。请注意，这些列（其中大多数）已经分配有类型。这是基础 OData.Feed 函数的另一个功能。如果观看 Fiddler 中的请求，你将看到你已提取服务的 $metadata 文档。引擎的 OData 实现会自动执行此操作，以确定服务的架构、数据类型和关系。

Me 记录。

结束语

本课程指导你根据 OData.Feed 库函数创建简单的连接器。正如你所看到的那样，只需很少逻辑即可在 OData 基本函数上启用功能齐全的连接器。其他已启用可扩展性的函数（例如 ODBC.DataSource）可提供类似的功能。

在下一课中，你将所使用的 OData.Feed 替换为功能较少函数，即 Web.Contents。每个课程都会实现更多连接器功能，包括分页、元数据/架构检测和按 OData 查询语法折叠查询，直到自定义连接器支持与 OData.Feed 相同的功能范围。

后续步骤

TripPin 第 2 部分 - REST 服务的数据连接器

通过

TripPin 第 1 部分 - OData 服务的数据连接器

创建基本 OData 连接器

在 Power BI Desktop 中加载扩展

结束语

后续步骤

反馈

其他资源