Android Debug Bridge (adb)

تُعد Android Debug Bridge (adb) أداة سطر أوامر متعددة الاستخدامات تسمح لك بالتواصل مع أحد الأجهزة. يسهّل الأمر adb تنفيذ مجموعة من الإجراءات على الجهاز، مثل تثبيت التطبيقات وتصحيحها. adb تتيح الوصول إلى واجهة أوامر Unix التي يمكنك استخدامها لتنفيذ مجموعة متنوعة من الأوامر على الجهاز. وهو برنامج خادم عميل يضم ثلاثة مكونات:

• العميل الذي يُرسل الأوامر. يعمل العميل على جهاز التطوير الذي تستخدمه. ويمكنك استدعاء برنامج من وحدة طرفية سطر الأوامر من خلال إصدار الأمر adb.
• برنامج خفي (adbd)، يُشغِّل الأوامر على الجهاز. يتم تشغيل البرنامج الخفي كعملية في الخلفية على كل جهاز.
• خادم يدير الاتصال بين العميل والبرنامج الخفي. يعمل الخادم كعملية في الخلفية على جهاز التطوير الذي تستخدمه.

تم تضمين adb في حزمة أدوات النظام الأساسي لحزمة تطوير البرامج (SDK) لنظام التشغيل Android. نزِّل هذه الحزمة باستخدام مدير SDK، الذي يثبِّتها في android_sdk/platform-tools/. إذا كنت ترغب في الحصول على حزمة أدوات النظام الأساسي لحزمة تطوير البرامج (SDK) لنظام التشغيل Android، يمكنك تنزيلها من هنا.

للحصول على معلومات حول ربط جهاز لاستخدامه عبر adb، بما في ذلك طريقة استخدام "مساعد الاتصال" لتحديد المشاكل الشائعة وحلّها، يمكنك الاطّلاع على تشغيل التطبيقات على جهاز.

آلية عمل Adb

عند بدء تشغيل برنامج adb، يتحقّق البرنامج أولاً مما إذا كانت هناك عملية خادم adb قيد التشغيل حاليًا. وفي حال عدم توفّرها، يتم بدء عملية الخادم. عندما يبدأ الخادم، يرتبط بمنفذ TCP المحلي 5037 ويصغي إلى الأوامر المُرسَلة من برامج adb.

ملاحظة: تستخدم جميع برامج adb المنفذ 5037 للاتصال بخادم adb.

وبعد ذلك، يقوم الخادم بإعداد الاتصالات بجميع الأجهزة قيد التشغيل. وتحدد أماكن المحاكيات عن طريق مسح المنافذ ذات الأرقام الفردية في النطاق من 5555 إلى 5585، وهو النطاق الذي تستخدمه أول 16 محاكيًا. عندما يعثر الخادم على برنامج خفي لـ adb (adbd)، يضبط اتصالاً بهذا المنفذ.

يستخدم كل محاكي منفذًا من المنفذين التسلسليين، وهما منفذ زوجي لاتصالات وحدة التحكم ومنفذ فردي لاتصالات adb. مثلاً:

المحاكي 1، وحدة التحكّم: 5554
المحاكي 1، adb: 5555
المحاكي 2، وحدة التحكّم: 5556
المحاكي 2، adb: 5557
وما إلى ذلك.

كما هو موضّح، يكون المحاكي المتصل بـ adb على المنفذ 5555 مطابقًا للمحاكي الذي تستمع وحدة التحكّم فيه إلى المنفذ 5554.

بعد أن ينتهي الخادم من إعداد الاتصالات بجميع الأجهزة، يمكنك استخدام أوامر adb للوصول إلى تلك الأجهزة. وبما أنّ الخادم يدير الاتصالات بالأجهزة ويتعامل مع الأوامر من عملاء adb متعددين، يمكنك التحكّم في أي جهاز من أي جهاز أو من نص برمجي.

تفعيل خيار "تصحيح أخطاء Adb" على جهازك

لاستخدام Adb مع جهاز متصل عبر USB، يجب تفعيل تصحيح أخطاء USB في إعدادات نظام الجهاز، ضمن خيارات المطوّرين. في نظام التشغيل Android 4.2 (مستوى واجهة برمجة التطبيقات 17) والإصدارات الأحدث، تكون شاشة خيارات المطوّرين مخفية تلقائيًا. لإظهاره، فعِّل "خيارات المطوّرين".

يمكنك الآن ربط جهازك باستخدام منفذ USB. يمكنك التأكد من أنّ جهازك متصل من خلال تنفيذ سياسة adb devices من الدليل android_sdk/platform-tools/. إذا كان الجهاز متصلاً بالإنترنت، سيظهر لك اسم الجهاز مدرَجًا باسم "جهاز".

ملاحظة: عند توصيل جهاز يعمل بالإصدار 4.2.2 من واجهة برمجة التطبيقات (المستوى 17 من واجهة برمجة التطبيقات) أو بإصدار أحدث، يعرض النظام مربّع حوار يطلب منك قبول مفتاح RSA الذي يتيح تصحيح الأخطاء من خلال هذا الكمبيوتر. تحمي آلية الأمان هذه أجهزة المستخدمين لأنّها تضمن عدم إمكانية تنفيذ تصحيح أخطاء USB وأوامر adb الأخرى ما لم تتمكّن من فتح قفل الجهاز والإقرار بمربّع الحوار.

لمزيد من المعلومات حول التوصيل بجهاز عبر USB، يُرجى الاطّلاع على تشغيل التطبيقات على جهاز.

الاتصال بجهاز عبر Wi-Fi

ملاحظة: لا تنطبق التعليمات أدناه على أجهزة Wear OS التي تعمل بنظام التشغيل Android 11 (المستوى 30 من واجهة برمجة التطبيقات). للحصول على مزيد من المعلومات، يمكنك الاطّلاع على دليل تصحيح الأخطاء في تطبيق Wear OS.

يتيح الإصدار Android 11 (المستوى 30 لواجهة برمجة التطبيقات) والإصدارات الأحدث نشر تطبيقك وتصحيح الأخطاء فيه لاسلكيًا من محطة العمل باستخدام Android Debug Bridge (adb). على سبيل المثال، يمكنك نشر التطبيق الذي يمكن تصحيح الأخطاء به على عدة أجهزة بعيدة بدون الحاجة إلى توصيل جهازك فعليًا عبر USB. يلغي ذلك الحاجة إلى التعامل مع المشاكل الشائعة المتعلقة باتصال USB، مثل تثبيت برنامج التشغيل.

قبل البدء في استخدام ميزة "تصحيح الأخطاء اللاسلكي"، عليك تنفيذ ما يلي:

• تأكَّد من اتصال محطة العمل والجهاز بالشبكة اللاسلكية نفسها.

• تأكَّد من أنّ جهازك يعمل بنظام التشغيل Android 11 (المستوى 30 لواجهة برمجة التطبيقات) أو إصدار أحدث للهاتف أو Android 13 (المستوى 33 من واجهة برمجة التطبيقات) أو إصدارات أحدث للتلفزيون وWearOS. لمزيد من المعلومات، راجِع التحقّق من إصدار Android على جهازك وتحديثه.

• في حال استخدام بيئة التطوير المتكاملة، يجب التأكّد من أنّ أحدث إصدار من "استوديو Android" مثبّت على جهازك. يمكنك تنزيله هنا.

• على محطة العمل، ثبِّت أحدث إصدار من أدوات SDK Platform.

لاستخدام ميزة "تصحيح الأخطاء اللاسلكي"، يجب إقران جهازك بمحطة العمل باستخدام رمز الاستجابة السريعة أو رمز الإقران. يجب توصيل محطة العمل والجهاز بالشبكة اللاسلكية نفسها. للاتصال بجهازك، يُرجى اتّباع الخطوات التالية:

1. فعِّل خيارات المطوّرين على جهازك.

2. افتح "استوديو Android" واختَر إقران الأجهزة باستخدام شبكة Wi-Fi من قائمة تشغيل الإعدادات.

   

   الشكل 1. تشغيل قائمة الإعدادات

   ستظهر النافذة المنبثقة إقران الأجهزة عبر Wi-Fi، كما هو موضّح في الشكل 2.

   

   الشكل 2. نافذة منبثقة لإقران الأجهزة باستخدام رمز الاستجابة السريعة أو رمز الإقران.

3. على جهازك، انقر على تصحيح الأخطاء اللاسلكي وأقرِن جهازك:

   

   الشكل 3. لقطة شاشة لإعداد تصحيح الأخطاء اللاسلكي على هاتف Google Pixel

   1. لإقران جهازك برمز استجابة سريعة، اختَر إقران الجهاز باستخدام رمز الاستجابة السريعة وامسح ضوئيًا رمز الاستجابة السريعة الذي تم الحصول عليه من النافذة المنبثقة إقران الأجهزة عبر شبكة Wi-Fi التي تظهر في الشكل 2.

   2. لإقران جهازك برمز إقران، اختَر إقران الجهاز باستخدام رمز الإقران من النافذة المنبثقة إقران الأجهزة عبر شبكة Wi-Fi. على جهازك، اختَر الإقران باستخدام رمز الإقران ودوِّن الرمز المكوَّن من ستة أرقام المقدَّم. بعد أن يظهر جهازك في نافذة إقران الأجهزة عبر Wi-Fi، يمكنك اختيار إقران وإدخال الرمز المكوّن من ستة أرقام الذي يظهر على جهازك.

      

      الشكل 4. مثال على إدخال رمز مكوّن من ستة أرقام

4. بعد إقران جهازك، يمكنك محاولة نشر تطبيقك عليه.

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

5. إذا أردت تفعيل ميزة "تصحيح الأخطاء اللاسلكي" وإيقافها بسرعة، يمكنك استخدام مربّعات مطوّري البرامج للإعدادات السريعة من أجل تصحيح الأخطاء اللاسلكي في خيارات المطوّرين > مربّعات الإعدادات السريعة للمطوّرين.

   

   الشكل 5. يتيح لك الإعداد مربّعات مطوّري البرامج للإعدادات السريعة تفعيل ميزة "تصحيح الأخطاء اللاسلكي" وإيقافها بسرعة.

اتصال Wi-Fi باستخدام سطر الأوامر

يمكنك بدلاً من ذلك اتّباع الخطوات التالية للاتصال بجهازك باستخدام سطر الأوامر بدون Android Studio:

1. فعِّل خيارات المطوّرين على جهازك كما هو موضَّح سابقًا.

2. فعِّل تصحيح الأخطاء اللاسلكي على جهازك كما هو موضَّح سابقًا.

3. على محطة العمل، افتح نافذة طرفية وانتقِل إلى android_sdk/platform-tools.

4. يمكنك البحث عن عنوان IP ورقم المنفذ ورمز الإقران من خلال اختيار إقران الجهاز باستخدام رمز الإقران. دوِّن عنوان IP ورقم المنفذ ورمز الإقران المعروض على الجهاز.

5. على محطة العمل في محطة العمل، شغِّل adb pair ipaddr:port. استخدِم عنوان IP ورقم المنفذ المذكورَين أعلاه.

6. أدخِل رمز الإقران كما هو موضَّح أدناه عندما يُطلب منك ذلك.

   

   الشكل 6. تشير الرسالة إلى أنه تم إقران جهازك بنجاح.

حل مشاكل الاتصال اللاسلكي

إذا كنت تواجه مشاكل في الاتصال بجهازك لاسلكيًا، جرِّب الخطوات التالية لتحديد المشاكل وحلّها.

التحقّق ممّا إذا كانت محطة العمل والجهاز يستوفيان المتطلبات الأساسية

تأكَّد من أنّ محطة العمل والجهاز يستوفيان المتطلبات الأساسية المذكورة في بداية هذا القسم.

التحقّق من المشاكل المعروفة الأخرى

في ما يلي قائمة بالمشاكل المعروفة الحالية المتعلّقة بميزة "تصحيح الأخطاء اللاسلكي" (باستخدام Adb أو Android Studio) وكيفية حلّها:

• شبكة Wi-Fi غير متصلة: قد تحظر شبكات Wi-Fi الآمنة، مثل شبكات Wi-Fi للشركات، اتصالات p2p ولا تسمح لك بالاتصال عبر Wi-Fi. جرِّب الاتصال باستخدام كابل أو شبكة Wi-Fi أخرى (غير تابعة للشركة). ويُعدّ الاتصال اللاسلكي باستخدام adb connect ip:port عبر tcp/ip (بعد اتصال USB مبدئيًا) خيارًا آخر، في حال كان اللجوء إلى شبكة غير تابعة للشركة خيارًا آخر.

• adb يتم في بعض الأحيان إيقاف الاتصال عبر Wi-Fi بشكل تلقائي.: يمكن أن يحدث ذلك عندما يبدّل الجهاز شبكات Wi-Fi أو انقطع اتصالها بالشبكة. لحلّ المشكلة، يجب إعادة الاتصال بالشبكة.

• تعذّر اتصال الجهاز بعد الإقران بنجاح: يعتمد adb على mDNS لاكتشاف الأجهزة المقترنة والاتصال بها تلقائيًا. إذا كانت إعدادات الشبكة أو الجهاز لا تتوافق مع mDNS أو إذا أوقفته، عليك الاتصال يدويًا بالجهاز باستخدام adb connect ip:port.

الاتصال لاسلكيًا بجهاز بعد توصيله بكابل USB (يتوفّر هذا الخيار فقط على نظام التشغيل Android 10 والإصدارات الأقدم)

ملاحظة: ينطبق سير العمل هذا أيضًا على نظام التشغيل Android 11 (والإصدارات الأحدث)، علمًا بأنّه يتضمّن أيضًا اتصالًا *أوليًا* عبر منفذ USB محمول.

ملاحظة: لا تنطبق التعليمات التالية على أجهزة Wear OS التي تعمل بنظام التشغيل Android 10 (المستوى 29 من واجهة برمجة التطبيقات) أو الإصدارات الأقدم. للحصول على مزيد من المعلومات، يمكنك الاطّلاع على الدليل حول تصحيح أخطاء تطبيق Wear OS.

يتواصل adb عادةً مع الجهاز عبر USB، ولكن يمكنك أيضًا استخدام adb عبر شبكة Wi-Fi. لربط جهاز يعمل بنظام التشغيل Android 10 (المستوى 29 من واجهة برمجة التطبيقات) أو بإصدار أقدم، اتّبِع الخطوات الأولية التالية عبر USB:

1. وصِّل جهاز Android وجهاز الكمبيوتر المضيف adb بشبكة Wi-Fi مشتركة.

ملاحظة: يجب الانتباه إلى أنّ جميع نقاط الوصول ليست مناسبة. قد تحتاج إلى استخدام نقطة وصول تم إعداد جدار الحماية الخاص بها بشكل صحيح لدعم adb.

2. وصِّل الجهاز بالكمبيوتر المضيف باستخدام كابل USB.
3. اضبط الجهاز المستهدف لتلقّي اتصال TCP/IP على المنفذ 5555:

   adb tcpip 5555
   

4. افصِل كابل USB عن الجهاز المستهدَف.
5. ابحث عن عنوان IP لجهاز Android. على سبيل المثال، على جهاز Nexus، يمكنك العثور على عنوان IP من خلال الإعدادات > حول الجهاز اللوحي (أو حول الهاتف) > الحالة > عنوان IP.
6. اتصِل بالجهاز باستخدام عنوان IP الخاص بجهازه:

   adb connect device_ip_address:5555
   

7. تأكَّد من اتصال الكمبيوتر المضيف بالجهاز المستهدف:

   $ adb devices
   List of devices attached
   device_ip_address:5555 device
   

جهازك مرتبط الآن بـ "adb".

في حال انقطاع اتصال adb بجهازك:

• تأكَّد من أنّ مضيفك لا يزال متصلاً بشبكة Wi-Fi نفسها التي يتصل بها جهاز Android.
• يُرجى إعادة الاتصال من خلال تنفيذ خطوة adb connect مجددًا.
• إذا لم تنجح هذه الطريقة، يمكنك إعادة ضبط مضيف adb:

  adb kill-server
  

  ثم ابدأ من جديد.

طلب بحث للأجهزة

قبل إصدار أوامر adb، من المفيد معرفة مثيلات الجهاز المتصلة بخادم adb. يمكنك إنشاء قائمة بالأجهزة المتصلة باستخدام الأمر devices:

  adb devices -l
  

استجابةً لذلك، يطبع adb معلومات الحالة هذه لكل جهاز:

• الرقم التسلسلي: ينشئ adb سلسلة لتعريف الجهاز بشكلٍ فريد من خلال رقم منفذه. إليك مثال على الرقم التسلسلي: emulator-5554.
• الحالة: يمكن أن تكون حالة اتصال الجهاز واحدة مما يلي:
  • offline: الجهاز غير متصل بشبكة adb أو لا يستجيب.
  • device: الجهاز متصل بخادم adb. يُرجى العِلم أنّ هذه الحالة لا تشير إلى أنّ نظام Android في وضع التشغيل بالكامل وأنّ الجهاز يتصل بـ adb أثناء تشغيل النظام. بعد بدء التشغيل، تكون هذه هي الحالة التشغيلية الطبيعية للجهاز.
  • no device: ما مِن أجهزة متصلة.
• الوصف: في حال تضمين الخيار -l، يوضّح لك الأمر devices نوع الجهاز. وتكون هذه المعلومات مفيدة عندما تتوفّر لديك عدة أجهزة متصلة كي تتمكّن من التفريق بينها.

يعرض المثال التالي الأمر devices ونتائجه. هناك ثلاثة أجهزة قيد التشغيل. السطران الأولان في القائمة عبارة عن أدوات محاكاة، والسطر الثالث عبارة عن جهاز متصل بالكمبيوتر.

$ adb devices
List of devices attached
emulator-5556 device product:sdk_google_phone_x86_64 model:Android_SDK_built_for_x86_64 device:generic_x86_64
emulator-5554 device product:sdk_google_phone_x86 model:Android_SDK_built_for_x86 device:generic_x86
0a388e93      device usb:1-1 product:razor model:Nexus_7 device:flo

المحاكي غير مدرَج

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

• خادم adb ليس قيد التشغيل.
• يمكنك استخدام الأمر emulator مع الخيار -port أو -ports مع قيمة منفذ ذات أرقام فردية بين 5554 و5584.
• المنفذ ذو الأرقام الفردية التي اخترتها غير مشغول، لذا يمكن إجراء اتصال المنفذ من رقم المنفذ المحدّد، وإذا كان المنفذ مشغولاً، ينتقل المحاكي إلى منفذ آخر يستوفي المتطلبات الواردة في 2.
• تبدأ تشغيل خادم adb بعد بدء المحاكي.

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

المثال 1: في تسلسل الأوامر التالي، يبدأ الأمر adb devices خادم adb، ولكن لا تظهر قائمة الأجهزة.

أوقِف خادم adb وأدخِل الأوامر التالية بالترتيب المعروض. بالنسبة إلى اسم AVD، قدِّم اسم AVD صالحًا من نظامك. للحصول على قائمة بأسماء AVD، اكتب emulator -list-avds. يمكنك العثور على الأمر emulator في الدليل android_sdk/tools.

$ adb kill-server
$ emulator -avd Nexus_6_API_25 -port 5555
$ adb devices

List of devices attached
* daemon not running. starting it now on port 5037 *
* daemon started successfully *

المثال 2: في تسلسل الأوامر التالي، يعرض adb devices قائمة الأجهزة لأنه تم بدء تشغيل خادم adb أولاً.

لعرض المحاكي في إخراج adb devices، أوقِف خادم adb ثم شغِّله مرة أخرى بعد استخدام الأمر emulator وقبل استخدام الأمر adb devices، كما يلي:

$ adb kill-server
$ emulator -avd Nexus_6_API_25 -port 5557
$ adb start-server
$ adb devices

List of devices attached
emulator-5557 device

لمزيد من المعلومات حول خيارات سطر أوامر المحاكي، راجع خيارات بدء تشغيل سطر الأوامر.

إرسال الأوامر إلى جهاز معيّن

في حال تشغيل عدة أجهزة، يجب تحديد الجهاز المستهدف عند إصدار الأمر adb. لتحديد الهدف، اتّبِع الخطوات التالية:

1. استخدِم الأمر devices للحصول على الرقم التسلسلي للهدف.
2. بعد الحصول على الرقم التسلسلي، يمكنك استخدام الخيار -s مع طلبات adb لتحديد الرقم التسلسلي.
   1. إذا كنت بصدد إصدار العديد من أوامر adb، يمكنك ضبط متغيّر بيئة $ANDROID_SERIAL بحيث يتضمّن الرقم التسلسلي بدلاً من ذلك.
   2. وإذا كنت تستخدم كلاً من -s و$ANDROID_SERIAL، سيؤدي استخدام -s إلى إلغاء $ANDROID_SERIAL.

في المثال التالي، يتم الحصول على قائمة الأجهزة المتصلة، ثم يتم استخدام الرقم التسلسلي لأحد الأجهزة لتثبيت helloWorld.apk على هذا الجهاز:

$ adb devices
List of devices attached
emulator-5554 device
emulator-5555 device
0.0.0.0:6520  device

# To install on emulator-5555
$ adb -s emulator-5555 install helloWorld.apk
# To install on 0.0.0.0:6520
$ adb -s 0.0.0.0:6520 install helloWorld.apk

ملاحظة: إذا أصدرت أمرًا بدون تحديد جهاز مستهدف عند توفر عدة أجهزة، ستعرض adb رسالة الخطأ "adb: أكثر من جهاز/محاكي واحد".

إذا كانت لديك عدة أجهزة ولكن جهاز واحد فقط هو محاكي، استخدِم الخيار -e لإرسال الأوامر إلى المحاكي. في حال كانت هناك عدة أجهزة ولكن تم توصيل جهاز واحد فقط بها، استخدِم الخيار -d لإرسال الأوامر إلى هذه الأجهزة.

تثبيت تطبيق

يمكنك استخدام adb لتثبيت حزمة APK على محاكي أو جهاز متصل باستخدام الأمر install:

adb install path_to_apk

يجب استخدام الخيار -t مع الأمر install عند تثبيت حزمة APK تجريبية. لمزيد من المعلومات، يمكنك الاطّلاع على -t.

لتثبيت حِزم APK متعددة، استخدِم install-multiple. هذه الطريقة مفيدة عند تنزيل جميع حِزم APK على جهاز معيّن لتطبيقك من Play Console والرغبة في تثبيتها على محاكي أو جهاز مادي.

وللحصول على مزيد من المعلومات حول كيفية إنشاء ملف APK يمكنك تثبيته على مثيل محاكي/جهاز، يمكنك مراجعة إنشاء تطبيقك وتشغيله.

ملاحظة: إذا كنت تستخدم "استوديو Android"، لن تحتاج إلى استخدام adb مباشرةً لتثبيت تطبيقك على المحاكي أو الجهاز. بدلاً من ذلك، يعالج "استوديو Android" حزمة التطبيق وتثبيته.

إعداد قاعدة إعادة توجيه المنفذ

استخدام الأمر forward لإعداد منفذ عشوائي يعيد توجيه الطلبات على منفذ مضيف محدّد إلى منفذ مختلف على الجهاز يعمل المثال التالي على إعداد إعادة توجيه منفذ المضيف 6100 إلى منفذ الجهاز 7100:

adb forward tcp:6100 tcp:7100

يقوم المثال التالي بإعداد إعادة توجيه منفذ المضيف 6100 إلى local:logd:

adb forward tcp:6100 local:logd

وقد تكون هذه الطريقة مفيدة إذا كنت تحاول تحديد ما يتم إرساله إلى منفذ معيّن على الجهاز. ستتم كتابة جميع البيانات التي تم استلامها في البرنامج الخفي لتسجيل النظام وسيتم عرضها في سجلّات الجهاز.

نسخ الملفات من جهاز وإليه

استخدِم الأمرَين pull وpush لنسخ الملفات من أحد الأجهزة وإليها. بخلاف الأمر install الذي ينسخ ملف APK إلى موقع جغرافي محدّد فقط، يتيح لك الأمران pull وpush نسخ الأدلة والملفات العشوائية إلى أي موقع في الجهاز.

لنسخ ملف أو دليل والأدلة الفرعية الخاصة به من الجهاز، نفِّذ ما يلي:

adb pull remote local

لنسخ ملف أو دليل وأدلةه الفرعية إلى الجهاز، يُرجى اتّباع الخطوات التالية:

adb push local remote

استبدل local وremote بالمسارات المؤدية إلى الملفات/الدليل المستهدف على جهاز التطوير (المحلي) وعلى الجهاز (عن بُعد). مثلاً:

adb push myfile.txt /sdcard/myfile.txt

إيقاف خادم adb

في بعض الحالات، قد تحتاج إلى إنهاء عملية خادم adb ثم إعادة تشغيلها لحل المشكلة. على سبيل المثال، قد يحدث ذلك في حال عدم استجابة adb لطلب معيّن.

لإيقاف خادم adb، يمكنك استخدام الأمر adb kill-server. يمكنك بعد ذلك إعادة تشغيل الخادم من خلال إصدار أي أمر adb آخر.

إصدار أوامر adb

أصدر adb أوامر من سطر أوامر على جهاز التطوير أو من نص برمجي باستخدام ما يلي:

adb [-d | -e | -s serial_number] command

في حال وجود محاكي واحد فقط قيد التشغيل أو جهاز واحد فقط متصل به، يتم إرسال الأمر adb إلى هذا الجهاز تلقائيًا. إذا كانت أدوات المحاكاة المتعددة قيد التشغيل و/أو تم إرفاق أجهزة متعدّدة، عليك استخدام الخيار -d أو -e أو -s لتحديد الجهاز المستهدف الذي يجب توجيه الأمر إليه.

يمكنك الاطّلاع على قائمة مفصّلة بجميع طلبات adb المتوافقة باستخدام الأمر التالي:

adb --help

إصدار أوامر واجهة المستخدم

يمكنك استخدام الأمر shell لإصدار أوامر الجهاز من خلال adb أو لبدء واجهة برمجة تطبيقات تفاعلية. لإصدار أمر واحد، استخدِم الأمر shell على النحو التالي:

adb [-d |-e | -s serial_number] shell shell_command

لتشغيل واجهة أوامر تفاعلية على جهاز، استخدِم الأمر shell على النحو التالي:

adb [-d | -e | -s serial_number] shell

للخروج من وحدة تحكّم تفاعلية، اضغط على Control+D أو اكتب exit.

يوفّر Android معظم أدوات سطر أوامر Unix المعتادة. للحصول على قائمة بالأدوات المتاحة، استخدم الأمر التالي:

adb shell ls /system/bin

تتوفّر المساعدة لمعظم الأوامر من خلال الوسيطة --help. يوفّر toybox العديد من أوامر واجهة الأوامر. تتوفّر المساعدة العامة المطبَّقة على جميع أوامر toybox من خلال toybox --help.

في أدوات نظام Android الأساسية رقم 23 والإصدارات الأحدث، يعالج adb الوسيطات بالطريقة نفسها التي يتعامل بها الأمر ssh(1). ساعد هذا التغيير في حل الكثير من المشاكل المتعلّقة بإدخال الأوامر وأتاح له إمكانية تنفيذ الأوامر التي تحتوي على أحرف وصفية خاصة بواجهة الأوامر، مثل adb install Let\'sGo.apk. يعني هذا التغيير أنّه تم أيضًا تغيير تفسير أي أمر يحتوي على أحرف وصفية في واجهة الأوامر.

على سبيل المثال، أصبحت adb shell setprop key 'value' الآن رسالة خطأ لأنّه يتم ابتلاع علامات الاقتباس المفردة (') من خلال واجهة الأوامر المحلية، ولا يرى الجهاز علامة adb shell setprop key value. لجعل الأمر يعمل، استخدِم اقتباس مرتين، إحداهما للواجهة المحلية والأخرى لوحدة التحكّم عن بُعد، تمامًا كما تفعل في ssh(1). مثلاً: adb shell setprop key 'value'

راجِع أيضًا أداة سطر أوامر Logcat، وهي مفيدة لمراقبة سجلّ النظام.

مدير نشاط الاتصال

ضِمن واجهة أوامر adb، يمكنك إصدار الأوامر باستخدام أداة مدير الأنشطة (am) لتنفيذ إجراءات نظام مختلفة، مثل بدء نشاط وفرض إيقاف عملية وبث هدف وتعديل خصائص شاشة الجهاز وغير ذلك.

في واجهة الأوامر، تكون بنية am كما يلي:

am command

يمكنك أيضًا إصدار أمر مدير النشاط مباشرةً من adb بدون الدخول إلى وحدة تحكّم عن بُعد. مثلاً:

adb shell am start -a android.intent.action.VIEW

الجدول 1. أوامر مدير النشاط المتاحة

مواصفات وسيطات الغرض

بالنسبة إلى أوامر مدير النشاط التي تستخدم الوسيطة intent، يمكنك تحديد الغرض من خلال الخيارات التالية:

الاتصال بمدير حِزم البيانات (pm)

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

في واجهة الأوامر، تكون بنية pm كما يلي:

pm command

يمكنك أيضًا إصدار أمر مدير حزم مباشرةً من adb بدون إدخال واجهة أوامر عن بُعد. مثلاً:

adb shell pm uninstall com.example.MyApp

الجدول 2. أوامر مدير الحِزم المتاحة

الاتصال بمدير سياسة الجهاز (dpm)

لمساعدتك في تطوير تطبيقات إدارة الأجهزة واختبارها، يمكنك إصدار الأوامر إلى أداة مدير سياسات الجهاز (dpm). استخدِم الأداة للتحكّم في تطبيق المشرف النشط أو تغيير بيانات حالة سياسة على الجهاز.

في واجهة الأوامر، نجد أنّ بناء الجملة dpm هو:

dpm command

يمكنك أيضًا إصدار أمر مدير سياسة الجهاز مباشرةً من adb بدون الدخول إلى وحدة تحكّم عن بُعد:

adb shell dpm command

الجدول 3. أوامر مدير سياسة الجهاز المتاحة

أخذ لقطة شاشة

الأمر screencap هو أداة مساعدة في واجهة الأوامر لأخذ لقطة شاشة لشاشة عرض جهاز.

في واجهة الأوامر، تكون بنية screencap كما يلي:

screencap filename

لاستخدام screencap من سطر الأوامر، أدخِل ما يلي:

adb shell screencap /sdcard/screen.png

في ما يلي مثال على جلسة لقطة شاشة باستخدام واجهة أوامر adb لأخذ لقطة الشاشة والأمر pull لتنزيل الملف من الجهاز:

$ adb shell
shell@ $ screencap /sdcard/screen.png
shell@ $ exit
$ adb pull /sdcard/screen.png

تسجيل مقطع فيديو

الأمر screenrecord هو أداة مساعدة في واجهة الأوامر لتسجيل طريقة عرض الأجهزة التي تعمل بنظام التشغيل Android 4.4 (مستوى واجهة برمجة التطبيقات 19) والإصدارات الأحدث. تسجِّل الأداة نشاط الشاشة في ملف MPEG-4. يمكنك استخدام هذا الملف لإنشاء فيديوهات ترويجية أو تدريبية أو لتصحيح الأخطاء والاختبار.

في واجهة أوامر، استخدم الصيغة التالية:

screenrecord [options] filename

لاستخدام screenrecord من سطر الأوامر، أدخِل ما يلي:

adb shell screenrecord /sdcard/demo.mp4

أوقِف تسجيل الشاشة من خلال الضغط على Control+C (Command+C على نظام التشغيل macOS). وبخلاف ذلك، يتوقف التسجيل تلقائيًا عند ثلاث دقائق أو عند بلوغ الحد الزمني الذي يتم ضبطه من قِبل --time-limit.

لبدء تسجيل شاشة جهازك، شغِّل الأمر screenrecord لتسجيل الفيديو. شغِّل بعد ذلك الأمر pull لتنزيل الفيديو من الجهاز إلى الكمبيوتر المضيف. إليك مثال على جلسة التسجيل:

$ adb shell
shell@ $ screenrecord --verbose /sdcard/demo.mp4
(press Control + C to stop)
shell@ $ exit
$ adb pull /sdcard/demo.mp4

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

قيود أداة screenrecord:

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

الجدول 4. screenrecord خيار

screenrecord --bit-rate 6000000 /sdcard/demo.mp4

قراءة الملفات الشخصية لـ ART للتطبيقات

بدءًا من الإصدار 7.0 من نظام التشغيل Android (المستوى 24 من واجهة برمجة التطبيقات)، يجمع قسم "وقت تشغيل Android" (ART) الملفات الشخصية للتنفيذ للتطبيقات المثبّتة والتي تُستخدَم لتحسين أداء التطبيقات. افحص الملفات الشخصية التي تم جمعها لمعرفة الطرق التي يتم تنفيذها بشكل متكرر والفئات التي يتم استخدامها أثناء بدء تشغيل التطبيق.

ملاحظة: لا يمكن استرداد اسم ملف الملف الشخصي للتنفيذ إلا إذا كان لديك إذن وصول الجذر إلى نظام الملفات، على سبيل المثال، في محاكي.

لإنتاج نموذج نصي لمعلومات الملف الشخصي، استخدم الأمر التالي:

adb shell cmd package dump-profiles package

لاسترداد الملف الذي تم إنتاجه، استخدم:

adb pull /data/misc/profman/package.prof.txt

إعادة ضبط أجهزة الاختبار

إذا اختبرت تطبيقك على عدة أجهزة اختبار، قد يكون من المفيد إعادة ضبط جهازك بين الاختبارات، على سبيل المثال، لإزالة بيانات المستخدم وإعادة ضبط بيئة الاختبار. يمكنك إجراء إعادة ضبط على الإعدادات الأصلية لجهاز اختبار يعمل بنظام التشغيل Android 10 (المستوى 29 لواجهة برمجة التطبيقات) أو إصدار أحدث باستخدام أمر الأوامر testharness adb على النحو الموضَّح:

adb shell cmd testharness enable

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

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

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

إذا كان تطبيقك يحتاج إلى رصد الإعدادات التلقائية للأمر testharness والتكيّف معها، استخدِم ActivityManager.isRunningInUserTestHarness().

قناة sqlite

تبدأ sqlite3 برنامج سطر الأوامر sqlite لفحص قواعد بيانات SQLite. وتتضمّن أوامر مثل .dump لطباعة محتوى الجدول و.schema لطباعة عبارة SQL CREATE لجدول حالي. يمكنك أيضًا تنفيذ أوامر SQLite من سطر الأوامر، كما هو موضّح:

$ adb -s emulator-5554 shell
$ sqlite3 /data/data/com.example.app/databases/rssitems.db
SQLite version 3.3.12
Enter ".help" for instructions

ملاحظة: لا يمكن الوصول إلى قاعدة بيانات SQLite إلا إذا كان لديك إذن وصول جذر إلى نظام الملفات، من خلال محاكي مثلاً.

لمزيد من المعلومات، يُرجى الاطّلاع على مستندات سطر أوامر sqlite3.