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 trong 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 vạch ra thông tin cơ bản về báo cáo sẽ chạy, cũng như cấu trúc của kết quả 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 báo cáo hợp lệ không phải là một nhiệm vụ đơ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 các 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 để 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 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 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. Quá trình 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. Thực hiện 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 đó. Quá trình 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 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. Mặc dù vậy, 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, là CSV hoặc Excel.
lịch biểu	Lịch biểu được dùng để chạy báo cáo theo định kỳ.

Các 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ạ cách tạo 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 chọn 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ỉ trả về thông tin có liên quan. Tiêu chí này cũng xác định cấu trúc của kết quả báo cáo.

Tiêu chí được dùng sẽ tuỳ 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 tập hợp trường hơi khác nhau, nhưng có một tập hợp các trường tiêu chí chung thường hữu ích để kiểm soát kết quả báo cáo:

Trường	Mô tả
dateRange	Ngày mà báo cáo này sẽ chạ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 phạm vi ngày tương đối như YESTERDAY sẽ được phân giải theo múi giờ của Hoa Kỳ/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 giúp 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 sẽ đưa vào kết quả báo cáo.
metricNames	Đơn vị đo lường chuẩn sẽ đưa vào kết quả 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 dành riêng cho từng 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 thêm tiêu chí cơ bản vào tài nguyên báo cáo chuẩn:

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 = datetime.date.today()
start_date = end_date - datetime.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ế kết quả 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.

Truy vấn giá trị phương diện cơ bả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 thêm bộ lọc nếu cần giới hạn thêm kết quả truy vấn.

Ví dụ dưới đây tra cứu các giá trị bộ lọc nhà quảng cáo hợp lệ trong những ngày mà báo cáo của chúng ta 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 tổ hợp chỉ số, phương diện và bộ lọc nào cũng hợp lệ. Bạn sẽ không được phép lưu báo cáo chứa tổ hợp không hợp lệ, vì vậy, bạn cần đảm bảo các trường mà bạn định dùng tương thích với nhau.

Khi tạo tài nguyên báo cáo, bạn có thể chuyển tài nguyên đó vào dịch vụ Reports.compatibleFields để xem những trường nào hợp lệ dựa trên các trường mà bạn đã chọn. Cấu hình của báo cáo sẽ được phân tích và 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 tất cả đều 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 mà bạn chọn sẽ hoạt động cùng nhau.

Ví dụ dưới đây minh hoạ cách thực hiện yêu cầu mẫu về các trường tương thích, sử dụng tài nguyên báo cáo 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 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=str(profile_id), body=report).execute()
)

Ruby

report = service.insert_report(profile_id, report)

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 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, trong đó quan trọng nhất là trường id. Bạn sẽ dùng mã nhận dạng này để tham chiếu đến báo cáo này trong suốt phần còn lại của quy trình làm việc.