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

En esta guía, se explica cómo crear y actualizar de manera programática los informes del Creador de informes a través del 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, te recomendamos que generes informes inicialmente 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 deseas crear un informe nuevo, comenzarás con un recurso vacío y establecerás los campos necesarios. Si deseas actualizar un informe existente, tienes las siguientes opciones:

1. Preferido: Realizar una actualización parcial. Con este enfoque, comenzarás con un recurso vacío y establecerás los campos que quieres cambiar. Una actualización parcial solo guarda los cambios en los campos que especifiques.
2. Realizando una actualización completa. Con este enfoque, cargarás un recurso de informe existente y modificarás 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 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	La configuración de envío por correo electrónico del informe.
fileName	El nombre de archivo que se usa al generar archivos de informe para este informe.
formato	El formato de salida del informe, ya sea CSV o Excel.
programar	Es una programación que se utiliza para ejecutar el informe de forma recurrente.

Estos campos comunes conforman el esqueleto 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'
}

Rita

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 campos comunes, el siguiente paso es definir los criterios del informe. Los criterios del informe se utilizan para limitar el alcance de tu informe y garantizar que solo se muestre la información relevante. 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
ESTÁNDAR	criterios
REACH	reachCriteria
PATH_TO_CONVERSION	pathToConversionCriteria
FLOODLIGHT	floodlightCriteria
CROSS_DIMENSION_REACH	crossDimensionReachCriteria

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

Campo	Descripción
dateRange	Son las fechas en las que se debe ejecutar este informe. Se puede utilizar para especificar una fecha de inicio y finalización personalizada o un período relativo. Nota: Cuando se ejecutan 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 de diferentes zonas horarias.
dimensionFilters	Una lista de filtros que restringen los resultados que se muestran. Consulta la sección valores del filtro de consulta para obtener más información sobre la configuración de filtros.
dimensiones	Una lista de elementos de Campaign Manager 360 para incluir en el resultado del informe.
metricNames	Unidades de medida estándar que se incluirán en los resultados del informe.

Consulta la sección 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 adicionales de criterios específicos para el 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 = 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

Rita

# 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 del filtro de consulta

Cuando configuras filtros para un informe, debes especificar los valores exactos que los filtros usarán para restringir los resultados del informe. Si no tienes certeza de cuáles son los valores posibles para un filtro específico, búscalos 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 valores válidos dentro de ese período. Puedes especificar filtros adicionales si necesitas limitar más los resultados de la consulta.

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]]

Rita

# 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 campos

Cuando configures los criterios de tus informes, es importante recordar que no todas las combinaciones de métricas, dimensiones y filtros son válidas. No podrá guardar un informe que contenga una combinación no válida, por lo que es importante asegurarse de que los campos que desea utilizar 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 en función de 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. Dado que no se garantiza que todos los campos en 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.

El siguiente ejemplo ilustra cómo realizar una solicitud de campos compatibles de muestra, usando 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'])

Rita

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 paso final de este proceso es guardar el recurso del informe. Si deseas 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()

Rita

report = service.insert_report(profile_id, report)

Si realizas una actualización parcial, puedes 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();

Rita

# Patch an existing report.
patched_report = service.patch_report(profile_id, report_id, report)

O bien, si decidió realizar una actualización completa, puede llamar a Reports.update para guardar los cambios:

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

Rita

# Update an existing report.
updated_report = service.update_report(profile_id, report.id, report);

Después de que la solicitud de guardado se realice 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 de ellos es el campo id. Este ID es el que usarás para hacer referencia a este informe en el resto de tu flujo de trabajo.