Membuat dan Memperbarui Laporan

Layanan Laporan untuk Campaign Manager 360 API memungkinkan Anda membuat dan memperbarui laporan Pembuat Laporan menggunakan objek resource laporan. Resource laporan menguraikan informasi dasar tentang laporan yang akan dijalankan, serta struktur output laporan.

Panduan ini menjelaskan cara membuat dan memperbarui laporan Pembuat Laporan secara terprogram melalui layanan Laporan.

Catatan: Membuat laporan yang valid bukanlah tugas yang mudah. Beberapa subkumpulan dimensi dan metrik hanya valid dalam kombinasi tertentu. Oleh karena itu, sebaiknya Anda membuat laporan dengan Pembuat Laporan terlebih dahulu, lalu meng-clone dan mengubah laporan ini melalui API.

Mengonfigurasi aset laporan

Langkah pertama dalam membuat atau memperbarui laporan Pembuat Laporan adalah mengonfigurasi objek resource laporan. Jika Anda membuat laporan baru, Anda akan memulai dengan resource kosong dan menetapkan kolom yang diperlukan. Jika memperbarui laporan yang sudah ada, Anda dapat memilih:

1. Direkomendasikan: Melakukan update sebagian. Dengan pendekatan ini, Anda akan memulai dengan resource kosong dan menetapkan kolom yang ingin diubah. Update parsial hanya menyimpan perubahan pada kolom yang Anda tentukan.
2. Melakukan update lengkap. Dengan pendekatan ini, Anda akan memuat aset laporan yang ada dan langsung mengubah kolomnya. Pembaruan lengkap selalu menyimpan semua kolom laporan.

Konten sebenarnya dari aset laporan bervariasi, bergantung pada jenis laporan yang Anda konfigurasikan. Meskipun demikian, ada beberapa kolom yang umum untuk semua jenis laporan:

Kolom	Deskripsi
Kolom wajib diisi
name	Nama laporan.
tipe	Jenis laporan.
Kolom opsional
pengantaran	Setelan pengiriman email laporan.
namafile	Nama file yang digunakan saat membuat file laporan untuk laporan ini.
format	Format output laporan, baik CSV atau Excel.
jadwal	Jadwal yang digunakan untuk menjalankan laporan Anda secara berulang.

Kolom umum ini membentuk kerangka laporan Anda. Contoh di bawah menggambarkan pembuatan resource laporan standar yang baru:

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

Menentukan kriteria laporan

Setelah Anda memilih jenis laporan dan mengonfigurasi kolom umum, langkah berikutnya adalah menentukan kriteria laporan. Kriteria laporan digunakan untuk membatasi cakupan laporan, sehingga memastikan hanya informasi relevan yang ditampilkan. Bagian ini juga menentukan struktur output laporan.

Kriteria yang digunakan bergantung pada jenis laporan. Hubungan antara jenis laporan dan kriteria dijelaskan dalam tabel berikut:

Jenis laporan	Kolom kriteria
STANDAR	kriteria
REACH	reachCriteria
PATH_TO_CONVERSION	pathToConversionCriteria
FLOODLIGHT	kriteria cahaya banjir
CROSS_DIMENSION_REACH	crossDimensionReachCriteria

Meskipun masing-masing kriteria khusus jenis ini mengekspos kumpulan kolom yang sedikit berbeda, ada serangkaian kolom kriteria umum yang umumnya berguna untuk mengontrol output laporan:

Kolom	Deskripsi
rentang tanggal	Tanggal pelaksanaan laporan ini. Dapat digunakan untuk menentukan tanggal mulai dan akhir kustom atau rentang tanggal relatif. Catatan: Saat menjalankan laporan melalui API, rentang tanggal relatif seperti YESTERDAY diselesaikan dalam zona waktu Amerika/Los Angeles. Hal ini dapat menyebabkan hasil yang tidak terduga bagi pengguna di zona waktu yang berbeda-beda.
DimensiFilters	Daftar filter yang membatasi hasil yang ditampilkan. Lihat bagian nilai filter kueri untuk informasi selengkapnya tentang cara mengonfigurasi filter.
dimensi	Daftar elemen Campaign Manager 360 yang akan disertakan dalam output laporan.
nama metrik	Satuan ukuran standar untuk disertakan dalam output laporan.

Lihat bagian menentukan kompatibilitas kolom untuk informasi selengkapnya tentang memilih dimensi, metrik, dan filter untuk laporan. Kolom kriteria khusus jenis tambahan dijelaskan dalam dokumentasi referensi dan pusat bantuan.

Contoh di bawah menambahkan kriteria dasar ke referensi laporan standar kami:

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

Nilai filter kueri

Saat mengonfigurasi filter untuk laporan, Anda harus menentukan nilai persis yang akan digunakan filter untuk membatasi output laporan. Jika Anda tidak yakin nilai yang mungkin untuk filter tertentu, cari nilai tersebut menggunakan layanan DimensionValues.

Kueri nilai dimensi dasar berisi nama dimensi, serta tanggal mulai dan tanggal akhir. Tanggal mulai dan akhir membatasi respons terhadap nilai yang valid dalam jangka waktu tersebut. Filter tambahan dapat ditentukan jika Anda perlu membatasi hasil kueri lebih lanjut.

Contoh di bawah ini mencari nilai filter pengiklan yang valid selama tanggal saat laporan kami akan dijalankan dan menambahkannya ke kriteria laporan:

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

Menentukan kompatibilitas kolom

Saat mengonfigurasi kriteria laporan, penting untuk diingat bahwa tidak semua kombinasi metrik, dimensi, dan filter valid. Anda tidak akan diizinkan untuk menyimpan laporan yang berisi kombinasi yang tidak valid, sehingga penting untuk memastikan kolom yang akan digunakan kompatibel satu sama lain.

Saat membuat resource laporan, Anda dapat meneruskannya ke layanan Reports.compatibleFields untuk melihat kolom yang valid berdasarkan kolom yang telah Anda pilih. Konfigurasi laporan akan dianalisis, dan respons yang berisi dimensi, metrik, dan filter yang kompatibel akan ditampilkan. Karena kolom dalam respons ini tidak semuanya dijamin kompatibel satu sama lain, Anda mungkin harus membuat beberapa permintaan untuk memastikan semua kolom yang dipilih akan berfungsi bersama-sama.

Contoh di bawah menggambarkan cara membuat sampel permintaan kolom yang kompatibel, menggunakan referensi laporan kami sebagai input:

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

Menyimpan laporan

Langkah terakhir dalam proses ini adalah menyimpan aset laporan. Jika membuat laporan baru, Anda dapat menyisipkannya dengan panggilan ke 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)

Jika melakukan update sebagian, Anda dapat menyimpan perubahan dengan memanggil 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)

Atau, jika memutuskan untuk melakukan update penuh, Anda dapat menyimpan perubahan dengan memanggil 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);

Setelah permintaan simpan berhasil, salinan aset laporan akan dikembalikan dalam isi respons. Resource ini akan memiliki beberapa kolom baru yang terisi, dan yang terpenting adalah kolom id. ID ini adalah ID yang akan Anda gunakan untuk merujuk ke laporan ini di seluruh alur kerja Anda lainnya.