Создание и обновление отчетов

Сервис «Отчеты» для API Campaign Manager 360 позволяет создавать и обновлять отчеты Report Builder с помощью объектов ресурсов отчетов. Ресурс отчета содержит основную информацию о запускаемом отчете, а также структуру выходных данных отчета.

В этом руководстве подробно описано, как программно создавать и обновлять отчеты Report Builder через службу Reports.

Настройте ресурс отчета.

Первый шаг при создании или обновлении отчета в Report Builder — это настройка объекта ресурса отчета. Если вы создаете новый отчет, вы начинаете с пустого ресурса и задаете необходимые поля. Если вы обновляете существующий отчет, у вас есть выбор:

  1. Предпочтительный вариант : частичное обновление . При таком подходе вы начинаете с пустого ресурса и задаете поля, которые хотите изменить. Частичное обновление сохраняет изменения только в указанных вами полях.
  2. Выполнение полного обновления. При таком подходе вы загружаете существующий ресурс отчета и напрямую изменяете его поля. Полное обновление всегда сохраняет все поля отчета.

Точное содержимое ресурса отчета зависит от типа настраиваемого отчета . Тем не менее, есть несколько полей, общих для всех типов отчетов:

Поле Описание
Обязательные поля
имя Название отчета.
тип Тип отчета.
Необязательные поля
доставка Настройки отправки отчета по электронной почте.
имя файла Имя файла, используемое при создании файлов отчета для данного отчета.
формат Формат вывода отчета: CSV или Excel.
расписание Расписание, используемое для периодического запуска вашего отчета.

Эти общие поля составляют основу вашего отчета. Пример ниже иллюстрирует создание нового стандартного ресурса отчета:

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

Руби 

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

Определите критерии составления отчета.

После выбора типа отчета и настройки общих полей следующим шагом является определение критериев отчета. Критерии отчета используются для ограничения области действия отчета, гарантируя, что будет возвращена только релевантная информация. Они также определяют структуру выходных данных отчета.

Используемые критерии зависят от типа отчета. Взаимосвязь между типом отчета и критериями объяснена в следующей таблице:

Тип отчета Поле критериев
СТАНДАРТ критерии
ДОСТИГАТЬ reachCriteria
ПУТЬ К КОНВЕРСИИ pathToConversionCriteria
ПРОЖЕКТОР Критерии прожектора
CROSS_DIMENSION_REACH crossDimensionReachCriteria

Хотя каждый из этих критериев, специфичных для конкретного типа данных, предоставляет несколько отличающийся набор полей, существует ряд общих полей критериев, которые, как правило, полезны для управления выводом отчетов:

Поле Описание
диапазон дат Даты, за которые должен быть сформирован этот отчет. Можно указать либо пользовательские начальную и конечную даты, либо относительный диапазон дат .
dimensionFilters Список фильтров, ограничивающих возвращаемые результаты. Дополнительную информацию о настройке фильтров см. в разделе « Значения фильтров запроса» .
размеры Список элементов Campaign Manager 360, которые следует включить в отчет.
metricNames Стандартные единицы измерения, которые следует включить в итоговый отчет.

Дополнительную информацию о выборе измерений, показателей и фильтров для отчета см. в разделе, посвященном определению совместимости полей . Дополнительные поля критериев, специфичные для каждого типа данных, описаны в справочной документации и центре поддержки .

В приведенном ниже примере к стандартному ресурсу отчета добавляется базовый критерий:

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

Руби 

# 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

Значения фильтра запроса

При настройке фильтров для отчета необходимо указать точные значения, которые фильтры будут использовать для ограничения вывода отчета. Если вы не уверены в возможных значениях для конкретного фильтра, найдите их с помощью службы DimensionValues .

Базовый запрос значений измерений содержит имя измерения , а также начальную и конечную даты . Начальная и конечная даты ограничивают ответ значениями, действительными в течение этого периода времени. При необходимости можно указать дополнительные фильтры для дальнейшего ограничения результатов запроса.

В приведенном ниже примере выполняется поиск допустимых значений фильтра рекламодателей на даты, когда будет формироваться наш отчет, и добавляется к критериям отчета:

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

Руби 

# 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

Определите совместимость поля

При настройке критериев отчета важно помнить, что не все комбинации метрик, измерений и фильтров являются допустимыми. Вы не сможете сохранить отчет, содержащий недопустимую комбинацию, поэтому важно убедиться, что поля, которые вы планируете использовать, совместимы друг с другом.

При создании ресурса отчета вы можете передать его в службу Reports.compatibleFields , чтобы проверить, какие поля допустимы с учетом уже выбранных вами полей. Конфигурация отчета будет проанализирована, и в ответ будет возвращен список совместимых измерений, метрик и фильтров. Поскольку совместимость полей в этом ответе не гарантируется, вам может потребоваться сделать несколько запросов, чтобы убедиться, что все выбранные вами поля будут работать вместе.

Приведенный ниже пример иллюстрирует, как создать запрос на совместимость полей, используя в качестве входных данных наш ресурс отчета:

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

Руби 

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

Сохраните отчёт

Последний шаг в этом процессе — сохранение ресурса отчета. Если вы создаете новый отчет, вы можете вставить его с помощью вызова метода 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()

Руби 

report = service.insert_report(profile_id, report)

При частичном обновлении вы можете сохранить изменения, вызвав функцию 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();

Руби 

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

Или, если вы решили выполнить полное обновление, вы можете сохранить изменения, вызвав функцию 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();

Руби 

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

После успешного запроса на сохранение в теле ответа будет возвращена копия ресурса отчета. Этот ресурс будет содержать несколько новых полей, наиболее важным из которых является поле id . Именно этот id вы будете использовать для ссылки на данный отчет на протяжении всего рабочего процесса .