Criar e atualizar relatórios

O serviço de relatórios para a API Campaign Manager 360 permite criar e atualizar relatórios do Criador de relatórios usando objetos de recurso de relatório. Um recurso de relatório descreve as informações básicas sobre um relatório a ser executado, bem como a estrutura de saída do relatório.

Este guia detalha como criar e atualizar relatórios do Criador de relatórios de forma programática por meio do serviço Relatórios.

Observação: criar um relatório válido não é uma tarefa simples. Alguns subconjuntos de dimensões e métricas são válidos somente em combinações específicas. Portanto, recomendamos que você gere relatórios inicialmente com o Criador de relatórios e, em seguida, clone e modifique esses relatórios por meio da API.

Configurar um recurso de relatório

A primeira etapa na criação ou atualização de um relatório no Criador de relatórios é configurar um objeto de recurso de relatório. Se você estiver criando um novo relatório, começará com um recurso vazio e definirá os campos necessários. Se estiver atualizando um relatório existente, você terá as seguintes opções:

1. Preferencial: fazer uma atualização parcial. Usando essa abordagem, você começará com um recurso vazio e definirá os campos que gostaria de alterar. Uma atualização parcial salva apenas as alterações nos campos especificados.
2. Executando uma atualização completa. Com essa abordagem, você carrega um recurso de relatório existente e modifica diretamente os campos dele. Uma atualização completa sempre salva todos os campos do relatório.

O conteúdo exato de um recurso de relatório varia de acordo com o tipo de relatório que você está configurando. Mesmo assim, há alguns campos comuns a todos os tipos de relatório:

Campo	Descrição
Campos obrigatórios
nome	O nome do relatório.
digitar	O tipo de relatório.
Campos opcionais
entrega	Configurações de entrega de e-mails do relatório.
Nome do arquivo	O nome de arquivo usado ao gerar arquivos de relatório.
formato	O formato de saída do relatório, CSV ou Excel.
programação	Uma programação usada para gerar seu relatório regularmente.

Esses campos comuns compõem o esqueleto do seu relatório. O exemplo abaixo ilustra a criação de um novo recurso de relatório padrão:

C#

Report report = new Report();

// Set the required fields "name" and "type".
report.Name = "Example standard report";
report.Type = "STANDARD";

// Set optional fields.
report.FileName = "example_report";
report.Format = "CSV";

Java

Report report = new Report();

// Set the required fields "name" and "type".
report.setName("Example standard report");
report.setType("STANDARD");

// Set optional fields
report.setFileName("example_report");
report.setFormat("CSV");

PHP

$report = new Google_Service_Dfareporting_Report();

// Set the required fields "name" and "type".
$report->setName('Example standard report');
$report->setType('STANDARD');

// Set optional fields.
$report->setFileName('example_report');
$report->setFormat('CSV');

Python

report = {
    # Set the required fields "name" and "type".
    'name': 'Example Standard Report',
    'type': 'STANDARD',
    # Set optional fields.
    'fileName': 'example_report',
    'format': 'CSV'
}

Ruby

report = DfareportingUtils::API_NAMESPACE::Report.new(
  # Set the required fields "name" and "type".
  name: 'Example Standard Report',
  type: 'STANDARD',
  # Set optional fields.
  file_name: 'example_report',
  format: 'CSV'
)

Definir os critérios do relatório

Depois de escolher um tipo de relatório e configurar os campos comuns, a próxima etapa é definir os critérios do relatório. Os critérios de relatório são usados para limitar o escopo do relatório, garantindo que somente informações relevantes sejam retornadas. Ele também define a estrutura de saída do relatório.

Os critérios usados dependem do tipo de relatório. A relação entre o tipo de relatório e os critérios é explicada na tabela a seguir:

Tipo de relatório	Campo de critérios
PADRÃO	critérios
REACH	alcance de critérios
PATH_TO_CONVERSION	pathToConversionCriteria:
Floodlight	floodlightCriteria
CROSS_DIMENSION_REACH (em inglês)	crossDimensionReachCriteria (em inglês)

Embora cada um desses critérios específicos do tipo exponha um conjunto de campos ligeiramente diferente, há um conjunto de campos de critérios comuns geralmente úteis para controlar a saída do relatório:

Campo	Descrição
dateRange	As datas para as quais esse relatório deve ser gerado. Pode ser usado para especificar uma data de início e de término personalizada ou um período relativo. Observação: ao gerar relatórios pela API, os períodos relativos como YESTERDAY serão resolvidos no fuso horário de Los Angeles (EUA). Isso pode causar resultados inesperados para usuários em fusos horários diferentes.
dimensionFilters	Uma lista de filtros que restringem os resultados retornados. Consulte a seção de valores de filtro de consulta para mais informações sobre como configurar filtros.
dimensions	Uma lista de elementos do Campaign Manager 360 a serem incluídos na saída do relatório.
Nomes das métricas	Unidades de medida padrão a serem incluídas na saída do relatório.

Consulte a seção sobre determinação da compatibilidade de campos para mais informações sobre como escolher dimensões, métricas e filtros para seu relatório. Os campos de critérios específicos a cada tipo são explicados na documentação de referência e na Central de Ajuda.

O exemplo abaixo adiciona um critério básico ao nosso recurso de relatório padrão:

C#

// Define a date range to report on. This example uses explicit start and
// end dates to mimic the "LAST_30_DAYS" relative date range.
DateRange dateRange = new DateRange();
dateRange.EndDate = DateTime.Now.ToString("yyyy-MM-dd");
dateRange.StartDate = DateTime.Now.AddDays(-30).ToString("yyyy-MM-dd");

// Create a report criteria.
SortedDimension dimension = new SortedDimension();
dimension.Name = "advertiser";

Report.CriteriaData criteria = new Report.CriteriaData();
criteria.DateRange = dateRange;
criteria.Dimensions = new List<SortedDimension>() { dimension };
criteria.MetricNames = new List<string>() {
  "clicks",
  "impressions"
};

// Add the criteria to the report resource.
report.Criteria = criteria;

Java

// Define a date range to report on. This example uses explicit start and end dates to mimic
// the "LAST_MONTH" relative date range.
DateRange dateRange = new DateRange();
dateRange.setEndDate(new DateTime(true, System.currentTimeMillis(), null));

Calendar lastMonth = Calendar.getInstance();
lastMonth.add(Calendar.MONTH, -1);
dateRange.setStartDate(new DateTime(true, lastMonth.getTimeInMillis(), null));

// Create a report criteria.
Report.Criteria criteria = new Report.Criteria();
criteria.setDateRange(dateRange);
criteria.setDimensions(Lists.newArrayList(new SortedDimension().setName("advertiser")));
criteria.setMetricNames(Lists.newArrayList("clicks", "impressions"));

// Add the criteria to the report resource.
report.setCriteria(criteria);

PHP

// Define a date range to report on. This example uses explicit start and
// end dates to mimic the "LAST_30_DAYS" relative date range.
$dateRange = new Google_Service_Dfareporting_DateRange();
$dateRange->setStartDate(
    date('Y-m-d', mktime(0, 0, 0, date('m'), date('d') - 30, date('Y')))
);
$dateRange->setEndDate(date('Y-m-d'));

// Create a report criteria.
$dimension = new Google_Service_Dfareporting_SortedDimension();
$dimension->setName('advertiser');

$criteria = new Google_Service_Dfareporting_ReportCriteria();
$criteria->setDateRange($dateRange);
$criteria->setDimensions([$dimension]);
$criteria->setMetricNames(['clicks', 'impressions']);

// Add the criteria to the report resource.
$report->setCriteria($criteria);

Python

# Define a date range to report on. This example uses explicit start and end
# dates to mimic the "LAST_30_DAYS" relative date range.
end_date = date.today()
start_date = end_date - timedelta(days=30)

# Create a report criteria.
criteria = {
    'dateRange': {
        'startDate': start_date.strftime('%Y-%m-%d'),
        'endDate': end_date.strftime('%Y-%m-%d')
    },
    'dimensions': [{
        'name': 'advertiser'
    }],
    'metricNames': ['clicks', 'impressions']
}

# Add the criteria to the report resource.
report['criteria'] = criteria

Ruby

# Define a date range to report on. This example uses explicit start and end
# dates to mimic the "LAST_30_DAYS" relative date range.
start_date = DateTime.now.prev_day(30).strftime('%Y-%m-%d')
end_date = DateTime.now.strftime('%Y-%m-%d')

# Create a report criteria
criteria = DfareportingUtils::API_NAMESPACE::Report::Criteria.new(
  date_range: DfareportingUtils::API_NAMESPACE::DateRange.new(
    start_date: start_date,
    end_date: end_date
  ),
  dimensions: [
    DfareportingUtils::API_NAMESPACE::SortedDimension.new(
      name: 'advertiser'
    )
  ],
  metric_names: ['clicks', 'impressions']
)

# Add the criteria to the report resource.
report.criteria = criteria

Valores de filtro de consulta

Ao configurar filtros para um relatório, você precisa especificar os valores exatos que os filtros usarão para restringir a saída do relatório. Se você não tiver certeza sobre quais são os valores possíveis para um filtro específico, procure-os usando o serviço DimensionValues.

Uma consulta básica de valores de dimensão contém um nome de dimensão, uma data de início e uma data de término. As datas de início e término limitam a resposta a valores válidos nesse período. Filtros adicionais podem ser especificados se for necessário limitar os resultados da consulta.

O exemplo abaixo procura valores de filtro de anunciante válidos nas datas em que o relatório será gerado e os adiciona aos critérios do relatório:

C#

// Query advertiser dimension values for report run dates.
DimensionValueRequest request = new DimensionValueRequest();
request.StartDate = report.Criteria.DateRange.StartDate;
request.EndDate = report.Criteria.DateRange.EndDate;
request.DimensionName = "advertiser";

DimensionValueList values =
    service.DimensionValues.Query(request, profileId).Execute();

if (values.Items.Any()) {
  // Add a value as a filter to the report criteria.
  report.Criteria.DimensionFilters = new List<DimensionValue>() {
    values.Items[0]
  };
}

Java

// Query advertiser dimension values for report run dates.
DimensionValueRequest request = new DimensionValueRequest();
request.setStartDate(report.getCriteria().getDateRange().getStartDate());
request.setEndDate(report.getCriteria().getDateRange().getEndDate());
request.setDimensionName("advertiser");

DimensionValueList values = reporting.dimensionValues().query(profileId, request).execute();

if (!values.getItems().isEmpty()) {
  // Add a value as a filter to the report criteria.
  List<DimensionValue> filters = Lists.newArrayList(values.getItems().get(0));
  report.getCriteria().setDimensionFilters(filters);
}

PHP

// Query advertiser dimension values for report run dates.
$request = new Google_Service_Dfareporting_DimensionValueRequest();
$request->setStartDate(
    $report->getCriteria()->getDateRange()->getStartDate()
);
$request->setEndDate(
    $report->getCriteria()->getDateRange()->getEndDate()
);
$request->setDimensionName('advertiser');

$values =
    $this->service->dimensionValues->query($userProfileId, $request);

if (!empty($values->getItems())) {
    // Add a value as a filter to the report criteria.
    $report->getCriteria()->setDimensionFilters([$values->getItems()[0]]);
}

Python

# Query advertiser dimension values for report run dates.
request = {
    'dimensionName': 'advertiser',
    'endDate': report['criteria']['dateRange']['endDate'],
    'startDate': report['criteria']['dateRange']['startDate']
}

values = service.dimensionValues().query(
    profileId=profile_id, body=request).execute()

if values['items']:
  # Add a value as a filter to the report criteria.
  report['criteria']['dimensionFilters'] = [values['items'][0]]

Ruby

# Query advertiser dimension values for report run dates.
dimension = DfareportingUtils::API_NAMESPACE::DimensionValueRequest.new(
  dimension_name: 'advertiser',
  start_date: report.criteria.date_range.start_date,
  end_date: report.criteria.date_range.end_date
)

values = service.query_dimension_value(profile_id, dimension)

unless values.items.empty?
  # Add a value as a filter to the report criteria.
  report.criteria.dimension_filters = [values.items.first]
end

Determinar a compatibilidade de campos

Ao configurar seus critérios de relatório, é importante lembrar que nem todas as combinações de métricas, dimensões e filtros são válidas. Você não poderá salvar um relatório que contenha uma combinação inválida. Desse modo, é importante garantir que os campos que você planeja usar são compatíveis entre si.

À medida que você cria seu recurso de relatório, é possível transmiti-lo ao serviço Reports.compatibleFields para ver quais campos são válidos levando em conta os que já foram selecionados. A configuração do relatório será analisada, e uma resposta contendo as dimensões, métricas e filtros compatíveis será retornada. Como nem todos os campos dessa resposta são compatíveis, talvez seja necessário fazer várias solicitações para garantir que todos os campos escolhidos funcionem juntos.

O exemplo abaixo ilustra como fazer uma solicitação de amostra de campos compatíveis usando nosso recurso de relatório como entrada:

C#

CompatibleFields fields =
    service.Reports.CompatibleFields.Query(report, profileId).Execute();

ReportCompatibleFields reportFields = fields.ReportCompatibleFields;

if(reportFields.Dimensions.Any()) {
  // Add a compatible dimension to the report.
  Dimension dimension = reportFields.Dimensions[0];
  SortedDimension sortedDimension = new SortedDimension();
  sortedDimension.Name = dimension.Name;
  report.Criteria.Dimensions.Add(sortedDimension);
} else if (reportFields.Metrics.Any()) {
  // Add a compatible metric to the report.
  Metric metric = reportFields.Metrics[0];
  report.Criteria.MetricNames.Add(metric.Name);
}

Java

CompatibleFields fields = reporting.reports().compatibleFields()
    .query(profileId, report).execute();

ReportCompatibleFields reportFields = fields.getReportCompatibleFields();

if (!reportFields.getDimensions().isEmpty()) {
  // Add a compatible dimension to the report.
  Dimension dimension = reportFields.getDimensions().get(0);
  SortedDimension sortedDimension = new SortedDimension().setName(dimension.getName());
  report.getCriteria().getDimensions().add(sortedDimension);
} else if (!reportFields.getMetrics().isEmpty()) {
  // Add a compatible metric to the report.
  Metric metric = reportFields.getMetrics().get(0);
  report.getCriteria().getMetricNames().add(metric.getName());
}

PHP

$fields = $this->service->reports_compatibleFields->query(
    $userProfileId,
    $report
);

$reportFields = $fields->getReportCompatibleFields();

if (!empty($reportFields->getDimensions())) {
    // Add a compatible dimension to the report.
    $dimension = $reportFields->getDimensions()[0];
    $sortedDimension = new Google_Service_Dfareporting_SortedDimension();
    $sortedDimension->setName($dimension->getName());
    $report->getCriteria()->setDimensions(
        array_merge(
            $report->getCriteria()->getDimensions(),
            [$sortedDimension]
        )
    );
} elseif (!empty($reportFields->getMetrics())) {
    // Add a compatible metric to the report.
    $metric = $reportFields->getMetrics()[0];
    $report->getCriteria()->setMetricNames(
        array_merge(
            $report->getCriteria()->getMetricNames(),
            [$metric->getName()]
        )
    );
}

Python

fields = service.reports().compatibleFields().query(
    profileId=profile_id, body=report).execute()

report_fields = fields['reportCompatibleFields']

if report_fields['dimensions']:
  # Add a compatible dimension to the report.
  report['criteria']['dimensions'].append({
      'name': report_fields['dimensions'][0]['name']
  })
elif report_fields['metrics']:
  # Add a compatible metric to the report.
  report['criteria']['metricNames'].append(
      report_fields['metrics'][0]['name'])

Ruby

fields = service.query_report_compatible_field(profile_id, report)

report_fields = fields.report_compatible_fields

if report_fields.dimensions.any?
  # Add a compatible dimension to the report.
  report.criteria.dimensions <<
    DfareportingUtils::API_NAMESPACE::SortedDimension.new(
      name: report_fields.dimensions.first.name
    )
elsif report_fields.metrics.any?
  # Add a compatible metric to the report.
  report.criteria.metric_names << report_fields.metrics.first.name
end

Salvar o relatório

A etapa final do processo é salvar o recurso do relatório. Se você estiver criando um novo relatório, poderá inseri-lo com uma chamada para Reports.insert:

C#

Report insertedReport =
    service.Reports.Insert(report, profileId).Execute();

Java

Report insertedReport = reporting.reports().insert(profileId, report).execute();

PHP

$insertedReport =
    $this->service->reports->insert($userProfileId, $report);

Python

inserted_report = service.reports().insert(
    profileId=profile_id, body=report).execute()

Ruby

report = service.insert_report(profile_id, report)

Se você estiver executando uma atualização parcial, será possível salvar suas alterações chamando Reports.patch:

C#

// Patch an existing report.
Report patchedReport =
    service.Reports.Patch(report, profileId, reportId).Execute();

Java

// Patch an existing report.
Report patchedReport = reporting.reports().patch(profileId, reportId, report).execute();

PHP

# Patch an existing report.
$patchedReport =
    $this->service->reports->patch($userProfileId, $reportId, $report)

Python

# Patch an existing report.
patched_report = service.reports().patch(
    profileId=profile_id, reportId=report_id, body=report).execute();

Ruby

# Patch an existing report.
patched_report = service.patch_report(profile_id, report_id, report)

Se você decidiu realizar uma atualização completa, salve as alterações chamando Reports.update:

C#

// Update an existing report.
Report updatedReport =
    service.Reports.Update(report, profileId, report.Id).Execute();

Java

// Update an existing report.
Report updatedReport = reporting.reports().update(profileId, report.getId(), report).execute();

PHP

# Update an existing report.
$updatedReport =
    $this->service->reports->update($userProfileId, $report->getId(), $report)

Python

# Update an existing report.
updated_report = service.reports().update(
    profileId=profile_id, reportId=report['id'], body=report).execute();

Ruby

# Update an existing report.
updated_report = service.update_report(profile_id, report.id, report);

Após uma solicitação de salvamento bem-sucedida, uma cópia do recurso de relatório será retornada no corpo da resposta. Esse recurso terá alguns campos novos preenchidos, o mais importante é o id field. Esse ID é o que você usará para se referir a esse relatório no restante do seu fluxo de trabalho.