Richiedere e scaricare un report
La creazione di report è un processo asincrono. Di seguito è riportato il flusso generale per la richiesta di un report.
- Creare una richiesta con i parametri del report
- Inviare una richiesta al servizio di report
- Il servizio accoda la richiesta fino a quando non è in grado di elaborarla
- Eseguire periodicamente il polling del servizio per ottenere lo stato del processo del report
- Quando lo stato è Operazione riuscita, usare l'URL fornito dal servizio per scaricare il report.
Se si usa un linguaggio .NET, Java o Python, è consigliabile usare le librerie client dell'API Bing Ads. Gli SDK .NET, Java e Python astraggono i dettagli di basso livello descritti di seguito. Ad esempio, invece di chiamare SubmitGenerateReportRequest e PollGenerateReportRequest per scaricare un report, è possibile usare un metodo con l'Service Manager Reporting.
Per esempi di codice che illustrano come scaricare i report, vedere Esempio di codice richieste di report.
Richiedere un report
Determinare il report da richiedere. Per un elenco dei report che è possibile richiedere, vedere Tipi di report.
Creare un'istanza dell'oggetto richiesta del report. Alcuni degli elementi della richiesta di report sono obbligatori e altri facoltativi. Impostare gli elementi in base alle esigenze dell'applicazione. Gli elementi della richiesta di report determinano, tra gli altri, l'ambito dei dati da includere nel report, le colonne di dati da includere nel report e se generare il report solo se tutti i dati sono disponibili.
Nota
È necessario creare un'istanza di uno degli oggetti che deriva dall'oggetto dati ReportRequest . se si tenta di passare l'oggetto ReportRequest all'operazione SubmitGenerateReport , la chiamata avrà esito negativo.
Creare un'istanza dell'oggetto SubmitGenerateReportRequest e impostare l'elemento ReportRequest sulla richiesta di report selezionata nel passaggio precedente.
Chiamare l'operazione SubmitGenerateReport per inviare la richiesta. L'operazione è un'operazione asincrona che viene restituita prima della creazione del report. L'operazione restituisce un ReportRequestId usato nei passaggi seguenti per determinare quando il report viene completato. L'identificatore della richiesta di report è valido per due giorni. Se il report non viene scaricato entro due giorni, è necessario richiederlo nuovamente.
Creare un'istanza dell'oggetto PollGenerateReportRequest e impostare l'identificatore della richiesta di report sull'identificatore restituito nel passaggio precedente.
Nota
È necessario usare le stesse credenziali utente per le operazioni SubmitGenerateReport e PollGenerateReport .
Chiamare l'operazione PollGenerateReport in un ciclo mentre lo stato è In sospeso. L'operazione imposta lo stato su Operazione completata quando la richiesta viene completata correttamente. uno stato diverso da In sospeso o Operazione riuscita indica che il report non è riuscito.
Il tempo necessario per il completamento di una richiesta di report dipende da diverse variabili, ad esempio il tipo di report richiesto. i valori di aggregazione, ambito e periodo di tempo specificati; il numero di righe previste; e il numero di richieste già presenti nella coda. A causa di queste variabili, è difficile determinare un intervallo di polling appropriato per tutti i casi. Poiché la maggior parte dei report deve essere completata entro pochi minuti, il polling a intervalli da due a 15 minuti deve essere appropriato per la maggior parte dei casi. Se il periodo di polling complessivo supera i 60 minuti, provare a salvare l'identificatore del report, uscire dal ciclo e riprovare più tardi.
Se la richiesta viene completata correttamente, usare l'URL nell'elemento ReportDownloadUrl per scaricare il file che contiene il report. Dopo aver ottenuto l'URL di download, sono disponibili cinque minuti per scaricare il report. Se non si scarica il report entro cinque minuti dal recupero dell'URL, è necessario eseguire il polling di un nuovo URL da usare per scaricare il report.
Il file di report è compresso; pertanto, è necessario decomprimerlo per leggere il report.
Creare un intervallo di date personalizzato
La procedura seguente illustra come specificare un intervallo di date personalizzato per una richiesta di report. Questa opzione è facoltativa per il flusso di lavoro delle richieste di report descritto in precedenza. Se si specifica un intervallo di date personalizzato, non è necessario impostare l'elemento ReportTime.PredefinedTime . Si noti inoltre che l'elemento Aggregation dell'oggetto richiesta del report determina la modalità di aggregazione dei dati per il periodo di tempo specificato.
Creare un'istanza dell'oggetto ReportTime . Assegnare l'oggetto ReportTime all'elemento Time dell'oggetto dati ReportRequest .
Creare un oggetto Date che specifica la data di inizio dell'intervallo di date personalizzato. Assegnare l'oggetto Date all'elemento ReportTime.CustomDateRangeStart .
Creare un altro oggetto Date che specifica la data di fine dell'intervallo di date personalizzato. Assegnare l'oggetto Date all'elemento ReportTime.CustomDateRangeEnd .
Il frammento di codice seguente illustra come inizializzare un oggetto richiesta di report per richiedere un intervallo di date personalizzato.
// 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