Halaman ini menjelaskan cara membuat permintaan upload yang dapat dilanjutkan ke Google Photos Library API melalui protokol REST. Protokol ini memungkinkan Anda untuk melanjutkan operasi upload setelah kegagalan komunikasi mengganggu aliran data.
Jika Anda adalah developer yang menggunakan library klien, perhatikan bahwa beberapa library klien menyediakan dukungan native untuk upload yang dapat dilanjutkan.
Gunakan opsi upload yang dapat dilanjutkan jika:
- Anda mengupload file berukuran besar.
- Kemungkinan gangguan jaringan atau beberapa kegagalan transmisi lainnya tinggi (misalnya, jika Anda mengupload file dari aplikasi seluler).
Upload yang dapat dilanjutkan juga dapat mengurangi penggunaan bandwidth saat terjadi kegagalan jaringan, karena Anda tidak perlu memulai ulang upload file berukuran besar dari awal.
Langkah 1: Memulai sesi upload
Mulai sesi upload yang dapat dilanjutkan dengan mengirim permintaan POST ke
https://photoslibrary.googleapis.com/v1/uploads
. Dengan menggunakan URL upload
yang dapat dilanjutkan yang ditampilkan dalam permintaan ini, upload file tersebut.
Permintaan POST harus menyertakan header berikut:
Kolom header | |
---|---|
Content-Length |
Tetapkan ke 0 karena isi permintaan kosong. |
X-Goog-Upload-Command |
Tetapkan ke start . |
X-Goog-Upload-Content-Type |
Tetapkan ke jenis mime file, misalnya,
image/jpeg . |
X-Goog-Upload-Protocol |
Tetapkan ke resumable . |
X-Goog-Upload-Raw-Size |
Tetapkan ke jumlah total byte data file yang akan ditransfer. |
Berikut adalah header permintaan POST:
POST https://photoslibrary.googleapis.com/v1/uploads Authorization: Bearer oauth2-token Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: mime-type X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: bytes-of-file
Langkah 2: Menyimpan URL sesi
Jika berhasil, permintaan POST akan menampilkan kode status HTTP 200 OK
, termasuk header berikut.
X-Goog-Upload-URL: url-to-make-uploads-to X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes
Kolom header x-goog-upload-chunk-granularity
berisi penyelarasan byte
dan perincian ukuran untuk semua potongan data yang dikirim oleh klien. Jika upload
dilakukan dalam beberapa bagian, semua upload, kecuali upload terakhir,
harus dilakukan dalam kelipatan nilai ini. Artinya, byte upload file
harus selaras dengan nilai ini. Di potongan terakhir, Anda dapat
mengupload byte yang tersisa.
Kolom header X-Goog-Upload-URL
berisi URL unik yang harus digunakan untuk
menyelesaikan upload melalui semua permintaan yang tersisa. Salin dan simpan URL sesi yang dapat dilanjutkan ini sehingga Anda dapat menggunakannya untuk permintaan berikutnya.
Langkah 3: Mengupload file
Ada dua cara untuk mengupload file dengan sesi yang dapat dilanjutkan:
- Dalam satu permintaan. Pendekatan ini biasanya yang terbaik, karena memerlukan lebih sedikit permintaan, sehingga memiliki performa yang lebih baik.
-
Dalam beberapa bagian. Dalam pendekatan ini, upload dilakukan dalam beberapa permintaan dengan membagi data. Data ini dibagi dalam kelipatan
x-goog-upload-chunk-granularity
. Jika perlu, permintaan potongan dapat dicoba ulang.Gunakan pendekatan ini jika:
- Anda perlu mengurangi jumlah data yang ditransfer dalam satu permintaan. Anda mungkin perlu melakukan hal ini jika ada batas waktu tetap untuk masing-masing permintaan.
- Anda harus memberikan indikator kustom yang menunjukkan progres upload.
- Anda perlu mengetahui kapan waktu yang aman untuk membuang data.
Permintaan Tunggal
Untuk mengupload file dalam satu permintaan:
- Buat permintaan
POST
ke URL sesi yang dapat dilanjutkan. - Tambahkan data file ke isi permintaan.
Tambahkan header HTTP berikut:
Content-Length
: Menetapkan jumlah byte dalam file.X-Goog-Upload-Command
: Tetapkan keupload, finalize
.
Kirim permintaan.
Jika permintaan upload terhenti atau Anda menerima respons 5xx
, ikuti prosedur dalam Melanjutkan upload yang terhenti.
Jika permintaan berhasil, Anda akan menerima kode status HTTP 200 OK
dan token upload dalam isi respons.
Buat
item media menggunakan token upload ini.
Beberapa Bagian
Untuk mengupload file dalam beberapa bagian:
- Buat permintaan
POST
ke URL sesi yang dapat dilanjutkan. -
Tambahkan data potongan ke isi permintaan.
Kecuali untuk potongan terakhir yang menyelesaikan upload, buat potongan lainnya dalam kelipatan ukuran potongan yang diterima. Pertahankan ukuran potongan sebesar mungkin agar proses upload efisien.
-
Tambahkan header HTTP berikut:
Content-Length
: Menetapkan ke jumlah byte dalam potongan tersebut.X-Goog-Upload-Command
: Tetapkan keupload
. Untuk potongan terakhir, tetapkan keupload, finalize
.X-Goog-Upload-Offset
: Menyetel ke offset di mana byte harus ditulis. Perhatikan bahwa byte harus diupload secara berurutan. Offset pertama adalah0
.
- Kirim permintaan.
Jika permintaan upload terhenti atau Anda menerima respons
5xx
, ikuti prosedur dalam Melanjutkan upload yang terhenti. - Ulangi langkah-langkah di atas untuk setiap potongan yang tersisa dalam {i>file<i} tersebut.
Jika permintaan berhasil, Anda akan menerima kode status HTTP 200 OK
dan token upload dalam isi respons.
Buat
item media menggunakan token upload ini.
Contoh
Permintaan Tunggal
Contoh berikut menunjukkan permintaan yang dapat dilanjutkan untuk mengupload file JPEG 3.039.417 byte dalam satu permintaan.
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
Respons berisi URL upload dan ukuran potongan yang diharapkan:
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
Permintaan upload terakhir:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 3039417 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 0 [BYTES 0-4199999]
Beberapa Bagian
Contoh berikut menunjukkan permintaan yang dapat dilanjutkan untuk mengupload
file JPEG 3.039.417 byte dalam beberapa potongan, menggunakan URL sesi
yang dapat dilanjutkan dan perincian ukuran potongan yang diterima, yang diperoleh pada langkah sebelumnya.
Contoh ini menggunakan potongan ukuran 262.144 byte yang ditampilkan di
kolom header, x-goog-upload-chunk-granularity
, saat
sesi upload diinisialisasi. Perhatikan bahwa setiap upload berisi byte yang
berada dalam kelipatan 262.144.
Lakukan inisialisasi sesi upload untuk menerima URL upload dan ukuran potongan seperti yang dijelaskan pada langkah sebelumnya:
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
Respons berisi URL upload dan ukuran potongan yang diharapkan:
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
Potongan pertama:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 0 [BYTES 0-1048575]
Bagian kedua:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 1048576 [BYTES 1048576-2097151]
Potongan terakhir:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 942265 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 2097152 [BYTES 2097152-4200000]
Melanjutkan upload yang terhenti
Jika permintaan upload terhenti atau jika Anda menerima kode status HTTP non-200
, kueri server untuk mengetahui seberapa banyak upload yang berhasil.
Berikut adalah permintaan POST
ke URL sesi yang dapat dilanjutkan. X-Goog-Upload-Command
harus ditetapkan ke query
.
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: query
Respons dari server menyertakan kode status HTTP 200 OK
dan
ukuran upload saat ini.
HTTP/1.1 200 OK X-Goog-Upload-Status: active X-Goog-Upload-Size-Received: 100
Anda dapat melanjutkan upload dengan offset ini. Anda harus melanjutkan pada offset yang diberikan oleh server, kecuali jika Anda mengirim perintah upload gabungan dan menyelesaikan, dalam hal ini Anda juga dapat melanjutkan pada offset 0.
Jika header X-Goog-Upload-Status
dalam respons HTTP perintah kueri Anda ada dan nilainya bukan active
, itu menunjukkan bahwa upload telah dihentikan.