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.

Jika Anda adalah developer yang menggunakan library klien, perhatikan bahwa beberapa library klien memberikan 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 ada jaringan gagal, karena Anda tidak perlu memulai ulang unggahan file berukuran besar dari memulai.

Langkah 1: Memulai sesi upload

Mulai sesi upload yang dapat dilanjutkan dengan mengirim permintaan POST ke https://photoslibrary.googleapis.com/v1/uploads. Menggunakan upload yang dapat dilanjutkan URL 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`	Ditetapkan total jumlah byte dari 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 {i>header<i} berikut ini.

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 file yang diupload dilakukan di beberapa potongan, semua upload, kecuali upload terakhir, harus dilakukan dalam kelipatan dari nilai ini. Artinya, byte upload dari file harus selaras dengan nilai ini. Di potongan terakhir, Anda dapat mengunggah sisa {i>byte.<i}

Bidang header X-Goog-Upload-URL berisi URL unik yang harus digunakan untuk menyelesaikan upload melalui semua permintaan yang tersisa. Salin dan simpan ini URL sesi yang dapat dilanjutkan, 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 adalah yang terbaik, karena memerlukan lebih sedikit permintaan, sehingga memiliki performa yang lebih baik.
Dalam beberapa bagian. Dengan pendekatan ini, upload dilakukan dalam beberapa permintaan dengan memotong data. Data tersebut dibagi menjadi kelipatan x-goog-upload-chunk-granularity. Jika perlu, permintaan yang telah dipotong bisa dicoba ulang.

Gunakan pendekatan ini jika:
- Anda perlu mengurangi jumlah data yang ditransfer dalam satu permintaan. Anda mungkin perlu melakukan ini ketika ada batas waktu yang tetap untuk permintaan individual.
- Anda harus memberikan indikator kustom yang menunjukkan file yang diupload progresif.
- Anda perlu tahu kapan waktu yang aman untuk membuang data.

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: Setel ke jumlah byte di .
- X-Goog-Upload-Command: Tetapkan ke upload, finalize.
Kirim permintaan.

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

Jika permintaan berhasil, Anda akan menerima 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 potongan tersebut ke isi permintaan.

Kecuali untuk potongan terakhir yang menyelesaikan upload, buat potongan lainnya dalam kelipatan dari ukuran potongan yang dapat diterima. Tetap sebesar mungkin agar proses upload efisien.
Tambahkan header HTTP berikut:
- Content-Length: Setel ke jumlah byte di potongan data.
- 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. Offset pertama adalah 0.
Kirim permintaan.
Jika permintaan upload terganggu atau Anda menerima 5xx ikuti prosedur di Melanjutkan upload yang terhenti.
Ulangi langkah-langkah di atas untuk setiap bagian yang tersisa dalam {i>file<i}.

Jika permintaan berhasil, Anda akan menerima 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 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 berukuran 3.039.417 byte dalam beberapa potongan, menggunakan sesi yang dapat dilanjutkan URL dan perincian ukuran potongan yang diterima yang diperoleh di langkah sebelumnya. Contoh ini menggunakan ukuran potongan 262.144 byte yang dikembalikan dalam bidang header, x-goog-upload-chunk-granularity, jika sesi upload telah diinisialisasi. Perhatikan, setiap upload berisi byte yang dalam kelipatan 262.144.

Inisialisasi sesi upload untuk menerima URL upload dan ukuran potongan seperti yang dijelaskan dalam 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]

Potongan 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 status HTTP non-200 kode, 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 mencakup 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 di offset yang disediakan oleh server kecuali Anda mengirimkan perintah {i>upload<i} dan {i>final<i} yang digabungkan, dalam hal ini Anda juga dapat melanjutkan pada offset 0.

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