إنشاء حزمة

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

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

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

Linux

تنزيل برنامج التحميل 1 من Android Over The Air API لنظام التشغيل Linux

أجهزة Windows

تنزيل برنامج التحميل 1 من واجهة برمجة التطبيقات Android Over The Air API لنظام التشغيل Windows.

ولاستخدامه، عليك أولاً إنشاء حساب خدمة والحصول على ملف مفتاح JSON لهذا الحساب. يُرجى الاطّلاع على دليل إنشاء الحساب هنا.
بعد أن يتوفر لديك البرنامج الثنائي وملف المفتاح، يمكنك تشغيله باستخدام خيارات سطر الأوامر لتحديد ملف المفتاح والنشر والحزمة التي تحمِّلها. يُرجى استخدام --help للاطّلاع على جميع الخيارات.

بروتوكولات التحميل

يمكنك تقديم طلبات التحميل بأي من الطرق التالية. حدِّد الطريقة التي تستخدمها مع عنوان الطلب X-Goog-Upload-Protocol.

  • تحميل متعدد الأجزاء: X-Goog-Upload-Protocol: multipart. لنقل الملفات الأصغر والبيانات الوصفية بسرعة، يمكن نقل الملف مع البيانات الوصفية التي تصفه، وكل ذلك في طلب واحد.
  • تحميل قابل للاستئناف: X-Goog-Upload-Protocol: resumable. لإجراء عملية نقل موثوق بها، لا سيما مع الملفات الكبيرة الحجم. باستخدام هذه الطريقة، يمكنك استخدام طلب بدء جلسة، والذي يمكن أن يتضمن بيانات وصفية اختياريًا. وهي استراتيجية جيدة يمكن استخدامها مع معظم التطبيقات، لأنّها تصلح أيضًا للملفات الأصغر حجمًا من خلال طلب HTTP إضافي واحد لكل عملية تحميل.

تحميل متعدد الأجزاء

ويُعدّ هذا اختيارًا مناسبًا إذا كانت البيانات التي ترسلها صغيرة بما يكفي لتحميلها مرة أخرى بالكامل في حال تعذُّر الاتصال.

لاستخدام التحميل المتعدد الأجزاء، أرسِل طلب POST إلى معرّف الموارد المنتظم /upload/package واضبط 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.

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. في ما يلي نموذج طلب يفترض أنّك تستخدم مفتاح خدمة (راجِع كيفية إجراء التفويض لمعرفة مزيد من المعلومات).

مثال على طلب 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

تحميل قابل للاستئناف

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

يستخدم بروتوكول التحميل القابل للاستئناف عدة أوامر:

  1. بدء جلسة قابلة للاستئناف. قدِّم طلبًا أوليًا إلى معرّف الموارد المنتظم (URI) للتحميل الذي يتضمّن البيانات الوصفية ويحدّد موقعًا جغرافيًا فريدًا للتحميل.
  2. احفظ عنوان URL للجلسة القابلة للاستئناف. احفظ معرّف الموارد المنتظم (URI) للجلسة الذي تم عرضه في استجابة الطلب الأولي، وستستخدمه للطلبات المتبقية في هذه الجلسة.
  3. حمِّل الملف. أرسل ملف ZIP بأكمله أو جزءًا منه إلى معرّف الموارد المنتظم (URI) للجلسة القابلة للاستئناف.

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

ملاحظة: تنتهي صلاحية معرِّف الموارد المنتظم (URI) للتحميل بعد 3 أيام.

الخطوة 1: بدء جلسة قابلة للاستئناف

لبدء عملية تحميل قابلة للاستئناف، عليك تقديم طلب POST إلى معرّف الموارد المنتظم (URI) /upload/package وضبط 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.

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

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

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

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

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

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