Membuat Paket

Opsi upload

Android Over The Air API memungkinkan Anda mengupload data paket untuk membuat resource Package baru. Berikut adalah Paket OTA yang dapat dikaitkan dengan satu atau beberapa konfigurasi sehingga update dikirimkan ke perangkat.

Kami menyediakan biner untuk Linux dan Windows untuk memfasilitasi upload paket yang dapat dilanjutkan bebas digunakan daripada menerapkan protokol yang dijelaskan di bawah ini. Jika Anda ingin mempelajari integrasi Anda, harap gunakan salah satu protokol yang dijelaskan di bawah ini.

Catatan: Biner ini disediakan apa adanya tanpa dukungan sesuai dengan persyaratan layanan.

Linux

Download klien uploader Android Over The Air API v1 untuk Linux.

Windows

Download klien uploader Android Over The Air API v1 untuk Windows.

Untuk menggunakannya, pertama-tama Anda harus membuat akun layanan dan mendapatkan file kunci JSON untuk akun tersebut. Lihat panduan kami untuk membuat akun di sini.
Setelah memiliki biner dan file kunci, Anda dapat menjalankannya dengan opsi command line untuk menentukan file kunci, deployment, dan paket yang Anda upload. Gunakan --help untuk melihat semua opsi.

Protokol Upload

Anda dapat membuat permintaan upload dengan salah satu cara berikut. Tentukan metode yang Anda gunakan dengan header permintaan X-Goog-Upload-Protocol.

• Upload multibagian: X-Goog-Upload-Protocol: multipart. Untuk mentransfer dengan cepat file dan {i>metadata<i} yang lebih kecil; mentransfer file beserta metadata yang menjelaskannya, semuanya dalam satu permintaan.
• Upload yang dapat dilanjutkan: X-Goog-Upload-Protocol: resumable. Untuk transfer yang andal, sangat penting dengan . Dengan metode ini, Anda menggunakan permintaan untuk memulai sesi, yang secara opsional dapat menyertakan metadata. Ini adalah strategi yang baik untuk digunakan oleh aplikasi, karena ia juga berfungsi untuk file yang lebih kecil dan hanya memerlukan satu permintaan HTTP tambahan per unggahan.

Upload multibagian

Ini adalah pilihan yang baik jika data yang Anda kirim berukuran kecil cukup untuk mengunggah lagi secara keseluruhan jika koneksi gagal.

Untuk menggunakan upload multibagian, buat permintaan POST ke /upload/package URI dan tetapkan X-Goog-Upload-Protocol ke multipart.

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

• Content-Type. Setel ke multibagian/terkait dan sertakan string batas yang gunakan untuk mengidentifikasi bagian-bagian dari permintaan.
• Content-Length. Setel ke jumlah total byte dalam isi permintaan.

Isi permintaan diformat sebagai konten multipart/related ketik [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 application/json.
2. Bagian media: Harus ada di urutan kedua, dan Content-Type harus application/zip.

Contoh: Upload multibagian

Contoh di bawah ini menunjukkan permintaan upload multibagian untuk Android Over The Air API.

POST /upload/package HTTP/1.1
Host: androidovertheair.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=BOUNDARY
Content-Length: number_of_bytes_in_entire_request_body

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

{"deployment": "id", "package_title": "title" }
--BOUNDARY
Content-Type: application/zip; charset=UTF-8

Package ZIP
--BOUNDARY--

Jika permintaan berhasil, server akan menampilkan kode status 200 OK HTTP

HTTP/1.1 200

Cara untuk melakukannya dengan mudah adalah dengan menggunakan curl dan oauth2l. Berikut adalah contoh permintaan yang mengasumsikan Anda menggunakan kunci layanan (lihat perintah otorisasi untuk informasi lebih lanjut).

Contoh permintaan curl

    JSON={"deployment": "id", "package_title": "title" }
    SERVICE_KEY_FILE=path to your service key json file
    curl \
    -H "$(./oauth2l header --json $SERVICE_KEY_FILE android_partner_over_the_air)" \
    -H "Host: androidovertheair.googleapis.com" \
    -H "X-Goog-Upload-Protocol: multipart" \
    -H "Content-Type: multipart/form-data" \
    -F "json=$JSON;type=application/json" \
    -F "data=@update.zip;type=application/zip" \
    androidovertheair.googleapis.com/upload/package
  

Upload yang dapat dilanjutkan

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

Protokol upload yang dapat dilanjutkan menggunakan beberapa perintah:

1. Mulai sesi yang dapat dilanjutkan. Buat permintaan awal ke URI upload yang menyertakan metadata dan menetapkan lokasi upload unik yang dapat dilanjutkan.
2. Simpan URI sesi yang dapat dilanjutkan. Simpan URI sesi yang ditampilkan di respons permintaan awal; Anda akan menggunakannya untuk permintaan yang tersisa dalam sesi ini.
3. Upload file. Kirim semua atau sebagian file ZIP 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 bersifat terputus, cari tahu berapa banyak data yang berhasil diterima, lalu lanjutkan upload mulai dari titik tersebut.

Catatan: Masa berlaku URI upload akan berakhir setelah 3 hari.

Langkah 1: Mulai sesi yang dapat dilanjutkan

Untuk memulai upload yang dapat dilanjutkan, buat permintaan POST ke /upload/package URI dan tetapkan X-Goog-Upload-Protocol ke resumable.

Untuk permintaan memulai ini, isi hanya boleh berisi metadata; Anda akan mentransfer isi file yang ingin Anda upload dalam permintaan berikutnya.

Gunakan header HTTP berikut dengan permintaan awal:

• X-Goog-Upload-Header-Content-Type. Ini adalah jenis konten dari file yang sedang diupload dan harus ditetapkan ke application/zip.
• X-Goog-Upload-Command. Disetel ke start
• X-Goog-Upload-Header-Content-Length. Setel ke jumlah byte data upload yang akan ditransfer dalam permintaan berikutnya. Jika panjangnya tidak diketahui pada saat permintaan ini, Anda dapat menghilangkan header ini.
• Content-Type. Ini adalah jenis konten metadata dan harus ditetapkan ke application/json.
• Content-Length. Setel ke jumlah byte yang diberikan dalam isi permintaan awal ini.

Contoh: Permintaan untuk memulai sesi yang dapat dilanjutkan

Contoh berikut menunjukkan cara memulai sesi yang dapat dilanjutkan untuk Android Over The Air API.

POST /upload/package HTTP/1.1
Host: android/over-the-air.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Goog-Upload-Command: start
X-Goog-Upload-Header-Content-Type: application/zip
X-Goog-Upload-Header-Content-Length: 2000000

{"deployment": "id", "package_title": "title" }

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, menyediakan header X-Goog-Upload-URL yang menentukan URI sesi yang dapat dilanjutkan. Header X-Goog-Upload-URL, yang ditunjukkan dalam contoh di bawah, menyertakan parameter kueri upload_id yang memberikan ID upload unik untuk digunakan dalam sesi ini. Respons juga berisi X-Goog-Upload-Status header, yaitu active jika permintaan upload valid dan diterima. Status ini mungkin final jika upload ditolak.

Contoh: Respons memulai sesi yang dapat dilanjutkan

Berikut adalah respons terhadap permintaan pada Langkah 1:

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-URL: androidovertheair.googleapis.com/?upload_id=xa298sd_sdlkj2
Content-Length: 0

Nilai header X-Goog-Upload-URL, 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 POST ke URI upload yang Anda dapatkan di langkah sebelumnya. Format permintaan upload adalah:

POST session_uri

Header HTTP yang akan digunakan saat membuat permintaan upload file yang dapat dilanjutkan meliputi:

1. Content-Length. Setel ini ke jumlah byte yang Anda upload dalam permintaan ini, yang umumnya merupakan ukuran file upload.
2. X-Goog-Upload-Command. Tetapkan ini ke upload dan finalize.
3. X-Goog-Upload-Offset. Hal ini menentukan offset di mana byte harus ditulis. Perhatikan bahwa klien harus mengupload byte secara berurutan.

Contoh: Permintaan upload file yang dapat dilanjutkan

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

POST /?upload_id=xa298sd_sdlkj2 HTTP/1.1
Host: androidovertheair.googleapis.com
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0
Content-Length: 2000000
Content-Type: application/zip

bytes 0-1999999

Jika permintaan berhasil, server merespons dengan 200 Ok HTTP.

Jika permintaan upload terganggu atau jika Anda menerima 503 Service Unavailable HTTP atau respons 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 itu umumnya tidak diperlukan. Sebaiknya klien mengupload semua byte payload yang tersisa dan sertakan perintah finalize dengan setiap perintah upload.

Namun, Anda mungkin perlu menggunakan pemotongan untuk mengurangi jumlah data yang ditransfer permintaan tunggal. Ini juga memungkinkan Anda melakukan hal-hal seperti memberikan indikasi progres upload untuk browser lama yang secara {i>default<i} tidak memiliki dukungan progres upload.

Luaskan untuk info lebih lanjut

Jika Anda mengupload data dalam potongan, gunakan X-Goog-Upload-Offset untuk menunjukkan offset yang Anda upload.

• Content-Length. Setel ke ukuran potongan atau yang lebih kecil, yang mungkin berlaku untuk permintaan terakhir.
• X-Goog-Upload-Offset. Hal ini menentukan offset di mana byte harus ditulis. Perhatikan bahwa klien harus mengupload byte secara berurutan.

Pembatasan ukuran bagian: Server dapat merespons dengan header X-Goog-Upload-Chunk-Granularity yang menentukan penyelarasan byte dan perincian ukuran dari semua potongan yang dikirim oleh klien. Semua potongan harus dimulai pada yang selaras dengan nilai {i>header<i} ini, dan semua potongan (kecuali potongan terakhir) harus memiliki ukuran dari nilai {i>header<i} ini. Jika header tidak disediakan oleh server, tidak ada persyaratan penyelarasan atau perincian.

Contoh: Permintaan upload file potongan yang dapat dilanjutkan

Permintaan yang mengirimkan 524.288 byte pertama mungkin terlihat seperti ini:

POST /?upload_id=xa298sd_sdlkj2 HTTP/1.1
Host: androidovertheair.googleapis.com
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0
Content-Type: application/zip
Content-Length: 524288

bytes 0-524288

Jika permintaan berhasil, server merespons dengan 200 Ok HTTP.

Jika ada permintaan PUT potongan yang terganggu atau jika Anda menerima 503 Service Unavailable atau HTTP respons 5xx lainnya dari server, ikuti prosedur yang diuraikan dalam lanjutkan upload yang terhenti, tetapi alih-alih mengupload sisa file, cukup lanjutkan mengupload potongan dari titik itu.

Catatan Penting:

• Pastikan untuk menyelesaikan sesi ketika Anda telah selesai mengirim semua potongan.
• Setiap URI upload memiliki masa berlaku yang terbatas dan akan berakhir (dalam waktu sekitar satu hari, jika tidak digunakan). Karena alasan ini, sebaiknya mulai upload yang dapat dilanjutkan segera setelah Anda mendapatkan URI upload, dan melanjutkan upload yang terhenti sesaat setelah terjadi gangguan.
• Jika Anda mengirimkan permintaan dengan ID sesi upload yang sudah tidak berlaku lagi, server akan menampilkan status 404 Not Found pada kode sumber. Dalam kasus ini, Anda harus memulai upload dapat dilanjutkan yang baru, mendapatkan URI upload baru, dan memulai upload dari awal menggunakan endpoint baru.

Saat seluruh upload file selesai, server merespons dengan 200 Ok HTTP beserta X-Goog-Upload-Status ditetapkan ke final.

---

Melanjutkan upload yang terhenti

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

1. Status permintaan. Buat kueri status upload saat ini dengan mengajukan permintaan ke URI upload dengan X-Goog-Upload-Command ditetapkan ke query.

   Catatan: Anda dapat meminta status di antara setiap potongan, bukan hanya jika upload terganggu. Ini adalah 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 X-Goog-Upload-Size-Received dalam responsnya untuk menentukan berapa banyak byte yang telah diterima sejauh ini.
3. Upload data yang tersisa. Terakhir, setelah Anda tahu di mana harus melanjutkan permintaan, kirim data yang tersisa atau potongan saat ini. Perhatikan bahwa Anda perlu memperlakukan data yang tersisa sebagai potongan terpisah dalam kedua kasus tersebut, jadi Anda harus menyetel header X-Goog-Upload-Offset ke offset yang tepat saat melanjutkan upload.

Contoh: Melanjutkan upload yang terhenti

1) Minta status upload.

POST /?upload_id=xa298sd_sdlkj2 HTTP/1.1
Host: androidovertheair.googleapis.com
X-Goog-Upload-Command: query

Seperti semua perintah, klien harus memeriksa header X-Goog-Upload-Status dalam respons HTTP perintah kueri. Jika header ada dan nilainya bukan active, berarti upload telah dihentikan.

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

Respons server menggunakan header X-Goog-Upload-Size-Received untuk menunjukkan bahwa respons menerima 43 byte pertama dari file sejauh ini.

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-Size-Received: 42

3) Lanjutkan upload dari titik terakhir upload sebelumnya.

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

POST /?upload_id=xa298sd_sdlkj2 HTTP/1.1
Host: androidovertheair.googleapis.com
X-Goog-Upload-Command: upload, finalize
Content-Length: 1999957
X-Goog-Upload-Offset: 43

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 10 percobaan ulang atau kurang sebelum melaporkan error.
• Tangani error 404 Not Found 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. Hal 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.