处理数据源路径

项目
05/15/2024

M 引擎使用其种类和路径的组合来标识数据源。在查询评估期间遇到数据源时，M 引擎会尝试查找匹配的凭据。如果未找到凭据，引擎将返回一个特殊错误，从而导致 Power Query 中显示凭据提示。

种类值来自数据源种类定义。

路径值派生自数据源函数的必要参数。可选参数不会纳入数据源路径标识符。因此，与数据源类型关联的所有数据源函数均须具有相同的参数。对于具有 Uri.Type 类型的单个参数的函数，会进行特殊处理。有关详细信息，请转到包含 URI 参数的函数。

可看到如何在 Power BI Desktop 的数据源设置对话框中存储凭据的示例。在此对话框中，“种类”由图标表示，“路径”值则显示为文本。

数据源设置凭据的屏幕截图。

注意

如果在开发过程中更改数据源函数的必要参数，则先前存储的凭据将失效（因为路径值不再匹配）。每当更改数据源函数参数时，均应删除所有存储的凭据。如果发现不兼容的凭据，可能会在运行时收到错误。

数据源路径格式

数据源的路径值派生自数据源函数的必要参数。通过将 DataSource.Path = false 添加到函数的元数据，可从路径中排除必要参数。有关详细信息，请转到从数据源路径中排除必要参数。

默认情况下，可在 Power BI Desktop 的数据源设置对话框中和凭据提示中看到实际字符串值。如果数据源种类定义包含 Label 值，则会看到标签值。

例如，HelloWorldWithDocs 示例中的数据源函数具有以下签名：

HelloWorldWithDocs.Contents = (message as text, optional count as number) as table => ...

该函数具有一个 text 类型的必要参数 (message)，且用于计算数据源路径。可选参数 (count) 将忽略。路径如下所示：

凭据提示

带有路径的凭据提示的屏幕截图。

数据源设置 UI

数据源设置 UI 的屏幕截图。

定义标签值时，不会显示数据源路径值：

定义了标签的数据源设置的屏幕截图。

注意

目前，我们建议：如果函数附带必要参数，则不包含数据源的标签，因为用户无法区分他们输入的不同凭据。我们希望在未来改进这一点（即，允许数据连接器显示自己的自定义数据源路径）。

从数据源路径中排除必要参数

如果希望将某一函数参数设为必要参数，但不作为数据源路径的一部分包含在内，则可将 DataSource.Path = false 添加到函数文档元数据。可将此属性添加到函数的一个或多个参数。此字段将从数据源路径中删除值（这意味着不会再将其传递给 TestConnection 函数），因此它只应该用于不需要标识数据源的参数，或是区分不同的用户凭据。

例如，HelloWorldWithDocs 示例中的连接器要求为不同的 message 值使用不同的凭据。将 DataSource.Path = false 添加到 message 参数会将其从数据源路径计算中删除，从而使连接器变为“单一实例”。对 HelloWorldWithDocs.Contents 的所有调用均被视为同一数据源，且用户仅提供一次凭据。

HelloWorldType = type function (
    message as (type text meta [
        DataSource.Path = false,
        Documentation.FieldCaption = "Message",
        Documentation.FieldDescription = "Text to display",
        Documentation.SampleValues = {"Hello world", "Hola mundo"}
    ]),
    optional count as (type number meta [
        Documentation.FieldCaption = "Count",
        Documentation.FieldDescription = "Number of times to repeat the message",
        Documentation.AllowedValues = { 1, 2, 3 }
    ]))
    as table meta [
        Documentation.Name = "Hello - Name",
        Documentation.LongDescription = "Hello - Long Description",
        Documentation.Examples = {[
            Description = "Returns a table with 'Hello world' repeated 2 times",
            Code = "HelloWorldWithDocs.Contents(""Hello world"", 2)",
            Result = "#table({""Column1""}, {{""Hello world""}, {""Hello world""}})"
        ],[
            Description = "Another example, new message, new count!",
            Code = "HelloWorldWithDocs.Contents(""Goodbye"", 1)",
            Result = "#table({""Column1""}, {{""Goodbye""}})"
        ]}
    ];

带 URI 参数的函数

由于具有基于 URI 的标识符的数据源非常常见，因此处理基于 URI 的数据源路径时，Power Query UI 会进行特殊处理。遇到基于 URI 的数据源时，凭据对话框会提供一个下拉列表，从而允许用户选择基本路径，而不是完整路径（以及中间的所有路径）。

凭据对话框的屏幕截图，显示凭据应用于的设置路径。

在 M 语言中，由于 Uri.Type 为归属类型而不是基元类型，因此需使用 Value.ReplaceType 函数来指示应将文本参数视为 URI。

shared GithubSample.Contents = Value.ReplaceType(Github.Contents, type function (url as Uri.type) as any);

通过