สร้างและอัปเดตรายงาน

บริการรายงานสำหรับ Campaign Manager 360 API ช่วยให้คุณสร้างและอัปเดตรายงานของเครื่องมือสร้างรายงานได้โดยใช้ออบเจ็กต์ทรัพยากรรายงาน แหล่งข้อมูลของรายงานมีข้อมูลพื้นฐานเกี่ยวกับรายงานที่จะเรียกใช้ รวมถึงโครงสร้างของผลลัพธ์รายงาน

คู่มือนี้จะอธิบายวิธีสร้างและอัปเดตรายงานของเครื่องมือสร้างรายงานแบบเป็นโปรแกรมผ่านบริการรายงาน

หมายเหตุ: การสร้างรายงานที่ถูกต้องไม่ใช่เรื่องง่าย ชุดย่อยของมิติข้อมูลและเมตริกบางรายการใช้ได้ในชุดค่าผสมที่เฉพาะเจาะจงเท่านั้น ดังนั้น เราขอแนะนำให้คุณสร้างรายงานในขั้นต้นด้วยเครื่องมือสร้างรายงาน จากนั้นจึงโคลนและแก้ไขรายงานเหล่านี้ผ่าน API

กำหนดค่าแหล่งข้อมูลของรายงาน

ขั้นตอนแรกในการสร้างหรืออัปเดตรายงานเครื่องมือสร้างรายงานคือการกำหนดค่าออบเจ็กต์ทรัพยากรของรายงาน หากคุณกำลังสร้างรายงานใหม่ คุณจะเริ่มต้นด้วยแหล่งข้อมูลเปล่าและตั้งค่าช่องที่จำเป็น หากกำลังอัปเดตรายงานที่มีอยู่ คุณจะมีตัวเลือกดังนี้

1. แนะนำ: ดำเนินการอัปเดตบางส่วน เมื่อใช้วิธีการนี้ คุณจะเริ่มต้นด้วยทรัพยากรเปล่าและตั้งค่าช่องที่คุณต้องการเปลี่ยนแปลง การอัปเดตบางส่วนจะบันทึกเฉพาะการเปลี่ยนแปลงในช่องที่คุณระบุเท่านั้น
2. กำลังอัปเดตโดยสมบูรณ์ ด้วยวิธีการนี้ คุณจะโหลดทรัพยากรรายงานที่มีอยู่และแก้ไขฟิลด์ของทรัพยากรดังกล่าวได้โดยตรง การอัปเดตแบบเต็มจะบันทึกช่องทั้งหมดของรายงานเสมอ

เนื้อหาจริงของทรัพยากรรายงานจะแตกต่างกันไปตามประเภทของรายงานที่คุณกำหนดค่า อย่างไรก็ตาม ก็มีช่อง 2-3 ช่องที่เหมือนกับรายงานทุกประเภทอยู่แล้ว ได้แก่

ช่อง	คำอธิบาย
ช่องที่ต้องกรอก
ชื่อ	ชื่อรายงาน
ประเภท	ประเภทของรายงาน
ช่องที่ไม่บังคับ
การจัดส่ง	การตั้งค่าการส่งอีเมลของรายงาน
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";

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

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 ช่อง โดยช่องที่สำคัญที่สุดคือช่องรหัส รหัสนี้จะเป็นสิ่งที่คุณจะใช้เพื่ออ้างอิงรายงานนี้ตลอดเวิร์กโฟลว์ที่เหลือของคุณ