Melakukan Upload yang Dapat Dilanjutkan

Halaman ini menjelaskan cara membuat permintaan upload yang dapat dilanjutkan di Street View Publish API. Protokol ini memungkinkan Anda melanjutkan operasi upload setelah kegagalan komunikasi mengganggu aliran data. Gunakan opsi ini jika:

  • Anda mengupload file besar.
  • Kemungkinan gangguan jaringan atau 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 proses upload file besar dari awal.

Jika mengirim file kecil melalui koneksi jaringan yang andal, Anda dapat menggunakan upload sederhana.

Memulai sesi upload yang dapat dilanjutkan

Setelah mendapatkan uploadUrl, Anda dapat memulai sesi upload yang dapat dilanjutkan:

  1. Buat permintaan POST ke uploadUrl.

  2. Tambahkan header HTTP berikut:

    • X-Goog-Upload-Protocol: Tetapkan ke resumable.
    • X-Goog-Upload-Header-Content-Length: Tetapkan ke jumlah total byte data file, yang akan ditransfer dalam permintaan berikutnya.
    • X-Goog-Upload-Header-Content-Type: Tetapkan ke jenis MIME data file.
    • X-Goog-Upload-Command: Tetapkan ke start.

  3. Kirim permintaan.

Contoh: Memulai sesi upload yang dapat dilanjutkan

Contoh berikut menunjukkan cara memulai sesi yang dapat dilanjutkan untuk mengupload file baru. Dalam hal ini, file tersebut adalah gambar dan jumlah total byte dalam file adalah 4200000. Perhatikan bahwa isi permintaan kosong; oleh karena itu, header Content-Length ditetapkan ke 0.

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234 HTTP/1.1
Authorization: Bearer [YOUR_AUTH_TOKEN]
Content-Length: 0
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Header-Content-Length: 4200000
X-Goog-Upload-Header-Content-Type: image/jpeg
X-Goog-Upload-Command: start

Menyimpan URL sesi yang dapat dilanjutkan menjelaskan cara menangani respons untuk permintaan memulai sesi upload yang dapat dilanjutkan.

Menyimpan URL sesi yang dapat dilanjutkan

Untuk permintaan yang dikirim untuk memulai sesi upload yang dapat dilanjutkan, server akan membalas dengan kode status HTTP 200 OK, termasuk header berikut:

  • X-Goog-Upload-URL: URL unik yang harus digunakan untuk menyelesaikan upload melalui semua permintaan yang tersisa.

Salin dan simpan URL sesi yang dapat dilanjutkan sehingga Anda dapat menggunakannya untuk permintaan berikutnya.

Contoh: Menyimpan URL sesi yang dapat dilanjutkan

Contoh berikut menunjukkan respons yang menyertakan URL sesi yang dapat dilanjutkan dan persyaratan granularitas ukuran.

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable

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 dan dengan demikian memiliki performa yang lebih baik.
  2. Dalam beberapa potongan. Gunakan pendekatan ini jika:
    • Anda perlu mengurangi jumlah data yang ditransfer dalam satu permintaan. Anda mungkin perlu melakukannya jika ada batas waktu tetap untuk masing-masing permintaan.
    • Anda perlu memberikan indikator yang disesuaikan yang menunjukkan progres upload.
    • Anda perlu mengetahui kapan data dapat dihapus dengan aman.

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: Tetapkan ke jumlah byte dalam file.
    • X-Goog-Upload-Command: Tetapkan ke upload, finalize.

  4. Kirim permintaan.

Jika permintaan upload terganggu atau Anda menerima respons 5xx, ikuti prosedur di Melanjutkan upload yang terganggu.

Beberapa Potongan

Untuk mengupload file dalam beberapa potongan:

  1. Buat permintaan POST ke URL sesi yang dapat dilanjutkan.
  2. Tambahkan data potongan ke isi permintaan. Buat potongan dalam kelipatan 2 MiB (mebibyte), kecuali untuk potongan terakhir yang menyelesaikan proses upload. Pertahankan ukuran potongan sebesar mungkin agar proses upload efisien.

  3. Tambahkan header HTTP berikut:

    • Content-Length: Tetapkan ke jumlah byte dalam potongan.
    • X-Goog-Upload-Command: Tetapkan ke upload. Untuk potongan terakhir, tetapkan ke upload, finalize.
    • X-Goog-Upload-Offset: Tetapkan ke offset tempat byte harus ditulis. Perhatikan bahwa byte harus diupload secara berurutan.

  4. Kirim permintaan. Jika permintaan upload terganggu atau Anda menerima respons 5xx, ikuti prosedur di Melanjutkan upload yang terganggu.

  5. Ulangi langkah 1 hingga 4 untuk setiap potongan yang tersisa dalam file.

Contoh: Mengupload file

Permintaan Tunggal

Contoh berikut menunjukkan permintaan yang dapat dilanjutkan untuk mengupload seluruh file JPEG 4.200.000 byte dalam satu permintaan, menggunakan URL sesi yang dapat dilanjutkan yang diperoleh pada langkah sebelumnya:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 4200000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

Jika permintaan berhasil, Anda akan menerima kode status HTTP 200 OK.

Beberapa Potongan

Contoh berikut menunjukkan permintaan yang dapat dilanjutkan untuk mengupload file JPEG 4.200.000 byte dalam beberapa potongan, menggunakan URL sesi yang dapat dilanjutkan dan granularitas ukuran yang diperoleh pada langkah sebelumnya. Contoh ini menggunakan ukuran potongan 2097000 byte, yang merupakan kelipatan 2 MiB (mebibyte).

Potongan pertama: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0



[BYTES 0-2096999]

Potongan kedua: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 2097000



[BYTES 2097000-4193999]

Potongan terakhir: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 6000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 4194000



[BYTES 4194000-4200000]

Melanjutkan upload yang terganggu

Jika permintaan upload terganggu atau jika Anda menerima kode status HTTP non-200, kirim kueri ke server untuk mengetahui jumlah upload yang berhasil:

  1. Buat permintaan POST ke URL sesi yang dapat dilanjutkan.
  2. Tetapkan X-Goog-Upload-Command ke query.
  3. Kirim permintaan.

Server akan merespons dengan 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 pada offset ini. Anda harus melanjutkan pada offset yang diberikan oleh server, kecuali jika Anda mengirim perintah gabungan upload dan finalisasi, yang 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, upload telah dihentikan.