Android Debug Bridge (adb)

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

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

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

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

طريقة عمل adb

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• إذا كنت تستخدم بيئة التطوير المتكاملة، تأكَّد من تثبيت أحدث إصدار من Android Studio. يمكنك تنزيله من هنا.

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

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

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

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

   

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

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

   

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

3. على جهازك، انقر على تصحيح الأخطاء عبر شبكة Wi-Fi وأقرِن جهازك باتّباع الخطوات التالية:

   

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

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

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

      

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

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

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

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

   

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

الاتصال بشبكة 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 الخاصة بالشركات، اتصالات الند للند، ما يمنعك من الاتصال عبر شبكة Wi-Fi. جرِّب الاتصال باستخدام كابل أو شبكة Wi-Fi أخرى (غير تابعة للشركة). يمكنك أيضًا استخدام اتصال لاسلكي عبر adb connect ip:port على بروتوكول tcp/ip (بعد إجراء اتصال أوّلي عبر USB)، في حال كان استخدام شبكة غير تابعة للشركة خيارًا متاحًا.

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

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

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

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

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

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

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

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

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

   adb tcpip 5555
   

4. افصل كابل USB عن الجهاز المستهدف.
5. ابحث عن عنوان IP لجهاز Android. على سبيل المثال، يمكنك العثور على عنوان IP على جهاز Nexus من خلال الانتقال إلى الإعدادات > لمحة عن الجهاز اللوحي (أو لمحة عن الهاتف) > الحالة > عنوان 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 وأدخِل الأوامر التالية بالترتيب الموضّح. بالنسبة إلى اسم الجهاز الافتراضي Android، أدخِل اسمًا صالحًا من نظامك. للحصول على قائمة بأسماء الأجهزة الافتراضية لنظام التشغيل Android، اكتب 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 Studio، لن تحتاج إلى استخدام 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

يمكنك استخدام الأمر 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. يتم توفير العديد من أوامر shell من خلال toybox. تتوفّر المساعدة العامة التي تنطبق على جميع أوامر Toybox من خلال toybox --help.

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

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

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

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

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

أثناء استخدام shell، يكون بناء الجملة am على النحو التالي:

am command

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

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

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

الأمر	الوصف
start [options] intent	ابدأ Activity محدّدًا بواسطة intent. يمكنك الاطّلاع على مواصفات وسيطات الأهداف. الخيارات هي: ‫-D: لتفعيل تصحيح الأخطاء -W: انتظِر إلى أن يكتمل الإطلاق. --start-profiler file: ابدأ المحلّل وأرسِل النتائج إلى file. -P file: مثل --start-profiler، ولكن يتوقف إنشاء الملف الشخصي عندما يصبح التطبيق غير نشط. -R count: كرِّر عملية تشغيل النشاط count مرات. قبل كل تكرار، سيتم إنهاء النشاط الأهم. -S: فرض إيقاف التطبيق المستهدف قبل بدء النشاط --opengl-trace: تفعيل تتبُّع وظائف OpenGL --user user_id | current: حدِّد المستخدم الذي سيتم التشغيل باسمه. إذا لم يتم تحديد مستخدم، سيتم التشغيل باسم المستخدم الحالي.
startservice [options] intent	ابدأ Service المحدّد بواسطة intent. يمكنك الاطّلاع على مواصفات وسيطات الأهداف. الخيارات هي: --user user_id | current: تحدّد المستخدم الذي سيتم التشغيل باسمه. في حال عدم تحديدها، سيتم التنفيذ باسم المستخدم الحالي.
force-stop package	فرض إيقاف كل ما يرتبط بـ "package"
kill [options] package	أوقِف جميع العمليات المرتبطة بـ "package". لا يؤدي هذا الأمر إلا إلى إيقاف العمليات التي يمكن إيقافها بأمان ولن تؤثر في تجربة المستخدم. الخيارات هي: --user user_id | all | current: حدِّد عمليات المستخدم التي تريد إيقافها. في حال عدم تحديد ذلك، سيتم إيقاف جميع عمليات المستخدمين.
kill-all	إنهاء جميع العمليات التي تعمل في الخلفية
broadcast [options] intent	إصدار رسالة Intent بث. يمكنك الاطّلاع على مواصفات وسيطات الأهداف. الخيارات هي: [--user user_id | all | current]: حدِّد المستخدم الذي تريد إرسال الرسالة إليه. في حال عدم تحديدها، سيتم إرسالها إلى جميع المستخدمين.
instrument [options] component	ابدأ التتبّع باستخدام مثيل Instrumentation. عادةً ما يكون العنصر المستهدف component هو النموذج test_package/runner_class. الخيارات هي: -r: طباعة النتائج الأولية (بدون فك الترميز report_key_streamresult). يجب استخدام هذا الخيار مع [-e perf true] لإنشاء نتائج أولية لقياس الأداء. -e name value: اضبط الوسيطة name على value. بالنسبة إلى أدوات تشغيل الاختبارات، يكون التنسيق الشائع هو -e testrunner_flag value[,value...]. -p file: كتابة بيانات تحديد الملف الشخصي في file ‫-w: الانتظار إلى حين انتهاء عملية القياس قبل الرجوع. مطلوب لتشغيل الاختبارات. --no-window-animation: إيقاف الصور المتحركة للنوافذ أثناء التشغيل --user user_id | current: حدِّد أداة قياس المستخدم التي يتم تشغيلها. في حال عدم تحديدها، سيتم تشغيلها باسم المستخدم الحالي.
profile start process file	ابدأ المحلّل على process، واكتب النتائج في file.
profile stop process	إيقاف أداة تحليل الأداء على process
dumpheap [options] process file	تفريغ مجموعة process، والكتابة إلى file الخيارات هي: --user [user_id | current]: عند تقديم اسم عملية، حدِّد مستخدم العملية المطلوب تفريغها. في حال عدم تحديدها، يتم استخدام المستخدم الحالي. ‫-b [| png | jpg | webp]: تفريغ الصور النقطية من ذاكرة الرسومات (المستوى 35 لواجهة برمجة التطبيقات والإصدارات الأحدث) يمكنك اختياريًا تحديد التنسيق الذي تريد عرض البيانات به (PNG تلقائيًا). ‫-n: تسجيل نَسْخ الذاكرة الأصلية بدلاً من الذاكرة المُدارة
dumpbitmaps [options] [-p process]	عرض معلومات حول الصورة النقطية من process (المستوى 36 لواجهة برمجة التطبيقات والإصدارات الأحدث) الخيارات هي: -d|--dump [format]: يتم عرض محتوى الصورة النقطية في format المحدّد، والذي يمكن أن يكون png أو jpg أو webp، ويتم ضبطه تلقائيًا على png في حال عدم تحديد أي قيمة. سيتم إنشاء ملف zip dumpbitmaps-<time>.zip يحتوي على الصور النقطية. -p process: تفريغ الصور النقطية من process، يمكن تحديد -p process عدة مرات. إذا لم يتم تحديد process، سيتم تفريغ الصور النقطية من جميع العمليات.
set-debug-app [options] package	اضبط تطبيق package على وضع تصحيح الأخطاء. الخيارات هي: -w: انتظار مصحّح الأخطاء عند بدء تشغيل التطبيق --persistent: الاحتفاظ بهذه القيمة
clear-debug-app	محو الحزمة السابقة التي تم ضبطها لتصحيح الأخطاء باستخدام set-debug-app
monitor [options]	ابدأ تتبُّع الأعطال أو أخطاء ANR. الخيارات هي: ‫--gdb: بدء gdbserv على المنفذ المحدّد عند حدوث عطل أو خطأ ANR
screen-compat {on | off} package	التحكّم في وضع التوافق مع حجم الشاشة في package
display-size [reset | widthxheight]	تجاوز حجم العرض على الجهاز يفيد هذا الأمر في اختبار تطبيقك على أحجام شاشات مختلفة من خلال محاكاة درجة دقة شاشة صغيرة باستخدام جهاز بشاشة كبيرة، والعكس صحيح. مثال: am display-size 1280x800
display-density dpi	تجاوز كثافة العرض على الجهاز يفيد هذا الأمر في اختبار تطبيقك على مختلف كثافات الشاشة من خلال محاكاة بيئة شاشة عالية الكثافة باستخدام شاشة منخفضة الكثافة، والعكس صحيح. مثال: am display-density 480
to-uri intent	طباعة مواصفات الغرض المحدّد كمعرّف موارد منتظم (URI) يمكنك الاطّلاع على مواصفات وسيطات الأهداف.
to-intent-uri intent	طباعة مواصفات الغرض المحدّد كعنوان intent: URI يمكنك الاطّلاع على مواصفات وسيطات الأهداف.

مواصفات وسيطات الهدف

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

عرض الكلّ

-a action

حدِّد إجراء الهدف، مثل android.intent.action.VIEW. يمكنك إدخال هذه المعلومات مرة واحدة فقط.

-d data_uri

حدِّد معرّف الموارد المنتظم (URI) لبيانات الهدف، مثل content://contacts/people/1. يمكنك إدخال هذه المعلومات مرة واحدة فقط.

-t mime_type

حدِّد نوع MIME الخاص بالغرض، مثل image/png. يمكنك إدخال هذه المعلومات مرة واحدة فقط.

-c category

حدِّد فئة نية، مثل android.intent.category.APP_CONTACTS.

-n component

حدِّد اسم المكوّن مع بادئة اسم الحزمة لإنشاء هدف ضمني، مثل com.example.app/.ExampleActivity.

-f flags

أضِف العلامات إلى الغرض، على النحو الذي يتيحه setFlags().

--esn extra_key

أضِف قيمة فارغة إلى البيانات الإضافية. لا يتوفّر هذا الخيار لأهداف URI.

-e | --es extra_key extra_string_value

أضِف بيانات السلسلة كزوج مفتاح/قيمة.

--ez extra_key extra_boolean_value

أضِف بيانات منطقية كزوج مفتاح/قيمة.

--ei extra_key extra_int_value

أضِف بيانات عدد صحيح كزوج مفتاح/قيمة.

--el extra_key extra_long_value

أضِف البيانات الطويلة كزوج مفتاح/قيمة.

--ef extra_key extra_float_value

أضِف بيانات الأعداد العشرية كزوج مفتاح/قيمة.

--eu extra_key extra_uri_value

أضِف بيانات معرّف الموارد المنتظم كزوج مفتاح/قيمة.

--ecn extra_key extra_component_name_value

أضِف اسم مكوّن يتم تحويله وتمريره كعنصر ComponentName.

--eia extra_key extra_int_value[,extra_int_value...]

أضِف مصفوفة من الأعداد الصحيحة.

--ela extra_key extra_long_value[,extra_long_value...]

أضِف مصفوفة من الأعداد الصحيحة الطويلة.

--efa extra_key extra_float_value[,extra_float_value...]

أضِف مجموعة من الأرقام العشرية.

--grant-read-uri-permission

أدرِج العلم FLAG_GRANT_READ_URI_PERMISSION.

--grant-write-uri-permission

أدرِج العلم FLAG_GRANT_WRITE_URI_PERMISSION.

--debug-log-resolution

أدرِج العلم FLAG_DEBUG_LOG_RESOLUTION.

--exclude-stopped-packages

أدرِج العلم FLAG_EXCLUDE_STOPPED_PACKAGES.

--include-stopped-packages

أدرِج العلم FLAG_INCLUDE_STOPPED_PACKAGES.

--activity-brought-to-front

أدرِج العلم FLAG_ACTIVITY_BROUGHT_TO_FRONT.

--activity-clear-top

أدرِج العلم FLAG_ACTIVITY_CLEAR_TOP.

--activity-clear-when-task-reset

أدرِج العلم FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET.

--activity-exclude-from-recents

أدرِج العلم FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS.

--activity-launched-from-history

أدرِج العلم FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY.

--activity-multiple-task

أدرِج العلم FLAG_ACTIVITY_MULTIPLE_TASK.

--activity-no-animation

أدرِج العلم FLAG_ACTIVITY_NO_ANIMATION.

--activity-no-history

أدرِج العلم FLAG_ACTIVITY_NO_HISTORY.

--activity-no-user-action

أدرِج العلم FLAG_ACTIVITY_NO_USER_ACTION.

--activity-previous-is-top

أدرِج العلم FLAG_ACTIVITY_PREVIOUS_IS_TOP.

--activity-reorder-to-front

أدرِج العلم FLAG_ACTIVITY_REORDER_TO_FRONT.

--activity-reset-task-if-needed

أدرِج العلم FLAG_ACTIVITY_RESET_TASK_IF_NEEDED.

--activity-single-top

أدرِج العلم FLAG_ACTIVITY_SINGLE_TOP.

--activity-clear-task

أدرِج العلم FLAG_ACTIVITY_CLEAR_TASK.

--activity-task-on-home

أدرِج العلم FLAG_ACTIVITY_TASK_ON_HOME.

--receiver-registered-only

أدرِج العلم FLAG_RECEIVER_REGISTERED_ONLY.

--receiver-replace-pending

أدرِج العلم FLAG_RECEIVER_REPLACE_PENDING.

--selector

يتطلّب استخدام الخيارَين -d و-t لضبط بيانات الغرض ونوعه.

URI component package

يمكنك تحديد معرّف موارد منتظم واسم حزمة واسم مكوّن مباشرةً عندما لا تكون مؤهلاً بأحد الخيارات السابقة. عندما تكون الوسيطة غير مؤهَّلة، تفترض الأداة أنّ الوسيطة هي معرّف موارد منتظم (URI) إذا كانت تحتوي على ":" (نقطتين). تفترض الأدوات أنّ الوسيطة هي اسم مكوّن إذا كانت تحتوي على "/" (شرطة مائلة للأمام)، وإلا فإنّها تفترض أنّ الوسيطة هي اسم حزمة.

الاتصال بأداة إدارة الحِزم (pm)

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

أثناء استخدام shell، يكون بناء الجملة pm على النحو التالي:

pm command

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

adb shell pm uninstall com.example.MyApp

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

الأمر	الوصف
list packages [options] filter	طباعة جميع الحِزم، ويمكنك الاقتصار على الحِزم التي يتضمّن اسم حزمتها النص الوارد في filter. الخيارات: -f: الاطّلاع على الملف المرتبط -d: فلتر لعرض الحِزم غير المفعّلة فقط -e: فلتر لعرض الحِزم المفعَّلة فقط -s: فلترة الحزم لعرض حزم النظام فقط -3: فلتر لعرض حِزم الجهات الخارجية فقط -i: اطّلِع على أداة التثبيت الخاصة بالحِزم. -u: لتضمين الحِزم التي تم إلغاء تثبيتها ‫--user user_id: مساحة المستخدم التي سيتم البحث فيها.
list permission-groups	طباعة جميع مجموعات الأذونات المعروفة
list permissions [options] group	طباعة جميع الأذونات المعروفة، ويمكن الاقتصار على تلك الواردة في group. الخيارات: -g: التنظيم حسب المجموعة -f: لطباعة جميع المعلومات -s: ملخّص قصير -d: لعرض الأذونات الخطيرة فقط -u: أدرِج الأذونات التي سيراها المستخدمون فقط.
list instrumentation [options]	أدرِج جميع حِزم الاختبار. الخيارات: استبدِل -f بقائمة ملفات APK لحزمة الاختبار. target_package: لعرض حِزم الاختبار لهذا التطبيق فقط
list features	طباعة جميع ميزات النظام
list libraries	طباعة جميع المكتبات المتوافقة مع الجهاز الحالي
list users	طباعة جميع المستخدمين على النظام
path package	اطبع مسار حزمة APK الخاصة بـ package المحدّدة.
install [options] path	تثبيت حزمة، محدّدة بواسطة path، في النظام الخيارات: ‫-r: إعادة تثبيت تطبيق حالي مع الاحتفاظ ببياناته ‫-t: السماح بتثبيت حِزم APK التجريبية ينشئ Gradle حِزمة APK تجريبية عندما تنفّذ تطبيقك أو تصحّحه أو تستخدم الأمر إنشاء > إنشاء حِزمة APK في "استوديو Android". إذا تم إنشاء حزمة APK باستخدام حزمة تطوير برامج (SDK) لمعاينة الإصدارات التجريبية، عليك تضمين الخيار -t مع الأمر install إذا كنت تثبّت حزمة APK تجريبية. -i installer_package_name: حدِّد اسم حزمة أداة التثبيت. --user user_id: حدِّد المستخدم الذي سيتم تثبيت الحزمة له. يتم تلقائيًا تثبيت الحزمة لجميع المستخدمين الحاليين على الجهاز. --install-location location: اضبط موقع التثبيت باستخدام إحدى القيم التالية: ‫0: استخدِم موقع التثبيت التلقائي. 1: تثبيت التطبيق على مساحة التخزين الداخلية للجهاز 2: التثبيت على وسائط خارجية ‫-f: تثبيت الحزمة في ذاكرة النظام الداخلية ‫-d: السماح بخفض رمز الإصدار. -g: منح جميع الأذونات المُدرَجة في بيان التطبيق ‫--fastdeploy: لتحديث حزمة مثبَّتة بسرعة من خلال تعديل أجزاء حزمة APK التي تم تغييرها فقط --incremental: تثبِّت هذه الحزمة جزءًا كافيًا من حزمة APK لتشغيل التطبيق أثناء بثّ البيانات المتبقية في الخلفية. لاستخدام هذه الميزة، يجب توقيع حِزمة APK وإنشاء ملف الإصدار 4 من مخطّط توقيع حزمة APK ووضع هذا الملف في الدليل نفسه الذي توجد فيه حِزمة APK. لا تتوفّر هذه الميزة إلا على أجهزة معيّنة. يفرض هذا الخيار على adb استخدام الميزة أو تعذُّر استخدامها إذا كانت غير متاحة، مع تقديم معلومات تفصيلية عن سبب تعذُّر استخدامها. أضِف الخيار --wait إلى الانتظار إلى أن يتم تثبيت حزمة APK بالكامل قبل منح إذن الوصول إليها. تمنع --no-incremental adb من استخدام هذه الميزة.
uninstall [options] package	تزيل هذه السمة حزمة من النظام. الخيارات: استبدِل -k بما يلي: الاحتفاظ بمجلدات البيانات وذاكرة التخزين المؤقت بعد إزالة الحزمة. ‫--user user_id: تحدّد هذه السمة المستخدم الذي ستتم إزالة الحزمة منه. يتم تلقائيًا إزالة الحزمة لجميع المستخدمين على الجهاز. ‫--versionCode version_code: لا يتم إلغاء التثبيت إلا إذا كان التطبيق يتضمّن رمز الإصدار المحدّد.
clear package	حذف جميع البيانات المرتبطة بحزمة
enable package_or_component	تفعيل الحزمة أو المكوّن المحدّد (يُكتب على النحو التالي: "package/class").
disable package_or_component	إيقاف الحزمة أو المكوّن المحدّدَين (المكتوبَين بالتنسيق "الحزمة/الفئة").
disable-user [options] package_or_component	الخيارات: --user user_id: المستخدم الذي سيتم إيقافه
grant package_name permission	يجب منح التطبيق إذنًا، ويمكن أن يكون هذا الإذن أي إذن تم تحديده في بيان التطبيق على الأجهزة التي تعمل بالإصدار 6.0 من نظام التشغيل Android (المستوى 23 من واجهة برمجة التطبيقات) والإصدارات الأحدث. على الأجهزة التي تعمل بالإصدار 5.1 (المستوى 22 من واجهة برمجة التطبيقات) والإصدارات الأقدم من نظام التشغيل Android، يجب أن يكون الإذن اختياريًا ويحدّده التطبيق.
revoke package_name permission	إلغاء إذن من تطبيق: على الأجهزة التي تعمل بالإصدار 6.0 من نظام التشغيل Android (المستوى 23 من واجهة برمجة التطبيقات) والإصدارات الأحدث، يمكن أن يكون الإذن أي إذن تم الإعلان عنه في بيان التطبيق. على الأجهزة التي تعمل بالإصدار 5.1 (المستوى 22 من واجهة برمجة التطبيقات) والإصدارات الأقدم من نظام التشغيل Android، يجب أن يكون الإذن اختياريًا ويحدّده التطبيق.
set-install-location location	غيِّر موقع التثبيت التلقائي. قيم الموقع الجغرافي: 0: تلقائي: السماح للنظام بتحديد أفضل موقع جغرافي 1: داخلي: يتم التثبيت على مساحة التخزين الداخلية للجهاز. ‫2: خارجي: التثبيت على وسائط خارجية ملاحظة: هذا الإجراء مخصّص لتصحيح الأخطاء فقط. قد يؤدي استخدام هذا الخيار إلى تعطُّل التطبيقات وسلوكيات أخرى غير مرغوب فيها.
get-install-location	تعرض هذه السمة موقع التثبيت الحالي. قيم العائد: ‫0 [auto]: السماح للنظام بتحديد أفضل موقع جغرافي ‫1 [internal]: التثبيت على مساحة التخزين الداخلية للجهاز ‫2 [external]: التثبيت على وسائط خارجية
set-permission-enforced permission [true | false]	تحديد ما إذا كان يجب فرض الإذن المحدّد
trim-caches desired_free_space	تقليل حجم ملفات ذاكرة التخزين المؤقت للوصول إلى المساحة الحرة المحدّدة
create-user user_name	أنشئ مستخدمًا جديدًا باستخدام user_name المحدّد، مع طباعة معرّف المستخدم الجديد.
remove-user user_id	إزالة المستخدم الذي يحمل المعرّف user_id، مع حذف جميع البيانات المرتبطة بهذا المستخدم
get-max-users	طباعة الحد الأقصى لعدد المستخدمين الذين يمكن للجهاز استيعابهم
get-app-links [options] [package]	طباعة حالة إثبات ملكية النطاق للحزمة المحدّدة package، أو لجميع الحِزم في حال عدم تحديد أي حزمة يتم تحديد رموز الحالة على النحو التالي: none: لم يتم تسجيل أي بيانات لهذا النطاق ‫verified: تم التحقّق من النطاق بنجاح ‫approved: تمت الموافقة عليها بشكل إلزامي، عادةً من خلال shell ‫denied: تم الرفض بشكل إجباري، عادةً من خلال shell ‫migrated: تم الاحتفاظ بعملية التحقّق من ردّ قديم restored: تم الاحتفاظ بعملية إثبات الهوية من خلال استعادة بيانات المستخدم ‫legacy_failure: تم رفضها من قِبل خدمة التحقّق القديمة، والسبب غير معروف ‫system_configured: تمت الموافقة عليه تلقائيًا من خلال إعدادات الجهاز ‫ >= 1024: رمز خطأ مخصّص خاص بخدمة التحقّق من الجهاز الخيارات هي: ‫--user user_id: تضمين اختيارات المستخدم تضمين جميع النطاقات، وليس فقط تلك التي يتم التحقّق منها تلقائيًا
reset-app-links [options] [package]	إعادة ضبط حالة إثبات ملكية النطاق للحزمة المحدّدة أو لجميع الحِزم في حال عدم تحديد أي حزمة استبدِل package بالحزمة المطلوب إعادة ضبطها، أو استخدِم "all" لإعادة ضبط جميع الحِزم. الخيارات هي: ‫--user user_id: تضمين اختيارات المستخدم تضمين جميع النطاقات، وليس فقط تلك التي يتم التحقّق منها تلقائيًا
verify-app-links [--re-verify] [package]	بث طلب تحقّق للحزمة package المحدّدة أو لجميع الحِزم في حال عدم تحديد أي حزمة يتم إرسالها فقط إذا لم تسجّل الحزمة ردًا من قبل. ‫--re-verify: إرسال حتى إذا سجّلت الحزمة ردًا
set-app-links [--package package] state domains	اضبط حالة النطاق يدويًا لحزمة. يجب أن تحدّد الحزمة النطاق على أنّه autoVerify لكي تعمل هذه الميزة. لن يعرض هذا الأمر رسالة خطأ بشأن النطاقات التي تعذّر تطبيقه عليها. ‫--package package: الحزمة المطلوب ضبطها، أو "all" لضبط جميع الحِزم ‫state: الرمز المستخدَم لضبط النطاقات. القيم الصالحة هي: ‫STATE_NO_RESPONSE (0): إعادة الضبط كما لو لم يتم تسجيل أي ردّ على الإطلاق STATE_SUCCESS (1): يتم التعامل مع النطاق على أنّه تم إثبات ملكيته بنجاح من خلال وكيل إثبات ملكية النطاق. يُرجى العِلم أنّه يمكن لوكيل إثبات ملكية النطاق إلغاء هذا الإعداد. استبدِل STATE_APPROVED (2) بما يلي: تعامَل مع النطاق على أنّه معتمَد دائمًا، ما يمنع وكيل إثبات ملكية النطاق من تغييره. STATE_DENIED (3): يتم التعامل مع النطاق على أنّه مرفوض دائمًا، ما يمنع وكيل إثبات ملكية النطاق من تغييره. ‫domains: قائمة بالنطاقات مفصولة بمسافات لتغييرها، أو "all" لتغيير كل النطاقات
set-app-links-user-selection --user user_id [--package package] enabled domains	ضبط حالة اختيار المستخدم المضيف لحزمة يدويًا يجب أن تحدّد الحزمة النطاق لكي تعمل هذه الميزة. لن يعرض هذا الأمر رسالة خطأ للنطاقات التي تعذّر تطبيقه عليها. --user user_id: المستخدِم الذي سيتم تغيير اختياراته ‫--package package: الحزمة المطلوب ضبطها enabled: ما إذا كنت تريد الموافقة على النطاق ‫domains: قائمة بالنطاقات المراد تغييرها مفصولة بمسافات، أو "all" لتغيير كل النطاقات
set-app-links-allowed --user user_id [--package package] allowed	يمكنك تفعيل أو إيقاف إعداد معالجة الروابط التي تم التحقّق منها تلقائيًا لحزمة معيّنة. --user user_id: المستخدِم الذي سيتم تغيير اختياراته ‫--package package: الحزمة المطلوب ضبطها، أو "all" لضبط جميع الحِزم، وسيتم إعادة ضبط الحِزم إذا لم يتم تحديد أي حزمة allowed: true للسماح للحزمة بفتح الروابط التي تم التحقّق منها تلقائيًا، false لإيقاف هذه الميزة
get-app-link-owners --user user_id [--package package] domains	اطبع المالكين لنطاق معيّن لمستخدم معيّن بترتيب الأولوية من الأدنى إلى الأعلى. ‫--user user_id: المستخدم الذي سيتم البحث عنه --package package: يمكن أيضًا طباعة جميع نطاقات الويب المحدّدة في الحزمة، أو "all" لطباعة جميع الحِزم domains: قائمة بالنطاقات مفصولة بمسافات للبحث عنها

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

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

أثناء استخدام shell، تكون dpmالصيغة كما يلي:

dpm command

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

adb shell dpm command

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

الأمر	الوصف
set-active-admin [options] component	يضبط component كمشرف نشط. الخيارات هي: --user user_id: حدِّد المستخدم المستهدَف. يمكنك أيضًا تمرير --user current لاختيار المستخدم الحالي.
set-profile-owner [options] component	اضبط component كمشرف نشط وحِزْمته كمالك للملف الشخصي لمستخدم حالي. الخيارات هي: --user user_id: حدِّد المستخدم المستهدَف. يمكنك أيضًا تمرير --user current لاختيار المستخدم الحالي. --name name: حدِّد اسم المؤسسة الذي يمكن للمستخدمين قراءته.
set-device-owner [options] component	ضبط component كمشرف نشط وحزمة التطبيق كمالك للجهاز الخيارات هي: --user user_id: حدِّد المستخدم المستهدَف. يمكنك أيضًا تمرير --user current لاختيار المستخدم الحالي. --name name: حدِّد اسم المؤسسة الذي يمكن للمستخدمين قراءته.
remove-active-admin [options] component	إيقاف حساب مشرف نشط يجب أن يوضّح التطبيق android:testOnly في ملف البيان. يزيل هذا الأمر أيضًا مالكي الأجهزة والملفات الشخصية. الخيارات هي: --user user_id: حدِّد المستخدم المستهدَف. يمكنك أيضًا تمرير --user current لاختيار المستخدم الحالي.
clear-freeze-period-record	محو سجل فترات التجميد التي تم ضبطها سابقًا لتحديثات النظام عبر شبكة غير سلكية ويكون ذلك مفيدًا لتجنُّب القيود المفروضة على جدولة الأجهزة عند تطوير تطبيقات تدير فترات التجميد. اطّلِع على مقالة إدارة تحديثات النظام. تتوفّر هذه الميزة على الأجهزة التي تعمل بالإصدار 9.0 من نظام التشغيل Android (المستوى 28 من واجهة برمجة التطبيقات) والإصدارات الأحدث.
force-network-logs	إجبار النظام على إعداد أي سجلّات شبكة حالية لاسترجاعها من خلال وحدة تحكّم بسياسة الجهاز (DPC) إذا كانت هناك سجلّات اتصال أو سجلّات نظام أسماء النطاقات متاحة، يتلقّى DPC onNetworkLogsAvailable() رد الاتصال. راجِع تسجيل أنشطة الشبكة. هذا الأمر يخضع لقيود على معدّل الاستخدام. تتوفّر هذه الميزة على الأجهزة التي تعمل بالإصدار 9.0 من نظام التشغيل Android (المستوى 28 من واجهة برمجة التطبيقات) والإصدارات الأحدث.
force-security-logs	فرض إتاحة أي سجلّات أمان حالية لوحدة التحكّم بسياسة الجهاز (DPC) إذا كانت هناك سجلّات متاحة، سيتلقّى تطبيق DPC ردّ الاتصال onSecurityLogsAvailable(). تسجيل نشاط أجهزة المؤسسة هذا الأمر يخضع لقيود على معدّل الاستخدام. تتوفّر هذه الميزة على الأجهزة التي تعمل بالإصدار 9.0 من نظام التشغيل Android (المستوى 28 من واجهة برمجة التطبيقات) والإصدارات الأحدث.

أخذ لقطة شاشة

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

أثناء استخدام shell، يكون بناء الجملة screencap على النحو التالي:

screencap filename

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

adb shell screencap /sdcard/screen.png

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

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

بدلاً من ذلك، إذا حذفت اسم الملف، ستكتب screencap الصورة إلى الإخراج العادي. عند دمجه مع الخيار -p لتحديد تنسيق PNG، يمكنك بث لقطة شاشة الجهاز مباشرةً إلى ملف على جهازك المحلي.

في ما يلي مثال على التقاط لقطة شاشة وحفظها محليًا في أمر واحد:

# use 'exec-out' instead of 'shell' to get raw data
$ adb exec-out screencap -p > screen.png

تسجيل فيديو

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

في shell، استخدِم بنية الجملة التالية:

screenrecord [options] filename

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

adb shell screenrecord /sdcard/demo.mp4

أوقِف تسجيل الشاشة بالضغط على Control+C. وإلّا، سيتوقّف التسجيل تلقائيًا بعد ثلاث دقائق أو المدة الزمنية التي يحدّدها --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

الخيارات	الوصف
--help	عرض بناء جملة الأوامر وخياراتها
--size widthxheight	اضبط حجم الفيديو: 1280x720. القيمة التلقائية هي درجة دقة العرض الأصلية للجهاز (إذا كانت متوافقة)، أو 1280x720 إذا لم تكن متوافقة. للحصول على أفضل النتائج، استخدِم حجمًا متوافقًا مع برنامج ترميز AVC في جهازك.
--bit-rate rate	اضبط معدّل نقل بيانات الفيديو بالميغابت في الثانية. القيمة التلقائية هي 20 ميغابت في الثانية. يمكنك زيادة معدّل نقل البيانات لتحسين جودة الفيديو، ولكن سيؤدي ذلك إلى زيادة حجم ملفات الأفلام. يضبط المثال التالي معدّل نقل البيانات أثناء التسجيل على 6 ميغابت في الثانية: screenrecord --bit-rate 6000000 /sdcard/demo.mp4
--time-limit time	اضبط الحد الأقصى لوقت التسجيل بالثواني. القيمة التلقائية والحد الأقصى للقيمة هو 180 (3 دقائق).
--rotate	تدوير الناتج بمقدار 90 درجة هذه الميزة تجريبية.
--verbose	عرض معلومات السجلّ على شاشة سطر الأوامر في حال عدم ضبط هذا الخيار، لن تعرض الأداة أي معلومات أثناء التشغيل.

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

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

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

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

adb shell cmd package dump-profiles package

لاسترداد الملف الناتج، استخدِم:

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

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

إذا كنت تختبِر تطبيقك على عدة أجهزة اختبار، قد يكون من المفيد إعادة ضبط جهازك بين الاختبارات، مثلاً لإزالة بيانات المستخدم وإعادة ضبط بيئة الاختبار. يمكنك إعادة ضبط جهاز اختباري يعمل بالإصدار 10 من نظام التشغيل Android (المستوى 29 من واجهة برمجة التطبيقات) أو إصدار أحدث على الإعدادات الأصلية باستخدام أمر shell 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.

برامج الخلفية الخاصة بـ adb عبر USB

يمكن لخادم adb التفاعل مع حزمة USB من خلال نظامَين خلفيَّين. يمكنه استخدام الخلفية الأصلية لنظام التشغيل (Windows أو Linux أو macOS) أو استخدام خلفية libusb. لا تتوفّر بعض الميزات، مثل attach وdetach ورصد سرعة USB، إلا عند استخدام libusb كخادم خلفي.

يمكنك اختيار واجهة خلفية باستخدام متغيّر البيئة ADB_LIBUSB. إذا لم يتم ضبطها، سيستخدم adb الخلفية التلقائية. يختلف السلوك التلقائي باختلاف نظام التشغيل. اعتبارًا من الإصدار 34 من Android Debug Bridge، يتم استخدام liubusb كخادم خلفي تلقائي على جميع أنظمة التشغيل باستثناء Windows، حيث يتم استخدام الخادم الخلفي الأصلي تلقائيًا. في حال ضبط ADB_LIBUSB، يحدّد هذا الإعداد ما إذا كان سيتم استخدام الخلفية الأصلية أو libusb. يمكنك الاطّلاع على صفحة دليل adb للحصول على مزيد من المعلومات حول متغيرات بيئة adb.

تجريبي: إنّ إتاحة استخدام الخلفية libusb مع نظام التشغيل Windows هي تجريبية. اعتبارًا من الإصدار 34 من ADB، تم اختبار نظامَي التشغيل macOS وLinux فقط باستخدام مكتبة libusb.

الخدمات الخلفية لبروتوكول mDNS في adb

يمكن أن يستخدم ADB بروتوكول نظام أسماء النطاقات المتعدد البث لربط الخادم والأجهزة تلقائيًا. يتضمّن خادم ADB نظامَي خلفية، هما Bonjour (mdnsResponder من Apple) وOpenscreen.

يحتاج Bonjour إلى برنامج خفي يعمل على الجهاز المضيف. على نظام التشغيل macOS، يتم تشغيل البرنامج الخفي المضمّن من Apple دائمًا، ولكن على نظامَي التشغيل Windows وLinux، يجب أن يتأكّد المستخدم من أنّ البرنامج الخفي mdnsd قيد التشغيل. إذا عرض الأمر adb mdns check خطأً، من المحتمل أنّ ADB تستخدم Bonjour في الخلفية ولكن لا يتوفّر برنامج Bonjour خفي يعمل.

لا يحتاج الخلفية البرمجية لـ Openscreen إلى تشغيل برنامج خفي على الجهاز. يبدأ توفير Openscreen backend على أجهزة macOS بالإصدار 35 من "أداة تصحيح أخطاء Android" (ADB). يتوافق الإصدار 34 من "أداة تصحيح أخطاء Android" مع نظامَي التشغيل Windows وLinux.

يستخدم ADB تلقائيًا Bonjour backend. يمكن تغيير هذا السلوك باستخدام متغيّر البيئة ADB_MDNS_OPENSCREEN (يتم ضبطه على 1 أو 0). راجِع صفحة دليل ADB للحصول على مزيد من التفاصيل.

وضع "اللقطات المتتالية" في أداة adb (بدءًا من الإصدار 36.0.0 من أداة adb)

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

يكون "وضع الالتقاط المتواصل" غير مفعَّل تلقائيًا. لتفعيل الميزة، اتّبِع أحد الإجراءَين التاليَين:

• اضبط متغيّر البيئة ADB_DELAYED_ACK على 1.
• في "استوديو Android"، انتقِل إلى إعدادات مصحّح الأخطاء من خلال ملف (File) (أو استوديو Android (Android Studio) على نظام التشغيل macOS) > الإعدادات (Settings) > الإنشاء والتنفيذ والنشر (Build, Execution, Deployment) > مصحّح الأخطاء (Debugger) واضبط وضع التشغيل السريع لخادم ADB (ADB Server Burst Mode) على مفعّل (Enabled).