Ringkasan YouTube Data API

Pengantar

Dokumen ini ditujukan bagi developer yang ingin menulis aplikasi yang berinteraksi dengan YouTube. Dokumen ini menjelaskan konsep dasar YouTube dan API itu sendiri. Dokumen ini juga memberikan ringkasan 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 yang didaftarkan untuk digunakan oleh aplikasi Anda:

    1. Buka Konsol API, lalu pilih project yang baru saja Anda daftarkan.
    2. Buka halaman API yang diaktifkan. Dalam daftar API, pastikan status YouTube Data API v3 adalah AKTIF.

  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. Pahami konsep inti format data JSON (JavaScript Object Notation). JSON adalah format data umum yang tidak terikat bahasa yang memberikan representasi teks sederhana untuk struktur data arbitrer. Untuk informasi selengkapnya, buka json.org.

Resource dan jenis resource

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

Resource
activity Berisi informasi tentang tindakan yang telah dilakukan pengguna tertentu di situs YouTube. Tindakan pengguna yang dilaporkan di feed aktivitas mencakup memberi rating pada video, membagikan video, menandai video sebagai favorit, dan memposting buletin channel, serta tindakan lainnya.
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 dipilih channel untuk ditampilkan. Misalnya, bagian dapat menampilkan upload terbaru channel, upload paling populer, atau video dari satu atau beberapa playlist.
guideCategory Mengidentifikasi kategori yang dikaitkan YouTube dengan channel berdasarkan konten atau indikator lainnya, seperti popularitas. Kategori panduan berupaya mengatur channel sedemikian rupa sehingga memudahkan pengguna YouTube menemukan konten yang mereka cari. Meskipun channel dapat dikaitkan dengan satu atau beberapa kategori panduan, channel tersebut tidak dijamin akan 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 sebagai lokalitas konten.
playlist Mewakili satu playlist YouTube. Playlist adalah kumpulan video yang dapat ditonton secara berurutan dan dibagikan kepada pengguna lain.
playlistItem Mengidentifikasi konten, seperti video, yang merupakan bagian dari playlist. Resource playlistItem juga berisi detail yang menjelaskan cara penggunaan konten 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 tidak memiliki data persistennya sendiri.
subscription Berisi informasi tentang langganan pengguna YouTube. Langganan memberi tahu pengguna saat video baru ditambahkan ke channel atau saat pengguna lain melakukan salah satu dari beberapa tindakan di YouTube, seperti mengupload video, memberi rating pada 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 dituju link gambar serta detail waktu yang menentukan kapan tanda air muncul selama pemutaran video dan berapa lama tanda air tersebut terlihat.

Perhatikan bahwa, dalam banyak kasus, resource berisi referensi ke resource lain. Misalnya, properti snippet.resourceId.videoId resource playlistItem mengidentifikasi resource video yang, pada gilirannya, berisi informasi lengkap tentang video tersebut. Sebagai contoh lain, 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 yang lebih spesifik untuk resource tersebut. Misalnya, metode videos.rate mengaitkan rating pengguna dengan video, dan metode thumbnails.set mengupload gambar thumbnail video ke YouTube dan mengaitkannya dengan video.

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

API saat ini mendukung metode untuk mencantumkan setiap jenis resource yang didukung, dan 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 sah dan tidak sah, dengan permintaan yang tidak sah hanya mengambil data publik, sedangkan permintaan yang sah juga dapat mengambil informasi tentang atau pribadi untuk 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 sesuai yang dimaksudkan dan tidak membuat aplikasi yang secara tidak adil mengurangi kualitas layanan atau membatasi akses bagi orang lain. Semua permintaan API, termasuk permintaan yang tidak valid, dikenai biaya kuota minimal satu poin. Anda dapat menemukan kuota yang tersedia untuk aplikasi Anda di API Console.

Project yang mengaktifkan YouTube Data API memiliki alokasi kuota default sebesar 10.000 unit per hari, jumlah yang cukup untuk sebagian besar pengguna API kami. Kuota default, yang dapat berubah, membantu kami mengoptimalkan alokasi kuota dan menskalakan infrastruktur dengan cara yang lebih bermakna bagi pengguna API kami. Anda dapat melihat penggunaan kuota di halaman Kuota 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 berbiaya 1 unit.
  • Operasi tulis yang membuat, memperbarui, atau menghapus resource biasanya dikenai biaya 50 unit.
  • Permintaan penelusuran dikenai biaya 100 unit.
  • Mengupload video memerlukan 100 unit.

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

Aset parsial

API ini memungkinkan, dan sebenarnya memerlukan, pengambilan resource parsial sehingga aplikasi menghindari transfer, parsing, 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 suatu resource.
  • Parameter fields memfilter respons API agar 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 mengidentifikasi satu atau beberapa properti resource tingkat teratas (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 grup kolom metadata yang mungkin (atau mungkin tidak) diambil oleh server API. Oleh karena itu, parameter part mengharuskan Anda memilih komponen resource yang benar-benar digunakan aplikasi Anda. Persyaratan ini memiliki dua tujuan utama:

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

Seiring waktu, saat resource menambahkan lebih banyak bagian, manfaat ini hanya akan meningkat karena aplikasi Anda tidak akan meminta properti yang baru diperkenalkan 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 sekumpulan kolom tertentu. Parameter fields memungkinkan Anda menghapus properti bertingkat dari respons API dan dengan demikian mengurangi penggunaan bandwidth lebih lanjut. (Parameter part tidak dapat digunakan untuk memfilter properti bertingkat dari respons.)

Aturan berikut menjelaskan sintaks yang didukung untuk nilai parameter fields, yang secara longgar didasarkan pada sintaks 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 memungkinkan beberapa nilai parameter fields yang berbeda untuk mengambil respons API yang sama. Misalnya, jika Anda ingin mengambil ID item playlist, judul, dan posisi 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 parameter value kueri, parameter value fields harus berenkode URL. Agar lebih mudah dibaca, contoh dalam dokumen ini tidak mencantumkan 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 mencakup empat bagian serta properti kind dan etag.
  2. Contoh 2 menampilkan resource video yang mencakup 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 mencakup dua bagian, tetapi mengecualikan kind dan etag serta beberapa properti bertingkat dalam 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 tertentu dari resource API tertentu. Resource dapat berupa seluruh feed atau item dalam feed tersebut. Fungsi ini mendukung kasus penggunaan berikut:

  • Caching dan pengambilan bersyarat – Aplikasi Anda dapat menyimpan resource API dan ETag-nya dalam cache. Kemudian, saat aplikasi Anda meminta resource yang disimpan lagi, aplikasi akan menentukan ETag yang terkait dengan resource tersebut. Jika resource telah berubah, API akan menampilkan resource yang 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 tidak berubah. Aplikasi Anda dapat mengurangi latensi dan penggunaan bandwidth dengan menyajikan resource yang di-cache dengan cara ini.

    Library klien untuk Google API berbeda dalam dukungan ETag. 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 penyimpanan cache browser normal terjadi sehingga jika ETag aset tidak berubah, aset dapat ditayangkan 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 secara tidak sengaja. Saat mengupdate atau menghapus resource, aplikasi Anda dapat menentukan ETag resource. Jika ETag tidak cocok dengan versi terbaru resource tersebut, permintaan API akan gagal.

Menggunakan ETag di aplikasi Anda memberikan beberapa manfaat:

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

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

Menggunakan gzip

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

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

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

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

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