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

[アーティクル]
05/23/2024

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" events 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)

エンドツーエンドの例