Halaman ini diterjemahkan oleh Cloud Translation API.

Membuat dan Memperbarui Laporan

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

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

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 referensi kosong dan menetapkan kolom yang diperlukan. Jika memperbarui laporan yang sudah ada, Anda dapat memilih untuk:

Lebih disukai: Menjalankan pembaruan parsial. Dengan menggunakan pendekatan ini, Anda akan memulai dengan resource kosong dan menetapkan kolom yang ingin diubah. Update parsial hanya menyimpan perubahan pada kolom yang Anda tentukan.
Melakukan update lengkap. Dengan pendekatan ini, Anda akan memuat referensi laporan yang ada dan langsung mengubah kolomnya. Pembaruan lengkap selalu menyimpan semua kolom laporan.

Konten yang tepat dari resource laporan bervariasi bergantung pada jenis laporan yang Anda konfigurasi. Meski begitu, ada beberapa kolom yang bersifat 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 hasil 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 referensi 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 bidang umum, langkah berikutnya adalah menentukan kriteria laporan. Kriteria laporan digunakan untuk membatasi cakupan laporan Anda, memastikan hanya informasi relevan yang ditampilkan. Tag Assistant juga menentukan struktur output laporan.

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

Jenis laporan	Kolom kriteria
STANDAR	kriteria
REACH	reachCriteria
PATH_TO_CONVERSION	pathToConversionCriteria
SOROTAN	floodlightCriteria
CROSS_DIMENSION_REACH	crossDimensionReachCriteria

Meskipun setiap kriteria spesifik per jenis ini menampilkan kumpulan kolom yang sedikit berbeda, ada sekumpulan kolom kriteria umum yang umumnya berguna untuk mengontrol output laporan:

Kolom	Deskripsi
dateRange	Tanggal kapan 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/Los Angeles. Hal ini dapat menyebabkan hasil yang tidak diharapkan 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 menentukan kompatibilitas kolom untuk mendapatkan 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 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 yang tepat yang akan digunakan filter untuk membatasi hasil laporan. Jika Anda tidak yakin dengan nilai yang mungkin untuk filter tertentu, cari 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 mencari nilai filter pengiklan yang valid selama tanggal laporan kami akan berjalan 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, perhatikan bahwa tidak semua kombinasi metrik, dimensi, dan filter valid. Anda tidak akan diizinkan untuk menyimpan laporan yang berisi kombinasi tidak valid, jadi Anda harus memastikan kolom yang akan digunakan kompatibel satu sama lain.

Saat membuat resource laporan, Anda dapat meneruskannya ke layanan Reports.compatibleFields untuk melihat kolom mana yang valid berdasarkan 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 dipilih akan berfungsi bersama.

Contoh di bawah mengilustrasikan cara membuat contoh 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

Simpan laporan

Langkah terakhir dalam proses ini adalah menyimpan referensi laporan Anda. 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 parsial, 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 telah memutuskan untuk melakukan update lengkap, 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 referensi laporan akan ditampilkan dalam isi respons. Beberapa kolom baru akan terisi pada resource ini, yang paling penting adalah kolom id. ID inilah yang akan Anda gunakan untuk merujuk ke laporan ini di seluruh bagian alur kerja Anda lainnya.

Membuat dan Memperbarui Laporan Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Mengonfigurasi resource laporan

C#

Java

PHP

Python

Ruby

Menentukan kriteria laporan

C#

Java

PHP

Python

Ruby

Nilai filter kueri

C#

Java

PHP

Python

Ruby

Menentukan kompatibilitas kolom

C#

Java

PHP

Python

Ruby

Simpan laporan

C#

Java

PHP

Python

Ruby

C#

Java

PHP

Python

Ruby

C#

Java

PHP

Python

Ruby

Membuat dan Memperbarui Laporan