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

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

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

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

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

  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 путьToConversionCriteria
ПРОЖЕКТОР прожекторКритерии
CROSS_DIMENSION_REACH CrossDimensionReachCriteria

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

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

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

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

С# 

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