ページ分割されたレポートをファイルにエクスポートする
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 の容量によってサポートされているワークスペースに存在する必要があります。
exportToFileAPI には、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 パス) は機能しません。
関連するコンテンツ
顧客向けおよび自分の組織向けのコンテンツを埋め込む方法を確認します。
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示