Criar e atualizar relatórios

O serviço de relatórios da API Campaign Manager 360 permite criar e atualizar relatórios do Criador de relatórios usando objetos de recurso de relatórios. 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 de maneira programática relatórios do Criador de relatórios 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. Ao criar um novo relatório, você começará com um recurso vazio e definirá os campos necessários. Se estiver atualizando um relatório, você poderá escolher entre:

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

CampoDescrição
Campos obrigatórios
nomeO nome do relatório.
tipoO tipo do relatório.
Campos opcionais
deliveryAs configurações de entrega do relatório por e-mail.
fileNameO nome de arquivo usado ao gerar os arquivos de relatório.
formatoO formato de saída do relatório, CSV ou Excel.
programaçãoUma programação usada para gerar seu relatório de forma recorrente.

Esses campos comuns compõem 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 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 apenas as 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 reachCriteria
PATH_TO_CONVERSION pathToConversionCriteria
FLOODLIGHT (link em inglês) 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érios comuns que geralmente são úteis para controlar a saída do relatório:

Campo Descrição
dateRange As datas em que este relatório deve ser gerado. Use 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 de valores de filtro de consulta para mais informações sobre como configurar filtros.
dimensões É uma lista de elementos do Campaign Manager 360 a serem incluídos na saída do relatório.
metricNames 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 mais informações sobre como escolher dimensões, métricas e filtros para o relatório. Outros campos de critérios 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 = "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 do filtro de consulta

Ao configurar filtros para um relatório, especifique os valores exatos que eles vão usar para restringir os resultados. 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 aos valores válidos dentro desse período. Filtros adicionais podem ser especificados se você precisa limitar ainda mais os resultados da consulta.

O exemplo abaixo procura valores de filtro de anunciante válidos durante as datas em que nosso 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 campo

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. Não é possível salvar um relatório que contenha uma combinação inválida. Portanto, é importante garantir que os campos que você planeja usar sejam 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 de acordo com os já 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 nem todos os campos dessa resposta são compatíveis entre si, pode ser 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 de relatório. Ao criar um novo relatório, é 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)

Se você estiver fazendo uma atualização parcial, será possível salvar as 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)

Como opção, se você decidiu realizar uma atualização completa, é possível salvar suas 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.