บริการรายงานสําหรับ API ของ Campaign Manager 360 ช่วยให้คุณสร้างและอัปเดตรายงานของเครื่องมือสร้างรายงานโดยใช้ออบเจ็กต์ทรัพยากรรายงานได้ ทรัพยากรของรายงานจะระบุข้อมูลพื้นฐานเกี่ยวกับรายงานที่จะเรียกใช้ รวมทั้งโครงสร้างของผลลัพธ์รายงาน
คู่มือนี้จะอธิบายวิธีการสร้างและอัปเดตรายงานของเครื่องมือสร้างรายงานผ่านบริการรายงาน
กําหนดค่าทรัพยากรของรายงาน
ขั้นตอนแรกในการสร้างหรืออัปเดตรายงานของเครื่องมือสร้างรายงานคือการกําหนดค่าออบเจ็กต์ทรัพยากรรายงาน หากคุณกําลังสร้างรายงานใหม่ คุณจะเริ่มต้นด้วยทรัพยากรว่างและตั้งค่าฟิลด์ที่จําเป็น หากคุณกําลังอัปเดตรายงานที่มีอยู่ คุณจะมีตัวเลือกต่อไปนี้
- แนะนําให้ดําเนินการ: ดําเนินการอัปเดตบางส่วน เมื่อใช้วิธีนี้ คุณจะเริ่มต้นด้วยทรัพยากรที่ว่างเปล่าและตั้งค่าช่องที่ต้องการเปลี่ยน การอัปเดตบางส่วนจะบันทึกการเปลี่ยนแปลงของช่องที่คุณระบุเท่านั้น
- ดําเนินการอัปเดตแบบเต็ม เมื่อใช้วิธีนี้ คุณจะโหลดทรัพยากรรายงานที่มีอยู่และแก้ไขช่องของทรัพยากรโดยตรง การอัปเดตเต็มรูปแบบจะบันทึกข้อมูลทุกช่องในรายงานเสมอ
เนื้อหาที่แน่นอนของทรัพยากรรายงานจะแตกต่างกันไปขึ้นอยู่กับประเภทรายงานที่คุณกําลังกําหนดค่า อย่างไรก็ตาม มีช่องสองสามฟิลด์ที่เหมือนกันในรายงานทุกประเภท:
| ช่อง | คำอธิบาย |
|---|---|
| ช่องที่ต้องกรอก | |
| name | ชื่อรายงาน |
| ประเภท | ประเภทของรายงาน |
| ช่องที่ไม่บังคับ | |
| การจัดส่ง | การตั้งค่าการส่งอีเมลของรายงาน |
| ชื่อไฟล์ | ชื่อไฟล์ที่ใช้สร้างไฟล์รายงานสําหรับรายงานนี้ |
| รูปแบบ [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";
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'
)
กําหนดเกณฑ์ของรายงาน
เมื่อคุณเลือกประเภทรายงานและกําหนดค่าช่องทั่วไปแล้ว ขั้นตอนถัดไปคือการกําหนดเกณฑ์ของรายงาน เกณฑ์ของรายงานจะใช้เพื่อจํากัดขอบเขตของรายงาน เพื่อให้มั่นใจว่าเฉพาะข้อมูลที่เกี่ยวข้องเท่านั้นที่จะถูกส่งคืน นอกจากนี้ยังเป็นการกําหนดโครงสร้างของผลลัพธ์รายงานด้วย
เกณฑ์ที่ใช้จะขึ้นอยู่กับประเภทของรายงาน ความสัมพันธ์ระหว่างประเภทรายงานและเกณฑ์ได้อธิบายไว้ในตารางต่อไปนี้
| ประเภทรายงาน | ช่องเกณฑ์ |
|---|---|
| มาตรฐาน | เกณฑ์ |
| REACH | เกณฑ์การเข้าถึง |
| PATH_TO_CONVERSION | เส้นทางที่ทําให้เกิด Conversion |
| ฟลัดไลท์ | floodlightCriteria |
| CRSS_DIMENSION_REACH | crossDimensionReachCriteria |
แม้ว่าเกณฑ์เฉพาะประเภทเหล่านี้จะมีชุดของฟิลด์ที่แตกต่างกันเล็กน้อย แต่มีชุดของฟิลด์เกณฑ์ทั่วไปที่โดยทั่วไปจะใช้ในการควบคุมผลลัพธ์ของรายงาน:
| ช่อง | คำอธิบาย |
|---|---|
| ช่วงวันที่ | วันที่ที่เรียกใช้รายงานนี้ สามารถใช้เพื่อระบุวันที่เริ่มต้นและวันที่สิ้นสุดที่กําหนดเอง หรือช่วงวันที่สัมพัทธ์ |
| ตัวกรองมิติข้อมูล | รายการตัวกรองที่จํากัดผลลัพธ์ที่ได้ โปรดดูข้อมูลเพิ่มเติมเกี่ยวกับการกําหนดค่าตัวกรองที่ส่วนค่าของตัวกรองการค้นหา |
| มิติข้อมูล | รายการองค์ประกอบ 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;
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
ค่าตัวกรองการค้นหา
เมื่อกําหนดค่าตัวกรองสําหรับรายงาน คุณต้องระบุค่าที่แน่นอนที่ตัวกรองจะใช้เพื่อจํากัดผลลัพธ์ของรายงาน หากคุณไม่แน่ใจว่าค่าหนึ่งๆ มีค่าใดสําหรับตัวกรองหนึ่งๆ ให้ค้นหาโดยใช้บริการ 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]
};
}
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
ตรวจสอบความเข้ากันได้ของช่อง
ในการกําหนดค่าเกณฑ์ในรายงาน สิ่งสําคัญคือการผสมระหว่างเมตริก มิติข้อมูล และตัวกรองบางรายการไม่ถูกต้อง คุณไม่ได้รับอนุญาตให้บันทึกรายงานที่มีชุดค่าผสมที่ไม่ถูกต้อง ดังนั้น สิ่งสําคัญที่คุณจะต้องแน่ใจว่าฟิลด์ที่คุณวางแผนจะใช้งานร่วมกันจึงสอดคล้องกัน
เมื่อสร้างทรัพยากรของรายงาน คุณจะส่งต่อทรัพยากรดังกล่าวไปยังบริการ 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);
}
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
บันทึกรายงาน
ขั้นตอนสุดท้ายในกระบวนการนี้คือการบันทึกทรัพยากรของรายงาน หากสร้างรายงานใหม่ คุณจะแทรกรายงานนั้นโดยเรียกใช้ 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)
หากทําการอัปเดตเพียงบางส่วน คุณจะบันทึกการเปลี่ยนแปลงได้โดยเรียกใช้ 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)
หรือหากคุณตัดสินใจดําเนินการอัปเดตแบบเต็ม คุณสามารถบันทึกการเปลี่ยนแปลงได้โดยเรียกใช้ 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);
หลังจากบันทึกคําขอสําเร็จแล้ว สําเนาของทรัพยากรรายงานจะแสดงขึ้นในส่วนเนื้อหาของการตอบกลับ ทรัพยากรนี้จะกรอกข้อมูลในช่องใหม่ 2-3 ช่อง จุดที่สําคัญที่สุดคือช่องรหัส รหัสนี้คือรหัสที่คุณใช้ในการอ้างอิงรายงานนี้ในส่วนที่เหลือของขั้นตอนการทํางาน