Halaman ini diterjemahkan oleh Cloud Translation API.

Membuat Paket

Opsi upload

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

Kami menyediakan biner untuk Linux dan Windows guna memfasilitasi upload paket yang dapat dilanjutkan yang bebas Anda gunakan, bukan mengimplementasikan protokol yang dijelaskan di bawah. Jika Anda menginginkan integrasi yang lebih mendalam, gunakan salah satu protokol yang dijelaskan di bawah.

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 file biner dan kunci, Anda dapat menjalankannya dengan opsi command line untuk menentukan file kunci, deployment, dan paket yang akan diupload. Harap 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 file dan metadata berukuran lebih kecil dengan cepat; mentransfer file dengan metadata yang mendeskripsikannya, semuanya dalam satu permintaan.
Upload yang dapat dilanjutkan: X-Goog-Upload-Protocol: resumable. Untuk transfer yang andal, sangat penting untuk file dengan ukuran 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.

Upload multibagian

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 ke URI /upload/package 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 Anda gunakan untuk mengidentifikasi bagian permintaan.
Content-Length. Setel ke jumlah total byte dalam isi permintaan.

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:

Bagian metadata: Harus didahulukan, dan Content-Type harus application/json.
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. Di bawah ini adalah contoh permintaan yang mengasumsikan bahwa Anda menggunakan kunci layanan (lihat cara memberi 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 melanjutkan operasi upload setelah kegagalan komunikasi mengganggu aliran data. Hal ini sangat berguna jika Anda mentransfer file besar dan ada kemungkinan terjadinya gangguan jaringan atau kegagalan transmisi lainnya yang tinggi, misalnya saat mengupload dari aplikasi klien seluler. Hal ini juga dapat mengurangi penggunaan bandwidth jika terjadi kegagalan jaringan, karena Anda tidak perlu memulai ulang upload file berukuran besar dari awal.

Protokol upload yang dapat dilanjutkan menggunakan beberapa perintah:

Mulai sesi yang dapat dilanjutkan. Buat permintaan awal ke URI upload yang menyertakan metadata dan tetapkan lokasi upload unik yang dapat dilanjutkan.
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.
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 terganggu, cari tahu berapa banyak data yang berhasil diterima, lalu lanjutkan upload mulai dari titik tersebut.

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

Langkah 1: Mulai sesi yang dapat dilanjutkan

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

Untuk permintaan yang memulai ini, isi harus berisi metadata saja; Anda akan mentransfer konten sebenarnya dari 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 file yang 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, server API menyediakan header X-Goog-Upload-URL yang menentukan URI sesi yang dapat dilanjutkan. Header X-Goog-Upload-URL, yang ditampilkan dalam contoh di bawah, menyertakan bagian parameter kueri upload_id yang memberikan ID upload unik untuk digunakan pada sesi ini. Respons juga berisi header X-Goog-Upload-Status, yang akan berupa 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 dalam contoh respons di atas, adalah URI sesi yang akan Anda gunakan sebagai endpoint HTTP untuk melakukan upload file sebenarnya atau mengkueri 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:

Content-Length. Setel ini ke jumlah byte yang Anda upload dalam permintaan ini, yang umumnya merupakan ukuran file upload.
X-Goog-Upload-Command. Setel ke upload dan finalize.
X-Goog-Upload-Offset. Parameter ini menentukan offset yang digunakan untuk menulis byte. 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 saat 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 terhenti atau jika Anda menerima respons 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 biasanya tidak diperlukan. Sebaiknya klien mengupload semua byte payload yang tersisa dan menyertakan perintah finalize dengan setiap perintah upload.

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

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. Parameter ini menentukan offset yang digunakan untuk menulis byte. 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 semua bagian yang dikirim oleh klien. Semua potongan harus dimulai pada offset yang selaras dengan nilai header ini, dan semua potongan (kecuali potongan terakhir) harus memiliki ukuran yang merupakan kelipatan dari nilai header ini. Jika header tidak disediakan oleh server, maka 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 terhenti atau jika Anda menerima respons 503 Service Unavailable HTTP atau respons 5xx lain dari server, ikuti prosedur yang diuraikan dalam melanjutkan upload yang terhenti. Namun, cukup lanjutkan mengupload potongan dari titik tersebut, bukan mengupload sisa file.

Catatan Penting:

Pastikan untuk menyelesaikan sesi ketika Anda 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 lanjutkan upload yang terhenti segera setelah terjadi gangguan.
Jika Anda mengirimkan permintaan dengan ID sesi upload yang sudah tidak berlaku lagi, server akan menampilkan kode status 404 Not Found. Dalam hal 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 yang ditetapkan ke final.

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 melakukannya:

Status permintaan. Buat kueri status upload saat ini dengan mengajukan permintaan ke URI upload dengan X-Goog-Upload-Command yang ditetapkan ke query.
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.
Dapatkan jumlah byte yang diupload. Proses respons dari kueri status. Server menggunakan header X-Goog-Upload-Size-Received dalam responsnya untuk menentukan jumlah byte yang telah diterima sejauh ini.
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 perlu menyetel header X-Goog-Upload-Offset ke offset yang sesuai 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 dari 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 server telah menerima 43 byte pertama 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:

Buat permintaan ke API.
Terima respons HTTP 503, yang menunjukkan bahwa Anda harus mencoba lagi permintaan tersebut.
Tunggu 1 detik + random_number_milliseconds dan coba lagi permintaan tersebut.
Terima respons HTTP 503, yang menunjukkan bahwa Anda harus mencoba lagi permintaan tersebut.
Tunggu 2 detik + random_number_milliseconds dan coba lagi permintaan tersebut.
Terima respons HTTP 503, yang menunjukkan bahwa Anda harus mencoba lagi permintaan tersebut.
Tunggu 4 detik + random_number_milliseconds dan coba lagi permintaan tersebut.
Terima respons HTTP 503, yang menunjukkan bahwa Anda harus mencoba lagi permintaan tersebut.
Tunggu 8 detik + random_number_milliseconds dan coba lagi permintaan tersebut.
Terima respons HTTP 503, yang menunjukkan bahwa Anda harus mencoba lagi permintaan tersebut.
Tunggu 16 detik + random_number_milliseconds dan coba lagi permintaan tersebut.
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.