Anfordern und Herunterladen eines Berichts
Die Berichterstellung ist ein asynchroner Prozess. Es folgt der allgemeine Ablauf zum Anfordern eines Berichts.
- Erstellen einer Anforderung mit den Berichtsparametern
- Senden einer Anforderung an den Berichterstellungsdienst
- Der Dienst stellt die Anforderung in die Warteschlange, bis er sie verarbeiten kann.
- Rufen Sie den Dienst in regelmäßigen Abständen ab, um die status des Berichtsauftrags zu erhalten.
- Wenn der status auf Success festgelegt ist, verwenden Sie die URL, die der Dienst bereitstellt, um den Bericht herunterzuladen.
Wenn Sie eine .NET-Sprache, Java oder Python verwenden, sollten Sie die Clientbibliotheken der Bing Ads-API verwenden. Die .NET-, Java- und Python-SDKs abstrahen die unten beschriebenen Details auf niedriger Ebene. Anstatt beispielsweise SubmitGenerateReportRequest und PollGenerateReportRequest zum Herunterladen eines Berichts aufzurufen, können Sie eine Methode mit dem Reporting Service Manager verwenden.
Codebeispiele, die das Herunterladen von Berichten veranschaulichen, finden Sie unter Codebeispiel für Berichtsanforderungen.
Anfordern eines Berichts
Bestimmen Sie den Bericht, den Sie anfordern möchten. Eine Liste der Berichte, die Sie anfordern können, finden Sie unter Berichtstypen.
Erstellen Sie eine instance des Berichtsanforderungsobjekts. Einige der Elemente der Berichtsanforderung sind erforderlich, andere sind optional. Legen Sie die Elemente entsprechend Ihrer Anwendung fest. Die Elemente der Berichtsanforderung bestimmen unter anderem den Datenbereich, der in den Bericht aufgenommen werden soll, die Spalten der Daten, die in den Bericht eingeschlossen werden sollen, und ob der Bericht nur generiert werden soll, wenn alle Daten verfügbar sind.
Hinweis
Sie müssen eine instance eines der Objekte erstellen, die vom ReportRequest-Datenobjekt abgeleitet sind. Wenn Sie versuchen, das ReportRequest-Objekt an den SubmitGenerateReport-Vorgang zu übergeben, schlägt der Aufruf fehl.
Erstellen Sie eine instance des SubmitGenerateReportRequest-Objekts, und legen Sie das ReportRequest-Element auf die Berichtsanforderung fest, die Sie im vorherigen Schritt ausgewählt haben.
Rufen Sie den SubmitGenerateReport-Vorgang auf, um die Anforderung zu übermitteln. Der Vorgang ist ein asynchroner Vorgang, der zurückgibt, bevor der Bericht erstellt wird. Der Vorgang gibt eine ReportRequestId zurück, die Sie in den folgenden Schritten verwenden, um zu bestimmen, wann der Bericht abgeschlossen ist. Der Berichtsanforderungsbezeichner ist zwei Tage lang gültig. Wenn Sie den Bericht nicht innerhalb von zwei Tagen herunterladen, müssen Sie den Bericht erneut anfordern.
Erstellen Sie eine instance des PollGenerateReportRequest-Objekts, und legen Sie den Berichtsanforderungsbezeichner auf den im vorherigen Schritt zurückgegebenen Bezeichner fest.
Hinweis
Sie müssen die gleichen Benutzeranmeldeinformationen für die Vorgänge SubmitGenerateReport und PollGenerateReport verwenden.
Rufen Sie den PollGenerateReport-Vorgang in einer Schleife auf, während die status ausstehend ist. Der Vorgang legt die status auf Erfolg fest, wenn die Anforderung erfolgreich abgeschlossen wurde. Ein anderer status als Ausstehend oder Erfolg gibt an, dass der Bericht fehlgeschlagen ist.
Die Dauer, für die eine Berichtsanforderung benötigt wird, hängt von einer Reihe von Variablen ab, z. B. vom Typ des angeforderten Berichts; die von Ihnen angegebenen Aggregations-, Bereichs- und Zeitraumwerte; die Anzahl der erwarteten Zeilen; und die Anzahl der Anforderungen, die sich bereits in der Warteschlange befinden. Aufgrund dieser Variablen ist es schwierig, ein geeignetes Abrufintervall für alle Fälle zu bestimmen. Da die meisten Berichte innerhalb von Minuten abgeschlossen werden sollten, sollte die Abfrage in Intervallen von zwei bis 15 Minuten für die meisten Fälle geeignet sein. Wenn der gesamte Abrufzeitraum 60 Minuten überschreitet, sollten Sie den Berichtsbezeichner speichern, die Schleife beenden und es später erneut versuchen.
Wenn die Anforderung erfolgreich abgeschlossen wurde, verwenden Sie die URL im ReportDownloadUrl-Element , um die Datei herunterzuladen, die den Bericht enthält. Nachdem Sie die Download-URL erhalten haben, haben Sie fünf Minuten Zeit, um den Bericht herunterzuladen. Wenn Sie den Bericht nicht innerhalb von fünf Minuten nach dem Abrufen der URL herunterladen, müssen Sie eine neue URL abfragen, die zum Herunterladen des Berichts verwendet werden soll.
Die Berichtsdatei ist komprimiert. Daher müssen Sie es entzippen, um den Bericht zu lesen.
Erstellen eines benutzerdefinierten Datumsbereichs
Das folgende Verfahren zeigt, wie Sie einen benutzerdefinierten Datumsbereich für eine Berichtsanforderung angeben. Dies ist für den oben beschriebenen Berichtsanforderungsworkflow optional. Wenn Sie einen benutzerdefinierten Datumsbereich angeben, dürfen Sie das ReportTime.PredefinedTime-Element nicht festlegen. Beachten Sie außerdem, dass das Aggregation-Element des Berichtsanforderungsobjekts bestimmt, wie die Daten für den angegebenen Zeitraum aggregiert werden.
Erstellen Sie eine instance des ReportTime-Objekts. Weisen Sie das ReportTime-Objekt dem Time-Element des ReportRequest-Datenobjekts zu.
Erstellen Sie ein Date-Objekt , das das Startdatum des benutzerdefinierten Datumsbereichs angibt. Weisen Sie das Date-Objekt dem ReportTime.CustomDateRangeStart-Element zu.
Erstellen Sie ein weiteres Date-Objekt , das das Enddatum des benutzerdefinierten Datumsbereichs angibt. Weisen Sie das Date-Objekt dem ReportTime.CustomDateRangeEnd-Element zu.
Der folgende Codeausschnitt zeigt, wie Sie ein Berichtsanforderungsobjekt initialisieren, um einen benutzerdefinierten Datumsbereich anzufordern.
// 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