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 secara mendetail cara membuat dan memperbarui laporan Pembuat Laporan secara terprogram melalui layanan Laporan.

Catatan: Membuat laporan yang valid bukanlah tugas yang mudah. Beberapa subset 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 resource laporan

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

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

Isi yang tepat dari resource laporan bervariasi, bergantung pada jenis laporan yang Anda konfigurasi. Meski begitu, ada beberapa kolom yang umum untuk semua jenis laporan:

Kolom	Deskripsi
Kolom wajib diisi
nama	Nama laporan.
jenis	Jenis laporan.
Kolom opsional
pesan antar	Setelan pengiriman email laporan.
fileName	Nama file yang digunakan saat membuat file laporan untuk laporan ini.
format	Format output laporan, baik CSV maupun Excel.
jadwal	Jadwal yang digunakan untuk menjalankan laporan Anda secara berulang.

Kolom umum ini membentuk kerangka laporan Anda. Contoh di bawah mengilustrasikan pembuatan resource laporan standar 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 selanjutnya adalah menentukan kriteria laporan. Kriteria laporan digunakan untuk membatasi cakupan laporan, sehingga hanya informasi yang relevan yang ditampilkan. File 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
STANDARD	kriteria
REACH	reachCriteria
PATH_TO_CONVERSION	pathToConversionCriteria
FLOODLIGHT	floodlightCriteria
CROSS_DIMENSION_REACH	crossDimensionReachCriteria

Meskipun setiap kriteria khusus jenis ini menampilkan serangkaian kolom yang sedikit berbeda, ada serangkaian kolom kriteria umum yang umumnya berguna untuk mengontrol output laporan:

Kolom	Deskripsi
dateRange	Tanggal laporan ini harus dijalankan. 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 Serikat/Los Angeles. Hal ini dapat menyebabkan hasil yang tidak terduga bagi pengguna di zona waktu yang berbeda.
dimensionFilters	Daftar filter yang membatasi hasil yang ditampilkan. Lihat bagian nilai filter kueri untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi filter.
dimensi	Daftar elemen Campaign Manager 360 yang akan disertakan dalam output laporan.
metricNames	Satuan ukuran standar yang akan disertakan dalam output laporan.

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

Contoh di bawah ini menambahkan kriteria dasar ke resource laporan standar:

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 apa saja kemungkinan nilai 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 ke 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 laporan 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 menyimpan laporan yang berisi kombinasi tidak valid, jadi pastikan kolom yang akan Anda gunakan kompatibel satu sama lain.

Saat membuat resource laporan, Anda dapat meneruskannya ke layanan Reports.compatibleFields untuk melihat kolom mana 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 perlu membuat beberapa permintaan untuk memastikan semua kolom yang Anda pilih akan berfungsi bersama.

Contoh di bawah mengilustrasikan cara membuat permintaan kolom yang kompatibel untuk sampel, menggunakan resource 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

Simpan laporan

Langkah terakhir dalam proses ini adalah menyimpan resource laporan Anda. Jika Anda 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 Anda telah 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 penyimpanan berhasil, salinan resource laporan akan ditampilkan dalam isi respons. Resource ini akan memiliki beberapa kolom baru yang diisi, yang paling penting adalah kolom id. ID ini adalah yang akan Anda gunakan untuk merujuk ke laporan ini di seluruh alur kerja Anda.