Power Query では、関数の引数に基づいて呼び出し UI が自動的に生成されます。 既定では、この UI には関数の名前と、各パラメーターの入力が含まれます。
同様に、パラメーターを指定せずに関数の名前を評価すると、それに関する情報が表示されます。
通常、組み込み関数は、説明、ヒント、さらにはサンプル値を使用して、より優れたユーザー エクスペリエンスを提供します。 関数の型に特定のメタ値を定義することで、この同じメカニズムを利用できます。 このトピックでは、Power Query で使用されるメタ フィールドと、それらを拡張機能で使用する方法について説明します。
関数型
カスタム 型 の値を定義することで、関数のドキュメントを提供できます。 プロセスは次のようになります。
- 各パラメーターの型を定義します。
- 関数の型を定義します。
- さまざまな
Documentation.*フィールドを型メタデータ レコードに追加します。 - Value.ReplaceType を呼び出して、型を共有関数に登録します。
型とメタデータ値の詳細については、 M 言語仕様を参照してください。
この方法を使用すると、関数の説明と表示名、および個々のパラメーターを指定できます。 パラメーターのサンプル値を指定したり、値のプリセット リストを定義したりすることもできます (既定のテキスト ボックス コントロールをドロップダウンに変換します)。
Power Query エクスペリエンスでは、 Value.Type、 Type.FunctionParameters、および Value.Metadata の呼び出しを組み合わせて使用して、関数の型のメタ値からドキュメントを取得します。
関数のドキュメント
次の表に、 関数のメタデータで設定できるドキュメント フィールドの一覧を示します。 すべてのフィールドは省略可能です。
| フィールド | タイプ | 詳細 |
|---|---|---|
| ドキュメンテーションの例 | list | 関数の使用例を含むレコード オブジェクトの一覧。 関数情報の一部としてのみ表示されます。 各レコードには、省略可能なテキスト フィールド ( Description、 Code、および Result) が含まれている必要があります。 |
| ドキュメント.詳細説明 | SMS 送信 | 関数の機能の完全な説明。関数情報に表示されます。 |
| ドキュメント名 | SMS 送信 | 関数呼び出しダイアログの上部に表示するテキスト。 |
パラメーターのドキュメント
次の表に、 関数パラメーターのメタデータで設定できるドキュメント フィールドの一覧を示します。 すべてのフィールドは省略可能です。
| フィールド | タイプ | 詳細 |
|---|---|---|
| Documentation.AllowedValues | list | このパラメーターの有効な値の一覧。 このフィールドを指定すると、入力がテキスト ボックスからドロップダウン リストに変更されます。 これにより、ユーザーがクエリを手動で編集して代替値を指定できなくなることはありません。 |
| ドキュメント.フィールドキャプション | SMS 送信 | パラメーターに使用するフレンドリ表示名。 |
| ドキュメント.フィールド説明 | SMS 送信 | 表示名の横に表示する説明。 |
| ドキュメント.サンプル値 | list | テキスト ボックス内に表示するサンプル値の一覧 (フェード されたテキストとして)。 |
| Formatting.IsMultiLine | ブーリアン | ネイティブ クエリに貼り付けるなど、複数行の入力を作成できます。 |
| Formatting.IsCode | ブーリアン | コードの入力フィールドを書式設定します。一般的には、複数行の入力を使用します。 標準フォントではなく、コードに似たフォントを使用します。 |
基本的な例
次のコード スニペット (および結果のダイアログ) は 、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)" または "ラインフィード" として表されます。
