Power BI レポートをファイルにエクスポートする

[アーティクル]
12/19/2023

exportToFile API を使用すると、REST の呼び出しを使用して Power BI レポートをエクスポートできます。次のファイル形式がサポートされています。

.pptx (PowerPoint)
.pdf
.png
- .png にエクスポートすると、複数ページのレポートは .zip ファイルに圧縮されます
- .zip 内の各ファイルは、レポートのページを表します
- ページ名は、ページ取得 API またはグループ内のページ取得 API の戻り値と同じです

Note

exportToFile API を使用した Power BI レポートのファイルへのエクスポートは、Premium Per User (PPU) ではサポートされていません。

使用例

エクスポート機能は、さまざまな方法で使用できます。いくつかの例を次に示します。

印刷に送信ボタン - アプリケーションで、クリックされたらエクスポートジョブをトリガーするボタンを作成します。ジョブは .pdf または .pptx として閲覧済みのレポートをエクスポートできます。完了すると、ユーザーはファイルをダウンロードとして受け取ることができます。ブックマークを使用すると、構成済みのフィルター、スライサー、その他の設定などを含めた特定の状態で、レポートをエクスポートできます。 API は非同期であるため、ファイルが使用可能になるまでに時間がかかることがあります。
メールの添付ファイル - .pdf レポートを添付して、設定された間隔で自動的にメールを送信します。このシナリオは、週単位のレポートを役員に自動的に送信する場合に便利です。詳細については、「Power Automate を使用して、Power BI レポートをエクスポートし、電子メールで送信する」を参照してください

API を使用する

ライセンス要件

エクスポートするレポートは、Premium、Embedded、または Fabric の容量によってサポートされているワークスペースに存在する必要があります。
exportToFile API は、Premium Per User (PPU) では "サポートされていません"。

管理者の設定

API を使用する前に、次の管理者テナント設定が有効になっていることを確認します。

[PowerPoint プレゼンテーションまたは PDF ドキュメントとしてレポートをエクスポート] - 既定で有効になります。
[画像ファイルとしてレポートをエクスポート] - .png の場合にのみ必要で、既定では無効になります。

イベントの "レンダリング"

ビジュアルのレンダリングが完了する前にエクスポートが開始されないようにするには、"Rendering" events API を使用し、レンダリングが完了したときにのみエクスポートを開始します。

ポーリング

API は非同期です。 exportToFile API を呼び出すと、エクスポートジョブがトリガーされます。エクスポートジョブをトリガーした後は、ポーリングを使用して、ジョブが完了するまで追跡します。

ポーリングの間、API からは完了した作業量を表す数値が返されます。各エクスポートジョブの作業は、ジョブ内のエクスポートの合計に基づいて計算されます。 1 つのエクスポートには、1 つのビジュアル、またはブックマークありまたはなしのページのエクスポートが含まれます。すべてのエクスポートに同じ重みが設定されます。たとえば、エクスポートジョブに 10 ページのレポートのエクスポートが含まれていて、ポーリングから 70 が返された場合は、API によりエクスポートジョブで 10 ページのうち 7 ページが処理されたことを意味します。

エクスポートが完了すると、ポーリング API の呼び出しから、ファイルを取得するための Power BI URL が返されます。その URL は 24 時間有効です。

サポートされている機能

このセクションでは、サポートされている次の機能の使用方法について説明します。

印刷するページの選択
ページまたは 1 つのビジュアルのエクスポート
Bookmarks
フィルター
認証
行レベルセキュリティ (RLS)
データ保護
ローカリゼーション
動的バインディング

印刷するページの選択

ページ取得またはグループ内のページ取得の戻り値に従って、印刷するページを指定します。エクスポートするページの順序を指定することもできます。

ページまたは 1 つのビジュアルのエクスポート

エクスポートするページまたは 1 つのビジュアルを指定できます。ページは、ブックマークがある状態でもない状態でもエクスポートできます。

エクスポートの種類に応じて、異なる属性を ExportReportPage オブジェクトに渡す必要があります。次の表では、各エクスポートジョブに必要な属性を示します。

Note

1 つのビジュアルのエクスポートの場合、ページ (ブックマークありまたはなし) のエクスポートと同じ重みがあります。つまり、システムの計算においては、両方の操作で同じ値が使用されます。

属性	ページ	説明
`bookmark`	オプション	特定の状態のページをエクスポートするために使用します
`pageName`		GetPages REST API または `getPages` クライアント API を使用します。
`visualName`		ビジュアルの名前を取得するには、2 つの方法があります。 `getVisuals` クライアント API を使用する。ビジュアルが選択されたときにトリガーされる visualClicked イベントをリッスンしてログに記録する。詳細については、「イベントの処理方法」を参照してください。 .

ブックマーク

ブックマークを使用すると、適用されているフィルターやレポートの視覚エフェクトの状態など、特定の構成のレポートを保存できます。 exportToFile API を使用して、次の 2 つの方法でレポートのブックマークをプログラムでエクスポートできます。

既存のブックマークをエクスポートする

既存のレポートブックマークをエクスポートするには、Bookmarks JavaScript API を使用して取得できる一意の (大文字と小文字が区別される) 識別子である name プロパティを使用します。
レポートの状態をエクスポートする

レポートの現在の状態をエクスポートするには、state プロパティを使用します。たとえば、ブックマークの bookmarksManager.capture メソッドを使用すると、特定のユーザーがレポートに対して行った変更をキャプチャし、capturedBookmark.state を使用して現在の状態でそれをエクスポートできます。

注意

個人用ブックマークと永続的フィルターはサポートされていません。

フィルター

PowerBIReportExportConfiguration の reportLevelFilters を使用すると、フィルター処理された条件でレポートをエクスポートできます。

フィルター処理されたレポートをエクスポートするには、フィルターとして使用する URL クエリ文字列パラメーターを、ExportFilter に挿入します。文字列を入力する場合は、URL クエリパラメーターの ?filter= 部分を削除する必要があります。

この表には、ExportFilter に渡すことができる文字列の構文の例が含まれます。

Assert	構文	例
フィールド内の値	<テーブル>/<フィールド> eq '<値>'	Store/Territory eq 'NC'
フィールド内の複数の値	<テーブル>/<フィールド> in ('<値 1>', '<値 2>')	Store/Territory in ('NC', 'TN')
あるフィールド内の個別の値と、別のフィールド内の異なる個別の値	<テーブル>/<フィールド 1> eq '<値 1>' and <テーブル>/<フィールド 2> eq '<値 2>'	Store/Territory eq 'NC' and Store/Chain eq 'Fashions Direct'

認証

ユーザー (またはマスターユーザー) またはサービスプリンシパルを使用して認証できます。

行レベルセキュリティ (RLS)

行レベルセキュリティ (RLS) では、特定のユーザーのみが見ることのできるデータが表示されるレポートをエクスポートできます。たとえば、リージョンのロールで定義されている売上レポートをエクスポートする場合は、特定のリージョンのみが表示されるように、プログラムでレポートをフィルター処理できます。

RLS を使用してエクスポートするには、次のアクセス許可を持っている必要があります。

レポートが接続されているセマンティックモデルに対する書き込みと再共有のアクセス許可
レポートが存在するワークスペースのワークスペースメンバーまたは管理者

データ保護

.pdf と .pptx 形式では、機密ラベルがサポートされています。秘密度ラベルが設定されたレポートを .pdf または .pptx にエクスポートすると、エクスポートされたファイルでは、レポートとその機密ラベルが表示されます。

機密ラベルが設定されたレポートは、サービスプリンシパルを使用して .pdf または .pptx にエクスポートすることはできません。

ローカライズ

exportToFile API を使用すると、目的のロケールを渡すことができます。ローカライズの設定は、選択したローカルに応じた書式設定の変更など、レポートの表示方法に影響します。

動的バインディング

既定のセマンティックモデル以外のセマンティックモデルに接続された状態のレポートをエクスポートするには、API を呼び出すときに、必要なデータセット ID を datasetToBind パラメーターに指定します。動的バインディングの詳細については、こちらを参照してください。

同時要求数

exportToFile API でサポートされている同時実行要求の数には制限があります。サポートされている同時実行要求の最大数は、容量あたり 500 です。制限を超えて、"要求が多すぎます (429)" のエラーが発生するのを回避するには、時間をかけて負荷を分散するか、容量の負荷を分散してください。同時に処理されるレポートのページ数は、5 ページだけです。たとえば、50 ページを含むレポートをエクスポートする場合、エクスポートジョブは 10 個の連続した間隔で処理されます。エクスポートジョブを最適化する場合は、いくつかのジョブを並行して実行することをお勧めします。

コード例

エクスポートジョブを作成するときは、次の 4 つのステップに従って行います。

エクスポート要求の送信。
ポーリング。
ファイルの取得。
ファイルストリームの使用。

ここでは、各ステップの例を示します。

ステップ 1 - エクスポート要求を送信する

最初のステップでは、エクスポート要求を送信します。この例では、特定のページに対するエクスポート要求が送信されます。

private async Task<string> PostExportRequest(
    Guid reportId,
    Guid groupId,
    FileFormat format,
    IList<string> pageNames = null, /* Get the page names from the GetPages REST API */
    string urlFilter = null)
{
    var powerBIReportExportConfiguration = new PowerBIReportExportConfiguration
    {
        Settings = new ExportReportSettings
        {
            Locale = "en-us",
        },
        // Note that page names differ from the page display names
        // To get the page names use the GetPages REST API
        Pages = pageNames?.Select(pn => new ExportReportPage(Name = pn)).ToList(),
        // ReportLevelFilters collection needs to be instantiated explicitly
        ReportLevelFilters = !string.IsNullOrEmpty(urlFilter) ? new List<ExportFilter>() { new ExportFilter(urlFilter) } : null,

    };

    var exportRequest = new ExportReportRequest
    {
        Format = format,
        PowerBIReportConfiguration = powerBIReportExportConfiguration,
    };

    // The 'Client' object is an instance of the Power BI .NET SDK
    var export = await Client.Reports.ExportToFileInGroupAsync(groupId, reportId, exportRequest);

    // Save the export ID, you'll need it for polling and getting the exported file
    return export.Id;
}

ステップ 2 - ポーリングを行う

エクスポート要求を送信した後、ポーリングを使用して、待機しているエクスポートファイルの準備ができたことを確認します。

private async Task<HttpOperationResponse<Export>> PollExportRequest(
    Guid reportId,
    Guid groupId,
    string exportId /* Get from the PostExportRequest response */,
    int timeOutInMinutes,
    CancellationToken token)
{
    HttpOperationResponse<Export> httpMessage = null;
    Export exportStatus = null;
    DateTime startTime = DateTime.UtcNow;
    const int c_secToMillisec = 1000;
    do
    {
        if (DateTime.UtcNow.Subtract(startTime).TotalMinutes > timeOutInMinutes || token.IsCancellationRequested)
        {
            // Error handling for timeout and cancellations 
            return null;
        }

        // The 'Client' object is an instance of the Power BI .NET SDK
        httpMessage = await Client.Reports.GetExportToFileStatusInGroupWithHttpMessagesAsync(groupId, reportId, exportId);
        exportStatus = httpMessage.Body;

        // You can track the export progress using the PercentComplete that's part of the response
        SomeTextBox.Text = string.Format("{0} (Percent Complete : {1}%)", exportStatus.Status.ToString(), exportStatus.PercentComplete);
        if (exportStatus.Status == ExportState.Running || exportStatus.Status == ExportState.NotStarted)
        {
            // The recommended waiting time between polling requests can be found in the RetryAfter header
            // Note that this header is not always populated
            var retryAfter = httpMessage.Response.Headers.RetryAfter;
            var retryAfterInSec = retryAfter.Delta.Value.Seconds;
            await Task.Delay(retryAfterInSec * c_secToMillisec);
        }
    }
    // While not in a terminal state, keep polling
    while (exportStatus.Status != ExportState.Succeeded && exportStatus.Status != ExportState.Failed);

    return httpMessage;
}

ステップ 3 - ファイルを取得する

ポーリングから URL が返されたら、次の例を使用して受信したファイルを取得します。

private async Task<ExportedFile> GetExportedFile(
    Guid reportId,
    Guid groupId,
    Export export /* Get from the PollExportRequest response */)
{
    if (export.Status == ExportState.Succeeded)
    {
        // The 'Client' object is an instance of the Power BI .NET SDK
        var fileStream = await Client.Reports.GetFileOfExportToFileAsync(groupId, reportId, export.Id);
        return new ExportedFile
        {
            FileStream = fileStream,
            FileSuffix = export.ResourceFileExtension,
        };
    }
    return null;
}

public class ExportedFile
{
    public Stream FileStream;
    public string FileSuffix;
}

ステップ 4 - ファイルストリームの使用

ファイルストリームがある場合は、ご自身のニーズに最も合った方法で処理できます。たとえば、メールで送信したり、エクスポートされたレポートをダウンロードするために使用したりできます。

エンドツーエンドの例

これは、レポートのエクスポートに関するエンドツーエンドの例です。この例には次のステージが含まれます。

エクスポート要求の送信。
ポーリング。
ファイルの取得。

private async Task<ExportedFile> ExportPowerBIReport(
	Guid reportId,
	Guid groupId,
	FileFormat format,
	int pollingtimeOutInMinutes,
	CancellationToken token,
	IList<string> pageNames = null,  /* Get the page names from the GetPages REST API */
    string urlFilter = null)
{
	const int c_maxNumberOfRetries = 3; /* Can be set to any desired number */
	const int c_secToMillisec = 1000;
	try
	{
		Export export = null;
		int retryAttempt = 1;
		do
		{
			var exportId = await PostExportRequest(reportId, groupId, format, pageNames, urlFilter);
			var httpMessage = await PollExportRequest(reportId, groupId, exportId, pollingtimeOutInMinutes, token);
			export = httpMessage.Body;
			if (export == null)
			{
				// Error, failure in exporting the report
				return null;
			}
			if (export.Status == ExportState.Failed)
			{
				// Some failure cases indicate that the system is currently busy. The entire export operation can be retried after a certain delay
				// In such cases the recommended waiting time before retrying the entire export operation can be found in the RetryAfter header
				var retryAfter = httpMessage.Response.Headers.RetryAfter;
				if(retryAfter == null)
				{
				    // Failed state with no RetryAfter header indicates that the export failed permanently
				    return null;
                }

                var retryAfterInSec = retryAfter.Delta.Value.Seconds;
                await Task.Delay(retryAfterInSec * c_secToMillisec);
            }
        }
        while (export.Status != ExportState.Succeeded && retryAttempt++ < c_maxNumberOfRetries);

        if (export.Status != ExportState.Succeeded)
        {
            // Error, failure in exporting the report
            return null;
        }

        var exportedFile = await GetExportedFile(reportId, groupId, export);

        // Now you have the exported file stream ready to be used according to your specific needs
        // For example, saving the file can be done as follows:
        /*
            var pathOnDisk = @"C:\temp\" + export.ReportName + exportedFile.FileSuffix;

            using (var fileStream = File.Create(pathOnDisk))
            {
                exportedFile.FileStream.CopyTo(fileStream);
            }
        */

        return exportedFile;
    }
    catch
    {
        // Error handling
        throw;
    }
}

考慮事項と制限事項

エクスポート API 操作の負荷は、「Premium の容量負荷の評価」で説明されているように、実行速度の遅いバックグラウンド操作として評価されます。
エクスポートするレポート内の関連セマンティックモデルは、直接クエリ接続が設定されたセマンティックモデルも含め、すべて Premium または Embedded 容量に存在する必要があります。
エクスポートされたレポートのファイルサイズは 250 MB を超えてはなりません。
.png にエクスポートする場合、秘密度ラベルはサポートされません。
エクスポートされた 1 つのレポートに含めることができるエクスポートの数 (1 つの視覚化またはレポートページ) は、50 個です (改ページ対応レポートのエクスポートは含まれません)。要求に含まれるエクスポートがそれより多い場合、API はエラーを返し、エクスポートジョブは取り消されます。
Power BI レポートをファイルにエクスポートする場合、個人用ブックマークと固定フィルターはサポートされていません。
ブックマークまたはレポートレベルフィルターなしで exportToFile API を使用すると、レポートは既定値でエクスポートされます。
ここで示す Power BI のビジュアルはサポートされていません。これらのビジュアルを含むレポートをエクスポートすると、これらのビジュアルが含まれるレポートの部分はレンダリングされず、エラー記号が表示されます。
- 認定されていない Power BI カスタムビジュアル
- R ビジュアル
- PowerApps
- Python のビジュアル
- Power Automate
- 改ページ対応レポートの視覚化
- Visio
- ArcGIS ビジュアル

顧客向けおよび自分の組織向けのコンテンツを埋め込む方法を確認します。

他にわからないことがある場合は、 Power BI コミュニティを利用してください

Power BI レポートをファイルにエクスポートする

使用例

API を使用する

ライセンス要件

管理者の設定

イベントの "レンダリング"

ポーリング

サポートされている機能

印刷するページの選択

ページまたは 1 つのビジュアルのエクスポート

ブックマーク

フィルター

認証

行レベルセキュリティ (RLS)

データ保護

ローカライズ

動的バインディング

同時要求数

コード例

ステップ 1 - エクスポート要求を送信する

ステップ 2 - ポーリングを行う

ステップ 3 - ファイルを取得する

ステップ 4 - ファイルストリームの使用

エンドツーエンドの例

考慮事項と制限事項

フィードバック

フィードバック

その他のリソース

Power BI レポートをファイルにエクスポートする

使用例

API を使用する

ライセンス要件

管理者の設定

イベントの "レンダリング"

ポーリング

サポートされている機能

印刷するページの選択

ページまたは 1 つのビジュアルのエクスポート

ブックマーク

フィルター

認証

行レベル セキュリティ (RLS)

データ保護

ローカライズ

動的バインディング

同時要求数

コード例

ステップ 1 - エクスポート要求を送信する

ステップ 2 - ポーリングを行う

ステップ 3 - ファイルを取得する

ステップ 4 - ファイル ストリームの使用

エンド ツー エンドの例

考慮事項と制限事項

関連するコンテンツ

フィードバック

フィードバック

その他のリソース

行レベルセキュリティ (RLS)

ステップ 4 - ファイルストリームの使用

エンドツーエンドの例