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

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

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

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

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

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

يتيح نظام التشغيل Android 11 (المستوى 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. على جهازك، انقر على تصحيح الأخطاء اللاسلكي واقرِن جهازك:

   

   الشكل 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") وكيفية حلّها:

• تعذُّر الاتصال بشبكة 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 (الخيار الوحيد المتاح على Android 10 والإصدارات الأقدم)

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

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

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

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

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

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

باستخدام الإصدار 23 من "أدوات نظام Android الأساسي" والإصدارات الأحدث، يعالج adb الوسيطات بالطريقة نفسها التي يعالج بها الأمر ssh(1) الوسيطات. وقد أدّى هذا التغيير إلى حلّ الكثير من المشاكل المتعلّقة بإدخال الأوامر وأصبح من الممكن تنفيذ الأوامر التي تحتوي على أحرف برمجية لنظام التشغيل بشكل آمن، مثل 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، يمكنك إصدار أوامر باستخدام أداة "مدير الأنشطة" (am) لأداء إجراءات مختلفة في النظام، مثل بدء نشاط أو إيقاف عملية بشكل قسري أو بث نية أو تعديل خصائص شاشة الجهاز وغير ذلك.

في بيئة شل، يكون تنسيق am على النحو التالي:

am command

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

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	إصدار طلب بث اطّلِع على مواصفات وسيطات النية. الخيارات هي: [--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: تفريغ الذاكرة المحجوزة للتطبيقات الأصلية بدلاً من الذاكرة المحجوزة للتطبيقات المُدارة
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	طباعة مواصفات النية المحدّدة كعنوان URL اطّلِع على مواصفات وسيطات النية.
to-intent-uri intent	اطبع مواصفات النية المحدّدة كعنوان URL intent:. اطّلِع على مواصفات وسيطات النية.

مواصفات وسيطات النية

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

إظهار الكل

-a action

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

-d data_uri

حدِّد عنوان URL لبيانات النية، مثل 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) ل تنفيذ الإجراءات وطلبات البحث في حِزم التطبيقات المثبَّتة على الجهاز.

في بيئة شل، يكون تنسيق 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: حدِّد اسم حزمة أداة التثبيت. --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	فعِّل الحزمة أو المكوّن المحدَّدَين (المكتوبَين على النحو "الحزمة/الفئة").
disable package_or_component	أوقِف الحزمة أو المكوّن المحدَّدَين (المكتوبَين على النحو "الحزمة/الفئة").
disable-user [options] package_or_component	الخيارات: ‫--user user_id: المستخدم المطلوب إيقافه
grant package_name permission	منح إذن لتطبيق: على الأجهزة التي تعمل بنظام التشغيل Android 6.0 (المستوى 23 من واجهة برمجة التطبيقات) والإصدارات الأحدث، يمكن أن يكون الإذن أي إذن مُعلَن عنه في بيان التطبيق. على الأجهزة التي تعمل بالإصدار 5.1 من Android (المستوى 22 من واجهة برمجة التطبيقات) والإصدارات الأقدم، يجب أن يكون إذنًا اختياريًا يحدّده التطبيق.
revoke package_name permission	إلغاء إذن من أحد التطبيقات: على الأجهزة التي تعمل بالإصدار 6.0 من نظام التشغيل Android (المستوى 23 من واجهة برمجة التطبيقات) والإصدارات الأحدث، يمكن أن يكون الإذن أي إذن تم الإعلان عنه في بيان التطبيق. على الأجهزة التي تعمل بالإصدار 5.1 من Android (المستوى 22 من واجهة برمجة التطبيقات) والإصدارات الأقدم، يجب أن يكون إذنًا اختياريًا يحدّده التطبيق.
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: الحزمة المطلوب إعادة ضبطها، أو "الكل" لإعادة ضبط كل الحِزم الخيارات هي: --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-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: صحيح للسماح للحزمة بفتح الروابط التي تم التحقّق منها تلقائيًا، خطأ لإيقاف هذه الميزة
get-app-link-owners --user user_id [--package package] domains	طباعة مالكي نطاق معيّن لمستخدم معيّن بترتيب من الأولوية المنخفضة إلى العالية --user user_id: المستخدم المطلوب البحث عنه --package package: اختياريًا أيضًا للطباعة لجميع نطاقات الويب التي تمّ الإعلان عنها في إحدى الحِزم، أو "الكل" لطباعة جميع الحِزم domains: قائمة النطاقات التي تريد البحث عنها مفصولة بمسافات

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

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

أثناء استخدام dpm، يكون أسلوب التركيب على النحو التالي:

dpm command

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

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 onNetworkLogsAvailable() مكالمة الاسترجاع. راجِع تسجيل نشاط الشبكة. هذا الأمر مُقيّد بمعدّل تكرار. تتوفّر هذه الميزة على الأجهزة التي تعمل بالإصدار 9.0 من نظام التشغيل Android (المستوى 28 من واجهة برمجة التطبيقات) والإصدارات الأحدث.
force-security-logs	إجبار النظام على إتاحة أي سجلّات أمان حالية لخدمة إدارة الخدمات والتطبيقات إذا كانت هناك سجلات متاحة، يتلقّى "المسؤول عن معالجة البيانات" onSecurityLogsAvailable() مكالمة المتابعة. راجِع مقالة تسجيل أنشطة الأجهزة في المؤسسة. هذا الأمر مُقيّد بمعدّل تكرار. تتوفّر هذه الميزة على الأجهزة التي تعمل بالإصدار 9.0 من نظام التشغيل Android (المستوى 28 من واجهة برمجة التطبيقات) والإصدارات الأحدث.

أخذ لقطة شاشة

إنّ الأمر screencap هو أداة قشرة لالتقاط لقطة شاشة لشاشة الجهاز.

في بيئة شل، يكون تنسيق screencap على النحو التالي:

screencap filename

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

adb shell screencap /sdcard/screen.png

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

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

تسجيل فيديو

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

في بيئة سطر الأوامر، استخدِم البنية التالية:

screenrecord [options] filename

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

adb shell screenrecord /sdcard/demo.mp4

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

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

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

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

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

adb shell cmd package dump-profiles package

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

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

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

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

الخلفيات في adb USB

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

يمكنك اختيار واجهة خلفية باستخدام متغيّر البيئة ADB_LIBUSB. في حال عدم ضبطه، يستخدم adb الخلفية التلقائية. يختلف السلوك التلقائي حسب نظام التشغيل. اعتبارًا من الإصدار 34 من أداة ADB، يتم استخدام 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 إلى تشغيل برنامج خفي على الجهاز. بدءًا من الإصدار 35 من أداة ADB، يتوفّر دعم لنظام Openscreen الأساسي على نظام التشغيل macOS. يتوافق نظاما التشغيل Windows وLinux مع الإصدار 34 من ADB.

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

وضع adb Burst (بدءًا من الإصدار 36.0.0 من ADB)

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

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

• اضبط متغيّر البيئة ADB_DELAYED_ACK على 1.
• في Android Studio، انتقِل إلى إعدادات أداة تصحيح الأخطاء من خلال ملف (أو Android Studio على نظام التشغيل macOS) > الإعدادات > الإنشاء والتنفيذ والنشر > أداة تصحيح الأخطاء واضبط وضع الذروة لخادم ADB على مفعَّل.