Halaman ini menjelaskan cara membuat permintaan upload yang dapat dilanjutkan ke Google Photos Library API melalui protokol REST. Protokol ini memungkinkan Anda melanjutkan operasi upload setelah kegagalan komunikasi mengganggu aliran data.
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 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
. Menggunakan upload yang dapat dilanjutkan
URL yang ditampilkan dalam permintaan ini, upload file.
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 |
Ditetapkan total jumlah byte dari 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
{i>header<i} berikut ini.
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 file yang diupload
dilakukan di beberapa potongan, semua upload, kecuali upload terakhir,
harus dilakukan dalam kelipatan dari nilai ini. Artinya, byte
upload dari file
harus selaras dengan nilai ini. Di potongan terakhir, Anda
dapat mengunggah sisa
{i>byte.<i}
Bidang header X-Goog-Upload-URL
berisi URL unik yang harus digunakan untuk
menyelesaikan upload melalui
semua permintaan yang tersisa. Salin dan simpan ini
URL sesi yang dapat dilanjutkan, 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 adalah yang terbaik, karena memerlukan lebih sedikit permintaan, sehingga memiliki performa yang lebih baik.
-
Dalam beberapa bagian. Dengan pendekatan ini, upload dilakukan dalam beberapa permintaan dengan memotong data. Data tersebut dibagi menjadi kelipatan
x-goog-upload-chunk-granularity
. Jika perlu, permintaan yang telah dipotong bisa dicoba ulang.Gunakan pendekatan ini jika:
- Anda perlu mengurangi jumlah data yang ditransfer dalam satu permintaan. Anda mungkin perlu melakukan ini ketika ada batas waktu yang tetap untuk permintaan individual.
- Anda harus memberikan indikator yang disesuaikan yang menunjukkan progres upload.
- Anda perlu tahu 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
: Setel ke jumlah byte di .X-Goog-Upload-Command
: Tetapkan keupload, finalize
.
Kirim permintaan.
Jika permintaan upload terganggu atau Anda menerima 5xx
ikuti prosedur di Melanjutkan
upload yang terhenti.
Jika permintaan berhasil, Anda akan menerima status HTTP 200 OK
dan token upload dalam isi respons.
Buat
item media menggunakan token upload ini.
Beberapa Potongan
Untuk mengupload file dalam beberapa potongan:
- Buat permintaan
POST
ke URL sesi yang dapat dilanjutkan. -
Tambahkan data potongan tersebut ke isi permintaan.
Kecuali untuk potongan terakhir yang menyelesaikan upload, buat potongan lainnya dalam kelipatan dari ukuran potongan yang dapat diterima. Tetap sebesar mungkin agar proses upload efisien.
-
Tambahkan header HTTP berikut:
Content-Length
: Tetapkan ke jumlah byte dalam bagian.X-Goog-Upload-Command
: Tetapkan keupload
. Untuk potongan terakhir, tetapkan keupload, finalize
.X-Goog-Upload-Offset
: Tetapkan ke offset tempat byte harus ditulis. Perhatikan bahwa byte harus diupload secara berurutan. Offset pertama adalah0
.
- Kirim permintaan.
Jika permintaan upload terganggu atau Anda menerima
5xx
ikuti prosedur di Melanjutkan upload yang terhenti. - Ulangi langkah-langkah ini untuk setiap bagian yang tersisa dalam {i>file<i}.
Jika permintaan berhasil, Anda akan menerima 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 sebesar 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 Potongan
Contoh berikut menunjukkan permintaan yang dapat dilanjutkan untuk mengupload file JPEG
3.039.417 byte dalam beberapa bagian, menggunakan URL sesi yang dapat dilanjutkan
dan tingkat perincian ukuran bagian yang diterima yang diperoleh di langkah sebelumnya.
Contoh ini menggunakan ukuran potongan 262.144 byte yang dikembalikan dalam
bidang header, x-goog-upload-chunk-granularity
, jika
sesi upload telah diinisialisasi. Perhatikan, setiap upload berisi byte yang
dalam kelipatan 262.144.
Inisialisasi sesi upload untuk menerima URL upload dan ukuran potongan seperti yang dijelaskan dalam 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]
Potongan 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 status HTTP non-200
kode, kueri server untuk mengetahui berapa 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 mencakup 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
Kemudian, Anda dapat melanjutkan upload dengan offset ini. Anda harus melanjutkan di offset yang disediakan oleh server kecuali Anda mengirimkan perintah {i>upload<i} dan {i>resolve<i} gabungan, dalam hal ini Anda juga dapat melanjutkan pada offset 0.
Jika header X-Goog-Upload-Status
dalam respons HTTP dari perintah kueri Anda
ada dan nilainya bukan active
, yang
menunjukkan bahwa upload memiliki
telah dihentikan.