Halaman ini diterjemahkan oleh Cloud Translation API.

Upload yang Dapat Dilanjutkan

Anda dapat mengupload video dengan lebih andal menggunakan protokol upload yang dapat dilanjutkan untuk Google API. Protokol ini memungkinkan Anda melanjutkan operasi upload setelah gangguan jaringan atau kegagalan transmisi lainnya, sehingga menghemat waktu dan bandwidth jika terjadi kegagalan jaringan.

Menggunakan upload yang dapat dilanjutkan sangat berguna dalam salah satu kasus berikut:

Anda mentransfer file berukuran besar.
Kemungkinan gangguan jaringan tinggi.
Upload berasal dari perangkat dengan bandwidth rendah atau koneksi Internet yang tidak stabil, seperti perangkat seluler.

Panduan ini menjelaskan urutan permintaan HTTP yang dibuat aplikasi untuk mengupload video menggunakan proses upload yang dapat dilanjutkan. Panduan ini terutama ditujukan untuk developer yang tidak dapat menggunakan library klien Google API, beberapa di antaranya menyediakan dukungan native untuk upload yang dapat dilanjutkan. Bahkan, panduan YouTube Data API - Mengupload Video menjelaskan cara menggunakan Library Klien Google API untuk Python guna mengupload video menggunakan proses upload yang dapat dilanjutkan.

Catatan: Anda juga dapat melihat serangkaian permintaan yang dibuat untuk upload yang dapat dilanjutkan atau operasi API lainnya dengan menggunakan salah satu library klien Google API yang mengaktifkan logging HTTPS. Misalnya, untuk mengaktifkan pelacakan HTTP untuk Python, gunakan library httplib2:

httplib2.debuglevel = 4

Langkah 1 - Mulai sesi yang dapat dilanjutkan

Untuk memulai upload video yang dapat dilanjutkan, kirim permintaan POST ke URL berikut. Di URL, tetapkan nilai parameter part ke nilai yang sesuai untuk permintaan Anda. Perlu diingat bahwa nilai parameter mengidentifikasi bagian yang berisi properti yang Anda tetapkan, dan juga mengidentifikasi bagian yang ingin Anda sertakan dalam respons API. Nilai parameter di URL permintaan harus dienkode URL.

https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=PARTS

Tetapkan isi permintaan ke resource video. Tetapkan juga header permintaan HTTP berikut:

Authorization – Token otorisasi untuk permintaan.
Content-Length – Jumlah byte yang diberikan dalam isi permintaan. Perhatikan bahwa Anda tidak perlu memberikan header ini jika menggunakan potongan encoding transfer.
Content-Type – Tetapkan nilai ke application/json; charset=UTF-8.
X-Upload-Content-Length – Jumlah byte yang akan diupload dalam permintaan berikutnya. Tetapkan nilai ini ke ukuran file yang Anda upload.
x-upload-content-type – jenis MIME file yang Anda upload. Anda dapat mengupload file dengan jenis MIME video apa pun (video/*) atau jenis MIME application/octet-stream.

contoh berikut menunjukkan cara memulai sesi yang dapat dilanjutkan untuk mengupload video. permintaan menetapkan (dan akan mengambil) properti di bagian snippet dan status resource video, dan juga akan mengambil properti di bagian contentdetails resource.

post /upload/youtube/v3/videos?uploadType=resumable&part=parts http/1.1
host: www.googleapis.com
authorization: bearer auth_token
content-length: content_length
content-type: application/json; charset=utf-8
x-upload-content-length: x_upload_content_length
X-Upload-Content-Type: X_UPLOAD_CONTENT_TYPE

video resource

Contoh berikut menunjukkan permintaan POST yang memiliki semua nilai ini diisi dengan pengecualian token autentikasi. Nilai categoryId dalam contoh sesuai dengan kategori video. Daftar kategori yang didukung dapat diambil menggunakan metode videoCategories.list API.

POST /upload/youtube/v3/videos?uploadType=resumable&part=snippet,status,contentDetails HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer AUTH_TOKEN
Content-Length: 278
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Length: 3000000
X-Upload-Content-Type: video/*

{
  "snippet": {
    "title": "My video title",
    "description": "This is a description of my video",
    "tags": ["cool", "video", "more keywords"],
    "categoryId": 22
  },
  "status": {
    "privacyStatus": "public",
    "embeddable": True,
    "license": "youtube"
  }
}

Langkah 2 - Simpan URI sesi yang dapat dilanjutkan

Jika permintaan Anda berhasil, server API akan merespons dengan kode status HTTP 200 (OK), dan responsnya akan menyertakan header HTTP Location yang menentukan URI untuk sesi yang dapat dilanjutkan. Ini adalah URI yang akan Anda gunakan untuk mengupload file video.

Contoh di bawah ini menunjukkan contoh respons API terhadap permintaan di langkah 1:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&upload_id=xa298sd_f&part=snippet,status,contentDetails
Content-Length: 0

Langkah 3 - Upload file video

Setelah mengekstrak URI sesi dari respons API, Anda harus mengupload konten file video yang sebenarnya ke lokasi tersebut. Isi permintaan adalah konten file biner untuk video yang Anda upload. Contoh di bawah menunjukkan format permintaan.

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: CONTENT_LENGTH
Content-Type: CONTENT_TYPE

BINARY_FILE_DATA

Permintaan menetapkan header permintaan HTTP berikut:

Authorization – Token otorisasi untuk permintaan.
Content-Length – Ukuran file yang Anda upload. Nilai ini harus sama dengan nilai header permintaan HTTP X-Upload-Content-Length di langkah 1.
Content-Type – Jenis MIME file yang Anda upload. Nilai ini harus sama dengan nilai header permintaan HTTP X-Upload-Content-Type di langkah 1.

Langkah 4 - Selesaikan proses upload

Permintaan Anda akan menghasilkan salah satu skenario berikut:

Upload Anda berhasil.

Server API merespons dengan kode respons HTTP 201 (Created). Isi respons adalah resource video yang Anda buat.
Upload Anda tidak berhasil, tetapi dapat dilanjutkan.

Anda seharusnya dapat melanjutkan upload dalam salah satu kasus berikut:
- Permintaan Anda terganggu karena koneksi antara aplikasi dan server API terputus. Dalam hal ini, Anda tidak akan menerima respons API.
- Respons API menentukan salah satu kode respons 5xx berikut. Kode Anda harus menggunakan strategi backoff eksponensial saat melanjutkan upload setelah menerima salah satu kode respons ini.
  - 500 – Internal Server Error
  - 502 – Bad Gateway
  - 503 – Service Unavailable
  - 504 – Gateway Timeout
Untuk melanjutkan upload, ikuti petunjuk cara memeriksa status upload dan melanjutkan upload di bawah. Ingat bahwa setiap URI sesi yang dapat dilanjutkan memiliki masa berlaku yang terbatas dan akan berakhir. Karena alasan ini, sebaiknya mulai upload yang dapat dilanjutkan segera setelah Anda mendapatkan URI sesi dan lanjutkan upload yang terhenti segera setelah terjadi gangguan.
Upload Anda gagal secara permanen.

Untuk upload yang gagal, respons berisi respons error yang membantu menjelaskan penyebab kegagalan. Untuk upload yang gagal secara permanen, respons API akan memiliki kode respons 4xx atau kode respons 5xx selain yang tercantum di atas.

Jika Anda mengirimkan permintaan dengan URI sesi yang sudah tidak berlaku lagi, server akan menampilkan kode respons HTTP 404 (Not Found). Dalam hal ini, Anda harus memulai upload baru yang dapat dilanjutkan, mendapatkan URI sesi baru, dan memulai upload dari awal menggunakan URI baru.

Langkah 4.1: Periksa status upload

Untuk memeriksa status upload yang dapat dilanjutkan yang terputus, kirim permintaan PUT kosong ke URL upload yang Anda ambil di langkah 2 dan juga digunakan di langkah 3. Dalam permintaan Anda, tetapkan nilai header Content-Range ke bytes */CONTENT_LENGTH, dengan CONTENT_LENGTH adalah ukuran file yang Anda upload.

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: 0
Content-Range: bytes */CONTENT_LENGTH

Langkah 4.2: Memproses respons API

Jika upload sudah selesai, terlepas dari apakah berhasil atau gagal, API akan menampilkan respons yang sama dengan yang dikirim saat upload awalnya selesai.

Namun, jika upload terhenti atau masih berlangsung, respons API akan memiliki kode respons HTTP 308 (Resume Incomplete). Dalam respons, header Range menentukan jumlah byte file yang telah berhasil diupload.

Nilai header diindeks dari 0. Dengan demikian, nilai header 0-999999 menunjukkan bahwa 1,000,000 byte pertama file telah diupload.
Jika belum ada yang diupload, respons API tidak akan menyertakan header Range.

Contoh respons di bawah menunjukkan format respons API untuk upload yang dapat dilanjutkan:

308 Resume Incomplete
Content-Length: 0
Range: bytes=0-999999

Jika respons API juga menyertakan header Retry-After, gunakan nilai header tersebut untuk menentukan kapan harus mencoba melanjutkan upload.

Langkah 4.3: Lanjutkan upload

Untuk melanjutkan upload, kirim permintaan PUT lain ke URL upload yang diambil di langkah 2. Tetapkan isi permintaan ke kode biner untuk bagian file video yang belum diupload.

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: REMAINING_CONTENT_LENGTH
Content-Range: bytes FIRST_BYTE-LAST_BYTE/TOTAL_CONTENT_LENGTH

PARTIAL_BINARY_FILE_DATA

Anda perlu menetapkan header permintaan HTTP berikut:

Authorization – Token otorisasi untuk permintaan.
Content-Length – Ukuran konten yang belum diupload, dalam byte. Jika mengupload sisa file, Anda dapat menghitung nilai ini dengan mengurangi nilai FIRST_BYTE dari nilai TOTAL_CONTENT_LENGTH. Kedua nilai tersebut digunakan di header Content-Range.
Content-Range – Bagian file yang Anda upload. Nilai header terdiri dari tiga nilai:
- FIRST_BYTE – Indeks numerik berbasis 0 dari nomor byte tempat Anda melanjutkan upload. Nilai ini satu angka lebih tinggi dari angka kedua di header Range yang diambil pada langkah sebelumnya. Pada contoh sebelumnya, nilai header Range adalah 0-999999, sehingga byte pertama dalam upload yang dilanjutkan berikutnya adalah 1000000.
- LAST_BYTE – Indeks numerik berbasis 0 dari byte terakhir file biner yang Anda upload. Biasanya, ini adalah byte terakhir dalam file. Jadi, misalnya, jika ukuran file adalah 3000000 byte, byte terakhir dalam file akan berupa angka 2999999.
- TOTAL_CONTENT_LENGTH – Total ukuran file video dalam byte. Nilai ini sama dengan header Content-Length yang ditentukan dalam permintaan upload asli.
Catatan: Anda tidak dapat mengupload blok file biner yang tidak berkelanjutan. Jika Anda mencoba mengupload blok yang tidak berkelanjutan, tidak ada konten biner yang tersisa yang akan diupload.

Dengan demikian, byte pertama yang diupload dalam upload yang dilanjutkan harus berupa byte berikutnya setelah byte terakhir yang telah berhasil diupload ke YouTube. (Lihat diskusi header Range di langkah 4.2.

Jadi, jika byte terakhir di header Range adalah 999999, byte pertama dalam permintaan untuk melanjutkan upload harus berupa byte 1000000. (Kedua angka tersebut menggunakan indeks berbasis 0.) Jika Anda mencoba melanjutkan upload dari byte 999999 atau lebih rendah (byte tumpang-tindih) atau byte 1000001 atau lebih tinggi (byte yang dilewati), tidak ada konten biner yang akan diupload.

Mengupload file dalam potongan

Daripada mencoba mengupload seluruh file dan melanjutkan upload jika terjadi gangguan jaringan, aplikasi Anda dapat membagi file menjadi beberapa bagian dan mengirim serangkaian permintaan untuk mengupload bagian tersebut secara berurutan. Pendekatan ini jarang diperlukan dan sebenarnya tidak disarankan karena memerlukan permintaan tambahan, yang memiliki implikasi performa. Namun, hal ini mungkin berguna jika Anda mencoba menampilkan indikator progres di jaringan yang sangat tidak stabil.

Petunjuk untuk mengupload file dalam beberapa bagian hampir sama dengan proses empat langkah yang dijelaskan sebelumnya dalam panduan ini. Namun, permintaan untuk mulai mengupload file (langkah 3 di atas) dan untuk melanjutkan upload (langkah 4.3 di atas) menetapkan nilai header Content-Length dan Content-Range secara berbeda saat file diupload dalam beberapa bagian.

Nilai header Content-Length menentukan ukuran bagian yang dikirim permintaan. Perhatikan batasan berikut pada ukuran bagian:
- Ukuran potongan harus kelipatan 256 KB. (Pembatasan ini tidak berlaku untuk potongan terakhir karena ukuran seluruh file mungkin bukan kelipatan 256 KB.) Ingat bahwa potongan yang lebih besar lebih efisien.
- Ukuran potongan harus sama untuk setiap permintaan dalam urutan upload, kecuali permintaan terakhir, yang menentukan ukuran potongan akhir.
Header Content-Range menentukan byte dalam file yang diupload permintaan. Petunjuk untuk menetapkan header Content-Range di langkah 4.3 berlaku saat menetapkan nilai ini.

Misalnya, nilai bytes 0-524287/2000000 menunjukkan bahwa permintaan mengirimkan 524.288 byte pertama (256 x 2048) dalam file 2.000.000 byte.

Contoh di bawah ini menunjukkan format pertama dari serangkaian permintaan yang akan mengupload file 2.000.000 byte dalam beberapa bagian:

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: 524888
Content-Type: video/*
Content-Range: bytes 0-524287/2000000

{bytes 0-524287}

Jika permintaan selain permintaan akhir berhasil, server API akan merespons dengan respons 308 (Resume Incomplete). Format respons akan sama dengan yang dijelaskan di Langkah 4.2: Memproses respons API di atas.

Gunakan nilai yang lebih besar yang ditampilkan dalam header Range respons API untuk menentukan tempat memulai potongan berikutnya. Lanjutkan untuk mengirim permintaan PUT, seperti yang dijelaskan di Langkah 4.3: Lanjutkan upload, untuk mengupload bagian file berikutnya hingga seluruh file diupload.

Saat seluruh file telah diupload, server akan merespons dengan kode respons HTTP 201 (Created) dan menampilkan bagian yang diminta dari resource video yang baru dibuat.

Jika ada permintaan yang terhenti atau aplikasi Anda menerima kode respons 5xx, ikuti prosedur yang dijelaskan di langkah 4 untuk menyelesaikan upload. Namun, alih-alih mencoba mengupload sisa file, cukup lanjutkan mengupload potongan dari titik tempat Anda melanjutkan upload. Pastikan untuk menggunakan pemeriksaan status upload untuk menentukan tempat melanjutkan upload file. Jangan berasumsi bahwa server menerima semua (atau tidak ada) byte yang dikirim dalam permintaan sebelumnya.

Catatan: Anda juga dapat meminta status upload aktif di antara potongan yang diupload. (Upload tidak perlu terganggu sebelum Anda dapat mengambil statusnya.)