ページ分割されたレポートをファイルにエクスポートする

[アーティクル]
02/04/2025

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

.pptx (PowerPoint)
.pdf (そしてアクセシビリティ対応 PDF または PDF/UA)
.xlsx (Excel)
.docx (Word)
.csv
.xml
.mhtml
イメージ
イメージにエクスポートする場合は、OutputFormat 形式の設定を使用してイメージ形式を設定します。サポートされている OutputFormat 値は次のとおりです。
- .tiff (既定値)
- .bmp
- .emf
- .gif
- .jpeg
- .png

使用例

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

[印刷に送信] ボタン - アプリケーションで、クリックするとエクスポートジョブをトリガーするボタンを作成します。ジョブは、表示されたレポートを .pdf または .pptxとしてエクスポートできます。完了すると、ユーザーはファイルをダウンロードとして受け取ることができます。レポートパラメーターと書式設定を使用すると、フィルター処理されたデータ、カスタムページサイズ、その他の書式固有の設定など、特定の状態でレポートをエクスポートできます。 API は非同期であるため、ファイルが使用可能になるには時間がかかる場合があります。
電子メールの添付ファイル - 一定の間隔で自動メールを送信し、.pdf レポートを添付します。このシナリオは、役員への週次レポートの送信を自動化する場合に役立ちます。

API の使用

ライセンス要件

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

イベントのレンダリング

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

ポーリング

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

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

サポートされている機能

書式の設定

ファイル形式ごとにさまざまな形式設定を指定します。サポートされているプロパティと値は、ページ分割されたレポート URL パラメーターにおけるデバイス情報パラメーターがに相当します。

2 つの例を次に示します。 1 つ目は、レポートページサイズを使用してレポートの最初の 4 ページを .pptx ファイルにエクスポートすることです。 2 番目の例は、レポートの 3 ページ目を .jpeg ファイルにエクスポートする場合です。

最初の 4 ページを .pptx にエクスポートする

{
      "format": "PPTX",
      "paginatedReportConfiguration":{
            "formatSettings":{
                  "UseReportPageSize": "true",
                  "StartPage": "1",
                  "EndPage": "4"
            }
      }
}

3 番目のページを.jpegにエクスポートする

{
      "format": "IMAGE",
      "paginatedReportConfiguration":{
            "formatSettings":{
                  "OutputFormat": "JPEG",
                  "StartPage": "3",
                  "EndPage": "3"
            }
      }
}

レポートパラメーター

exportToFile API を使用して、一連のレポートパラメーターを含むレポートをプログラムでエクスポートできます。このためには、レポートパラメーター機能を使用します。

レポートパラメーター値を設定する例を次に示します。

{
      "format": "PDF",
      "paginatedReportConfiguration":{
            "parameterValues":[
                  {"name": "State", "value": "WA"},
                  {"name": "City", "value": "Seattle"},
                  {"name": "City", "value": "Bellevue"},
                  {"name": "City", "value": "Redmond"}
            ]
      }
}

認証

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

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

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

RLS を使用してエクスポートするには、レポートがデータソースとして使用している Power BI セマンティックモデルの読み取りアクセス許可が必要です。

RLS の有効なユーザー名を指定する例を次に示します。

{
      "format": "PDF",
      "paginatedReportConfiguration":{
            "identities": [
                  {"username": "john@contoso.com"}
            ]
      }
}

シングルサインオンの SQL と Dataverse (SSO)

Power BI では、SSO で OAuth を設定するオプションがあります。この操作を行うと、レポートを表示するユーザーの資格情報がデータの取得に使用されます。要求ヘッダーのアクセストークンは、データへのアクセスには使用されません。トークンは、POST 本文の有効な ID と共に渡される必要があります。

アクセスするリソースの正しいアクセストークンを取得するのは難しい場合があります。

Azure SQL の場合、リソースは https://database.windows.net。
Dataverse の場合、リソースは環境の https:// アドレスです。たとえば、https://contoso.crm.dynamics.comします。

AuthenticationContext.AcquireTokenAsync メソッドを使用してトークン API にアクセスします。

アクセストークンを使用して有効な ID (ユーザー名) を指定する例を次に示します。

{
       "format":"PDF",
       "paginatedReportConfiguration":{
          "formatSettings":{
             "AccessiblePDF":"true",
             "PageHeight":"11in",
             "PageWidth":"8.5in",
             "MarginBottom":"2in"
          },
          "identities":[
             {
                "username":"john@contoso.com",
                "identityBlob": {
                "value": "eyJ0eX....full access token"
         }
        }
     ]
   }
}

同時リクエスト

exportToFile では、限られた数の同時要求がサポートされます。同時にページ分割されたレポートレンダリング要求の最大数は 500 です。制限を超え、要求が多すぎる (429) エラーが発生しないようにするには、時間の経過と同時に、または容量全体に負荷を分散します。

Premium Per User (PPU) を使用している場合、exportToFile API で 5 分間に許可される要求は 1 つだけです。 5 分以内に複数の要求が発生すると、要求が多すぎます (429) エラーが発生します。

コード例

コード例で使用されている Power BI API SDK は、ここでダウンロードできます。

エクスポートジョブを作成するときは、次の 3 つの手順を実行します。

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

このセクションでは、各手順の例を示します。

手順 1 - エクスポート要求の送信

最初の手順では、エクスポート要求を送信します。この例では、特定のページ範囲、サイズ、およびレポートパラメーター値に対してエクスポート要求が送信されます。

private async Task<string> PostExportRequest(
    Guid reportId,
    Guid groupId)
{
    // For documentation purposes the export configuration is created in this method
    // Ordinarily, it would be created outside and passed in
    var paginatedReportExportConfiguration = new PaginatedReportExportConfiguration()
    {
        FormatSettings = new Dictionary<string, string>()
        {
            {"PageHeight", "14in"},
            {"PageWidth", "8.5in" },
            {"StartPage", "1"},
            {"EndPage", "4"},
        },
        ParameterValues = new List<ParameterValue>()
        {
            { new ParameterValue() {Name = "State", Value = "WA"} },
            { new ParameterValue() {Name = "City", Value = "Redmond"} },
        },
    };

    var exportRequest = new ExportReportRequest
    {
        Format = FileFormat.PDF,
        PaginatedReportExportConfiguration = paginatedReportExportConfiguration,
    };

    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<Export> PollExportRequest(
    Guid reportId,
    Guid groupId,
    string exportId /* Get from the ExportToAsync response */,
    int timeOutInMinutes,
    CancellationToken token)
{
    Export exportStatus = null;
    DateTime startTime = DateTime.UtcNow;
    const int secToMillisec = 1000;
    do
    {
        if (DateTime.UtcNow.Subtract(startTime).TotalMinutes > timeOutInMinutes || token.IsCancellationRequested)
        {
            // Error handling for timeout and cancellations
            return null;
        }

        var httpMessage = 
            await Client.Reports.GetExportToFileStatusInGroupWithHttpMessagesAsync(groupId, reportId, exportId);
            
        exportStatus = httpMessage.Body;
        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 only populated when the status is either Running or NotStarted
            var retryAfter = httpMessage.Response.Headers.RetryAfter;
            var retryAfterInSec = retryAfter.Delta.Value.Seconds;

            await Task.Delay(retryAfterInSec * secToMillisec);
        }
    }
    // While not in a terminal state, keep polling
    while (exportStatus.Status != ExportState.Succeeded && exportStatus.Status != ExportState.Failed);

    return exportStatus;
}

手順 3 - ファイルを取得する

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

private async Task<ExportedFile> GetExportedFile(
    Guid reportId,
    Guid groupId,
    Export export /* Get from the GetExportStatusAsync response */)
{
    if (export.Status == ExportState.Succeeded)
    {
        var httpMessage = 
            await Client.Reports.GetFileOfExportToFileInGroupWithHttpMessagesAsync(groupId, reportId, export.Id);

        return new ExportedFile
        {
            FileStream = httpMessage.Body,
            ReportName = export.ReportName,
            FileExtension = export.ResourceFileExtension,
        };
    }

    return null;
}

public class ExportedFile
{
    public Stream FileStream;
    public string ReportName;
    public string FileExtension;
}

エンドツーエンドの例

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

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

private async Task<ExportedFile> ExportPaginatedReport(
    Guid reportId,
    Guid groupId,
    int pollingtimeOutInMinutes,
    CancellationToken token)
{
    try
    {
        var exportId = await PostExportRequest(reportId, groupId);

        var export = await PollExportRequest(reportId, groupId, exportId, pollingtimeOutInMinutes, token);
        if (export == null || export.Status != ExportState.Succeeded)
        {
           // Error, failure in exporting the report
            return null;
        }

        return await GetExportedFile(reportId, groupId, export);
    }
    catch
    {
        // Error handling
        throw;
    }
}

考慮事項と制限事項

Power BI セマンティックモデルをデータソースとして含むページ分割されたレポートのエクスポートは、次の場合はサポートされません。
- 呼び出し元は、サービスプリンシパルプロファイルです。
- セマンティックモデルのデータソースの 1 つがシングルサインオン (SSO) を有効にして構成され、有効な ID が提供されました。
- Power BI セマンティックモデルには、Azure Analysis Services または別の Power BI セマンティックモデルへの DirectQuery があり、有効な ID が提供されました。
シングルサインオン (SSO) が有効になっている Azure Analysis Services データソースが構成されているページ分割されたレポートのエクスポートは、次の場合はサポートされません。
- 呼び出し元は、サービスプリンシパルプロファイルです。
- 呼び出し元はマスターユーザーであり、有効な ID が提供されました。
ページ分割されたレポートを有効な ID でエクスポートするには、ユーザー名がテナントの Microsoft Entra ID の既存のユーザーである必要があります。
レポートのエクスポートは、ユーザーアクセストークンの有効期間と一致する 60 分に制限されます。大量のデータをエクスポートするときに 60 分を超えてタイムアウトエラーが発生する場合は、適切なフィルターを使用してデータ量を減らすことを検討してください。
Power BI サービスで発行済みのページ分割されたレポートをオンラインでエクスポートする場合、ファイル共有 URL ハイパーリンク (ファイル共有 /UNC パス) は機能しません。

顧客と組織にコンテンツを埋め込む方法を確認します。

次の方法で共有

ページ分割されたレポートをファイルにエクスポートする

使用例

API の使用

ライセンス要件

イベントのレンダリング

ポーリング

サポートされている機能

書式の設定

最初の 4 ページを .pptx にエクスポートする

3 番目のページを.jpegにエクスポートする

レポートパラメーター

認証

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

シングルサインオンの SQL と Dataverse (SSO)

同時リクエスト

コード例

手順 1 - エクスポート要求の送信

手順 2 - ポーリング

手順 3 - ファイルを取得する

エンドツーエンドの例

考慮事項と制限事項

フィードバック

その他のリソース

次の方法で共有

ページ分割されたレポートをファイルにエクスポートする

使用例

API の使用

ライセンス要件

イベントのレンダリング

ポーリング

サポートされている機能

書式の設定

最初の 4 ページを .pptx にエクスポートする

3 番目のページを.jpegにエクスポートする

レポート パラメーター

認証

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

シングル サインオンの SQL と Dataverse (SSO)

同時リクエスト

コード例

手順 1 - エクスポート要求の送信

手順 2 - ポーリング

手順 3 - ファイルを取得する

エンド ツー エンドの例

考慮事項と制限事項

関連コンテンツ

フィードバック

その他のリソース

レポートパラメーター

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

シングルサインオンの SQL と Dataverse (SSO)

エンドツーエンドの例