Criar e atualizar relatórios

O serviço de relatórios da API DCM/DFA Reporting and Trafficking 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, além da estrutura de saída do relatório.

Este guia detalha como criar e atualizar relatórios do Criador de relatórios programaticamente por meio do serviço de relatórios.

Configurar um recurso de relatório

A primeira etapa na criação ou atualização de um relatório do 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, poderá escolher entre os seguintes:

  1. Preferencial: fazer uma atualização parcial. Com essa abordagem, você começará com um recurso vazio e definirá os campos que deseja alterar. Uma atualização parcial só salva alterações nos campos especificados.
  2. Execução de uma atualização completa. Com essa abordagem, você carregará um recurso de relatório existente e modificará seus campos diretamente. 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:

CampoDescrição
Campos obrigatórios
nameO nome do relatório.
typeO tipo do relatório.
Campos opcionais
deliveryAs configurações de entrega de relatórios por e-mail.
fileNameO nome de arquivo usado ao gerar os arquivos de relatório.
formatO formato de saída do relatório, CSV ou Excel.
scheduleUma programação usada para executar seu relatório regularmente.

Esses campos comuns constituem o esqueleto do 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, o próximo passo é definir os critérios de relatório. Os critérios de relatório são usados para limitar o escopo do seu relatório, garantindo que somente as informações relevantes sejam retornadas. Eles também definem 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
STANDARD criteria
REACH reachCriteria
PATH_TO_CONVERSION pathToConversionCriteria
FLOODLIGHT floodlightCriteria
CROSS_DIMENSION_REACH crossDimensionReachCriteria

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

Campo Descrição
dateRange São as datas em que o relatório precisa ser gerado. Use isso para especificar datas de início e de término personalizadas ou um período relativo.
dimensionFilters É uma lista de filtros que restringe os resultados retornados. Consulte a seção valores de filtro de consulta para mais informações sobre como configurar filtros.
dimensions Uma lista de elementos do Campaign Manager a serem incluídos na saída do relatório.
metricNames São unidades de medida padrão a serem incluídas na saída do relatório.

Consulte a seção sobre como determinar a compatibilidade de campos para saber mais sobre como escolher dimensões, métricas e filtros para o relatório. Os outros campos de critério específicos dos tipos 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 = "dfa:advertiser";

Report.CriteriaData criteria = new Report.CriteriaData();
criteria.DateRange = dateRange;
criteria.Dimensions = new List<SortedDimension>() { dimension };
criteria.MetricNames = new List<string>() {
  "dfa:clicks",
  "dfa: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("dfa:advertiser")));
criteria.setMetricNames(Lists.newArrayList("dfa:clicks", "dfa: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('dfa:advertiser');

$criteria = new Google_Service_Dfareporting_ReportCriteria();
$criteria->setDateRange($dateRange);
$criteria->setDimensions([$dimension]);
$criteria->setMetricNames(['dfa:clicks', 'dfa: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': 'dfa:advertiser'
    }],
    'metricNames': ['dfa:clicks', 'dfa: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: 'dfa:advertiser'
    )
  ],
  metric_names: ['dfa:clicks', 'dfa:impressions']
)

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

Valores do filtro de consulta

Ao configurar filtros para um relatório, é necessário 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 determinado filtro, 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 de término limitam a resposta a valores válidos dentro desse período. Filtros adicionais poderão ser especificados se for necessário limitar ainda mais os resultados da consulta.

O exemplo abaixo pesquisa valores válidos de filtro de anunciante 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 = "dfa: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("dfa: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('dfa: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': 'dfa: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: 'dfa: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 dos 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 terá permissão para salvar um relatório que contenha uma combinação inválida. Por isso, é 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 considerando os que já foram selecionados. A configuração do relatório será analisada e uma resposta contendo as dimensões, as métricas e os filtros compatíveis será retornada. Como não é garantido que todos os campos dessa resposta sejam compatíveis uns com os outros, pode ser necessário fazer várias solicitações para ter certeza de 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 desse processo é salvar o recurso de relatório. Ao criar um novo relatório, não é possível 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)

Ao fazer uma atualização parcial, você pode chamar Reports.patch para salvar as alterações:

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ê fizer uma atualização completa, chame Reports.update para salvar as mudanças:

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);

Quando uma solicitação de salvamento é realizada, 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 código é o que você usará para se referir a esse relatório no restante do seu fluxo de trabalho.