Pedir e Transferir um Relatório
Os relatórios são um processo assíncrono. Segue-se o fluxo geral para pedir um relatório.
- Criar um pedido com os parâmetros do relatório
- Enviar um pedido para o serviço de relatórios
- O serviço coloca o pedido em fila até conseguir processá-lo
- Consultar periodicamente o serviço para obter o estado da tarefa de relatório
- Quando o estado for Êxito, utilize o URL que o serviço fornece para transferir o relatório.
Se estiver a utilizar uma linguagem .NET, Java ou Python, deve utilizar as Bibliotecas de Cliente da API de Anúncios do Bing. Os SDKs .NET, Java e Python abstraem os detalhes de baixo nível descritos abaixo. Por exemplo, em vez de chamar SubmitGenerateReportRequest e PollGenerateReportRequest para transferir um relatório, pode utilizar um método com a Service Manager Relatórios.
Para obter exemplos de código que demonstram como transferir relatórios, veja Exemplo de Código de Pedidos de Relatório.
Pedir um Relatório
Determine o relatório que pretende pedir. Para obter uma lista dos relatórios que pode pedir, veja Tipos de Relatório.
Crie uma instância do objeto de pedido de relatório. Alguns dos elementos do pedido de relatório são necessários e alguns são opcionais. Defina os elementos conforme adequado para a sua aplicação. Os elementos do pedido de relatório determinam, entre outros, o âmbito dos dados a incluir no relatório, as colunas de dados a incluir no relatório e se pretende gerar o relatório apenas se todos os dados estiverem disponíveis.
Nota
Tem de criar uma instância de um dos objetos que deriva do objeto de dados ReportRequest ; Se tentar transmitir o objeto ReportRequest para a operação SubmitGenerateReport , a chamada falhará.
Crie uma instância do objeto SubmitGenerateReportRequest e defina o elemento ReportRequest para o pedido de relatório que selecionou no passo anterior.
Chame a operação SubmitGenerateReport para submeter o pedido. A operação é uma operação assíncrona que é devolvida antes de o relatório ser criado. A operação devolve um ReportRequestId que utiliza nos passos seguintes para determinar quando o relatório é concluído. O identificador do pedido de relatório é válido durante dois dias. Se não transferir o relatório no prazo de dois dias, terá de pedir o relatório novamente.
Crie uma instância do objeto PollGenerateReportRequest e defina o identificador do pedido de relatório para o identificador devolvido no passo anterior.
Nota
Tem de utilizar as mesmas credenciais de utilizador para as operações SubmitGenerateReport e PollGenerateReport .
Chame a operação PollGenerateReport num ciclo enquanto o estado estiver Pendente. A operação define o estado como Êxito quando o pedido for concluído com êxito; um estado diferente de Pendente ou Êxito indica que o relatório falhou.
O período de tempo que um pedido de relatório demora a concluir depende de várias variáveis, como o tipo de relatório que pediu; os valores de agregação, âmbito e período de tempo que especificou; o número de linhas esperadas; e o número de pedidos já existentes na fila. Devido a estas variáveis, é difícil determinar um intervalo de consulta adequado para todos os casos. Uma vez que a maioria dos relatórios deve ser concluída em minutos, a consulta com intervalos de dois a 15 minutos deve ser adequada para a maioria dos casos. Se o período de consulta global exceder os 60 minutos, considere guardar o identificador do relatório, sair do ciclo e tentar novamente mais tarde.
Se o pedido for concluído com êxito, utilize o URL no elemento ReportDownloadUrl para transferir o ficheiro que contém o relatório. Depois de obter o URL de transferência, tem cinco minutos para transferir o relatório. Se não transferir o relatório no prazo de cinco minutos após obter o URL, tem de consultar um novo URL para utilizar para transferir o relatório.
O ficheiro de relatório é comprimido; por conseguinte, tem de deszipar para ler o relatório.
Criar um Intervalo de Datas Personalizado
O procedimento seguinte mostra como especificar um intervalo de datas personalizado para um pedido de relatório. Isto é opcional para o fluxo de trabalho do pedido de relatório descrito acima. Se especificar um intervalo de datas personalizado, não pode definir o elemento ReportTime.PredefinedTime . Tenha também em atenção que o elemento Agregação do objeto de pedido de relatório determina como os dados do período de tempo especificado são agregados.
Crie uma instância do objeto ReportTime . Atribua o objeto ReportTime ao elemento Time do objeto de dados ReportRequest .
Crie um objeto Data que especifique a data de início do intervalo de datas personalizado. Atribua o objeto Date ao elemento ReportTime.CustomDateRangeStart .
Crie outro objeto Data que especifique a data de fim do intervalo de datas personalizado. Atribua o objeto Date ao elemento ReportTime.CustomDateRangeEnd .
O fragmento de código seguinte mostra como inicializar um objeto de pedido de relatório para pedir um intervalo de datas personalizado.
// 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