Ringkasan YouTube Data API

Pengantar

Dokumen ini ditujukan bagi developer yang ingin menulis aplikasi yang berinteraksi dengan YouTube. Panduan ini menjelaskan konsep dasar YouTube dan API itu sendiri. Artikel ini juga memberikan ringkasan tentang berbagai fungsi yang didukung API.

Sebelum memulai

  1. Anda memerlukan Akun Google untuk mengakses Konsol API Google, meminta kunci API, dan mendaftarkan aplikasi Anda.

  2. Buat project di Google Developers Console dan dapatkan kredensial otorisasi agar aplikasi Anda dapat mengirimkan permintaan API.

  3. Setelah membuat project, pastikan YouTube Data API adalah salah satu layanan tempat aplikasi Anda terdaftar untuk digunakan:

    1. Buka Konsol API dan pilih project yang baru saja Anda daftarkan.
    2. Kunjungi halaman API yang Aktif. Dalam daftar API, pastikan statusnya AKTIF untuk YouTube Data API v3.

  4. Jika aplikasi Anda akan menggunakan metode API mana pun yang mewajibkan otorisasi pengguna, baca panduan autentikasi untuk mempelajari cara menerapkan otorisasi OAuth 2.0.

  5. Pilih pustaka klien untuk memudahkan Anda dalam menerapkan API.

  6. Pelajari konsep inti format data JSON (JavaScript Object Notation). JSON adalah format data umum independen bahasa yang memberikan representasi teks sederhana untuk struktur data arbitrer. Untuk informasi selengkapnya, buka json.org.

Resource dan jenis resource

Resource adalah entity data individual dengan ID unik. Tabel di bawah ini menjelaskan berbagai jenis resource yang dapat berinteraksi dengan Anda menggunakan API.

Referensi
activity Berisi informasi tentang tindakan yang telah dilakukan pengguna tertentu di situs YouTube. Tindakan pengguna yang dilaporkan dalam feed aktivitas antara lain memberi rating video, berbagi video, menandai video sebagai favorit, dan memposting buletin channel.
channel Berisi informasi tentang satu channel YouTube.
channelBanner Mengidentifikasi URL yang akan digunakan untuk menetapkan gambar yang baru diupload sebagai gambar banner untuk channel.
channelSection Berisi informasi tentang sekumpulan video yang telah dipilih channel untuk ditampilkan. Misalnya, bagian dapat menampilkan upload terbaru, upload paling populer, atau video dari satu atau beberapa playlist.
guideCategory Mengidentifikasi kategori yang dikaitkan oleh YouTube dengan channel berdasarkan konten atau indikator lainnya, seperti popularitas. Kategori panduan berusaha mengatur channel dengan cara yang memudahkan pengguna YouTube menemukan konten yang mereka cari. Meskipun dapat dikaitkan dengan satu atau beberapa kategori panduan, channel tidak dijamin berada di kategori panduan mana pun.
i18nLanguage Mengidentifikasi bahasa aplikasi yang didukung situs YouTube. Bahasa aplikasi juga dapat disebut sebagai bahasa UI.
i18nRegion Mengidentifikasi area geografis yang dapat dipilih pengguna YouTube sebagai wilayah konten pilihan. Wilayah konten juga dapat disebut lokalitas konten.
playlist Mewakili satu playlist YouTube. Playlist adalah kumpulan video yang dapat ditonton secara berurutan dan dibagikan kepada pengguna lain.
playlistItem Mengidentifikasi resource, seperti video, yang merupakan bagian dari playlist. Resource playlistItem juga berisi detail yang menjelaskan cara penggunaan resource yang disertakan dalam playlist.
search result Berisi informasi tentang video, channel, atau playlist YouTube yang cocok dengan parameter penelusuran yang ditentukan dalam permintaan API. Meskipun hasil penelusuran mengarah ke resource yang dapat diidentifikasi secara unik, seperti video, hasil penelusuran tersebut tidak memiliki data persisten sendiri.
subscription Berisi informasi tentang langganan pengguna YouTube. Subscription memberi tahu pengguna jika ada video baru yang ditambahkan ke channel atau saat pengguna lain melakukan salah satu dari beberapa tindakan di YouTube, seperti mengupload video, memberi rating video, atau mengomentari video.
thumbnail Mengidentifikasi gambar thumbnail yang terkait dengan resource.
video Mewakili satu video YouTube.
videoCategory Mengidentifikasi kategori yang telah atau dapat dikaitkan dengan video yang diupload.
watermark Mengidentifikasi gambar yang ditampilkan selama pemutaran video channel tertentu. Pemilik channel juga dapat menentukan channel target yang ditautkan dengan gambar serta detail pengaturan waktu yang menentukan kapan watermark muncul selama pemutaran video dan lama waktu kemunculannya.

Perlu diketahui bahwa dalam banyak kasus, resource berisi referensi ke resource lainnya. Misalnya, properti snippet.resourceId.videoId resource playlistItem mengidentifikasi resource video yang berisi informasi lengkap tentang video tersebut. Sebagai contoh lainnya, hasil penelusuran berisi properti videoId, playlistId, atau channelId yang mengidentifikasi resource video, playlist, atau channel tertentu.

Operasi yang didukung

Tabel berikut menunjukkan metode paling umum yang didukung API. Beberapa resource juga mendukung metode lain yang menjalankan fungsi secara lebih spesifik untuk resource tersebut. Misalnya, metode videos.rate mengaitkan rating pengguna dengan video, sedangkan metode thumbnails.set mengupload gambar thumbnail video ke YouTube dan mengaitkannya dengan video.

Operasi
list Mengambil (GET) daftar nol atau beberapa resource.
insert Membuat (POST) resource baru.
update Memodifikasi (PUT) resource yang ada untuk mencerminkan data dalam permintaan Anda.
delete Menghapus (DELETE) resource tertentu.

API tersebut saat ini mendukung metode untuk mencantumkan setiap jenis resource yang didukung, dan API ini juga mendukung operasi tulis untuk banyak resource.

Tabel di bawah ini mengidentifikasi operasi yang didukung untuk berbagai jenis resource. Operasi yang menyisipkan, memperbarui, atau menghapus resource selalu memerlukan otorisasi pengguna. Dalam beberapa kasus, metode list mendukung permintaan yang diotorisasi dan tidak sah. Permintaan yang tidak sah hanya akan mengambil data publik sedangkan permintaan yang diizinkan juga dapat mengambil informasi tentang atau pribadi bagi pengguna yang saat ini diautentikasi.

Operasi yang Didukung
list insert update delete
activity
caption
channel
channelBanner
channelSection
comment
commentThread
guideCategory
i18nLanguage
i18nRegion
playlist
playlistItem
search result
subscription
thumbnail
video
videoCategory
watermark

Penggunaan kuota

YouTube Data API menggunakan kuota untuk memastikan bahwa developer menggunakan layanan sebagaimana mestinya dan tidak membuat aplikasi yang secara tidak adil mengurangi kualitas layanan atau membatasi akses untuk orang lain. Semua permintaan API, termasuk permintaan yang tidak valid, dikenai setidaknya biaya kuota satu poin. Anda dapat menemukan kuota yang tersedia untuk aplikasi Anda di API Console.

Project yang mengaktifkan YouTube Data API memiliki alokasi kuota default 10.000 unit per hari, jumlah yang cukup untuk sebagian besar pengguna API kami. Kuota default, yang dapat berubah-ubah, membantu kami mengoptimalkan alokasi kuota dan menskalakan infrastruktur dengan cara yang lebih bermanfaat bagi pengguna API. Anda dapat melihat penggunaan kuota di halaman Quotas di Konsol API.

Catatan: Jika mencapai batas kuota, Anda dapat meminta kuota tambahan dengan mengisi formulir Permintaan perpanjangan kuota untuk Layanan YouTube API.

Menghitung penggunaan kuota

Google menghitung penggunaan kuota Anda dengan menetapkan biaya untuk setiap permintaan. Berbagai jenis operasi memiliki biaya kuota yang berbeda. Contoh:

  • Operasi baca yang mengambil daftar resource -- channel, video, playlist -- biasanya berharga 1 unit.
  • Operasi tulis yang membuat, memperbarui, atau menghapus resource biasanya memiliki biaya unit 50.
  • Permintaan penelusuran berharga 100 unit.
  • Biaya upload video sebesar 1600 unit.

Tabel Kuota biaya untuk permintaan API menampilkan biaya kuota setiap metode API. Dengan memperhatikan aturan ini, Anda dapat memperkirakan jumlah permintaan yang dapat dikirim aplikasi per hari tanpa melebihi kuota.

Resource parsial

API memungkinkan, dan benar-benar memerlukan, pengambilan resource sebagian sehingga aplikasi dapat menghindari transfer, penguraian, dan penyimpanan data yang tidak diperlukan. Pendekatan ini juga memastikan bahwa API menggunakan resource jaringan, CPU, dan memori secara lebih efisien.

API ini mendukung dua parameter permintaan, yang dijelaskan di bagian berikut, yang memungkinkan Anda mengidentifikasi properti resource yang harus disertakan dalam respons API.

  • Parameter part mengidentifikasi grup properti yang harus ditampilkan untuk resource.
  • Parameter fields memfilter respons API untuk hanya menampilkan properti tertentu dalam bagian resource yang diminta.

Cara menggunakan parameter part

Parameter part adalah parameter wajib untuk setiap permintaan API yang mengambil atau menampilkan resource. Parameter ini mengidentifikasi satu atau beberapa properti resource tingkat atas (tidak bertingkat) yang harus disertakan dalam respons API. Misalnya, resource video memiliki bagian berikut:

  • snippet
  • contentDetails
  • fileDetails
  • player
  • processingDetails
  • recordingDetails
  • statistics
  • status
  • suggestions
  • topicDetails

Semua bagian ini adalah objek yang berisi properti bertingkat, dan Anda dapat menganggap objek ini sebagai kelompok kolom metadata yang mungkin diambil (atau tidak) diambil oleh server API. Dengan demikian, parameter part mengharuskan Anda memilih komponen resource yang benar-benar digunakan aplikasi Anda. Persyaratan ini memiliki dua tujuan utama:

  • SSO mengurangi latensi dengan mencegah server API menghabiskan waktu untuk mengambil kolom metadata yang tidak digunakan aplikasi Anda.
  • Teknologi tersebut mengurangi penggunaan bandwidth dengan mengurangi (atau menghilangkan) jumlah data tidak perlu yang mungkin diambil oleh aplikasi Anda.

Seiring waktu, seiring bertambahnya bagian dari resource, manfaat ini hanya akan bertambah karena aplikasi Anda tidak akan meminta properti baru yang tidak didukungnya.

Cara menggunakan parameter fields

Parameter fields memfilter respons API, yang hanya berisi bagian resource yang diidentifikasi dalam nilai parameter part, sehingga respons hanya menyertakan kumpulan kolom tertentu. Parameter fields memungkinkan Anda menghapus properti bertingkat dari respons API sehingga semakin mengurangi penggunaan bandwidth. (Parameter part tidak dapat digunakan untuk memfilter properti bertingkat dari respons.)

Aturan berikut menjelaskan sintaksis yang didukung untuk nilai parameter fields, yang secara longgar didasarkan pada sintaksis XPath:

  • Gunakan daftar yang dipisahkan koma (fields=a,b) untuk memilih beberapa kolom.
  • Gunakan tanda bintang (fields=*) sebagai karakter pengganti untuk mengidentifikasi semua kolom.
  • Gunakan tanda kurung (fields=a(b,c)) untuk menentukan grup properti bertingkat yang akan disertakan dalam respons API.
  • Gunakan garis miring (fields=a/b) untuk mengidentifikasi properti bertingkat.

Dalam praktiknya, aturan ini sering kali mengizinkan beberapa nilai parameter fields yang berbeda untuk mengambil respons API yang sama. Misalnya, jika ingin mengambil ID, judul, dan posisi item playlist untuk setiap item dalam playlist, Anda dapat menggunakan salah satu nilai berikut:

  • fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
  • fields=items(id,snippet/title,snippet/position)
  • fields=items(id,snippet(title,position))

Catatan: Seperti semua nilai parameter kueri, nilai parameter fields harus dienkode ke URL. Agar lebih mudah dibaca, contoh dalam dokumen ini menghilangkan encoding.

Contoh permintaan sebagian

Contoh di bawah menunjukkan cara menggunakan parameter part dan fields untuk memastikan bahwa respons API hanya menyertakan data yang digunakan aplikasi Anda:

  1. Contoh 1 menampilkan resource video yang menyertakan empat bagian serta properti kind dan etag.
  2. Contoh 2 menampilkan resource video yang berisi dua bagian serta properti kind dan etag.
  3. Contoh 3 menampilkan resource video yang menyertakan dua bagian, tetapi tidak menyertakan properti kind dan etag.
  4. Contoh 4 menampilkan resource video yang menyertakan dua bagian, tetapi mengecualikan kind dan etag serta beberapa properti bertingkat di objek snippet resource.
Contoh 1
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,contentDetails,statistics,status

Description: This example retrieves a video resource and identifies several
             resource parts that should be included in the API response.

API response:


{ 
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "contentDetails": {
    "duration": "PT15M51S",
    "aspectRatio": "RATIO_16_9"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   },
   "status": {
    "uploadStatus": "STATUS_PROCESSED",
    "privacyStatus": "PRIVACY_PUBLIC"
   }
  }
 ]
}
Contoh 2
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics

Description: This example modifies the part parameter value so that the
             contentDetails and status properties are not included
             in the response.

API response:


{ 
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}
Contoh 3
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics&fields=items(id,snippet,statistics)

Description: This example adds the fields parameter to remove all
             kind and etag properties from the API response.

API response:


{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}
Contoh 4
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &fields=items(id,snippet(channelId,title,categoryId),statistics)&part=snippet,statistics

Description: This example modifies the fields parameter from example 3
             so that in the API response, each video resource's snippet
             object only includes the channelId, title,
             and categoryId properties.

API response:


{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": { 
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

Mengoptimalkan performa

Menggunakan ETag

ETags, bagian standar dari protokol HTTP, memungkinkan aplikasi merujuk ke versi spesifik dari resource API tertentu. Resource dapat berupa seluruh feed atau item dalam feed tersebut. Fungsi ini mendukung kasus penggunaan berikut:

  • Menyimpan ke cache dan pengambilan bersyarat – Aplikasi Anda dapat menyimpan resource API dan ETag-nya dalam cache. Kemudian, ketika kembali meminta resource yang tersimpan, aplikasi akan menentukan ETag yang terkait dengan resource tersebut. Jika resource telah berubah, API akan menampilkan resource yang telah dimodifikasi dan ETag yang terkait dengan versi resource tersebut. Jika resource tidak berubah, API akan menampilkan respons HTTP 304 (Not Modified), yang menunjukkan bahwa resource belum berubah. Aplikasi Anda dapat mengurangi latensi dan penggunaan bandwidth dengan menyajikan resource yang di-cache melalui cara ini.

    Library klien untuk Google API berbeda dalam dukungan ETag-nya. Misalnya, library klien JavaScript mendukung ETag melalui daftar yang diizinkan untuk header permintaan yang diizinkan yang mencakup If-Match dan If-None-Match. Daftar yang diizinkan memungkinkan terjadinya cache browser normal sehingga jika ETag sumber daya belum berubah, sumber daya bisa disalurkan dari cache browser. Di sisi lain, klien Obj-C tidak mendukung ETag.

  • Melindungi dari penimpaan perubahan yang tidak disengaja – ETag membantu memastikan bahwa beberapa klien API tidak saling menimpa perubahan yang dilakukan tanpa sengaja. Saat memperbarui atau menghapus resource, aplikasi Anda bisa menentukan ETag resource. Jika ETag tidak sesuai dengan versi terbaru resource tersebut, permintaan API akan gagal.

Penggunaan ETag dalam aplikasi Anda akan memberikan beberapa manfaat:

  • API merespons lebih cepat permintaan untuk resource yang di-cache tetapi tidak berubah, sehingga menghasilkan latensi lebih rendah dan penggunaan bandwidth yang lebih rendah.
  • Aplikasi Anda tidak akan menimpa perubahan pada resource yang dibuat dari klien API lain tanpa sengaja.

Google APIs Client Library for JavaScript mendukung header permintaan HTTP If-Match dan If-None-Match, sehingga ETag dapat berfungsi dalam konteks caching browser normal.

Menggunakan gzip

Anda juga dapat mengurangi bandwidth yang diperlukan untuk setiap respons API dengan mengaktifkan kompresi gzip. Meskipun aplikasi Anda akan membutuhkan waktu CPU tambahan untuk membatalkan kompresi respons API, manfaat menggunakan resource jaringan yang lebih sedikit biasanya lebih besar daripada biaya tersebut.

Untuk menerima respons yang dienkode dengan gzip, Anda harus melakukan dua hal:

  • Tetapkan header permintaan HTTP Accept-Encoding ke gzip.
  • Ubah agen pengguna agar memuat string gzip.

Contoh header HTTP di bawah ini menunjukkan persyaratan berikut untuk mengaktifkan kompresi gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)