Power Query での 起動 UI の記述方法

14198 ワード
UI PowerQuery CustomConnector UI テキストリンク

背景

カスタムコネクタを作った際に、起動 UI 部分について悩んだので別途記録

はじめに

Power Query で関数化する場合は特に気にせずで良いかと思います。

以下のような場合に、初めて有用になるかな、と

  1. カスタムコネクタを作る場合
    • コネクタ選択後に引数記入してもいいけど、以下のような入力 UI はあった方が便利
  2. Power Query で関数化した際に、使い方とかをちゃんと記録したい場合
    • 以下のように使用例を複数表示出来るので、使えると便利ですね。

UI 利用定義のまとめ

今回の内容は、function-docs.md を読んで、HelloWorldWithDocs を見るのが手っ取り早かった。

Function Documentation

Field Type Details 補足
.Name text Text to display across the top of the function invocation dialog. 名称
.LongDescription text Full description of what the function does, displayed in the function info. 説明
.Examples list List of record objects with example usage of the function. Only displayed as part of the function info. Each record should contain the following optional text fields: Description, Code, Result. 実行例の記載、プロパティは以下で

Documentation.Examples

Field Type 補足
Description text Example の説明。複数例示出来るので、それぞれ毎の説明を記載
Code text 実際の利用例
Result text 実際の実行結果例。text なので、#table や list 構文適当でも表示出来ちゃうので利用時は注意。😅

Parameter Documentation

Field Type Details 補足
.AllowedValues list List of valid values for this parameter. Providing this field will change the input from a textbox to a drop down list. Note, this does not prevent a user from manually editing the query to supply alternate values. 許可された選択肢の一覧。今回は未使用。
.FieldCaption text Friendly display name to use for the parameter. 呼び出し時の引数の名称
.FieldDescription text Description to show next to the display name. 呼び出し時の引数の説明
.SampleValues list List of sample values to be displayed (as faded text) inside of the text box. 引数の例

実際の画面での対比

カスタムコネクタの UI

起動時 UI

割付

関数の UI

比較用の実装例

IF部分
[DataSource.Kind="PQExtensionFormsAPI", Publish="PQExtensionFormsAPI.Publish"]
shared PQExtensionFormsAPI.Contents = Value.ReplaceType(PQExtensionFormsAPIImpl, PQExtensionFormsAPIType);
Type
PQExtensionFormsAPIType = type function (
    message as (type text meta [
        Documentation.FieldCaption = "Forms Url",
        Documentation.FieldDescription = "Text, 解析したい Forms の URL",
        Documentation.SampleValues = {"https://forms.office.com/Pages/DesignPage.aspx?route=Start#FormId=Ylunxf9LlkynIGYhzpl45X6btOKMGSpAhfdw3zJ9jQ1UNDdIVlZXN1JKSlNXVENEOU43RU9TSlJCNSQlQCN0PWcu"}
    ]))
    as list meta [
        Documentation.Name = "Forms API の解析",
        Documentation.LongDescription = "解析したい Forms API の URL をコピーして見ましょう。",
        Documentation.Examples = {[
            Description = "Returns error message with invalid Forms URL not including FormsId",
            Code = "PQExtensionFormsAPI.Contents(""invalid url"")",
            Result = "{ ""URL に ""FormId="" が含まれていませんでした。""}"
        ],[
            Description = "Returns valid responses!",
            Code = "PQExtensionFormsAPI.Contents(""https://forms.office.com/Pages/DesignPage.aspx?lang=ja&origin=OfficeDotCom&route=Start#FormId=Ylunxf9LlkynIGYhzpl45X6btOKMGSpAhfdw3zJ9jQ1UNDdIVlZXN1JKSlNXVENEOU43RU9TSlJCNSQlQCN0PWcu"")",
            Result = "{ [
                id = 1,
                startDate = ""2020-09-16T02:04:08.5515779Z"",
                submitDate = ""2020-09-16T02:04:08.5515779Z"",
                responder = ""[email protected]"",
                responderName = ""responderName"",
                answers = ""[{""answer1"":""回答だよ"",""questionId"":""r9fb6fe72246141c1a635db431345b17b""}]"",
                releaseDate = ""0001-01-01T00:00:00Z"",
                quizResult = null,
                emailReceiptConsent = null,
                submitLanguage = null,
                msRewardsData = null,
                FormsProData = null
            ]}"
        ]}
    ];
Impl
PQExtensionFormsAPIImpl = (formsUrl as text) =>
    let
        _formId =Text.Replace(PQExtensionFormsAPI.Matches("FormId=[^&]+", formsUrl), "FormId=", ""),
//         _formIdLength = Text.Length(_formId),
        _message = if (_formId = null or Text.Length(_formId) < 80) then List.Generate(() => 1, each _ > 0, each _ - 1, each "URL に ""FormId="" が含まれていませんでした。") else formId2responses(_formId)
    in
        _message as list;

UI の記述内容確認は Power Query Editor で行うと楽

  1. Type, Impl 関数を用意
  2. Value.ReplaceType() を呼び出して確認

参考資料

keyword

how to implement function documents in power query (M query)