YouTube Reporting API - System-Managed Reports

YouTube otomatis membuat serangkaian laporan pendapatan iklan yang dikelola sistem untuk pemilik konten yang memiliki akses ke laporan terkait di Creator Studio. Laporan ini dirancang untuk memberikan akses terprogram ke data yang juga tersedia dalam laporan yang dapat didownload secara manual yang dapat diakses di menu Laporan di YouTube Creator Studio.

Catatan: API ini memberikan akses ke kumpulan laporan yang berbeda dengan Creator Studio, meskipun laporan tersebut berisi data yang serupa. Laporan API mungkin memiliki kolom yang berbeda dan juga menggunakan nama kolom yang berbeda dari laporan Creator Studio.

Karena YouTube secara otomatis membuat laporan yang dikelola sistem, proses untuk mengambil laporan ini berbeda dengan proses untuk laporan data massal YouTube Analytics yang tersedia melalui API.

Mengambil laporan

Langkah berikut menjelaskan cara mengambil laporan yang dikelola sistem melalui API.

Langkah 1: Ambil kredensial otorisasi

Semua permintaan YouTube Reporting API harus diberi otorisasi. Panduan Otorisasi menjelaskan cara menggunakan protokol OAuth 2.0 untuk mengambil token otorisasi.

Permintaan YouTube Reporting API menggunakan cakupan otorisasi berikut:

Cakupan
https://www.googleapis.com/auth/yt-analytics.readonly Melihat laporan YouTube Analytics untuk konten YouTube Anda. Cakupan ini memberikan akses ke metrik aktivitas pengguna, seperti jumlah penayangan dan jumlah rating.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Melihat laporan moneter YouTube Analytics untuk konten YouTube Anda. Cakupan ini memberikan akses ke metrik aktivitas pengguna serta estimasi pendapatan dan metrik performa iklan.

Langkah 2: Ambil ID pekerjaan untuk laporan yang diinginkan

Panggil metode jobs.list untuk mengambil daftar tugas yang dikelola sistem. Setel parameter includeSystemManaged ke true.

Properti reportTypeId di setiap resource Job yang ditampilkan mengidentifikasi jenis laporan yang dikelola sistem yang terkait dengan tugas tersebut. Aplikasi Anda memerlukan nilai properti id dari resource yang sama pada langkah berikut.

Dokumen Laporan mencantumkan laporan yang tersedia, ID jenis laporannya, dan kolom yang ada di dalamnya. Anda juga dapat menggunakan metode reportTypes.list untuk mengambil daftar jenis laporan yang didukung.

Langkah 3: Ambil URL download laporan

Panggil metode jobs.reports.list guna mengambil daftar laporan yang dibuat untuk tugas. Dalam permintaan, tetapkan parameter jobId ke ID tugas laporan yang ingin Anda ambil.

Anda dapat memfilter daftar laporan menggunakan salah satu atau semua parameter berikut:

  • Gunakan parameter createdAfter untuk menunjukkan bahwa API hanya boleh menampilkan laporan yang dibuat setelah waktu yang ditentukan. Parameter ini dapat digunakan untuk memastikan bahwa API hanya menampilkan laporan yang belum Anda proses.

  • Gunakan parameter startTimeBefore untuk menunjukkan bahwa respons API hanya boleh berisi laporan jika data paling awal dalam laporan adalah sebelum tanggal yang ditentukan. Jika parameter createdAfter berkaitan dengan waktu pembuatan laporan, tanggal ini berkaitan dengan data dalam laporan.

  • Gunakan parameter startTimeAtOrAfter untuk menunjukkan bahwa respons API hanya boleh berisi laporan jika data paling awal dalam laporan pada atau setelah tanggal yang ditentukan. Seperti parameter startTimeBefore, nilai parameter ini sesuai dengan data dalam laporan, bukan waktu laporan dibuat.

Respons API berisi daftar resource Report untuk tugas tersebut. Setiap sumber daya mengacu pada laporan yang berisi data untuk periode tertentu.

  • Properti startTime dan endTime resource mengidentifikasi jangka waktu yang dicakup oleh data laporan.
  • Properti downloadUrl resource mengidentifikasi URL tempat laporan dapat diambil.

  • Properti createTime resource menentukan tanggal dan waktu saat laporan dibuat. Aplikasi Anda harus menyimpan nilai ini dan menggunakannya untuk menentukan apakah laporan yang didownload sebelumnya telah berubah.

Langkah 4: Download laporan

Kirim permintaan HTTP GET ke downloadUrl yang diperoleh pada langkah 4 untuk mengambil laporan.

Memproses laporan

Praktik terbaik

Aplikasi yang menggunakan YouTube Reporting API selalu mengikuti praktik berikut:

  • Gunakan baris header laporan untuk menentukan urutan kolom laporan. Misalnya, jangan asumsikan bahwa tampilan akan menjadi metrik pertama yang ditampilkan dalam laporan hanya karena ini adalah metrik pertama yang tercantum dalam deskripsi laporan. Sebagai gantinya, gunakan baris header laporan untuk menentukan kolom yang berisi data tersebut.

  • Catat laporan yang telah Anda download agar tidak berulang kali memproses laporan yang sama. Daftar berikut menyarankan beberapa cara untuk melakukannya.

    • Saat memanggil metode reports.list, gunakan parameter createdAfter untuk hanya mengambil laporan yang dibuat setelah tanggal tertentu. (Hapus parameter createdAfter saat pertama kali Anda mengambil laporan.)

      Setiap kali Anda mengambil dan berhasil memproses laporan, simpan stempel waktu yang sesuai dengan tanggal dan waktu saat laporan terbaru dibuat. Kemudian, perbarui nilai parameter createdAfter pada setiap panggilan berturut-turut ke metode reports.list untuk memastikan bahwa Anda hanya mengambil laporan baru, termasuk laporan baru dengan data yang diisi ulang, setiap kali Anda memanggil API.

      Sebagai perlindungan, sebelum mengambil laporan, periksa juga untuk memastikan bahwa ID laporan belum tercantum dalam database Anda.

    • Simpan ID untuk setiap laporan yang telah Anda download dan proses. Anda juga dapat menyimpan informasi tambahan seperti tanggal dan waktu saat setiap laporan dibuat atau startTime dan endTime laporan, yang bersama-sama mengidentifikasi periode laporan berisi data. Untuk laporan yang mengambil data massal untuk YouTube Analytics, setiap tugas kemungkinan akan memiliki banyak laporan karena setiap laporan berisi data untuk periode 24 jam. Tugas yang dikelola sistem yang mencakup jangka waktu yang lebih lama akan memiliki lebih sedikit laporan.

      Gunakan ID laporan untuk mengidentifikasi laporan yang masih harus Anda download dan impor. Namun, jika dua laporan baru memiliki nilai properti startTime dan endTime yang sama, hanya impor laporan dengan nilai createTime yang lebih baru.

Karakteristik laporan

Laporan API adalah file .csv (nilai yang dipisahkan koma) berversi yang memiliki karakteristik berikut:

  • Setiap laporan berisi data untuk periode unik yang berlangsung dari pukul 00.00 waktu Pasifik pada tanggal mulai laporan hingga pukul 23.59 waktu Pasifik pada tanggal akhir laporan.

  • Data laporan tidak diurutkan.