通过

Power Query SDK 概述

  • 项目

本文的目的是概述 Power Query SDK for Visual Studio Code 中的总体功能和开发体验。

新建项目

提示

在创建扩展项目之前，建议创建一个新文件夹，用于存储扩展项目。 在创建新项目期间，如果未选择任何文件夹，Power Query SDK 会在创建扩展项目之前帮你找到或创建一个新文件夹。

进入 Visual Studio Code 后，在 Visual Studio Code 的主 Explorer 窗格中，有一个名为 Power Query SDK 的分区。 该分区只有一个按钮，内容为“创建扩展项目”。 选择本按钮。

Visual Studio Code 中的“创建新的扩展项目”按钮。

此按钮会在 Visual Studio Code 界面顶部打开一个输入字段。 输入新扩展项目的名称，然后选择 Enter。

创建新的扩展项目并命名项目。

几秒钟后，Visual Studio Code 窗口将打开扩展项目的主 *.pq 文件，其中包含连接器逻辑。 Power Query SDK 会自动运行一些必要的任务来完成工作区的设置。 你可以在 Visual Studio Code 的输出控制台中检查这些任务。

使用 Hello World 模板创建的扩展项目。

Power Query SDK 会自动创建以下文件集：

  • settings.json 文件，说明要在工作区级别使用的特定设置。
  • 它将扩展名创建为 .mez 文件，并将其存储在新的 bin\AnyCPU\Debug 文件夹中。
  • 一组 .png 文件形式的连接器图标。
  • resources.resx 文件，作为扩展中使用的字符串的主存储空间。
  • 一个 .pq 文件，用于保存扩展或连接器的主要逻辑。
  • 一个 .query.pq 文件，主要用于创建测试查询以便日后进行评估。
  • 一个 .proj 文件，保存扩展项目的相关信息。

连接器文件列表。

Visual Studio Code 识别扩展项目后，Power Query SDK 部分的外观就会更改，现在会显示可针对新扩展项目运行的任务列表。

“Power Query SDK”部分中的任务。

凭据

重要

在评估任何数据连接器的查询之前，必须先为扩展项目创建一组凭据。

Power Query SDK 通过其用户界面提供多个任务，以便设置、列出和删除扩展项目中的凭据。

设置凭据

Power Query SDK 主要由可通过多个入口点触发的任务驱动。 可以通过两种方式设置凭据（其他凭据任务也可通过相同方法完成）。

  • 通过 Explorer 窗格中 Power Query SDK 部分的入口。

    通过浏览器中的“Power Query SDK”部分设置凭证。

  • 通过终端选择“运行任务”选项，然后选择“设置凭据”任务。

    通过“终端”菜单设置凭证。

运行此任务时，Visual Studio Code 将通过一系列提示引导你设置凭据。 这些提示系列是可预测的，并且始终包含相同的阶段：

  1. 选择数据源类型。
  2. 选择连接器文件。
  3. 选择身份验证方法。

对于现有扩展项目，身份验证方法是匿名的。 设置身份验证后，窗口右下角会显示确认凭据已成功生成的消息。

已成功生成凭证。

列出凭据

与设置凭据类似，列出凭据的任务也在同一位置有两个入口点：Explorer 窗格中的 Power Query SDK 部分和终端菜单中。

执行此任务时，可用凭据会在输出终端中展示。

“输出”控制台中列出的凭证。

清除所有凭据

与前面的两个任务类似，清除所有凭据的任务也在同一位置有两个入口点：Explorer 窗格中的 Power Query SDK 部分和终端菜单中。

当需要设置新凭据来评估查询时，此任务可清除当前会话中的所有凭据。

输出控制台也会显示此任务的信息性消息。

“清除所有凭证”任务的信息性消息。

评估查询和结果面板

在评估任何测试查询之前，必须设置凭据。 使用在前部分创建的连接器，可以打开用作测试查询文件的 *.query.pq 文件。

对于项目名称为 MyConnector 的特定连接器，代码如下所示：

// Use this file to write queries to test your data connector
let
    result = MyConnector.Contents()
in
    result

在评估查询之前，请按如下所示更改代码：

// Use this file to write queries to test your data connector
let
    result = MyConnector.Contents("Hello World")
in
    result

确保在更改代码后保存文件。

若要评估此查询，有三个选择：

  • 右键点选正在使用的文件，然后选择“评估当前电源查询文件”选项。

右键单击当前文件以对其进行评估。

  • 浏览“终端”菜单，然后选择“评估当前文件”任务。

在“终端”菜单中选择“评估当前文件”任务。

  • 通过 Visual Studio Code 中的本机运行和调试选项，选择超链接即可创建 launch.json 文件，然后评估该文件。

创建 launch.json 文件以通过“运行”和“调试”扩展性评估查询。

评估查询后，结果会显示在窗口底部的控制台和右侧名为“结果”的新面板中。

评估完成后显示的 Visual Studio Code 窗口，其中控制台和“结果”面板显示了输出。

结果面板包含三个选项卡：

  • “输出”选项卡：显示已评估查询的数据预览。 如果数据是表，则显示为网格。

    “结果”面板中的“输出”选项卡。

  • 摘要： 显示运行评估的活动摘要，以及与该活动相关的统计信息。

    “结果”面板中的“摘要”选项卡。

  • DataSource：显示评估所用数据源的一般信息。

    “结果”面板中的“DataSource”选项卡。

若要评估其他查询，只需修改 *.query.pq 文件并保存，然后使用这三种方法中的任何一种再次运行评估任务即可。

注意

Power Query SDK 不管理任何类型的评估缓存机制。

将旧扩展项目引入新 SDK

本节将帮助连接器开发人员了解使用旧版基于 Power Query SDK 的 Visual Studio 创建的扩展项目。

若要继续学习，我们建议从 DataConnectors 存储库下载用于 TripPin 示例的连接器项目，特别是示例 9-TestConnection。

若要将旧扩展项目引入新 SDK，请执行以下步骤：

  1. 在 Visual Studio Code 中，选择“文件”>“打开文件夹”，然后导航到扩展项目所在的文件夹。

  2. 通过以下两种方法之一，使用现有文件夹及其内容设置工作区：

    • Power Query SDK 具有识别文件夹内容的机制，建议将其转换为新的 Power Query SDK 工作区。

      Visual Studio Code 界面中的弹出窗口，建议用户升级到 Power Query SDK 工作区。

    • 从“终端”菜单中运行设置工作区和生成任务。 这将有效地创建工作区所需的 .mez 文件和 settings.json 文件。

加这两个新文件夹和文件后，当前工作区就变成了新的 Power Query SDK 工作区。

将扩展项目升级到新的 Power Query SDK。

设置工作区

设置工作区任务的作用是有效地为工作区创建 settings.json 文件，该文件规定了将用于工作区的评估和常规设置的某些变量。

生成扩展文件

生成任务允许按需为扩展创建 .mez 文件。

运行 TestConnection 函数

TestConnection 是一种通过 Power BI 等服务在微软云中刷新连接器的函数。 它是连接器数据源记录中的一条记录。 可以从测试连接可用示例中了解有关 TestConnection 处理程序实现的更多信息。

运行 TestConnection 的任务可让你在 Power Query SDK 中测试处理程序，而无需在 Microsoft 云中手动尝试该处理程序。

若要运行此任务，请先为连接器设置凭据，然后从 Explorer 中的 Power Query SDK 部分或通过终端菜单中的任务列表运行该任务。

此任务结果显示在窗口底部的输出终端中。

在 Power Query SDK 中运行“TestConnection”函数的结果。

反馈和 Bug

如果需要有关开发自定义连接器的帮助，或者想提出任何反馈、建议或错误，请访问 GitHub 上的官方公共存储库。

也可以使用 Power BI 社区论坛发布有关 Power Query、M 语言和自定义连接器开发的一般问题。