이 페이지는 Cloud Translation API를 통해 번역되었습니다.

보고서 작성 및 업데이트

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

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

보고서 리소스 구성

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

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

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

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

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

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	reachCriteria
PATH_TO_CONVERSION	pathToConversionCriteria
플러드라이트	floodlightCriteria
CROSS_DIMENSION_REACH	crossDimensionReachCriteria

각 유형별 기준은 약간 다른 입력란 집합을 제공하지만, 일반적으로 보고서 출력을 제어하는 데 유용한 공통 기준 입력란 집합이 있습니다.

필드	설명
dateRange	이 보고서를 실행할 날짜입니다. 시작일과 종료일을 직접 지정하거나 상대 기간을 지정하는 데 사용할 수 있습니다. 참고: API를 통해 보고서를 실행하면 `YESTERDAY`과 같은 상대적 기간이 미주/로스앤젤레스 시간대로 확인됩니다. 이로 인해 다른 시간대에 있는 사용자에게 예기치 않은 결과가 발생할 수 있습니다.
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;

자바

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

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

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

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

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

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

PHP

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

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

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

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

Ruby

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

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

보고서 작성 및 업데이트 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

보고서 리소스 구성

C#

자바

PHP

Python

Ruby

보고서 기준 정의

C#

자바

PHP

Python

Ruby

쿼리 필터 값

C#

자바

PHP

Python

Ruby

필드 호환성 확인

C#

자바

PHP

Python

Ruby

보고서 저장

C#

자바

PHP

Python

Ruby

C#

자바

PHP

Python

Ruby

C#

자바

PHP

Python

Ruby

보고서 작성 및 업데이트