إنشاء حزمة

خيارات التحميل

تتيح لك واجهة برمجة التطبيقات Android Over The Air API تحميل بيانات الحزمة لإنشاء مورد حزمة جديد. وهي حزم التحديث عبر الهواء التي يمكن ربطها بإعداد واحد أو أكثر حتى يتم تسليم التحديث للأجهزة.

ونحن نقدم برنامجًا ثنائيًا لنظامي التشغيل Linux وWindows من أجل تسهيل تحميلات الحزمة القابلة للاستئناف التي مجانية الاستخدام بدلاً من تنفيذ البروتوكولات الموضحة أدناه. إذا كنت ترغب في فهم التكامل، يُرجى استخدام أحد البروتوكولات الموضحة أدناه.

ولاستخدامه، عليك أولاً إنشاء حساب خدمة والحصول على ملف مفتاح 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) الخاص بالجلسة القابلة للاستئناف

إذا نجح طلب بدء الجلسة، يستجيب خادم واجهة برمجة التطبيقات برمز حالة HTTP 200 OK. بالإضافة إلى ذلك، توفّر السياسة عنوان X-Goog-Upload-URL يحدّد معرّف الموارد المنتظم (URI) القابل للاستئناف للجلسة. يتضمّن العنوان X-Goog-Upload-URL، الموضح في المثال أدناه، معلَمة طلب البحث 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 الذي يبلغ حجمه 2000,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

إذا نجح الطلب، يستجيب الخادم باستخدام 200 Ok HTTP.

في حال تمت مقاطعة طلب التحميل أو في حال تلقّي 503 Service Unavailable HTTP أو أي بروتوكول HTTP استجابة 5xx أخرى من الخادم، يُرجى اتباع الإجراء الموضح في استئناف عملية تحميل تمت مقاطعتها.


جارٍ تحميل الملف إلى أجزاء

مع التحميلات القابلة للاستئناف، يمكنك تقسيم الملف إلى أجزاء وإرسال سلسلة من الطلبات لتحميل كل مقطع بالتسلسل. هذا ليس النهج المفضل نظرًا لوجود تكاليف أداء مرتبطة بالطلبات الإضافية، غير ضرورية بشكل عام. نقترح على البرامج تحميل جميع وحدات البايت المتبقية من الحمولة ضمِّن الأمر finalize مع كل أمر upload.

ومع ذلك، قد تحتاج إلى استخدام التقسيم لتقليل كمية البيانات المنقولة في أي في طلب واحد. ويتيح لك أيضًا تنفيذ إجراءات، مثل تقديم مؤشرات حول مدى تقدّم عملية التحميل للمتصفّحات القديمة. التي لا تتيح بشكل تلقائي تقدّم التحميل


استئناف عملية تحميل تمت مقاطعتها

في حال إنهاء طلب تحميل قبل تلقّي ردّ أو إذا تلقّيت استجابة 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. أرسِل طلبًا إلى واجهة برمجة التطبيقات.
  2. تلقّي ردّ HTTP 503، ما يشير إلى أنّه يجب إعادة محاولة الطلب.
  3. انتظِر لمدة ثانية واحدة + Spam_number_milliseconds، ثم أعِد محاولة الطلب.
  4. تلقّي ردّ HTTP 503، ما يشير إلى أنّه يجب إعادة محاولة الطلب.
  5. انتظِر لمدة ثانيتين + معرّف عشوائي_number_milliseconds، ثم أعِد محاولة الطلب.
  6. تلقّي ردّ HTTP 503، ما يشير إلى أنّه يجب إعادة محاولة الطلب.
  7. يُرجى الانتظار لمدة 4 ثوانٍ + Spam_number_milliseconds، ثم إعادة محاولة الطلب.
  8. تلقّي ردّ HTTP 503، ما يشير إلى أنّه يجب إعادة محاولة الطلب.
  9. انتظِر لمدة 8 ثوانٍ + بشكل عشوائي_number_milliseconds، ثم أعِد محاولة الطلب.
  10. تلقّي ردّ HTTP 503، ما يشير إلى أنّه يجب إعادة محاولة الطلب.
  11. يُرجى الانتظار لمدة 16 ثانية + {9/}_number_milliseconds، ثم إعادة محاولة الطلب.
  12. إيقاف. الإبلاغ عن خطأ أو تسجيله

في التدفق أعلاه، Spam_number_milliseconds عبارة عن عدد عشوائي من المللي ثانية أقل من أو يساوي 1000. وهذا أمر ضروري، لأن إدخال تأخير عشوائي صغير يساعد في توزيع التحميل بالتساوي وتجنب إمكانية ختم الخادم. يجب إعادة تحديد قيمة Spam_number_milliseconds بعد كل انتظار.

ملاحظة: يكون وقت الانتظار دائمًا (2 ^ n) + ساعة عشوائية_number_milliseconds، حيث يكون n عددًا صحيحًا متزايدًا بشكل روتيني تم تحديده في البداية على أنّه 0. تتم زيادة العدد الصحيح n بمقدار 1 لكل تكرار (كل طلب).

يتم تعيين الخوارزمية على النهاية عندما تكون n هي 5. ويمنع هذا الحد الأقصى العملاء من إعادة المحاولة إلى ما لا نهاية، ويؤدي إلى تأخير إجمالي يصل إلى 32 ثانية تقريبًا قبل اعتبار الطلب "خطأ غير قابل للإصلاح". لا بأس من خلال عدد أكبر من المحاولات، خاصةً إذا كانت هناك عملية تحميل طويلة قيد التقدم؛ فقط تأكد من تقييد تأخير إعادة المحاولة إلى حد معقول، لنفترض، أقل من دقيقة واحدة.