보고서 작성 및 업데이트

Campaign Manager 360 API의 보고서 서비스를 사용하면 보고서 리소스 개체로 보고서 작성 도구 보고서를 만들고 업데이트할 수 있습니다. 보고서 리소스에는 실행할 보고서에 대한 기본 정보와 보고서 출력 구조가 요약되어 있습니다.

이 가이드에서는 보고서 서비스를 통해 프로그래매틱 방식으로 보고서 작성 도구 보고서를 만들고 업데이트하는 방법을 자세히 설명합니다.

참고: 유효한 보고서를 작성하는 것은 중요한 일입니다. 측정기준 및 측정항목의 일부 하위 집합은 특정 조합에서만 유효합니다. 따라서 먼저 보고서 작성 도구를 사용하여 보고서를 만든 다음 API를 통해 보고서를 클론하고 수정하는 것이 좋습니다.

보고서 리소스 구성하기

보고서 작성 도구 보고서를 만들거나 업데이트하는 첫 번째 단계는 보고서 리소스 객체를 구성하는 것입니다. 새 보고서를 만드는 경우 빈 리소스로 시작하여 필요한 필드를 설정합니다. 기존 보고서를 업데이트하는 경우 다음과 같은 옵션 중에서 선택할 수 있습니다.

1. 권장: 부분 업데이트를 수행합니다. 이 방법을 사용하면 빈 리소스로 시작하여 변경하려는 필드를 설정하게 됩니다. 부분 업데이트는 지정한 필드의 변경사항만 저장합니다.
2. 전체 업데이트 수행 이 방법을 사용하면 기존 보고서 리소스를 로드하고 해당 필드를 직접 수정할 수 있습니다. 전체 업데이트는 항상 보고서의 모든 필드를 저장합니다.

보고서 리소스의 정확한 콘텐츠는 구성하는 보고서 유형에 따라 다릅니다. 모든 보고서 유형에 공통으로 사용되는 몇 가지 필드는 다음과 같습니다.

필드	설명
필수 입력란
이름	보고서의 이름입니다.
유형	보고서의 유형입니다.
선택적 필드
배포	보고서의 이메일 전송 설정
파일 이름	이 보고서에 대한 보고서 파일을 생성할 때 사용되는 파일 이름입니다.
format	보고서의 출력 형식(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";

자바

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

2,399필리핀

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

보고서 기준 정의하기

보고서 유형을 선택하고 공통 필드를 구성한 후에는 보고서 기준을 정의해야 합니다. 보고서 기준은 보고서의 범위를 제한하여 관련 있는 정보만 반환되도록 하는 데 사용됩니다. 보고서 출력의 구조도 정의합니다.

사용되는 기준은 보고서 유형에 따라 다릅니다. 다음 표에는 보고서 유형과 기준의 관계가 설명되어 있습니다.

보고서 유형	기준 필드
표준	기준
REACH	도달범위 기준
PATH_TO_CONVERSION(경로)	pathToConversionCriteria
플러드라이트	투광등 기준
CROSS_DIMENSION_REACH	crossDimensionReachCriteria

이러한 유형별 기준마다 약간 다른 필드 집합이 표시되지만, 일반적으로 보고서 출력을 제어하는 데 유용한 공통 기준 필드 집합이 있습니다.

필드	설명
dateRange	이 보고서를 실행할 날짜입니다. 맞춤 시작일 및 종료일 또는 상대 기간을 지정하는 데 사용할 수 있습니다. 참고: API를 통해 보고서를 실행하면 YESTERDAY과 같은 상대적 기간이 미국/로스앤젤레스 시간대로 확인됩니다. 이로 인해 다른 시간대의 사용자에게 예상치 못한 결과가 발생할 수 있습니다.
측정기준 필터	반환되는 결과를 제한하는 필터 목록입니다. 필터 구성에 관한 자세한 내용은 쿼리 필터 값 섹션을 참고하세요.
dimensions	보고서 출력에 포함할 Campaign Manager 360 요소의 목록입니다.
측정항목 이름	보고서 출력에 포함할 표준 측정 단위입니다.

보고서의 측정기준, 측정항목, 필터를 선택하는 방법에 대한 자세한 내용은 필드 호환성 확인 섹션을 참고하세요. 추가적인 유형별 기준 필드는 참조 문서 및 고객센터에 설명되어 있습니다.

아래 예는 표준 보고서 리소스에 기본 기준을 추가합니다.

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;

자바

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

2,399필리핀

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

쿼리 필터 값

보고서 필터를 구성할 때 필터에서 보고서 출력을 제한하는 데 사용할 정확한 값을 지정해야 합니다. 특정 필터에 사용 가능한 값을 정확히 알 수 없는 경우 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]
  };
}

자바

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

2,399필리핀

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

필드 호환성 확인

보고서 기준을 구성할 때 측정항목, 측정기준, 필터의 모든 조합이 유효한 것은 아니라는 점에 유의해야 합니다. 잘못된 조합이 포함된 보고서는 저장할 수 없으므로 사용하려는 입력란이 서로 호환되는지 확인해야 합니다.

보고서 리소스를 만들 때 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);
}

자바

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

2,399필리핀

$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

보고서 저장

이 프로세스의 마지막 단계는 보고서 리소스를 저장하는 것입니다. 새 보고서를 만드는 경우 Reports.insert에 대한 호출로 삽입할 수 있습니다.

C#

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

자바

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

2,399필리핀

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

부분 업데이트를 수행하는 경우 Reports.patch를 호출하여 변경사항을 저장할 수 있습니다.

C#

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

2,399필리핀

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

또는 전체 업데이트를 수행하기로 결정한 경우 Reports.update를 호출하여 변경사항을 저장할 수 있습니다.

C#

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

2,399필리핀

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

저장 요청이 성공하면 보고서 리소스의 사본이 응답 본문에 반환됩니다. 이 리소스에는 몇 가지 새로운 필드가 작성되는데, 그중 가장 중요한 입력란은 ID 필드입니다. 이 ID는 워크플로의 나머지 부분에서 이 보고서를 참조하는 데 사용됩니다.