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 berukuran besar.
  • Kemungkinan gangguan jaringan atau beberapa kegagalan transmisi lainnya sangat 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.

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 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 guna 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 menjawab 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 respons 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 perincian 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 merupakan pendekatan terbaik karena memerlukan lebih sedikit permintaan sehingga memiliki performa yang lebih baik.
  2. Dalam beberapa bagian. Gunakan pendekatan ini jika:
    • Anda perlu mengurangi jumlah data yang ditransfer dalam satu permintaan. Anda mungkin perlu melakukannya saat ada batas waktu tetap untuk setiap permintaan.
    • Anda harus 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 terhenti atau Anda menerima respons 5xx, ikuti prosedur di Melanjutkan upload yang terhenti.

Beberapa Potongan

Untuk mengupload file dalam beberapa potongan:

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

  3. Tambahkan header HTTP berikut:

    • Content-Length: Tetapkan ke jumlah byte dalam bagian.
    • 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 serial.

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

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

Contoh: Mengupload file

Permintaan Tunggal

Contoh berikut menunjukkan permintaan yang dapat dilanjutkan untuk mengupload seluruh file JPEG sebesar 4.200.000 byte dalam satu permintaan, menggunakan URL sesi yang dapat dilanjutkan yang diperoleh di 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 berukuran 4.200.000 byte dalam beberapa bagian, menggunakan URL sesi yang dapat dilanjutkan dan granularitas ukuran yang diperoleh di langkah sebelumnya. Contoh ini menggunakan ukuran potongan sebesar 2097000 byte, yang merupakan kelipatan dari 2 MiB (mebibyte).

Bagian 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 terhenti

Jika permintaan upload terhenti atau jika Anda menerima kode status HTTP non-200, kueri server untuk mengetahui berapa banyak 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 dengan offset ini. Anda harus melanjutkan dengan offset yang diberikan oleh server, kecuali jika Anda mengirimkan perintah upload dan selesaikan gabungan, yang dalam hal ini Anda juga dapat melanjutkan dengan offset 0.

Jika header X-Goog-Upload-Status dalam respons HTTP perintah kueri Anda ada dan nilainya bukan active, upload telah dihentikan.