Crear y actualizar informes

El servicio Reports de la API de Campaign Manager 360 te permite crear y actualizar informes del Creador de informes con objetos de recursos de informes. Un recurso de informe describe la información básica sobre un informe que se ejecutará, así como la estructura del resultado del informe.

En esta guía, se detalla cómo crear y actualizar informes de forma programática en el Creador de informes a través del servicio de Reports.

Nota: Generar un informe válido no es una tarea trivial. Algunos subconjuntos de dimensiones y métricas solo son válidos en combinaciones específicas. Por lo tanto, te recomendamos que, en principio, crees informes con el Creador de informes y, luego, clones y modifiques estos informes a través de la API.

Configura un recurso de informe

El primer paso para crear o actualizar un informe del Creador de informes es configurar un objeto de recurso de informe. Si creas un informe nuevo, comenzarás con un recurso vacío y establecerás los campos necesarios. Si vas a actualizar un informe existente, tienes las siguientes opciones:

1. Preferida: Realizar una actualización parcial Con este enfoque, comenzarás con un recurso vacío y establecerás los campos que deseas cambiar. Una actualización parcial solo guarda los cambios en los campos que especificas.
2. Se está realizando una actualización completa. Con este enfoque, cargarás un recurso de informe existente y modificarás sus campos directamente. Una actualización completa siempre guarda todos los campos del informe.

El contenido exacto de un recurso de informe varía según el tipo de informe que configures. Aun así, hay algunos campos que son comunes a todos los tipos de informes:

Campo	Descripción
Campos obligatorios
nombre	Es el nombre del informe.
tipo	Es el tipo de informe.
Campos opcionales
entrega	Es la configuración de entrega por correo electrónico del informe.
fileName	Es el nombre de archivo que se usa cuando se generan archivos de informes para este informe.
formato	Es el formato de salida del informe, que puede ser CSV o Excel.
programar	Es una programación que se usa para ejecutar tu informe de forma recurrente.

Estos campos comunes conforman el esqueleto de tu informe. En el siguiente ejemplo, se ilustra la creación de un recurso de informe estándar nuevo:

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

Cómo definir los criterios del informe

Una vez que elijas un tipo de informe y configures los campos comunes, el siguiente paso es definir los criterios del informe. Los criterios del informe se utilizan para limitar su alcance y garantizar que solo se devuelva la información pertinente. También define la estructura del resultado del informe.

Los criterios utilizados dependen del tipo de informe. En la siguiente tabla, se explica la relación entre el tipo de informe y los criterios:

Tipo de informe	Campo de criterios
ESTÁNDAR	criterios
REACH	reachCriteria
PATH_TO_CONVERSION	pathToConversionCriteria
FLOODLIGHT	floodlightCriteria
CROSS_DIMENSION_REACH	crossDimensionReachCriteria

Si bien cada uno de estos criterios específicos del tipo expone un conjunto de campos ligeramente diferente, existe un conjunto de campos de criterios comunes que suelen ser útiles para controlar el resultado del informe:

Campo	Descripción
dateRange	Son las fechas para las que se debe ejecutar este informe. Se puede usar para especificar una fecha de inicio y finalización personalizadas, o bien un período relativo. Nota: Cuando ejecutas informes a través de la API, los períodos relativos, como YESTERDAY, se resuelven en la zona horaria de América/Los Ángeles. Esto puede generar resultados inesperados para los usuarios en diferentes zonas horarias.
dimensionFilters	Es una lista de filtros que restringen los resultados que se muestran. Consulta la sección Valores de filtro de consulta para obtener más información sobre la configuración de filtros.
dimensiones	Es una lista de elementos de Campaign Manager 360 que se incluirán en el resultado del informe.
metricNames	Son las unidades de medida estándar que se incluirán en el resultado del informe.

Consulta la sección sobre cómo determinar la compatibilidad de los campos para obtener más información sobre cómo elegir dimensiones, métricas y filtros para tu informe. Los campos de criterios adicionales específicos del tipo se explican en la documentación de referencia y el Centro de ayuda.

En el siguiente ejemplo, se agrega un criterio básico a nuestro recurso de informe estándar:

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 los filtros de consulta

Cuando configures filtros para un informe, deberás especificar los valores exactos que usarán los filtros para restringir el resultado del informe. Si no sabes cuáles son los valores posibles para un filtro en particular, puedes buscarlos con el servicio DimensionValues.

Una consulta básica de valores de dimensión contiene un nombre de dimensión, así como una fecha de inicio y una fecha de finalización. Las fechas de inicio y finalización limitan la respuesta a los valores válidos dentro de ese período. Se pueden especificar filtros adicionales si necesitas limitar aún más los resultados de la búsqueda.

En el siguiente ejemplo, se buscan valores de filtro de anunciantes válidos durante las fechas en las que se ejecutará nuestro informe y se agregan a los criterios del informe:

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

Cómo determinar la compatibilidad de los campos

Cuando configures los criterios de tu informe, es importante que recuerdes que no todas las combinaciones de métricas, dimensiones y filtros son válidas. No podrás guardar un informe que contenga una combinación no válida, por lo que es importante que te asegures de que los campos que planeas usar sean compatibles entre sí.

A medida que creas tu recurso de informe, puedes pasarlo al servicio Reports.compatibleFields para ver qué campos son válidos según los que ya seleccionaste. Se analizará la configuración del informe y se devolverá una respuesta que contendrá las dimensiones, las métricas y los filtros compatibles. Dado que no se garantiza que todos los campos de esta respuesta sean compatibles entre sí, es posible que debas realizar varias solicitudes para asegurarte de que todos los campos que elijas funcionen en conjunto.

En el siguiente ejemplo, se ilustra cómo realizar una solicitud de campos compatibles de muestra, utilizando nuestro recurso de informe 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

Guarda el informe

El último paso de este proceso es guardar el recurso del informe. Si vas a crear un informe nuevo, puedes insertarlo con una llamada a 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)

Si realizas una actualización parcial, puedes guardar los cambios llamando a 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)

O bien, si decidiste realizar una actualización completa, puedes guardar los cambios llamando a 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);

Después de una solicitud de guardado exitosa, se devolverá una copia del recurso del informe en el cuerpo de la respuesta. Este recurso tendrá algunos campos nuevos completados, el más importante de los cuales es el campo id. Este ID es el que usarás para hacer referencia a este informe durante el resto de tu flujo de trabajo.