関数ドキュメントの追加

Power Query では、関数の引数に基づいて、自動的に呼び出し UI が生成されます。 既定では、この UI には関数の名前と、各パラメーターに対する入力が含められます。

同様に、パラメーターを指定せずに関数の名前を評価すると、その関数についての情報が表示されます。

多くの場合、組み込みの関数では、説明、ツールヒント、およびサンプル値を使用して、より優れたユーザー エクスペリエンスが提供されます。 関数の型に特定のメタ値を定義すれば、これと同じメカニズムを利用することができます。 このトピックでは、Power Query によって使用されるメタ フィールドと、それらを拡張機能で使用する方法について説明します。

関数型

カスタム型の値を定義することで、関数のドキュメントを提供できます。 プロセスは次のようになります。

1. 各パラメーターの型を定義します。
2. 関数の型を定義します。
3. 型メタデータ レコードに、さまざまな Documentation.* フィールドを追加します。
4. Value.ReplaceType 値を呼び出して、型を共有関数に置き換えます。

型とメタデータ値の詳細については、M 言語仕様に関する記事を参照してください。

この方法を使用すると、関数の説明と表示名、および個々のパラメーターを指定できます。 また、パラメーターのサンプル値を指定したり、値のプリセット リストを定義する (既定のテキスト ボックス コントロールをドロップダウンに変える) こともできます。

Power Query では、関数の型に対するメタ値からドキュメントが取得されます (Value.Type、Type.FunctionParameters、および Value.Metadata への呼び出しが組み合わせて使用されます)。

関数ドキュメント

次の表は、関数のメタデータに対して設定できるドキュメント フィールドを示したものです。 すべてのフィールドは省略可能です。

フィールド	Type	詳細
Documentation.Examples	list	レコード オブジェクトの一覧と関数の使用例。 関数情報の一部としてのみ表示されます。 各レコードには、オプションのテキスト フィールド (Description、Code、Result) が含まれている必要があります。
Documentation.LongDescription	text	関数の機能についての詳細な説明。関数情報に表示されます。
Documentation.Name	text	関数呼び出しダイアログの上部に表示されるテキスト。

パラメーター ドキュメント

次の表は、関数パラメーターのメタデータに対して設定できるドキュメント フィールドを示したものです。 すべてのフィールドは省略可能です。

フィールド	Type	詳細
Documentation.AllowedValues	list	このパラメーターに対する有効な値の一覧。 このフィールドを指定すると、入力がテキスト ボックスからドロップダウン リストに変更されます。 なお、これを指定しても、ユーザーがクエリを手動で編集して、別の値を指定できなくなるわけではありません。
Documentation.FieldCaption	text	パラメーターに使用する表示名。
Documentation.FieldDescription	text	表示名の横に表示する説明。
Documentation.SampleValues	list	テキスト ボックス内に (薄い色のテキストとして) 表示されるサンプル値の一覧。
Formatting.IsMultiLine	boolean	複数行の入力を作成できます (ネイティブ クエリに貼り付ける場合など)。
Formatting.IsCode	boolean	コードの入力フィールドの書式を設定します。通常は複数行の入力で使用します。 標準フォントではなく、コード用のフォントを使用してください。

基本的な例

次のコード スニペット (および結果のダイアログ) は、HelloWorldWithDocs サンプルから抜粋したものです。

[DataSource.Kind="HelloWorldWithDocs", Publish="HelloWorldWithDocs.Publish"]
shared HelloWorldWithDocs.Contents = Value.ReplaceType(HelloWorldImpl, HelloWorldType);

HelloWorldType = type function (
    message as (type text meta [
        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""}})"
        ]}
    ];

HelloWorldImpl = (message as text, optional count as number) as table =>
    let
        _count = if (count <> null) then count else 5,
        listOfMessages = List.Repeat({message}, _count),
        table = Table.FromList(listOfMessages, Splitter.SplitByNothing())
    in
        table;

このコードを実行すると、Power BI に次のダイアログが表示されます。

関数の呼び出し

関数情報

複数行の例

[DataSource.Kind="HelloWorld", Publish="HelloWorld.Publish"]
shared HelloWorld.Contents =
    let
        HelloWorldType = type function (
            message1 as (type text meta [
                Documentation.FieldCaption = "Message 1",
                Documentation.FieldDescription = "Text to display for message 1",
                Documentation.SampleValues = {"Hello world"},
                Formatting.IsMultiLine = true,
                Formatting.IsCode = true
            ]),
            message2 as (type text meta [
                Documentation.FieldCaption = "Message 2",
                Documentation.FieldDescription = "Text to display for message 2",
                Documentation.SampleValues = {"Hola mundo"},
                Formatting.IsMultiLine = true,
                Formatting.IsCode = false
            ])) as text,
        HelloWorldFunction = (message1 as text, message2 as text) as text => message1 & message2
    in
        Value.ReplaceType(HelloWorldFunction, HelloWorldType);

このコード (関連する公開情報などを含む) により、Power BI で次のダイアログが表示されます。 改行は、テキストでは "# (lf)" または "line feed" で表現されます。