Cómo crear y actualizar informes

El servicio de informes 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 información básica sobre un informe que se ejecutará, así como la estructura del resultado del informe.

En esta guía, se explica cómo crear y actualizar informes del Creador de informes de manera programática mediante el servicio Informes.

Nota: Crear un informe válido no es una tarea trivial. Algunos subconjuntos de dimensiones y métricas son válidos solo en combinaciones específicas. Por lo tanto, le recomendamos que cree informes con el Creador de informes inicialmente y, luego, los clone y modifique a través de la API.

Cómo configurar 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 crea un informe nuevo, comenzará con un recurso vacío y establecerá los campos necesarios. Si desea actualizar un informe existente, puede elegir entre las siguientes opciones:

1. Preferido: Realizar una actualización parcial. Si utilizas 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 especifiques.
2. Realizar una actualización completa. Con este enfoque, cargará un recurso de informe existente y modificará directamente sus campos. 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 configure. Aun así, existen algunos campos que son comunes a todos los tipos de informes:

Campo	Descripción
Campos obligatorios
del espacio	Es el nombre del informe.
tipo	Es el tipo de informe.
Campos opcionales
entrega	La configuración de envío de correos electrónicos del informe.
Nombre de archivo	Es el nombre de archivo que se utiliza al generar archivos de informe para este informe.
format	El formato de salida del informe, ya sea CSV o Excel.
agenda	Es una programación que se utiliza para ejecutar su informe de forma recurrente.

Estos campos comunes conforman el esqueleto de su informe. En el siguiente ejemplo, se muestra 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'
)

Cómo definir los criterios del informe

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

Los criterios que se usan 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	reachCriterios
PATH_TO_CONVERSION	pathToConversionCriterios
FLOODLIGHT	criterios-luz
CROSS_DIMENSION_REACH;	crossDimensionReachCriterios

Si bien cada uno de estos criterios específicos de tipo expone un conjunto de campos ligeramente diferentes, hay un conjunto de campos de criterios comunes que generalmente son útiles para controlar el resultado del informe:

Campo	Descripción
Período	Son las fechas en las que se debe ejecutar este informe. Se puede usar para especificar una fecha de inicio y finalización personalizada, o un período relativo. Nota: Cuando se ejecutan informes mediante la API, los períodos relativos como YESTERDAY se resuelven en la zona horaria de América/Los Ángeles. Esto puede provocar resultados inesperados para usuarios en diferentes zonas horarias.
FilterFilters	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.
dimensions	Una lista de elementos de Campaign Manager 360 para incluir en el resultado del informe
nombres de métricas	Unidades de medida estándar para incluir en el resultado del informe.

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

En el siguiente ejemplo, se agregan criterios básicos a nuestro recurso estándar de informes:

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

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á seguro de cuáles son los valores posibles para un filtro en particular, búsquelos con el servicio DimensionValues.

Una consulta de valores de dimensión básica 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 durante ese período. Se pueden especificar filtros adicionales si necesitas limitar más los resultados de la consulta.

El siguiente ejemplo busca valores válidos de filtro de anunciante durante las fechas en que se ejecutará nuestro informe y los agrega 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 campos

Cuando configure los criterios de sus informes, es importante recordar que no todas las combinaciones de métricas, dimensiones y filtros son válidos. No podrá guardar un informe que contenga una combinación no válida, por lo que es importante asegurarse de que los campos que planea usar sean compatibles entre sí.

Cuando crees el 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 contiene las dimensiones, las métricas y los filtros compatibles. Debido a que no se garantiza que todos los campos de esta respuesta sean compatibles entre sí, es posible que debas realizar varias solicitudes para garantizar que todos los campos que elijas funcionen en conjunto.

En el siguiente ejemplo, se muestra cómo crear una solicitud de campos compatible 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

Guardar el informe

El último paso de este proceso es guardar el recurso de informe. Si desea crear un informe nuevo, puede 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 realiza una actualización parcial, puede llamar a Reports.patch para guardar los cambios:

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 decidió realizar una actualización completa, puede 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 que la solicitud se guarde correctamente, 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 es el campo de ID. Este ID es lo que usará para hacer referencia a este informe en el resto del flujo de trabajo.