یک بسته ایجاد کنید

گزینه های آپلود

Android Over The Air API به شما امکان می دهد داده های بسته را برای ایجاد یک منبع بسته جدید آپلود کنید. اینها بسته های OTA هستند که می توانند با یک یا چند پیکربندی مرتبط شوند تا به روز رسانی به دستگاه ها تحویل داده شود.

ما یک باینری برای لینوکس و ویندوز ارائه می دهیم تا بارگذاری بسته های قابل ازسرگیری را تسهیل کنیم که می توانید به جای اجرای پروتکل های شرح داده شده در زیر، از آن استفاده کنید. اگر مایل به یکپارچگی عمیق تر هستید، لطفاً از یکی از پروتکل های شرح داده شده در زیر استفاده کنید.

لینوکس

کلاینت آپلودکننده Android Over The Air API v1 را برای لینوکس دانلود کنید .

پنجره ها

کلاینت آپلودکننده Android Over The Air API v1 را برای ویندوز دانلود کنید .

برای استفاده از آن، ابتدا باید یک حساب سرویس ایجاد کنید و یک فایل کلید JSON برای آن حساب دریافت کنید. لطفاً راهنمای ما را برای ایجاد حساب اینجا ببینید.
هنگامی که فایل باینری و کلید را در اختیار دارید، می توانید آن را با گزینه های خط فرمان اجرا کنید تا فایل کلید، استقرار خود و بسته ای را که آپلود می کنید مشخص کنید. لطفا از --help برای دیدن همه گزینه ها استفاده کنید.

آپلود پروتکل ها

شما می توانید درخواست های آپلود را به یکی از روش های زیر ارسال کنید. روشی را که با هدر درخواست X-Goog-Upload-Protocol استفاده می کنید، مشخص کنید.

  • آپلود چند قسمتی : X-Goog-Upload-Protocol: multipart . برای انتقال سریع فایل های کوچکتر و متادیتا؛ فایل را به همراه ابرداده ای که آن را توصیف می کند، همه در یک درخواست منتقل می کند.
  • بارگذاری مجدد : X-Goog-Upload-Protocol: resumable . برای انتقال مطمئن، به ویژه در مورد فایل های بزرگتر مهم است. با این روش، شما از یک درخواست شروع جلسه استفاده می کنید که به صورت اختیاری می تواند شامل ابرداده باشد. این یک استراتژی خوب برای استفاده برای اکثر برنامه‌ها است، زیرا برای فایل‌های کوچک‌تر نیز با هزینه یک درخواست HTTP اضافی در هر بارگذاری کار می‌کند.

آپلود چند قسمتی

اگر داده‌هایی که می‌فرستید به اندازه‌ای کوچک هستند که در صورت خرابی اتصال، دوباره به طور کامل آپلود شوند، این انتخاب خوبی است.

برای استفاده از آپلود چند قسمتی، یک درخواست POST به /upload/package URI ارسال کنید و X-Goog-Upload-Protocol روی multipart تنظیم کنید.

هدرهای سطح بالای HTTP برای استفاده در هنگام درخواست آپلود چند قسمتی عبارتند از:

  • Content-Type . روی چندبخشی/مرتبط تنظیم کنید و رشته مرزی را که برای شناسایی بخش‌های درخواست استفاده می‌کنید، اضافه کنید.
  • Content-Length . تعداد کل بایت ها را در بدنه درخواست تنظیم کنید.

بدنه درخواست به عنوان یک نوع محتوای multipart/related [ RFC2387 ] فرمت شده است و دقیقاً شامل دو بخش است. قسمت ها با یک رشته مرزی مشخص می شوند و رشته مرزی نهایی با دو خط فاصله دنبال می شود.

هر بخش از درخواست چند قسمتی به یک سرصفحه Content-Type اضافی نیاز دارد:

  1. بخش فراداده: باید اول باشد و Content-Type باید application/json باشد.
  2. بخش رسانه: باید در رتبه دوم قرار گیرد و Content-Type باید application/zip باشد.

مثال: آپلود چند قسمتی

مثال زیر یک درخواست آپلود چند قسمتی برای 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--

اگر درخواست با موفقیت انجام شود، سرور کد وضعیت HTTP 200 OK را برمی گرداند

HTTP/1.1 200

راهی برای به راحتی انجام این کار استفاده از curl و oauth2l است. در زیر یک نمونه درخواست وجود دارد که فرض می‌کند از یک کلید سرویس استفاده می‌کنید (برای اطلاعات بیشتر به مجوز ما مراجعه کنید).

نمونه درخواست حلقه
    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

بارگذاری مجدد

برای آپلود مطمئن تر فایل های داده، می توانید از پروتکل بارگذاری مجدد استفاده کنید. این پروتکل به شما این امکان را می دهد که پس از قطع ارتباط جریان داده ها، عملیات آپلود را از سر بگیرید. مخصوصاً اگر در حال انتقال فایل‌های حجیم هستید و احتمال قطع شدن شبکه یا سایر خرابی‌های انتقال زیاد است، مثلاً هنگام آپلود کردن از یک برنامه مشتری تلفن همراه. همچنین می تواند استفاده از پهنای باند شما را در صورت خرابی شبکه کاهش دهد زیرا مجبور نیستید بارگذاری فایل های بزرگ را از ابتدا مجدداً راه اندازی کنید.

پروتکل بارگذاری مجدد از چندین دستور استفاده می کند:

  1. یک جلسه قابل ازسرگیری را شروع کنید . یک درخواست اولیه به URI آپلود که شامل ابرداده است و یک مکان آپلود قابل ازسرگیری منحصر به فرد را ایجاد می کند.
  2. URI جلسه قابل ازسرگیری را ذخیره کنید . URI جلسه ای را که در پاسخ درخواست اولیه بازگردانده شده است ذخیره کنید. شما از آن برای درخواست های باقی مانده در این جلسه استفاده خواهید کرد.
  3. فایل را آپلود کنید . تمام یا بخشی از فایل ZIP را به URI جلسه قابل تجدید ارسال کنید.

علاوه بر این، برنامه‌هایی که از آپلود قابل ازسرگیری استفاده می‌کنند باید کد داشته باشند تا آپلود قطع شده را از سر بگیرند . اگر آپلود قطع شد، ببینید چه مقدار داده با موفقیت دریافت شده است و سپس آپلود را از همان نقطه شروع کنید.

توجه: URI آپلود پس از 3 روز منقضی می شود.

مرحله 1: یک جلسه قابل ازسرگیری را شروع کنید

برای شروع آپلود مجدد، یک درخواست POST به /upload/package URI ارسال کنید و X-Goog-Upload-Protocol روی resumable تنظیم کنید.

برای این درخواست آغازگر، بدنه باید فقط حاوی ابرداده باشد. شما محتویات واقعی فایلی را که می خواهید آپلود کنید در درخواست های بعدی منتقل خواهید کرد.

از هدرهای HTTP زیر برای درخواست اولیه استفاده کنید:

  • X-Goog-Upload-Header-Content-Type . این نوع محتوای فایل در حال آپلود است و باید روی application/zip تنظیم شود.
  • X-Goog-Upload-Command . برای start تنظیم کنید
  • X-Goog-Upload-Header-Content-Length . تعداد بایت های داده آپلود را برای انتقال در درخواست های بعدی تنظیم کنید. اگر طول در زمان این درخواست ناشناخته است، می توانید این هدر را حذف کنید.
  • Content-Type . این نوع محتوای فراداده است و باید روی application/json تنظیم شود.
  • Content-Length . تعداد بایت های ارائه شده در بدنه این درخواست اولیه را تنظیم کنید.
مثال: درخواست شروع مجدد جلسه

مثال زیر نشان می دهد که چگونه می توان یک جلسه قابل ازسرگیری برای 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" }

بخش بعدی نحوه رسیدگی به پاسخ را شرح می دهد.

مرحله 2: URI جلسه قابل تجدید را ذخیره کنید

اگر درخواست شروع جلسه با موفقیت انجام شود، سرور API با یک کد وضعیت HTTP 200 OK پاسخ می دهد. علاوه بر این، یک هدر X-Goog-Upload-URL ارائه می کند که URI جلسه قابل ازسرگیری شما را مشخص می کند. هدر X-Goog-Upload-URL ، که در مثال زیر نشان داده شده است، شامل بخش پارامتر query upload_id است که شناسه آپلود منحصر به فرد را برای استفاده در این جلسه می دهد. این پاسخ همچنین حاوی یک هدر X-Goog-Upload-Status است که در صورت معتبر بودن و پذیرش درخواست آپلود active خواهد بود. در صورت رد شدن آپلود، این وضعیت ممکن است final شود.

مثال: پاسخ شروع مجدد جلسه

در اینجا پاسخ به درخواست در مرحله 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

مقدار هدر X-Goog-Upload-URL ، همانطور که در پاسخ مثال بالا نشان داده شده است، URI جلسه ای است که به عنوان نقطه پایانی HTTP برای انجام بارگذاری واقعی فایل یا پرس و جو از وضعیت آپلود استفاده می کنید.

URI جلسه را کپی و ذخیره کنید تا بتوانید برای درخواست های بعدی از آن استفاده کنید.

مرحله 3: فایل را آپلود کنید

برای آپلود فایل، یک درخواست POST به URI آپلود که در مرحله قبل به دست آوردید، ارسال کنید. فرمت درخواست آپلود:

POST session_uri

هدرهای HTTP برای استفاده در هنگام درخواست بارگذاری مجدد فایل عبارتند از:

  1. Content-Length . این را روی تعداد بایت هایی که در این درخواست آپلود می کنید، تنظیم کنید، که معمولاً اندازه فایل آپلود است.
  2. X-Goog-Upload-Command . این را برای upload و finalize تنظیم کنید.
  3. X-Goog-Upload-Offset . این افستی که بایت ها باید در آن نوشته شوند را مشخص می کند. توجه داشته باشید که کلاینت ها باید بایت ها را به صورت سریال آپلود کنند.
مثال: درخواست بارگذاری مجدد فایل

در اینجا یک درخواست مجدد برای آپلود کل فایل ZIP 2,000,000 بایتی برای مثال فعلی وجود دارد.

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

اگر درخواست با موفقیت انجام شود، سرور با یک HTTP 200 Ok پاسخ می دهد.

اگر درخواست آپلود قطع شد یا اگر یک 503 Service Unavailable یا هر پاسخ 5xx دیگری از سرور دریافت کردید، رویه ذکر شده در رزومه آپلود قطع شده را دنبال کنید.

آپلود فایل به صورت تکه تکه

با آپلودهای قابل ازسرگیری، می توانید یک فایل را به قطعات تقسیم کنید و یک سری درخواست برای آپلود هر تکه به ترتیب ارسال کنید. این رویکرد ترجیحی نیست زیرا هزینه‌های عملکرد مرتبط با درخواست‌های اضافی وجود دارد و معمولاً نیازی به آن نیست. ما توصیه می‌کنیم که کلاینت‌ها تمام بایت‌های باقی‌مانده از payload را آپلود کنند و فرمان finalize را با هر دستور upload اضافه کنند.

با این حال، ممکن است لازم باشد از chunking برای کاهش مقدار داده های منتقل شده در هر درخواست استفاده کنید. همچنین به شما امکان می دهد کارهایی مانند ارائه نشانه های پیشرفت آپلود برای مرورگرهای قدیمی که به طور پیش فرض از پیشرفت آپلود پشتیبانی نمی کنند، انجام دهید.

از سرگیری آپلود قطع شده

اگر یک درخواست آپلود قبل از دریافت پاسخ خاتمه یافت یا اگر پاسخ HTTP 503 Service Unavailable از سرور دریافت کردید، باید آپلود قطع شده را از سر بگیرید. برای انجام این:

  1. وضعیت درخواست با ارسال یک درخواست به URI آپلود با X-Goog-Upload-Command روی query تنظیم شده است، وضعیت فعلی آپلود را پرس و جو کنید.

    توجه: شما می توانید وضعیت را بین تکه ها درخواست کنید، نه فقط اگر آپلود قطع شود. برای مثال، اگر می‌خواهید نشانه‌های پیشرفت آپلود را برای مرورگرهای قدیمی نشان دهید، مفید است.

  2. دریافت تعداد بایت های آپلود شده پاسخ از پرس و جو وضعیت را پردازش کنید. سرور در پاسخ خود از هدر X-Goog-Upload-Size-Received استفاده می کند تا مشخص کند تا کنون چند بایت دریافت کرده است.
  3. داده های باقی مانده را بارگذاری کنید. در نهایت، اکنون که می‌دانید کجا درخواست را از سر بگیرید، داده‌های باقی‌مانده یا تکه فعلی را ارسال کنید. توجه داشته باشید که در هر صورت باید داده های باقیمانده را به عنوان یک تکه جداگانه در نظر بگیرید، بنابراین باید هنگام از سرگیری آپلود، هدر X-Goog-Upload-Offset را روی افست مناسب تنظیم کنید.
مثال: از سرگیری آپلود قطع شده

1) وضعیت آپلود را درخواست کنید.

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

مانند تمام دستورات، کلاینت باید هدر X-Goog-Upload-Status در پاسخ HTTP یک فرمان پرس و جو بررسی کند. اگر هدر موجود باشد و مقدار آن active نباشد، آپلود قبلاً خاتمه یافته است.

2) تعداد بایت های آپلود شده تا کنون را از پاسخ استخراج کنید.

پاسخ سرور از هدر X-Goog-Upload-Size-Received استفاده می کند تا نشان دهد که تاکنون 43 بایت اول فایل را دریافت کرده است.

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

3) آپلود را از نقطه ای که متوقف شد از سر بگیرید.

درخواست زیر با ارسال بایت‌های باقی‌مانده فایل که از بایت 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

بهترین شیوه ها

هنگام آپلود رسانه، آگاهی از برخی بهترین شیوه های مربوط به مدیریت خطا مفید است.

  • آپلودهایی را که به دلیل قطع اتصال یا هر گونه خطای 5xx ناموفق هستند، از سر بگیرید یا دوباره امتحان کنید، از جمله:
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • اگر هنگام از سرگیری یا تلاش مجدد درخواست های آپلود، خطای سرور 5xx برگردانده شد، از یک استراتژی عقب نشینی نمایی استفاده کنید. این خطاها ممکن است در صورت بارگیری بیش از حد سرور رخ دهند. عقب‌نشینی نمایی می‌تواند به کاهش این نوع مشکلات در دوره‌های پر حجم درخواست‌ها یا ترافیک سنگین شبکه کمک کند.
  • دیگر انواع درخواست‌ها را نباید با عقب‌نشینی تصاعدی بررسی کرد، اما همچنان می‌توانید تعدادی از آنها را دوباره امتحان کنید. هنگام امتحان مجدد این درخواست ها، تعداد دفعات تکرار آنها را محدود کنید. به عنوان مثال، کد شما می تواند قبل از گزارش خطا به 10 تکرار یا کمتر محدود شود.
  • با شروع کل آپلود از ابتدا، خطاهای 404 Not Found را هنگام انجام آپلودهای قابل ازسرگیری مدیریت کنید.

عقب نشینی نمایی

عقب نشینی نمایی یک استراتژی استاندارد مدیریت خطا برای برنامه های کاربردی شبکه است که در آن کلاینت به طور دوره ای یک درخواست ناموفق را در مدت زمان فزاینده ای تکرار می کند. اگر حجم بالای درخواست‌ها یا ترافیک شبکه سنگین باعث شود سرور خطاها را برگرداند، پس‌انداز نمایی ممکن است استراتژی خوبی برای رسیدگی به این خطاها باشد. برعکس، این یک استراتژی مناسب برای برخورد با خطاهای غیرمرتبط با حجم شبکه یا زمان پاسخ، مانند اعتبارنامه های مجوز نامعتبر یا خطاهای یافت نشدن فایل نیست.

اگر به درستی استفاده شود، پس‌انداز نمایی کارایی استفاده از پهنای باند را افزایش می‌دهد، تعداد درخواست‌های مورد نیاز برای دریافت پاسخ موفقیت‌آمیز را کاهش می‌دهد و توان عملیاتی درخواست‌ها را در محیط‌های همزمان به حداکثر می‌رساند.

جریان برای پیاده سازی عقب نشینی نمایی ساده به شرح زیر است:

  1. یک درخواست به API بدهید.
  2. پاسخ HTTP 503 را دریافت کنید، که نشان می دهد باید درخواست را دوباره امتحان کنید.
  3. 1 ثانیه + random_number_milliseconds صبر کنید و دوباره درخواست را امتحان کنید.
  4. پاسخ HTTP 503 را دریافت کنید، که نشان می دهد باید درخواست را دوباره امتحان کنید.
  5. 2 ثانیه + random_number_milliseconds صبر کنید و دوباره درخواست را امتحان کنید.
  6. پاسخ HTTP 503 را دریافت کنید، که نشان می دهد باید درخواست را دوباره امتحان کنید.
  7. 4 ثانیه + random_number_milliseconds صبر کنید و دوباره درخواست را امتحان کنید.
  8. پاسخ HTTP 503 را دریافت کنید، که نشان می دهد باید درخواست را دوباره امتحان کنید.
  9. ۸ ثانیه + random_number_milliseconds صبر کنید و دوباره درخواست را امتحان کنید.
  10. پاسخ HTTP 503 را دریافت کنید، که نشان می دهد باید درخواست را دوباره امتحان کنید.
  11. 16 ثانیه + random_number_milliseconds صبر کنید و دوباره درخواست را امتحان کنید.
  12. متوقف کردن. یک خطا را گزارش یا ثبت کنید.

در جریان فوق، random_number_milliseconds تعداد تصادفی میلی‌ثانیه کمتر یا مساوی 1000 است. این امر ضروری است، زیرا ارائه یک تاخیر تصادفی کوچک به توزیع یکنواخت بار و جلوگیری از احتمال ضربه زدن به سرور کمک می‌کند. مقدار random_number_milliseconds باید بعد از هر انتظار دوباره تعریف شود.

توجه: انتظار همیشه (2 ^ n) + random_number_milliseconds است، که در آن n یک عدد صحیح افزایشی یکنواخت است که در ابتدا 0 تعریف شده است. عدد صحیح n برای هر تکرار (هر درخواست) 1 افزایش می یابد.

الگوریتم تنظیم شده است تا زمانی که n 5 باشد خاتمه یابد. این سقف مانع از تلاش مجدد مشتریان برای بی نهایت می شود و منجر به تأخیر کلی در حدود 32 ثانیه قبل از اینکه یک درخواست "خطایی غیرقابل جبران" تلقی شود، می شود. حداکثر تعداد بیشتری از تلاش های مجدد خوب است، به خصوص اگر یک آپلود طولانی در حال انجام باشد. فقط مطمئن شوید که تاخیر تلاش مجدد را در چیزی معقول، مثلاً کمتر از یک دقیقه محدود کنید.