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

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

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: Menetapkan ke jumlah total byte data file, yang akan ditransfer dalam permintaan berikutnya.
    • X-Goog-Upload-Header-Content-Type: Menetapkan 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 berupa gambar dan jumlah total byte dalam file adalah 4200000. Perhatikan bahwa isi permintaan kosong; sehingga header Content-Length disetel 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 untuk 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 resolusi yang dapat dilanjutkan sehingga Anda dapat menggunakannya untuk permintaan selanjutnya.

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 yang 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 masing-masing permintaan.
    • Anda perlu 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:

  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 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 dalam 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 potongan ke isi permintaan. Buat potongan dalam kelipatan 2 MiB (mebibyte), kecuali untuk potongan terakhir yang menyelesaikan proses upload. Pertahankan ukuran potongan sebesar mungkin sehingga proses uploadnya efisien.

  3. Tambahkan header HTTP berikut:

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

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

  5. Ulangi langkah 1 sampai 4 untuk setiap potongan yang tersisa dalam {i>file<i}.

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 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 4.200.000 byte dalam beberapa bagian, menggunakan URL sesi yang dapat dilanjutkan dan perincian ukuran yang diperoleh pada langkah sebelumnya. Contoh ini menggunakan potongan berukuran 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 terhenti

Jika permintaan upload terhenti atau jika Anda menerima kode status HTTP non-200, buat kueri 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 dengan offset ini. Anda harus melanjutkan pada offset yang disediakan oleh server, kecuali jika Anda mengirimkan perintah upload dan final gabungan. 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, berarti upload telah dihentikan.