Learn about the new Picker API and important Library API changes. Details here.

Halaman ini diterjemahkan oleh Cloud Translation API.

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

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.

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 perataan 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 bagian 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:

Dalam satu permintaan. Pendekatan ini biasanya merupakan yang terbaik karena memerlukan lebih sedikit permintaan, sehingga memiliki performa yang lebih baik.
Dalam beberapa bagian. Dalam pendekatan ini, upload dilakukan dalam beberapa permintaan dengan mengelompokkan data. Data dipecah menjadi beberapa bagian dengan kelipatan x-goog-upload-chunk-granularity. Jika perlu, permintaan yang dikelompokkan dapat dicoba lagi.

Gunakan pendekatan ini jika:
- Anda perlu mengurangi jumlah data yang ditransfer dalam satu permintaan. Anda mungkin perlu melakukan ini ketika 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:

Buat permintaan POST ke URL sesi yang dapat dilanjutkan.
Tambahkan data file ke isi permintaan.
Tambahkan header HTTP berikut:
- Content-Length: Tetapkan ke jumlah byte dalam file.
- X-Goog-Upload-Command: Tetapkan ke upload, finalize.
Kirim permintaan.

Jika permintaan upload terhenti atau Anda menerima respons 5xx, ikuti prosedur di 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 Potongan

Untuk mengupload file dalam beberapa potongan:

Buat permintaan POST ke URL sesi yang dapat dilanjutkan.
Tambahkan data bagian ke isi permintaan.

Kecuali untuk potongan terakhir yang menyelesaikan upload, buat potongan lainnya dalam kelipatan ukuran potongan yang diterima. Pastikan ukuran potongan sebesar mungkin agar upload menjadi efisien.
Tambahkan header HTTP berikut:
- Content-Length: Setel ke jumlah byte dalam potongan.
- X-Goog-Upload-Command: Tetapkan ke upload. Untuk bagian terakhir, tetapkan ke upload, finalize.
- X-Goog-Upload-Offset: Tetapkan ke offset tempat byte harus ditulis. Perhatikan bahwa byte harus diupload secara berurutan. Offset pertama adalah 0.
Kirim permintaan.
Jika permintaan upload terhenti atau Anda menerima respons 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 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 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 bagian 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 akhir:

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 perincian ukuran bagian yang diterima yang diperoleh di langkah sebelumnya. Contoh ini menggunakan ukuran potongan sebesar 262.144 byte yang ditampilkan di kolom header, x-goog-upload-chunk-granularity, saat sesi upload diinisialisasi. Perhatikan,setiap upload berisi byte yang merupakan kelipatan 262.144.

Lakukan inisialisasi sesi upload untuk menerima URL upload dan ukuran bagian 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 bagian 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

Bagian 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, buat 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 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

Kemudian, Anda dapat melanjutkan upload dengan offset ini. Anda harus melanjutkan pada offset yang disediakan oleh server, kecuali jika Anda mengirim perintah upload dan finalisasi gabungan, 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, hal ini menunjukkan bahwa upload telah dihentikan.