Tạo và cập nhật báo cáo

Dịch vụ Báo cáo cho Campaign Manager 360 API cho phép bạn tạo và cập nhật báo cáo của Trình tạo báo cáo bằng cách sử dụng các đối tượng tài nguyên báo cáo. Tài nguyên báo cáo trình bày thông tin cơ bản về báo cáo sẽ được chạy, cũng như cấu trúc của đầu ra báo cáo.

Hướng dẫn này trình bày chi tiết cách tạo và cập nhật báo cáo trong Trình tạo báo cáo theo phương thức lập trình thông qua dịch vụ Báo cáo.

Lưu ý: Việc tạo một báo cáo hợp lệ không phải là một việc đơn giản. Một số tập hợp con của phương diện và chỉ số chỉ hợp lệ trong một số tổ hợp cụ thể. Do đó, bạn nên tạo báo cáo ban đầu bằng Trình tạo báo cáo, sau đó sao chép và sửa đổi các báo cáo này thông qua API.

Định cấu hình tài nguyên báo cáo

Bước đầu tiên trong việc tạo hoặc cập nhật báo cáo trong Trình tạo báo cáo là định cấu hình đối tượng tài nguyên báo cáo. Nếu đang tạo một báo cáo mới, bạn sẽ bắt đầu bằng một tài nguyên trống và đặt các trường cần thiết. Nếu đang cập nhật một báo cáo hiện có, bạn có thể chọn:

1. Ưu tiên: Thực hiện cập nhật một phần. Khi sử dụng phương pháp này, bạn sẽ bắt đầu bằng một tài nguyên trống và đặt các trường mà bạn muốn thay đổi. Thao tác cập nhật một phần chỉ lưu các thay đổi đối với những trường mà bạn chỉ định.
2. Đang thực hiện quy trình cập nhật đầy đủ. Khi sử dụng phương pháp này, bạn sẽ tải một tài nguyên báo cáo hiện có và sửa đổi trực tiếp các trường của tài nguyên đó. Bản cập nhật đầy đủ luôn lưu tất cả các trường của báo cáo.

Nội dung chính xác của một tài nguyên báo cáo sẽ khác nhau tuỳ thuộc vào loại báo cáo mà bạn đang định cấu hình. Tuy nhiên, có một số trường chung cho tất cả các loại báo cáo:

Trường	Mô tả
Trường bắt buộc
tên	Tên của báo cáo.
loại	Loại báo cáo.
Trường không bắt buộc
giao hàng	Chế độ cài đặt gửi báo cáo qua email.
fileName	Tên tệp được dùng khi tạo tệp báo cáo cho báo cáo này.
định dạng	Định dạng đầu ra của báo cáo, có thể là CSV hoặc Excel.
lịch biểu	Lịch biểu dùng để chạy báo cáo theo định kỳ.

Những trường chung này tạo nên cấu trúc cơ bản của báo cáo. Ví dụ dưới đây minh hoạ việc tạo một tài nguyên báo cáo chuẩn mới:

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

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

Xác định tiêu chí báo cáo

Sau khi bạn chọn một loại báo cáo và định cấu hình các trường chung, bước tiếp theo là xác định tiêu chí báo cáo. Tiêu chí báo cáo được dùng để giới hạn phạm vi của báo cáo, đảm bảo chỉ thông tin có liên quan được trả về. Nó cũng xác định cấu trúc của đầu ra báo cáo.

Tiêu chí được sử dụng phụ thuộc vào loại báo cáo. Mối quan hệ giữa loại báo cáo và tiêu chí được giải thích trong bảng sau:

Loại báo cáo	Trường tiêu chí
STANDARD	tiêu chí
REACH	reachCriteria
PATH_TO_CONVERSION	pathToConversionCriteria
FLOODLIGHT	floodlightCriteria
CROSS_DIMENSION_REACH	crossDimensionReachCriteria

Mặc dù mỗi tiêu chí dành riêng cho từng loại này sẽ hiển thị một nhóm trường hơi khác nhau, nhưng có một nhóm trường tiêu chí chung thường hữu ích cho việc kiểm soát đầu ra của báo cáo:

Trường	Mô tả
dateRange	Ngày mà bạn nên chạy báo cáo này. Có thể dùng để chỉ định ngày bắt đầu và ngày kết thúc tuỳ chỉnh hoặc phạm vi ngày tương đối. Lưu ý: Khi chạy báo cáo thông qua API, các dải ngày tương đối như YESTERDAY sẽ được phân giải theo múi giờ của khu vực Châu Mỹ/Los Angeles. Điều này có thể gây ra kết quả không mong muốn cho người dùng ở các múi giờ khác nhau.
dimensionFilters	Danh sách các bộ lọc hạn chế kết quả được trả về. Hãy xem phần giá trị bộ lọc truy vấn để biết thêm thông tin về cách định cấu hình bộ lọc.
phương diện	Danh sách các phần tử Campaign Manager 360 cần đưa vào đầu ra báo cáo.
metricNames	Đơn vị đo lường tiêu chuẩn cần đưa vào đầu ra của báo cáo.

Hãy xem phần xác định khả năng tương thích của trường để biết thêm thông tin về cách chọn phương diện, chỉ số và bộ lọc cho báo cáo. Các trường tiêu chí bổ sung theo loại được giải thích trong tài liệu tham khảo và trung tâm trợ giúp.

Ví dụ dưới đây sẽ thêm một tiêu chí cơ bản vào tài nguyên báo cáo tiêu chuẩn của chúng tôi:

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

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

Giá trị bộ lọc truy vấn

Khi định cấu hình bộ lọc cho báo cáo, bạn cần chỉ định chính xác các giá trị mà bộ lọc sẽ dùng để hạn chế đầu ra của báo cáo. Nếu bạn không chắc chắn về các giá trị có thể có cho một bộ lọc cụ thể, hãy tra cứu các giá trị đó bằng dịch vụ DimensionValues.

Một truy vấn cơ bản về giá trị phương diện chứa tên phương diện, cũng như ngày bắt đầu và ngày kết thúc. Ngày bắt đầu và ngày kết thúc giới hạn phản hồi đối với các giá trị hợp lệ trong khoảng thời gian đó. Bạn có thể chỉ định các bộ lọc bổ sung nếu cần giới hạn thêm kết quả truy vấn.

Ví dụ dưới đây sẽ tra cứu các giá trị bộ lọc hợp lệ của nhà quảng cáo trong khoảng thời gian báo cáo sẽ chạy và thêm các giá trị đó vào tiêu chí báo cáo:

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

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

Xác định khả năng tương thích của trường

Khi định cấu hình tiêu chí báo cáo, bạn cần lưu ý rằng không phải mọi tổ hợp chỉ số, phương diện và bộ lọc đều hợp lệ. Bạn sẽ không được phép lưu báo cáo có chứa một tổ hợp không hợp lệ, vì vậy, điều quan trọng là bạn phải đảm bảo các trường mà bạn dự định sử dụng tương thích với nhau.

Khi tạo tài nguyên báo cáo, bạn có thể truyền tài nguyên đó vào dịch vụ Reports.compatibleFields để xem những trường nào hợp lệ trong số những trường bạn đã chọn. Cấu hình của báo cáo sẽ được phân tích và một phản hồi chứa các phương diện, chỉ số và bộ lọc tương thích sẽ được trả về. Vì các trường trong phản hồi này không phải lúc nào cũng tương thích với nhau, nên bạn có thể cần thực hiện nhiều yêu cầu để đảm bảo tất cả các trường bạn chọn sẽ hoạt động cùng nhau.

Ví dụ dưới đây minh hoạ cách đưa ra yêu cầu về các trường tương thích mẫu, sử dụng tài nguyên báo cáo của chúng tôi làm dữ liệu đầu vào:

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

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

Lưu báo cáo

Bước cuối cùng trong quy trình này là lưu tài nguyên báo cáo. Nếu đang tạo báo cáo mới, bạn có thể chèn báo cáo đó bằng lệnh gọi đến 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()

Ruby

report = service.insert_report(profile_id, report)

Nếu đang thực hiện một bản cập nhật một phần, bạn có thể lưu các thay đổi bằng cách gọi 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();

Ruby

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

Hoặc nếu quyết định thực hiện một bản cập nhật đầy đủ, bạn có thể lưu các thay đổi bằng cách gọi 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();

Ruby

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

Sau khi yêu cầu lưu thành công, bản sao của tài nguyên báo cáo sẽ được trả về trong phần nội dung phản hồi. Tài nguyên này sẽ có một số trường mới được điền sẵn, trong đó quan trọng nhất là trường mã nhận dạng. Bạn sẽ dùng mã nhận dạng này để tham chiếu đến báo cáo này trong phần còn lại của quy trình làm việc.