レポートの要求とダウンロード

[アーティクル]
11/13/2024

レポートは非同期プロセスです。レポートを要求するための一般的なフローを次に示します。

レポートパラメーターを使用して要求を作成する
レポートサービスに要求を送信する
サービスは要求を処理できるようになるまでキューに入れます
サービスを定期的にポーリングして、レポートジョブの状態を取得する
状態が [成功] の場合は、サービスが提供する URL を使用してレポートをダウンロードします。

.NET 言語、Java、または Python を使用している場合は、 Bing Ads API クライアントライブラリを使用する必要があります。 .NET、Java、Python SDK では、以下で説明する低レベルの詳細が抽象化されています。たとえば、SubmitGenerateReportRequest と PollGenerateReportRequest を呼び出してレポートをダウンロードする代わりに、Reporting Service Managerで 1 つのメソッドを使用できます。

レポートをダウンロードする方法を示すコード例については、「レポート要求のコード例」を参照してください。

レポートを要求する

要求するレポートを決定します。要求できるレポートの一覧については、「レポートの種類」を参照してください。
レポート要求オブジェクトのインスタンスを作成します。レポート要求の一部の要素は必須であり、一部は省略可能です。アプリケーションに適した要素を設定します。レポート要求の要素は、特に、レポートに含めるデータの範囲、レポートに含めるデータの列、およびすべてのデータが使用可能な場合にのみレポートを生成するかどうかを決定します。

注:

ReportRequest データオブジェクトから派生するオブジェクトの 1 つのインスタンスを作成する必要があります。ReportRequest オブジェクトを SubmitGenerateReport 操作に渡そうとすると、呼び出しは失敗します。
SubmitGenerateReportRequest オブジェクトのインスタンスを作成し、ReportRequest 要素を前の手順で選択したレポート要求に設定します。
SubmitGenerateReport 操作を呼び出して要求を送信します。操作は、レポートが作成される前に返される非同期操作です。この操作では、レポートが完了したタイミングを判断するために次の手順で使用する ReportRequestId が返されます。レポート要求識別子は 2 日間有効です。 2 日以内にレポートをダウンロードしない場合は、レポートをもう一度要求する必要があります。
PollGenerateReportRequest オブジェクトのインスタンスを作成し、レポート要求識別子を前の手順で返された識別子に設定します。

注:

SubmitGenerateReport 操作と PollGenerateReport 操作には、同じユーザー資格情報を使用する必要があります。
状態が [保留中] の間に、ループで PollGenerateReport 操作を呼び出します。この操作では、要求が正常に完了したときに状態が [成功 ] に設定されます。 [保留中] または [成功 ] 以外の状態は、レポートが失敗したことを示します。

レポート要求が完了するまでにかかる時間は、要求したレポートの種類など、さまざまな変数によって異なります。指定した集計、スコープ、および期間の値。予想される行数。キューに既に存在する要求の数。これらの変数のため、すべてのケースに適切なポーリング間隔を決定することは困難です。ほとんどのレポートは数分で完了する必要があるため、ほとんどの場合、2 ~ 15 分の間隔でポーリングを行う必要があります。ポーリング期間全体が 60 分を超える場合は、レポート識別子を保存し、ループを終了し、後で再試行することを検討してください。
要求が正常に完了した場合は、 ReportDownloadUrl 要素の URL を使用して、レポートを含むファイルをダウンロードします。ダウンロード URL を取得した後、レポートをダウンロードするには 5 分かかります。 URL を取得してから 5 分以内にレポートをダウンロードしない場合は、レポートのダウンロードに使用する新しい 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

次の方法で共有

レポートの要求とダウンロード

レポートを要求する

カスタム日付範囲を作成する

関連項目

フィードバック

その他のリソース