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 del Creador de informes de forma programática a través del servicio Reports.

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 configurarás los campos necesarios. Si actualizas un informe existente, tienes las siguientes opciones:

  1. Opción preferida: Realizar una actualización parcial. Con este enfoque, comenzarás con un recurso vacío y configurarás los campos que deseas cambiar. Una actualización parcial solo guarda los cambios en los campos que especificas.
  2. Realizar 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:

CampoDescripción
Campos obligatorios
nombreEl nombre del informe
tipoEl tipo de informe
Campos opcionales
entregaLa configuración de entrega por correo electrónico del informe
fileNameEl nombre de archivo que se usa cuando se generan archivos de informes para este informe
formatoEl formato de salida del informe, ya sea CSV o Excel
programarUna programación que se usa para ejecutar tu informe de forma recurrente

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

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

Define los criterios del informe

Una vez que hayas elegido un tipo de informe y configurado los campos comunes, el siguiente paso es definir los criterios del informe. Los criterios del informe se usan para limitar el alcance del informe, lo que garantiza que solo se muestre la información pertinente. También define la estructura del resultado del informe.

Los criterios que se usan dependen del tipo de informe. La relación entre el tipo de informe y los criterios se explica en la siguiente tabla:

Tipo de informe Campo de criterios
STANDARD criteria
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, hay un conjunto de campos de criterios comunes que, por lo general, son útiles para controlar el resultado del informe:

Campo Descripción
dateRange Las fechas para las que se debe ejecutar este informe. Se puede usar para especificar una fecha de inicio y finalización personalizadas o un período relativo.
dimensionFilters Una lista de filtros que restringen los resultados que se muestran. Consulta la sección Valores de los filtros de consulta para obtener más información sobre la configuración de los filtros.
dimensiones Una lista de elementos de Campaign Manager 360 para incluir en el resultado del informe
metricNames Unidades de medida estándar para incluir 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 en 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 = datetime.date.today()
start_date = end_date - datetime.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 configuras filtros para un informe, debes especificar los valores exactos que usarán los filtros para restringir el resultado del informe. Si no estás seguro de cuáles son los valores posibles para un filtro en particular, búscalo 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 consulta.

En el siguiente ejemplo, se buscan valores de filtro de anunciante 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

Determina la compatibilidad de los campos

Cuando configuras los criterios del informe, es importante recordar 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 asegurarte 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 mostrará una respuesta que contenga 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 juntos.

En el siguiente ejemplo, se ilustra cómo realizar una solicitud de campos compatibles de muestra con 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 de informe. Si creas 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=str(profile_id), body=report).execute()
)

Ruby

report = service.insert_report(profile_id, report)

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 mostrará una copia del recurso de 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.