TripPin パート 8 - 診断の追加

注

このコンテンツは現在、Visual Studio の診断用の従来の実装のコンテンツを参照しています。コンテンツは近い将来更新され、Visual Studio Code の新しい Power Query SDK に対応する予定です。

このマルチパートチュートリアルでは、Power Query 用の新しいデータソース拡張機能の作成について説明します。このチュートリアルは順番に行う予定です。各レッスンは、前のレッスンで作成したコネクタに基づいて構築され、コネクタに新しい機能を段階的に追加します。

このレッスンでは、次の操作を行います。

Diagnostics.Trace 関数について説明します
診断ヘルパー関数を使用して、コネクタのデバッグに役立つトレース情報を追加する

診断の有効化

Power Query ユーザーは 、[オプション] | の下にあるチェックボックスをオンにすることで、トレースログを有効にすることができます。診断。

[診断] タブが選択され、トレースが有効になっている Power Query オプションのスクリーンショット。

有効にすると、後続のクエリによって、M エンジンは固定ユーザーディレクトリにあるログファイルにトレース情報を出力します。

Power Query SDK 内から M クエリを実行すると、プロジェクトレベルでトレースが有効になります。プロジェクトのプロパティページには、トレースに関連する 3 つの設定があります。

ログのクリア: trueに設定すると、クエリの実行時にログがリセットまたはクリアされます。この設定は true のままにしておくことをお勧めします。
エンジントレースの表示: この設定は、M エンジンからの組み込みトレースの出力を制御します。これらのトレースは Power Query チームのメンバーにのみ役立つため、通常は、このセットを falseのままにします。
ユーザートレースの表示: この設定は、コネクタによって出力されるトレース情報を制御します。この設定を trueに設定します。

有効にすると、[M クエリ出力] ウィンドウの [ログ] タブにログエントリが表示されます。

Diagnostics.Trace

Diagnostics.Trace 関数は、M エンジンのトレースログにメッセージを書き込むのに使用されます。

Diagnostics.Trace = (traceLevel as number, message as text, value as any, optional delayed as nullable logical as any) => ...

Important

M は、遅延評価を含む関数型言語です。 Diagnostics.Traceを使用する場合は、式が実際に評価される部分である場合にのみ関数が呼び出されることに注意してください。この動作の例については、このチュートリアルの後半で説明します。

traceLevel パラメーターには、次のいずれかの値を指定できます (降順)。

TraceLevel.Critical
TraceLevel.Error
TraceLevel.Warning
TraceLevel.Information
TraceLevel.Verbose

トレースが有効になっている場合、ユーザーは表示するメッセージの最大レベルを選択できます。このレベル以下のすべてのトレースメッセージがログに出力されます。たとえば、ユーザーが "警告" レベルを選択した場合、 TraceLevel.Warning、 TraceLevel.Error、および TraceLevel.Critical のトレースメッセージがログに表示されます。

message パラメーターは、トレースファイルへの実際のテキスト出力です。テキストに明示的に含めない限り、 value パラメーターはテキストに含まれません。

value パラメーターは、関数から返される値です。 delayed パラメーターが true に設定されている場合、valueは評価中の実際の値を返すゼロパラメーター関数です。 delayedが false に設定されている場合、valueは実際の値です。この動作の例は、遅延評価で確認できます。

TripPin コネクタでの Diagnostics.Trace の使用

Diagnostics.Trace の実際の使用例と、delayed パラメーターの影響については、TripPin コネクタのGetSchemaForEntity関数を更新して、error例外をラップします。

GetSchemaForEntity = (entity as text) as type =>
    try
        SchemaTable{[Entity=entity]}[Type]
    otherwise
        let
            message = Text.Format("Couldn't find entity: '#{0}'", {entity})
        in
            Diagnostics.Trace(TraceLevel.Error, message, () => error message, true);

無効なエンティティ名を GetEntity 関数に渡すことで、(テスト目的で) 評価中にエラーを強制できます。ここでは、withData関数のTripPinNavTable行を変更し、[Name]を"DoesNotExist"に置き換えます。

TripPinNavTable = (url as text) as table =>
    let
        // Use our schema table as the source of top level items in the navigation tree
        entities = Table.SelectColumns(SchemaTable, {"Entity"}),
        rename = Table.RenameColumns(entities, {{"Entity", "Name"}}),
        // Add Data as a calculated column
        withData = Table.AddColumn(rename, "Data", each GetEntity(url, "DoesNotExist"), type table),
        // Add ItemKind and ItemName as fixed text values
        withItemKind = Table.AddColumn(withData, "ItemKind", each "Table", type text),
        withItemName = Table.AddColumn(withItemKind, "ItemName", each "Table", type text),
        // Indicate that the node should not be expandable
        withIsLeaf = Table.AddColumn(withItemName, "IsLeaf", each true, type logical),
        // Generate the nav table
        navTable = Table.ToNavigationTable(withIsLeaf, {"Name"}, "Name", "Data", "ItemKind", "ItemName", "IsLeaf")
    in
        navTable;

プロジェクトのトレースを有効にして、テストクエリを実行します。 [ Errors ] タブに、発生したエラーのテキストが表示されます。

存在しないエラーが表示された M クエリ出力のスクリーンショット。

また、[ Log ] タブにも同じメッセージが表示されます。 messageパラメーターとvalue パラメーターに異なる値を使用する場合、これらの値は異なります。

ログメッセージが強調された M クエリ出力のログタグのスクリーンショット。

また、ログメッセージの Action フィールドには、拡張機能の名前 (データソースの種類) が含まれていることに注意してください (この場合、 Engine/Extension/TripPin)。このフィールドを使用すると、関連する複数のクエリやシステム (マッシュアップエンジン) トレースが有効になっている場合に、拡張機能に関連するメッセージを簡単に見つけることができます。

遅延評価

delayed パラメーターの動作の例として、いくつかの変更を加え、クエリをもう一度実行する必要があります。

最初に、 delayed 値を false に設定しますが、 value パラメーターは as-isのままにします。

Diagnostics.Trace(TraceLevel.Error, message, () => error message, false);

クエリを実行すると、発生した実際のエラーではなく、"関数型の値を型型に変換できません" というエラーが表示されます。この違いは、呼び出しが値自体ではなく、 function 値を返すようになったためです。

次に、 value パラメーターから関数を削除します。

Diagnostics.Trace(TraceLevel.Error, message, error message, false);

クエリを実行すると、正しいエラーが表示されますが、[ ログ ] タブを確認すると、メッセージはありません。この不一致は、error呼び出し中に、Diagnostics.Traceが最終的に持ち上げられ/評価されるため、メッセージが実際に出力されないことが原因です。

delayed パラメーターの影響を理解したら、続行する前にコネクタを動作状態にリセットしてください。

Diagnostics.pqm の診断ヘルパー関数

このプロジェクトに含まれる Diagnostics.pqm ファイルには、トレースを容易にする多くのヘルパー関数が含まれています。前のチュートリアルで示したように、このファイルをプロジェクトに含め (ビルドアクションをコンパイルに設定することを忘れないでください)、コネクタファイルに読み込むことができます。コネクタファイルの下部は、次のコードスニペットのようになります。このモジュールで提供されるさまざまな関数を自由に調べることができますが、このサンプルでは、 Diagnostics.LogValue 関数と Diagnostics.LogFailure 関数のみを使用します。

// Diagnostics module contains multiple functions. We can take the ones we need.
Diagnostics = Extension.LoadFunction("Diagnostics.pqm");
Diagnostics.LogValue = Diagnostics[LogValue];
Diagnostics.LogFailure = Diagnostics[LogFailure];

Diagnostics.LogValue

Diagnostics.LogValue関数はDiagnostics.Traceに似ていますが、評価対象の値を出力するために使用できます。

Diagnostics.LogValue = (prefix as text, value as any) as any => ...

prefix パラメーターは、ログメッセージの前に付加されます。このパラメーターを使用して、メッセージを出力する呼び出しを確認します。 value パラメーターは、関数が返すものであり、M 値のテキスト表現としてトレースにも書き込まれます。たとえば、 value が列 A と B の table と等しい場合、ログには同等の #table 表現が含まれます。 #table({"A", "B"}, {{"row1 A", "row1 B"}, {"row2 A", row2 B"}})

注

M 値をテキストにシリアル化すると、コストのかかる操作になる可能性があります。トレースに出力する値の潜在的なサイズに注意してください。

注

ほとんどの Power Query 環境では、トレースメッセージが所定の長さに短縮されます。

たとえば、 TripPin.Feed 関数を更新して、関数に渡された url 引数と schema 引数をトレースします。

TripPin.Feed = (url as text, optional schema as type) as table =>
    let
        _url = Diagnostics.LogValue("Accessing url", url),
        _schema = Diagnostics.LogValue("Schema type", schema),
        //result = GetAllPagesByNextLink(url, schema)
        result = GetAllPagesByNextLink(_url, _schema)
    in
        result;

_urlの呼び出しで新しい_schemaとGetAllPagesByNextLink値を使用する必要があります。元の関数パラメーターを使用した場合、 Diagnostics.LogValue 呼び出しは実際には評価されないので、トレースに書き込まれるメッセージはありません。 関数型プログラミングは楽しいです!

クエリを実行すると、ログに新しいメッセージが表示されます。

URL へのアクセス:

アクセス URL メッセージを示す M クエリ出力のスクリーンショット。

スキーマの種類:

スキーマの種類のメッセージを示す M クエリ出力のスクリーンショット。

シリアル化されたバージョンの schema パラメーター type が表示されます。これは、型値に対して単純な Text.FromValue を行うときに得られる処理ではなく、(結果として "type" になります)。

Diagnostics.LogFailure（診断.ログ失敗）

Diagnostics.LogFailure関数は、関数呼び出しをラップするために使用でき、関数呼び出しが失敗した場合 (つまり、errorを返す) 場合にのみトレースに書き込みます。

Diagnostics.LogFailure = (text as text, function as function) as any => ...

内部的には、Diagnostics.LogFailureはtry呼び出しにfunction演算子を追加します。呼び出しが失敗した場合、元のtextを返す前に、error値がトレースに書き込まれます。 function呼び出しが成功すると、トレースに何も書き込まずに結果が返されます。 M エラーには完全なスタックトレースが含まれていないため (通常はエラーのメッセージのみが表示されます)、この関数はエラーが発生した場所を特定する場合に役立ちます。

(不適切な) 例として、withData関数のTripPinNavTable行を変更して、もう一度エラーを強制します。

withData = Table.AddColumn(rename, "Data", each Diagnostics.LogFailure("Error in GetEntity", () => GetEntity(url, "DoesNotExist")), type table),

トレースには、 textと元のエラー情報を含む結果のエラーメッセージが表示されます。

ログエラーメッセージを示す M クエリ出力のスクリーンショット。

次のチュートリアルに進む前に、関数を動作状態にリセットしてください。

Conclusion

この簡単な (ただし重要な) レッスンでは、診断ヘルパー関数を使用して Power Query トレースファイルにログを記録する方法について説明しました。これらの関数を適切に使用すると、コネクタ内の問題のデバッグに役立ちます。

注

コネクタ開発者は、診断ログの一部として機密性の高い情報や個人を特定できる情報 (PII) をログに記録しないようにする必要があります。また、パフォーマンスに悪影響を及ぼす可能性があるため、あまり多くのトレース情報を出力しないように注意する必要があります。

次のステップ

TripPin パート 9 - TestConnection

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-11-26