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.

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

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

    لقطة شاشة ل هاتف Pixel يعرض إعدادات أنظمة تصحيح الأخطاء اللاسلكي
    الشكل 3: لقطة شاشة لإعداد تصحيح الأخطاء اللاسلكي على هاتف Google Pixel

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

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

      لقطة شاشة لمثال على إدخال رمز رقم التعريف الشخصي
      الشكل 4: مثال لإدخال رمز مكوّن من ست أرقام

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

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

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

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

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

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

    2. ملاحظة: يُرجى العِلم أنّ بعض نقاط الوصول قد لا تكون مناسبة. قد تحتاج إلى استخدام نقطة وصول تم ضبط جدار الحماية فيها بشكلٍ صحيح لتتوافق مع 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"، لن تحتاج إلى استخدام 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 لإصدار أوامر الجهاز من خلال 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، يمكنك تحديد النية باستخدام الخيارات التالية:

الاتصال بأداة إدارة الحِزم (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 بشكل كامل قبل منح إذن الوصول إلى حزمة APK.

    تمنع --no-incremental adb من استخدام هذه الميزة.

uninstall [options] package إزالة حزمة من النظام

الخيارات:

  • ‫-k: الاحتفاظ بملفَي البيانات وذاكرة التخزين المؤقت بعد إزالة الحزمة
  • --user user_id: لتحديد المستخدم الذي تتم إزالة الحزمة له.
  • ‫--versionCode version_code: لا يتم إلغاء التثبيت إلا إذا كان التطبيق يتضمّن رمز الإصدار المحدّد.
clear package حذف جميع البيانات المرتبطة بالحزمة.
enable package_or_component فعِّل الحزمة أو المكوّن المحدَّدَين (المكتوبَين على النحو "الحزمة/الفئة").
disable package_or_component إيقاف الحزمة أو المكوِّن المحدَّد (يُكتب كـ "package/class")
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: موافَق عليها من المؤسّسة، عادةً من خلال واجهة الأوامر
  • 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: الحزمة المطلوب ضبطها أو "الكل" لضبط كل الحِزم، وستتم إعادة ضبط الحزم إذا لم يتم تحديد حزمة
  • ‫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). في حال توفّر سجلّات للاتصال أو نظام أسماء النطاقات، ستتلقّى وحدة التحكّم بسياسة الجهاز (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().

SQL Lite

تبدأ 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.

خلفيات adb mDNS

يمكن أن يستخدم ADB بروتوكول نظام أسماء النطاقات المتعدد البث لربط الخادم بالأجهزة تلقائيًا. يشحن خادم ADB بواجهتين خلفيتين، Bonjour (mdnsResponseer من 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 للحصول على مزيد من التفاصيل.