Ringkasan YouTube Data API

Pengantar

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

Sebelum memulai

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

  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 oleh aplikasi Anda untuk digunakan:

    1. Buka Konsol API dan pilih project yang baru saja Anda daftarkan.
    2. Buka halaman APIs diaktifkan. 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 setiap entitas data dengan ID unik. Tabel di bawah ini menjelaskan berbagai jenis resource yang dapat Anda gunakan menggunakan API.

Resource
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 serangkaian video yang telah dipilih untuk ditampilkan oleh channel. Misalnya, bagian dapat menampilkan upload terbaru channel, upload terpopuler, atau video dari satu atau beberapa playlist.
guideCategory Mengidentifikasi kategori yang dikaitkan oleh YouTube dengan channel berdasarkan kontennya atau indikator lainnya, seperti popularitas. Kategori panduan berupaya mengatur channel dengan cara yang memudahkan pengguna YouTube untuk menemukan konten yang mereka cari. Meskipun channel dapat dikaitkan dengan satu atau beberapa kategori panduan, channel tersebut tidak dijamin berada dalam kategori panduan apa 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. Region konten juga dapat disebut sebagai lokalitas konten.
playlist Merepresentasikan 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 dikenali secara unik, seperti video, resource tersebut tidak memiliki data persisten 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 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 dari saluran yang ditentukan. Pemilik saluran juga dapat menentukan saluran target yang ditautkan ke gambar serta detail pengaturan waktu yang menentukan kapan watermark muncul selama pemutaran video, kemudian durasi penayangannya.

Perhatikan bahwa, dalam banyak kasus, resource berisi referensi ke resource lain. Misalnya, properti snippet.resourceId.videoId pada 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 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.

Operasional
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 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 sementara permintaan yang sah juga dapat mengambil informasi tentang atau bersifat 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 sebagaimana mestinya dan tidak membuat aplikasi yang mengurangi kualitas layanan secara tidak adil atau membatasi akses bagi orang lain. Semua permintaan API, termasuk permintaan yang tidak valid, akan menimbulkan setidaknya biaya kuota satu poin. Anda dapat menemukan kuota yang tersedia untuk aplikasi di API Console.

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

Catatan: Jika mencapai batas kuota, Anda dapat meminta kuota tambahan dengan melengkapi Formulir permintaan ekstensi 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, mengupdate, atau menghapus resource biasanya memiliki biaya 50 unit.
  • Permintaan penelusuran memerlukan biaya 100 unit.
  • Upload video memerlukan 1600 unit.

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

Resource parsial

API memungkinkan, dan sebenarnya memerlukan, pengambilan resource parsial, sehingga aplikasi 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 level teratas (non-nested) yang harus disertakan dalam respons API. Misalnya, resource video memiliki bagian-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 dapat (atau mungkin 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:

  • API ini mengurangi latensi dengan mencegah server API menghabiskan waktu untuk mengambil kolom metadata yang tidak digunakan oleh aplikasi Anda.
  • Mengurangi penggunaan bandwidth dengan mengurangi (atau menghilangkan) jumlah data yang tidak diperlukan 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 kumpulan kolom tertentu. Parameter fields memungkinkan Anda menghapus properti bertingkat dari respons API sehingga mengurangi penggunaan bandwidth Anda lebih lanjut. (Parameter part tidak dapat digunakan untuk memfilter properti bertingkat dari respons.)

Aturan berikut menjelaskan sintaksis yang didukung untuk parameter value 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 sekumpulan 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 parameter value 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 URL. Untuk keterbacaan yang lebih baik, contoh dalam dokumen ini menghapus 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 mencakup properti kind dan etag.
  4. Contoh 4 menampilkan resource video yang menyertakan dua bagian, tetapi tidak mencakup 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, yang merupakan bagian standar dari protokol HTTP, memungkinkan aplikasi untuk merujuk ke versi tertentu dari resource API tertentu. Resource dapat berupa seluruh feed atau item dalam feed tersebut. Fungsi ini mendukung kasus penggunaan berikut:

  • Pembuatan cache dan pengambilan bersyarat – Aplikasi Anda dapat menyimpan resource API dalam cache dan ETag-nya. Kemudian, ketika meminta kembali resource yang disimpan, aplikasi Anda akan menetapkan ETag yang terkait dengan resource tersebut. Jika resource telah berubah, API akan menampilkan resource yang telah diubah 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 menyalurkan resource yang di-cache dengan cara ini.

    Library klien untuk Google API berbeda dalam dukungannya untuk ETag. Misalnya, library klien JavaScript mendukung ETag melalui daftar yang diizinkan untuk header permintaan yang diizinkan yang menyertakan If-Match dan If-None-Match. Daftar putih memungkinkan cache browser normal terjadi sehingga jika ETag resource tidak berubah, resource dapat ditayangkan dari cache browser. Di sisi lain, klien Obj-C tidak mendukung ETag.

  • Melindungi dari penggantian perubahan yang tidak disengaja – ETag membantu memastikan bahwa beberapa klien API tidak menimpa perubahan satu sama lain secara tidak sengaja. Saat memperbarui atau menghapus resource, aplikasi Anda dapat menetapkan ETag resource. Jika ETag tidak cocok dengan versi terbaru resource tersebut, permintaan API akan gagal.

Menggunakan ETag di aplikasi akan memberikan beberapa manfaat:

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

Google APIs Client Library for JavaScript mendukung header permintaan HTTP If-Match dan If-None-Match, sehingga memungkinkan ETag untuk berfungsi dalam konteks 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 membuka 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 Anda untuk berisi string gzip.

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

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