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

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

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

Примечание. Создание корректного отчета — нетривиальная задача. Некоторые подмножества параметров и показателей действительны только в определенных сочетаниях. Поэтому мы рекомендуем сначала создавать отчеты с помощью построителя отчетов , а затем клонировать и изменять эти отчеты с помощью API.

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

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

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

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

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

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

С#

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";

Джава

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

питон

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

Определите критерии отчета

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

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

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

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

Поле	Описание
диапазон дат	Даты, за которые должен быть выполнен этот отчет. Можно использовать для указания пользовательских дат начала и окончания или относительного диапазона дат . Примечание. При запуске отчетов через API относительные диапазоны дат, такие как YESTERDAY , разрешаются в часовом поясе Америки/Лос-Анджелеса. Это может привести к неожиданным результатам для пользователей, находящихся в разных часовых поясах.
измерениеФильтры	Список фильтров, ограничивающих возвращаемые результаты. Дополнительную информацию о настройке фильтров см. в разделе значений фильтра запроса .
размеры	Список элементов Менеджера кампаний 360, которые необходимо включить в отчет.
metricNames	Стандартные единицы измерения для включения в отчет.

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

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

С#

// 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;

Джава

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

Питон

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

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

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

С#

// 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]
  };
}

Джава

// 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]]);
}

питон

# 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 , чтобы увидеть, какие поля допустимы с учетом тех, которые вы уже выбрали. Конфигурация отчета будет проанализирована, и будет возвращен ответ, содержащий совместимые параметры, показатели и фильтры. Поскольку не гарантируется, что все поля в этом ответе будут совместимы друг с другом, вам может потребоваться сделать несколько запросов, чтобы убедиться, что все выбранные вами поля будут работать вместе.

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

С#

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

Джава

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

питон

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 :

С#

Report insertedReport =
    service.Reports.Insert(report, profileId).Execute();

Джава

Report insertedReport = reporting.reports().insert(profileId, report).execute();

PHP

$insertedReport =
    $this->service->reports->insert($userProfileId, $report);

питон

inserted_report = service.reports().insert(
    profileId=profile_id, body=report).execute()

Рубин

report = service.insert_report(profile_id, report)

Если вы выполняете частичное обновление, вы можете сохранить изменения, вызвав Reports.patch :

С#

// Patch an existing report.
Report patchedReport =
    service.Reports.Patch(report, profileId, reportId).Execute();

Джава

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

питон

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

С#

// Update an existing report.
Report updatedReport =
    service.Reports.Update(report, profileId, report.Id).Execute();

Джава

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

питон

# 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 . Этот идентификатор вы будете использовать для ссылки на этот отчет в остальной части вашего рабочего процесса .