YouTube Reporting API - Get Bulk Data 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 dan dapat diakses di menu Laporan di YouTube Creator Studio.

Catatan: API memberikan akses ke serangkaian 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 dengan laporan Creator Studio.

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

Mengambil laporan

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

Langkah 1: Ambil kredensial otorisasi

Semua permintaan YouTube Reporting API harus mendapatkan 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 metrik perkiraan pendapatan dan performa iklan.

Langkah 2: Ambil ID tugas untuk laporan yang diinginkan

Panggil metode jobs.list untuk mengambil daftar tugas yang dikelola sistem. Tetapkan 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 berikutnya.

Dokumen Laporan mencantumkan laporan yang tersedia, ID jenis laporan, 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 untuk 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 satu atau semua parameter berikut:

  • Gunakan parameter createdAfter untuk menunjukkan bahwa API hanya boleh menampilkan laporan yang dibuat setelah waktu tertentu. 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. Sementara 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 adalah 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 resource mengacu pada laporan yang berisi data untuk periode unik.

  • 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 sebelumnya didownload 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 harus selalu mengikuti praktik berikut:

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

  • Simpan catatan laporan yang telah Anda download untuk menghindari pemrosesan laporan yang sama berulang kali. Daftar berikut menyarankan beberapa cara untuk melakukannya.

    • Saat memanggil metode reports.list, gunakan parameter createdAfter untuk hanya mengambil laporan yang dibuat setelah tanggal tertentu. (Abaikan 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 tersebut dibuat. Kemudian, perbarui nilai parameter createdAfter pada setiap panggilan berikutnya 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 pengamanan, 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 yang datanya ada dalam laporan. Untuk laporan yang mengambil data massal untuk YouTube Analytics, setiap tugas kemungkinan akan memiliki banyak laporan karena setiap laporan berisi data untuk jangka waktu 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 perlu Anda download dan impor. Namun, jika dua laporan baru memiliki nilai properti startTime dan endTime yang sama, impor hanya 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.