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

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

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

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

1. カスタムコネクタを作る場合
    - コネクタ選択後に引数記入してもいいけど、以下のような入力 UI はあった方が便利<br>![2022-01-05_14h31_47.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1645569/da9a08ad-395f-fd53-61f3-cd7c1765b91e.png)
1. Power Query で関数化した際に、使い方とかをちゃんと記録したい場合
    - 以下のように使用例を複数表示出来るので、使えると便利ですね。<br>![2022-01-05_14h36_43.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1645569/0b226d9c-3d28-d6b1-867f-908a6c174b41.png)

# UI 利用定義のまとめ
今回の内容は、[function-docs.md](https://github.com/microsoft/DataConnectors/blob/master/docs/function-docs.md) を読んで、[HelloWorldWithDocs](https://github.com/microsoft/DataConnectors/tree/master/samples/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)| 

### 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
![2022-01-05_15h10_08.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1645569/dafd5ab7-3f5d-9fba-6f90-ae7e71d8a927.png)
### 割付
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120072/757b586e-ed0b-b74d-f479-66738a9c4d73.png)


## 関数の UI

![2022-01-05_14h36_43.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1645569/9772580d-bbe5-c28e-24f3-aeb5a08671f2.png)

## 比較用の実装例
https://github.com/baku2san/PQExtensionFormsAPI

```powershell:IF部分
[DataSource.Kind="PQExtensionFormsAPI", Publish="PQExtensionFormsAPI.Publish"]
shared PQExtensionFormsAPI.Contents = Value.ReplaceType(PQExtensionFormsAPIImpl, PQExtensionFormsAPIType);
```

```powershell: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 = ""responder@hoge.onmicrosoft.com"",
                responderName = ""responderName"",
                answers = ""[{""answer1"":""回答だよ"",""questionId"":""r9fb6fe72246141c1a635db431345b17b""}]"",
                releaseDate = ""0001-01-01T00:00:00Z"",
                quizResult = null,
                emailReceiptConsent = null,
                submitLanguage = null,
                msRewardsData = null,
                FormsProData = null
            ]}"
        ]}
    ];
```

```powershell: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 関数を用意
1. Value.ReplaceType() を呼び出して確認<br>![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120072/9e747a62-864d-b9e3-c12f-ae3012cec1a2.png)

# 参考資料

https://github.com/microsoft/DataConnectors/blob/master/docs/function-docs.md

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