Upload yang dapat dilanjutkan

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:

  1. Dalam satu permintaan. Pendekatan ini biasanya yang terbaik, karena memerlukan lebih sedikit permintaan, sehingga memiliki performa yang lebih baik.

  2. 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:

  1. Buat permintaan POST ke URL sesi yang dapat dilanjutkan.
  2. Tambahkan data file ke isi permintaan.

  3. Tambahkan header HTTP berikut:

    • Content-Length: Menetapkan jumlah byte dalam file.
    • X-Goog-Upload-Command: Tetapkan ke upload, finalize.

  4. 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:

  1. Buat permintaan POST ke URL sesi yang dapat dilanjutkan.

  2. 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.

  3. Tambahkan header HTTP berikut:

    • Content-Length: Menetapkan ke jumlah byte dalam potongan tersebut.
    • X-Goog-Upload-Command: Tetapkan ke upload. Untuk potongan terakhir, tetapkan ke upload, finalize.
    • X-Goog-Upload-Offset: Menyetel ke offset di mana byte harus ditulis. Perhatikan bahwa byte harus diupload secara berurutan. Offset pertama adalah 0.
  4. Kirim permintaan.

    Jika permintaan upload terhenti atau Anda menerima respons 5xx, ikuti prosedur dalam Melanjutkan upload yang terhenti.

  5. 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.