Upload Media

Fitur upload media memungkinkan Campaign Manager 360 API menyimpan data di cloud dan menyediakannya untuk server. Jenis data yang mungkin ingin diupload mencakup foto, video, file PDF, file zip, atau jenis data lainnya.

Contoh yang diberikan dalam dokumen ini menunjukkan penggunaan upload media untuk Farm API fiktif. Namun, konsep yang sama berlaku untuk Campaign Manager 360 API.

Opsi upload

Campaign Manager 360 API memungkinkan Anda mengupload jenis data biner atau media tertentu. Karakteristik khusus dari data yang dapat Anda upload ditetapkan di halaman referensi untuk metode apa pun yang mendukung penguploadan media:

  • Ukuran file upload maksimum: Jumlah maksimum data yang dapat Anda simpan dengan metode ini.
  • Jenis MIME media yang diperbolehkan: Jenis data biner yang dapat Anda simpan menggunakan metode ini.

Anda dapat membuat permintaan upload dengan salah satu cara berikut. Tentukan metode yang Anda gunakan dengan parameter permintaan uploadType.

  • Upload sederhana: uploadType=media. Untuk mentransfer file berukuran lebih kecil dengan cepat, misalnya, 5 MB atau kurang.
  • Upload multibagian: uploadType=multipart. Untuk mentransfer file dan metadata berukuran lebih kecil dengan cepat; mentransfer file dengan metadata yang mendeskripsikannya, semuanya dalam satu permintaan.
  • Upload yang dapat dilanjutkan: uploadType=resumable. Untuk transfer yang andal, sangat penting untuk file dengan ukuran yang lebih besar. Dengan metode ini, Anda menggunakan permintaan untuk memulai sesi, yang secara opsional dapat menyertakan metadata. Ini adalah strategi yang cocok digunakan untuk kebanyakan aplikasi, karena metode ini juga dapat digunakan untuk file berukuran lebih kecil, dan hanya membutuhkan satu permintaan HTTP tambahan per upload.

Saat mengupload media, Anda menggunakan URI khusus. Kenyataannya, metode yang mendukung upload media memiliki dua endpoint URI:

  • URI /upload, untuk media. Format endpoint upload adalah URI resource standar dengan awalan “/upload”. Gunakan URI ini saat mentransfer data media itu sendiri.

    Contoh: POST /upload/farm/v1/animals

  • URI resource standar, untuk metadata. Jika resource berisi kolom data apa pun, kolom tersebut digunakan untuk menyimpan metadata yang mendeskripsikan file yang diupload. Anda dapat menggunakan URI ini saat membuat atau memperbarui nilai metadata.

    Contoh: POST /farm/v1/animals

Upload sederhana

Metode paling sederhana untuk mengupload file adalah dengan membuat permintaan upload sederhana. Opsi ini merupakan pilihan yang baik jika:

  • File cukup kecil untuk diupload lagi secara keseluruhan jika koneksi gagal.
  • Tidak ada metadata yang akan dikirim. Hal ini mungkin berlaku jika Anda berencana untuk mengirimkan metadata untuk resource ini dalam permintaan terpisah, atau jika tidak ada metadata yang didukung atau tersedia.

Untuk menggunakan upload sederhana, buat permintaan POST atau PUT ke URI /upload pada metode dan tambahkan parameter kueri uploadType=media. Contoh:

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=media

Header HTTP yang digunakan saat membuat permintaan upload sederhana meliputi:

  • Content-Type. Setel ke salah satu jenis data media upload yang diperbolehkan, yang ditentukan dalam referensi API.
  • Content-Length. Setel ke jumlah byte yang Anda upload. Tidak diperlukan jika Anda menggunakan potongan encoding transfer.

Contoh: Upload sederhana

Contoh berikut menunjukkan penggunaan permintaan upload sederhana untuk Farm API fiktif.

POST /upload/farm/v1/animals?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: image/jpeg
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

JPEG data

Jika permintaan berhasil, server akan menampilkan kode status 200 OK HTTP beserta metadata apa pun:

HTTP/1.1 200
Content-Type: application/json

{
  "name": "Llama"
}

Upload multibagian

Jika memiliki metadata yang ingin dikirim dengan data yang akan diupload, Anda dapat membuat satu permintaan multipart/related. Ini adalah pilihan yang bagus jika data yang Anda kirim cukup kecil untuk diupload lagi secara keseluruhan jika koneksi gagal.

Untuk menggunakan upload multibagian, buat permintaan POST atau PUT ke URI /upload metode dan tambahkan parameter kueri uploadType=multipart, misalnya:

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=multipart

Header HTTP tingkat atas yang digunakan saat membuat permintaan upload multibagian mencakup:

  • Content-Type. Setel ke multibagian/terkait dan sertakan string batas yang Anda gunakan untuk mengidentifikasi bagian permintaan.
  • Content-Length. Setel ke jumlah total byte dalam isi permintaan. Bagian media dari permintaan harus kurang dari ukuran file maksimum yang ditetapkan untuk metode ini.

Isi permintaan diformat sebagai jenis konten multipart/related [RFC2387] dan berisi tepat dua bagian. Bagian-bagian tersebut diidentifikasi oleh string batas, dan string batas akhir diikuti oleh dua tanda hubung.

Setiap bagian dari permintaan multibagian memerlukan header Content-Type tambahan:

  1. Bagian metadata: Harus didahulukan, dan Content-Type harus cocok dengan salah satu format metadata yang diperbolehkan.
  2. Bagian media: Harus ada di urutan kedua, dan Content-Type harus cocok dengan salah satu jenis MIME media yang diperbolehkan metode ini.

Lihat referensi API untuk daftar jenis MIME media yang diperbolehkan dan batas ukuran setiap metode untuk file yang diupload.

Catatan: Untuk membuat atau memperbarui bagian metadata saja, tanpa mengupload data terkait, cukup kirim permintaan POST atau PUT ke endpoint resource standar: https://www.googleapis.com/farm/v1/animals

Contoh: Upload multibagian

Contoh di bawah ini menunjukkan permintaan upload multibagian untuk Farm API fiktif.

POST /upload/farm/v1/animals?uploadType=multipart HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length: number_of_bytes_in_entire_request_body

--foo_bar_baz
Content-Type: application/json; charset=UTF-8

{
  "name": "Llama"
}

--foo_bar_baz
Content-Type: image/jpeg

JPEG data
--foo_bar_baz--

Jika permintaan berhasil, server akan menampilkan kode status 200 OK HTTP beserta metadata apa pun:

HTTP/1.1 200
Content-Type: application/json

{
  "name": "Llama"
}

Upload yang dapat dilanjutkan

Untuk mengupload file data dengan lebih andal, Anda dapat menggunakan protokol upload yang dapat dilanjutkan. Protokol ini memungkinkan Anda melanjutkan operasi upload setelah kegagalan komunikasi mengganggu aliran data. Protokol ini sangat berguna jika Anda mentransfer file besar dan ada kemungkinan besar terjadinya gangguan jaringan atau kegagalan transmisi lainnya, misalnya, saat mengupload dari aplikasi klien seluler. Protokol ini juga dapat mengurangi penggunaan bandwidth jika terjadi kegagalan jaringan, karena Anda tidak perlu memulai ulang proses upload file besar dari awal.

Langkah-langkah untuk menggunakan upload yang dapat dilanjutkan meliputi:

  1. Mulai sesi yang dapat dilanjutkan. Buat permintaan awal untuk URI upload yang menyertakan metadata, jika ada.
  2. Simpan URI sesi yang dapat dilanjutkan. Simpan URI sesi yang ditampilkan sebagai respons atas permintaan awal; Anda akan menggunakannya untuk permintaan yang tersisa dalam sesi ini.
  3. Upload file. Kirim file media ke URI sesi yang dapat dilanjutkan.

Selain itu, aplikasi yang menggunakan upload yang dapat dilanjutkan harus memiliki kode untuk melanjutkan upload yang terhenti. Jika upload terhenti, cari tahu berapa banyak data yang berhasil diterima, lalu lanjutkan upload mulai dari titik tersebut.

Catatan: masa berlaku URI upload akan berakhir setelah satu minggu.

Langkah 1: Mulai sesi yang dapat dilanjutkan

Untuk memulai upload yang dapat dilanjutkan, buat permintaan POST atau PUT ke URI /upload metode dan tambahkan parameter kueri uploadType=resumable, misalnya:

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable

Untuk permintaan memulai ini, bagian isi akan kosong atau hanya berisi metadata; Anda akan mentransfer konten yang sebenarnya dari file yang ingin diupload dalam permintaan berikutnya.

Gunakan header HTTP berikut dengan permintaan awal:

  • X-Upload-Content-Type. Setel ke jenis MIME media dari data upload yang akan ditransfer dalam permintaan berikutnya.
  • X-Upload-Content-Length. Setel ke jumlah byte data upload yang akan ditransfer dalam permintaan berikutnya.  Jika panjang tidak diketahui pada saat permintaan ini, Anda dapat menghilangkan header ini.
  • Jika menyediakan metadata: Content-Type. Setel sesuai dengan jenis data metadata.
  • Content-Length. Setel ke jumlah byte yang diberikan dalam isi permintaan awal ini. Tidak diperlukan jika Anda menggunakan potongan encoding transfer.

Lihat referensi API untuk daftar jenis MIME media yang diperbolehkan dan batas ukuran setiap metode untuk file yang diupload.

Contoh: Permintaan untuk memulai sesi yang dapat dilanjutkan

Contoh berikut menunjukkan cara memulai sesi yang dapat dilanjutkan untuk Farm API fiktif.

POST /upload/farm/v1/animals?uploadType=resumable HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: image/jpeg
X-Upload-Content-Length: 2000000

{
  "name": "Llama"
}

Catatan: Untuk permintaan update awal yang dapat dilanjutkan tanpa metadata, biarkan isi permintaan dalam keadaan kosong, dan setel header Content-Length ke 0.

Bagian selanjutnya menjelaskan cara menangani respons.

Langkah 2: Simpan URI sesi yang dapat dilanjutkan

Jika permintaan untuk memulai sesi berhasil, server API akan merespons dengan kode status HTTP 200 OK. Selain itu, server API memberikan header Location yang menentukan URI sesi yang dapat dilanjutkan. Header Location, yang ditunjukkan pada contoh di bawah, menyertakan bagian parameter kueri upload_id yang memberikan ID upload unik untuk digunakan pada sesi ini.

Contoh: Respons memulai sesi yang dapat dilanjutkan

Berikut adalah respons terhadap permintaan pada Langkah 1:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

Nilai header Location, seperti yang ditunjukkan pada contoh respons di atas, adalah URI sesi yang akan Anda gunakan sebagai endpoint HTTP untuk melakukan upload file sebenarnya atau membuat kueri status upload.

Salin dan simpan URI sesi sehingga Anda dapat menggunakannya untuk permintaan berikutnya.

Langkah 3: Upload file

Untuk mengupload file, kirim permintaan PUT ke URI upload yang Anda dapatkan di langkah sebelumnya. Format permintaan upload adalah:

PUT session_uri

Header HTTP yang akan digunakan saat membuat permintaan upload file yang dapat dilanjutkan meliputi Content-Length. Setel ini ke jumlah byte yang Anda upload dalam permintaan ini, yang umumnya merupakan ukuran file upload.

Contoh: Permintaan upload file yang dapat dilanjutkan

Berikut adalah permintaan yang dapat dilanjutkan guna mengupload seluruh file JPEG 2.000.000 byte untuk contoh ini.

PUT https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/jpeg

bytes 0-1999999

Jika permintaan berhasil, server merespons dengan HTTP 201 Created, beserta metadata apa pun yang terkait dengan resource ini. Jika permintaan awal sesi yang dapat dilanjutkan adalah PUT, untuk memperbarui resource yang ada, respons suksesnya adalah  200 OK, beserta metadata apa pun yang terkait dengan resource ini.

Jika permintaan upload terhenti atau jika Anda menerima respons HTTP 503 Service Unavailable atau 5xx lainnya dari server, ikuti prosedur yang diuraikan dalam melanjutkan upload yang terhenti.  

Mengupload file dalam potongan

Dengan upload yang dapat dilanjutkan, Anda dapat membagi file menjadi potongan-potongan dan mengirim serangkaian permintaan untuk mengupload setiap potongan secara berurutan. Ini bukan pendekatan yang disarankan karena ada biaya performa terkait permintaan tambahan, dan biasanya tidak diperlukan. Namun, Anda mungkin perlu menggunakan pemotongan untuk mengurangi jumlah data yang ditransfer dalam satu permintaan. Ini akan berguna apabila ada batas waktu tetap untuk masing-masing permintaan, seperti halnya untuk kelas tertentu dari permintaan Google App Engine. Ini juga memungkinkan Anda melakukan hal-hal seperti memberikan indikasi progres upload untuk browser lama yang tidak memiliki dukungan progres upload secara default.

Melanjutkan upload yang terhenti

Jika permintaan upload dihentikan sebelum menerima respons atau jika Anda menerima respons 503 Service Unavailable HTTP dari server, maka Anda perlu melanjutkan upload yang terhenti. Untuk melakukan ini:

  1. Status permintaan. Buat kueri status upload saat ini dengan mengajukan permintaan PUT kosong ke URI upload. Untuk permintaan ini, header HTTP harus menyertakan header Content-Range yang menunjukkan bahwa posisi saat ini pada file tidak diketahui.  Misalnya, setel Content-Range ke */2000000 jika total panjang file adalah 2.000.000. Jika Anda tidak mengetahui ukuran penuh file, setel Content-Range ke */*.

    Catatan: Anda dapat meminta status di antara setiap potongan, bukan hanya jika upload terganggu. Tindakan ini berguna, misalnya, jika Anda ingin menampilkan indikasi progres upload untuk browser lama.

  2. Dapatkan jumlah byte yang diupload. Proses respons dari kueri status. Server menggunakan header Range dalam responsnya untuk menentukan byte yang telah diterima sejauh ini.  Misalnya, header Range dari 0-299999 menunjukkan bahwa 300.000 byte pertama file telah diterima.
  3. Upload data yang tersisa. Terakhir, setelah Anda mengetahui tempat untuk melanjutkan permintaan, kirim data yang tersisa atau potongan saat ini. Perhatikan bahwa Anda harus memperlakukan data yang tersisa sebagai potongan terpisah dalam kedua kasus tersebut, jadi Anda harus mengirim header Content-Range saat melanjutkan upload.
Contoh: Melanjutkan upload yang terhenti

1) Minta status upload.

Permintaan berikut menggunakan header Content-Range untuk menunjukkan bahwa posisi saat ini dalam file 2.000.000 byte tidak diketahui.

PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000

2) Ekstrak jumlah byte yang diupload sejauh ini dari respons.

Respons server menggunakan header Range untuk menunjukkan bahwa server sejauh ini telah menerima 43 byte pertama dari file. Gunakan nilai yang lebih tinggi dari header Range untuk menentukan tempat memulai upload yang dilanjutkan.

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: 0-42

Catatan: Mungkin saja respons statusnya adalah 201 Created atau 200 OK jika upload selesai. Hal ini bisa terjadi jika koneksi terputus setelah semua byte diupload tetapi sebelum klien menerima respons dari server.

3) Lanjutkan upload dari titik terakhir upload sebelumnya.

Permintaan berikut melanjutkan upload dengan mengirimkan byte file yang tersisa, mulai byte 43.

PUT {session_uri} HTTP/1.1
Content-Length: 1999957
Content-Range: bytes 43-1999999/2000000

bytes 43-1999999

Praktik terbaik

Saat mengupload media, sebaiknya perhatikan beberapa praktik terbaik terkait penanganan error.

  • Lanjutkan atau coba lagi upload yang gagal karena gangguan koneksi atau error 5xx, termasuk:
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • Gunakan strategi backoff eksponensial jika error server 5xx apa pun ditampilkan saat melanjutkan atau mencoba lagi permintaan upload. Error ini dapat terjadi jika server mengalami kelebihan beban. Backoff eksponensial dapat membantu mengurangi masalah semacam ini selama periode permintaan yang tinggi atau traffic jaringan yang tinggi.
  • Jenis permintaan lain seharusnya tidak ditangani oleh backoff eksponensial, tetapi Anda masih bisa mencoba kembali beberapa darinya. Saat mencoba kembali permintaan ini, batasi frekuensi Anda mencoba lagi. Misalnya, kode Anda dapat dibatasi hingga sepuluh percobaan ulang atau kurang sebelum melaporkan error.
  • Tangani error 404 Not Found dan 410 Gone saat melakukan upload yang dapat dilanjutkan dengan memulai seluruh upload dari awal.

Backoff eksponensial

Backoff eksponensial adalah strategi penanganan error standar untuk aplikasi jaringan, yang mana klien secara berkala mencoba lagi permintaan yang gagal, dengan menambah lamanya penundaan antara setiap permintaan yang gagal. Jika volume permintaan yang tinggi atau traffic jaringan yang tinggi menyebabkan server menampilkan error, backoff eksponensial mungkin merupakan strategi yang tepat untuk menangani error tersebut. Sebaliknya, ini bukan strategi yang relevan untuk menangani error yang tidak terkait dengan volume jaringan atau waktu respons, seperti kredensial otorisasi yang tidak valid atau error file tidak ditemukan.

Jika digunakan dengan benar, backoff eksponensial akan meningkatkan efisiensi penggunaan bandwidth, mengurangi jumlah permintaan yang diperlukan untuk mendapatkan respons yang berhasil, dan memaksimalkan throughput permintaan dalam lingkungan serentak.

Alur untuk mengimplementasikan backoff eksponensial sederhana adalah sebagai berikut:

  1. Buat permintaan ke API.
  2. Terima respons HTTP 503, yang menunjukkan bahwa Anda harus mencoba lagi permintaan tersebut.
  3. Tunggu 1 detik + random_number_milliseconds dan coba lagi permintaan tersebut.
  4. Terima respons HTTP 503, yang menunjukkan bahwa Anda harus mencoba lagi permintaan tersebut.
  5. Tunggu 2 detik + random_number_milliseconds dan coba lagi permintaan tersebut.
  6. Terima respons HTTP 503, yang menunjukkan bahwa Anda harus mencoba lagi permintaan tersebut.
  7. Tunggu 4 detik + random_number_milliseconds dan coba lagi permintaan tersebut.
  8. Terima respons HTTP 503, yang menunjukkan bahwa Anda harus mencoba lagi permintaan tersebut.
  9. Tunggu 8 detik + random_number_milliseconds dan coba lagi permintaan tersebut.
  10. Terima respons HTTP 503, yang menunjukkan bahwa Anda harus mencoba lagi permintaan tersebut.
  11. Tunggu 16 detik + random_number_milliseconds dan coba lagi permintaan tersebut.
  12. Stop. Laporkan atau buat log untuk error.

Pada alur di atas, random_number_milliseconds adalah angka acak milidetik yang kurang dari atau sama dengan 1.000. Ini diperlukan, karena memperkenalkan penundaan acak yang singkat akan membantu mendistribusikan beban dengan lebih merata dan menghindari kemungkinan penyerbuan server. Nilai random_number_milliseconds harus ditentukan ulang setelah setiap periode tunggu.

Catatan: Periode tunggu selalu (2 ^ n) + random_number_milliseconds, yang mana n adalah bilangan bulat yang meningkat secara monotonik, yang awalnya ditetapkan sebagai 0. Integer n ditambah dengan 1 untuk setiap iterasi (setiap permintaan).

Algoritma disetel untuk dihentikan jika n adalah 5. Batas ini mencegah agar klien tidak terus mencoba tanpa batas, dan mengakibatkan penundaan total sekitar 32 detik sebelum permintaan dianggap "error yang tidak dapat dipulihkan". Jumlah percobaan ulang maksimum yang lebih besar tidak masalah, terutama jika upload yang panjang sedang berlangsung; tetapi pastikan untuk membatasi penundaan percobaan ulang pada jumlah yang masuk akal, misalnya, kurang dari satu menit.

Panduan library klien API