既定のエラーメッセージをオーバーライドする

[アーティクル]
09/17/2023

レポートで Power BI 埋め込み分析の既定のエラーメッセージを非表示にし、代わりにアプリの設計に合ったカスタムエラーメッセージを表示できます。

たとえば、次の既定のエラーダイアログを置き換えることができます。

Power BI 埋め込み分析の既定のエラーダイアログを示すスクリーンショット。

このカスタムエラーダイアログでは、次の操作を行います。

カスタムエラーダイアログを示すスクリーンショット。

エラーをオーバーライドする方法

カスタムエラーメッセージを使用するには、まず、power BI 埋め込み分析構成オブジェクトで hideErrors プロパティを true 設定して、既定の Power BI 埋め込み分析エラーメッセージを非表示にします。この構成には、他の powerbi.embed(element, config) 設定とオプションも含まれます。詳細については、「レポート設定の構成」を参照してください。

let config = {
    type: 'report',
    tokenType: models.TokenType.Embed,
    accessToken: accessToken,
    embedUrl: embedUrl,
    id: embedReportId,
    permissions: permissions,
    settings: {
        hideErrors: true
    }
};

既定のエラーメッセージを非表示にすると、エラーが発生した場合、エラーダイアログとメッセージは表示されなくなります。アプリのユーザーが、エラーが発生したときに一貫した有用な応答を取得するには、エラーイベントを処理する必要があります。

エラーを処理するには、まずイベントをリッスンしてエラーを error 取得します。

report.off("error");
report.on("error", function(event) {
    // Handle errors
});

levelIError インターフェイスのプロパティを使用すると、処理するエラーの種類を指定できます。

interface IError {
    message: string;
    detailedMessage?: string;
    errorCode?: string;
    level?: TraceType;
    technicalDetails?: ITechnicalDetails;
}

enum TraceType {
    Information = 0,
    Verbose = 1,
    Warning = 2,
    Error = 3,
    ExpectedError = 4,
    UnexpectedError = 5,
    Fatal = 6,
}

Fatal エラーは最も重大なエラーの種類です。これは、レポートが応答しなくなるためです。エラーを処理 Fatal して、エンドユーザーがエラーメッセージングなしで応答しないレポートや破損したレポートに直面しないようにします。

例

次のコード例は、イベントをリッスンして処理 error することでエラーをオーバーライドする方法を示しています。この例では、or error.detailedMessage 関数はnewAccessToken表示されません。指定された場所に独自の関数を実装します。

// Embed the loadConfiguration that hides the default errors.
let config = {
    type: 'report',
    tokenType: models.TokenType.Embed,
    accessToken: accessToken,
    embedUrl: embedUrl,
    id: embedReportId,
    permissions: permissions,
    settings: {
        hideErrors: true
    }
};

// Get a reference to the embedded report HTML element.
let embedContainer = $('#embedContainer')[0];

// Embed the report and display it within the div container.
let report = powerbi.embed(embedContainer, config);

// Set report.off to remove any pre-existing error event handler.
report.off("error");

// Set report.on to add the new error event handler.
report.on("error", function(event) {
    const error = event.detail;

    // If the error level isn't Fatal, log the error and continue.
    if (error.level !== models.TraceType.Fatal) {
        console.error(error);
        return;
    }

    // If the Fatal error is TokenExpired, refresh the token.
    if (error.message === models.CommonErrorCode.TokenExpired) {
        // Implement your own function here.
        let newAccessToken = refreshToken();
        
        // Set the new access token.
        report.setAccessToken(newAccessToken);
    } else {
        // If the error isn't TokenExpired, show the custom
        // dialog with detailed error message in the iframe.
        // Implement your own function here.
        showError(error.detailedMessage);
    }
});