要求和下載報表

發行項
12/21/2023

報表是非同步程式。以下是要求報表的一般流程。

使用報表參數建立要求
將要求傳送至 Reporting Service
服務會將要求排入佇列，直到能夠處理它為止
定期輪詢服務以取得報表作業的狀態
當狀態為 [成功] 時，請使用服務提供的 URL 來下載報表。

如果您使用 .NET 語言、JAVA 或 Python，您應該使用 Bing 廣告 API 用戶端程式庫。 .NET、JAVA 和 Python SDK 會抽象化以下所述的低階詳細資料。例如，您可以使用一個方法搭配報表Service Manager，而不是呼叫SubmitGenerateReportRequest和PollGenerateReportRequest來下載報表。

如需示範如何下載報表的程式碼範例，請參閱報表要求程式碼範例。

要求報表

判斷您想要要求的報表。如需您可以要求的報表清單，請參閱報表類型。
建立報表要求物件的實例。報表要求的某些專案是必要的，有些則是選擇性的。將專案設定為適合您的應用程式。報表要求的元素會決定要包含在報表中的資料範圍、要包含在報表中的資料行，以及是否只有在所有資料都可用時才產生報表。

注意事項

您必須建立其中一個衍生自 ReportRequest 資料物件之物件的實例;如果您嘗試將 ReportRequest 物件傳遞至 SubmitGenerateReport 作業，則呼叫將會失敗。
建立 SubmitGenerateReportRequest 物件的實例，並將 ReportRequest 元素設定為您在上一個步驟中選取的報表要求。
呼叫 SubmitGenerateReport 作業以提交要求。作業是在建立報表之前傳回的非同步作業。此作業會傳回 ReportRequestId ，您會在下列步驟中用來判斷報表何時完成。報表要求識別碼的有效期為兩天。如果您未在兩天內下載報表，則必須再次要求報表。
建立 PollGenerateReportRequest 物件的實例，並將報表要求識別碼設定為上一個步驟中傳回的識別碼。

注意事項

您必須針對 SubmitGenerateReport 和 PollGenerateReport 作業使用相同的使用者認證。
當狀態為Pending時，在迴圈中呼叫PollGenerateReport作業。作業會在要求成功完成時，將狀態設定為 Success ;[ 擱置 ] 或 [ 成功 ] 以外的狀態表示報表失敗。

報表要求完成所需的時間長度取決於一些變數，例如您要求的報表類型;您指定的匯總、範圍和時間週期值;預期的資料列數目;以及已在佇列中的要求數目。由於這些變數，因此很難判斷所有案例的適當輪詢間隔。因為大部分報表都應該在幾分鐘內完成，所以輪詢間隔 2 到 15 分鐘應該適用于大部分的情況。如果整體輪詢期間超過 60 分鐘，請考慮儲存報表識別碼、結束迴圈，稍後再試一次。
如果要求順利完成，請使用 ReportDownloadUrl 元素中的 URL 來下載包含報表的檔案。取得下載 URL 之後，您有五分鐘的時間可以下載報表。如果您未在取得 URL 的五分鐘內下載報表，則必須輪詢以取得用來下載報表的新 URL。
報表檔案已壓縮;因此，您必須將它解壓縮以讀取報表。

建立自訂日期範圍

下列程式示範如何指定報表要求的自訂日期範圍。對於上述的報表要求工作流程而言，這是選擇性的。如果您指定自訂日期範圍，則不得設定 ReportTime.PredefinedTime 元素。另請注意，報表要求物件的 Aggregation 元素會決定如何匯總指定時段的資料。

建立 ReportTime 物件的實例。將ReportTime物件指派給ReportRequest資料物件的Time元素。
建立 Date 物件，指定自訂日期範圍的開始日期。將 Date 物件指派給 ReportTime.CustomDateRangeStart 元素。
建立另一個 Date 物件，指定自訂日期範圍的結束日期。將 Date 物件指派給 ReportTime.CustomDateRangeEnd 元素。

下列程式碼片段示範如何初始化報表要求物件，以要求自訂日期範圍。

// Create an instance of the ReportTime class to hold the report date 
// information.
request.Time = new ReportTime();

// Set the start date for the report to one month before today.
DateTime startDate = DateTime.Today.AddMonths(-1);
request.Time.CustomDateRangeStart = new Date();
request.Time.CustomDateRangeStart.Day = startDate.Day;
request.Time.CustomDateRangeStart.Month = startDate.Month;
request.Time.CustomDateRangeStart.Year = startDate.Year;

// Set the end date to today.
DateTime endDate = DateTime.Today;
request.Time.CustomDateRangeEnd = new Date();
request.Time.CustomDateRangeEnd.Day = endDate.Day;
request.Time.CustomDateRangeEnd.Month = endDate.Month;
request.Time.CustomDateRangeEnd.Year = endDate.Year;

report.setTime(new ReportTime());

Calendar calendar = Calendar.getInstance();
report.getTime().setCustomDateRangeStart(new Date());
report.getTime().getCustomDateRangeStart().setMonth(1);
report.getTime().getCustomDateRangeStart().setDay(1);
report.getTime().getCustomDateRangeStart().setYear(calendar.get(Calendar.YEAR)-1);
report.getTime().setCustomDateRangeEnd(new Date());
report.getTime().getCustomDateRangeEnd().setMonth(12);
report.getTime().getCustomDateRangeEnd().setDay(31);
report.getTime().getCustomDateRangeEnd().setYear(calendar.get(Calendar.YEAR)-1);

$report->Time = new ReportTime();
$report->Time->PredefinedTime = null;

date_default_timezone_set('UTC');
$LastYear = date("Y") - 1;
$report->Time->CustomDateRangeStart = new Date();
$report->Time->CustomDateRangeStart->Month = 1;
$report->Time->CustomDateRangeStart->Day = 1;
$report->Time->CustomDateRangeStart->Year = $LastYear;
$report->Time->CustomDateRangeEnd = new Date();
$report->Time->CustomDateRangeEnd->Month = 12;
$report->Time->CustomDateRangeEnd->Day = 31;
$report->Time->CustomDateRangeEnd->Year = $LastYear;

report_time=reporting_service.factory.create('ReportTime')

custom_date_range_start=reporting_service.factory.create('Date')
custom_date_range_start.Day=1
custom_date_range_start.Month=1
custom_date_range_start.Year=int(strftime("%Y", gmtime()))-1
report_time.CustomDateRangeStart=custom_date_range_start
custom_date_range_end=reporting_service.factory.create('Date')
custom_date_range_end.Day=31
custom_date_range_end.Month=12
custom_date_range_end.Year=int(strftime("%Y", gmtime()))-1
report_time.CustomDateRangeEnd=custom_date_range_end
report_time.PredefinedTime=None

report_request.Time=report_time

另請參閱

Reporting Service 參考

共用方式為

要求和下載報表

要求報表

建立自訂日期範圍

另請參閱

意見反應

其他資源