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, 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 koneksi bandwidth rendah atau 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 bagi developer yang tidak dapat menggunakan library klien Google API, yang beberapa di antaranya memberikan dukungan native untuk upload yang dapat dilanjutkan. Bahkan, panduan YouTube Data API - Mengupload Video menjelaskan cara menggunakan Library Klien Google API untuk Python agar dapat 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 menggunakan salah satu library klien Google API dengan logging HTTPS yang diaktifkan. Misalnya, untuk mengaktifkan trace 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. Ingat bahwa nilai parameter mengidentifikasi bagian yang berisi properti yang Anda tetapkan, dan juga mengidentifikasi bagian yang Anda inginkan untuk disertakan oleh respons API. Nilai parameter di URL permintaan harus berenkode 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 Anda 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 dari 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 video resource snippet dan status, 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 semua nilainya 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 menunjukkan contoh respons API terhadap permintaan pada 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 ini 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 akan diupload. Nilai ini harus sama dengan nilai header permintaan HTTP X-Upload-Content-Length di langkah 1.
Content-Type – Jenis MIME dari file yang akan 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 menyebabkan 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 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 untuk 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 melanjutkan upload yang terhenti segera setelah terjadi gangguan.
Upload Anda gagal secara permanen.

Untuk upload yang gagal, respons tersebut 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 mengirim permintaan dengan URI sesi yang sudah tidak berlaku, 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 dan terputus, kirim permintaan PUT kosong ke URL upload yang Anda ambil di langkah 2 dan juga gunakan pada langkah 3. Dalam permintaan Anda, setel 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: Proses respons API

Jika upload sudah selesai, API akan menampilkan respons yang sama seperti yang dikirimkan saat upload pertama kali selesai atau gagal.

Namun, jika upload terhenti atau masih berlangsung, respons API akan memiliki kode respons 308 (Resume Incomplete) HTTP. 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 dari file tersebut telah diupload.
Jika belum ada yang diupload, respons API tidak akan menyertakan header Range.

Contoh respons di bawah ini 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 melanjutkan upload.

Langkah 4.3: Lanjutkan upload

Untuk melanjutkan upload, kirim permintaan PUT lainnya 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, dalam byte, dari konten yang belum diupload. Jika Anda 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 dari file yang Anda upload. Nilai header terdiri dari tiga nilai:
- FIRST_BYTE – Indeks numerik berbasis 0 dari nomor byte asal Anda melanjutkan upload. Nilai ini satu angka lebih tinggi daripada 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 adalah angka 2999999.
- TOTAL_CONTENT_LENGTH – Ukuran total 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 tanpa jeda, 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 berhasil diupload ke YouTube. (Lihat diskusi tentang header Range pada 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 menggunakan indeks berbasis 0.) Jika Anda mencoba untuk melanjutkan upload dari byte 999999 atau yang lebih rendah (overlap byte) atau byte 1000001 atau yang lebih tinggi (melewati byte), tidak ada konten biner yang akan diupload.

Mengupload potongan file

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

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

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

Misalnya, nilai bytes 0-524287/2000000 menunjukkan bahwa permintaan tersebut 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 bentuk potongan:

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 seperti yang dijelaskan dalam Langkah 4.2: Proses respons API di atas.

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

Setelah seluruh file 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 pada 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 status upload guna menentukan tempat untuk 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 diganggu sebelum Anda dapat mengambil statusnya.)