تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

تحديد المشاكل وحلّها

تطبيق نموذجي

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

جمع سجلّات Android

يجب أن يكون جهازك الجوّال متصلاً بجهازك المحلي في جميع الخطوات التي تتضمّن adb.

تثبيت أداة adb

إذا لم يسبق لك إجراء ذلك، عليك إعداد Android Debug Bridge على جهازك:

ثبِّت "adb" على الكمبيوتر.
فعِّل "خيارات المطوّرين" و"تصحيح أخطاء الجهاز عبر USB" على هاتف Android.

المكوّن الإضافي Google Home في "استوديو Android"

Google Home Plugin for Android Studio هي أداة مفيدة لجمع السجلات وتحليلها، وقد تم إنشاؤها خصيصًا لمطوّري Google Home platform. يمنحك هذا المكوّن الإضافي إمكانية الوصول إلى Google Assistant Simulator وCloud Logging وأدوات أخرى لتسهيل عملية تطوير smart home.

استخدِم هذه الأداة مع adb لتحليل سجلات جهاز Matter بشكل أكبر.

لمزيد من المعلومات والحصول على الأداة، يُرجى الاطّلاع على Google Home Plugin for Android Studio.

معلومات الإصدار

ننصحك بجمع كل معلومات الإصدار ذات الصلة بعملية الإعداد كلما قررت جمع السجلات. هذا الإجراء مطلوب إذا كنت بحاجة إلى مشاركة المشاكل مع Google.

الحصول على رقم تعريف جهازك الجوّال:
```
adb devices
```
```
List of devices attached
device-id    device
```
خزِّن هذه القيمة في متغيّر باسم phoneid:
```
phoneid=device-id
```

حفظ معلومات مختلفة عن الجهاز في متغيرات:

containerinfo=$(adb -s $phoneid shell dumpsys package com.google.android.gms | grep "versionName" || true);
homemoduleinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home " || true);
optionalhomemoduleinfo=$(adb -s $phoneid  shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.optional_home " || true);
policyhomemoduleinfo=$(adb -s $phoneid  shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.policy_home" || true);
threadinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.threadnetwork" || true);
ghainfo=$(adb -s $phoneid shell dumpsys package com.google.android.apps.chromecast.app | grep versionName || true);
enabledfeatures=$((adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "Enabled features" | grep -i "home") || true);
androidversion=$(adb -s $phoneid shell getprop ro.build.version.release || true);
androidapiversion=$(adb -s $phoneid shell getprop ro.build.version.sdk || true)

احفظ جميع المتغيرات في ملف باسم _versions.txt:

توسيع لعرض أوامر حفظ المتغيرات في ملف

يمكن نسخ المجموعة بأكملها ولصقها في نافذة طرفية في آن واحد.

versionfile=$logtimestamp"_versions.txt"
echo "Saving version info to $versionfile"

echo "Container version:" >> $versionfile
echo $containerinfo >> $versionfile
echo "" >> $versionfile

echo "Home Module version:" >> $versionfile
echo $homemoduleinfo >> $versionfile
echo "" >> $versionfile

echo "Optional Home Module version:" >> $versionfile
echo $optionalhomemoduleinfo >> $versionfile
echo "" >> $versionfile

echo "Policy Home Module version:" >> $versionfile
echo $policyhomemoduleinfo >> $versionfile
echo "" >> $versionfile

echo "Thread Module version:" >> $versionfile
echo $threadinfo >> $versionfile
echo "" >> $versionfile

echo "GHA version:" >> $versionfile
echo $ghainfo >> $versionfile
echo "" >> $versionfile

echo "Android version: " >> $versionfile
echo $androidversion >> $versionfile
echo "" >> $versionfile

echo "Android API version: " >> $versionfile
echo $androidapiversion >> $versionfile
echo "" >> $versionfile

echo "Found enabled features (blank if missing):" >> $versionfile
echo $enabledfeatures >> $versionfile
echo "" >> $versionfile

تحقَّق من محتوى _versions.txt:

cat _versions.txt

توسيع لعرض ناتج ملف العيّنة

Container version:
versionName=23.19.12 (190400-530524295) versionName=22.46.17 (190408-491726958)

Home Module version:
com.google.android.gms.home [v230508900]

Optional Home Module version:


Policy Home Module version:
com.google.android.gms.policy_home [230508900] [230508900065.505615668.505615668] [Download:000003be/dl-Home.integ_230508900100400.apk] [download:/Home.integ/230508900100400:Home.integ:230508900100400]

Thread Module version:
com.google.android.gms.threadnetwork [v231912000]

GHA version:
versionName=3.2.32.1

Android version:
13

Android API version:
33

Found enabled features (blank if missing):

يمكن الآن تقديم هذا الملف إلى Google عند الحاجة لتحديد المشاكل وحلّها.

جمع السجلات

لجمع السجلات، أغلق جميع التطبيقات التي تعمل على الجهاز الجوّال. بعد ذلك:

افتح نافذة المحطة الطرفية وامحُ سجلّات الجهاز الحالية:
```
adb logcat -b all -c
```
ابدأ عملية جمع السجلات باتّباع الخطوات التالية:
```
adb logcat >> _logs.txt
```
اترك هذه الوحدة الطرفية مفتوحة. سيؤدي ذلك إلى جمع السجلات من جهازك طالما أنّ العملية قيد التشغيل.
شغِّل التطبيق النموذجي وسجِّل جميع إجراءات واجهة المستخدم. بعد الانتهاء، أوقِف عملية logcat التي يتم تشغيلها على الوحدة الطرفية من خلال الضغط على Ctrl+C (أو Cmd+C على جهاز Mac).
يتم حفظ السجلّات من هذه الجلسة في ملف باسم _logs.txt.

يمكنك تحليل المعلومات الواردة في هذا الملف بطرق مختلفة، بما في ذلك البحث عن كلمات رئيسية مثل error أو exception أو crash.

نصوص السجلّ

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

تتوفّر هذه السجلّات في الدليل scripts في شجرة المصدر الخاصة بـ "التطبيق التجريبي". نفِّذ الخطوات التالية من دليل جذر المشروع:

الحصول على رقم تعريف جهازك الجوّال:
```
adb devices -l
```
```
List of devices attached
device-id device
```

شغِّل النص البرمجي get_logs.sh:

 ./scripts/get_logs.sh device-id

Cleared previous logs from device.
Saving version information to home_api_sample_logs_20240605233243.txt...
Saving logs to home_api_sample_logs_20240605233243.txt...
(Press CTRL+C to stop the script)

أعِد إظهار المشكلة.
اضغط على CTRL+C لإيقاف النص البرمجي.

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

سجلات أجهزة مركز البث

يمكنك الاطّلاع على سجلّات جهاز Google Nest Hub باستخدام هذه الطريقة المتوافقة مع الطُرز التالية:

Google Home
Google Nest Audio
Google Nest Hub
Google Nest Mini

لتفعيل مركز Cast لاسترداد السجلات المحلية، اتّبِع الخطوات التالية:

إعداد Android Debug Bridge
احصل على عنوان IP الخاص بالموزّع باتّباع الخطوات التالية:
- من الجهاز الرئيسي، إذا كان مزوّدًا بشاشة:
  1. التمرير سريعًا لأسفل الشاشة من أعلاها
  2. انقر على رمز الإعدادات .
  3. ابحث عن عنوان IP للجهاز: على Nest Hub (2nd gen)، انتقِل إلى معلومات الجهاز > المعلومات الفنية > عنوان IP
- من GHA على هاتفك:
  1. انقر على الجهاز لعرض صفحة تفاصيله
  2. انقر على رمز "الإعدادات" لفتح صفحة الإعدادات
  3. ابحث عن عنوان IP للجهاز: انتقِل إلى معلومات الجهاز > المعلومات الفنية > عنوان IP
على جهاز كمبيوتر متصل بشبكة Wi-Fi نفسها التي يتصل بها الجهاز:
```
  adb connect ip-address
  adb logcat
```
لتزويد شخص ما بالسجلات، نفِّذ العملية التي يتعذّر إجراؤها ووجِّه الإخراج إلى ملف نصي:
```
  adb logcat -d > platform-logs.txt
```

عمليات التشغيل المبرمَج

رصد الحواف

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

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

لا تعمل ميزة التشغيل الآلي على النحو المتوقّع

بعد احتساب رصد الحواف، إذا لم يعمل أحد الإجراءات المبرمَجة تلقائيًا على النحو المتوقّع، اتّبِع الخطوات التالية:

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

يتم تنفيذ عملية التشغيل الآلي عندما لا يكون ذلك مطلوبًا

إذا تم تشغيل عملية الإعداد الآلي عندما لا يكون ذلك مطلوبًا، راجِع معايير البدء. قد يكون من الضروري إضافة منطق إضافي للتأكّد من تسجيل تغيير الحالة مرة واحدة فقط وتشغيل التشغيل الآلي مرة واحدة فقط.

تعذُّر تجميع عملية التشغيل الآلي

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

تعذُّر التحقّق من صحة إنشاء عملية تشغيل آلي

إذا لم يتم اجتياز عملية إنشاء التشغيل الآلي، ستوفّر رسالة تحذير أو خطأ معلومات حول المشكلة. لمزيد من المعلومات، يُرجى الاطّلاع على مرجع ValidationIssueType.

تعرض دالة القائمة استثناءات

عند استدعاء دالة القائمة في Automation API، قد تعرض معالجات القراءة استثناءات بسبب عدم توفّر ميزات واجهة برمجة التطبيقات. لحلّ هذه المشكلة، احذف عملية التشغيل الآلي المتأثرة.

ولإجراء ذلك:

تأكَّد من تثبيت adb. اطّلِع على مقالة تثبيت adb.

يمكنك استرداد معرّف التشغيل الآلي من سجلّات Android عن طريق تنفيذ ما يلي:

adb logcat -s GhpNative

أمثلة على السجلّات:

adb logcat -s GhpNative level:debug | grep -A 10 -B 10 AutomationManagerTrait\.ListResponse

INTERACTION RESPONSE -> SendCommandsResponse:
1 {
1: "automation@global"
3 {
  1: "home.internal.traits.automation.AutomationManagerTrait.ListResponse"
  2:
  5 {
    1: "type.googleapis.com/home.internal.traits.automation.AutomationManagerTrait.ListResponse"
    1 {
        1: "1111-2222-3333-44444-55555" // Automation ID to delete
        2: "structure@2222-3333-4444-5555-6666"
...

إذا كان يجب حذف عدة معرّفات أتمتة، يمكنك استخدام برنامج عرض الصفحات في سطر الأوامر للتحكّم في الإخراج:

adb logcat -s GhpNative level:debug | less

احذف عملية التشغيل الآلي باستخدام معرّفها:

structure.deleteAutomation(new object : HasId(id = "1111-2222-3333-44444-55555"))

تسجّل واجهة برمجة التطبيقات Discovery API تحذيرًا عند إلغاء تسجيل سمة

إذا سجّلت Discovery API تحذيرًا بشأن Trait not found، يعني ذلك أنّ واجهة برمجة التطبيقات تحاول استخدام السمة للمرشحين في Discovery، ولكن لن تنجح لأنّه لم يتم تسجيل السمة أثناء عملية الإعداد. على سبيل المثال:

09-03 17:45:20.578 10646 10646 W AutomationSdk: trait_id: "home.matter.6006.clusters.fc43" and Exception occurred com.google.home.HomeException: 18: Trait not found: home.matter.6006.clusters.fc43
09-03 17:45:20.578 10646 10646 W AutomationSdk: While converting candidate: # com.google.home.platform.traits.AutomationCandidateNode@76f0b582

معرّف السمة هو home.matter.6006.clusters.fc43، وهو يتوافق مع RelativeHumidityControl. لتحديد اسم السمة من رقم تعريف، اطّلِع على فهرس السمات.

من هذا المثال، يجب تسجيل RelativeHumidityControl أثناء تهيئة التطبيق. راجِع تسجيل السمات لإضافة السمة إلى السجلّ.

OAuth

إذا كان لديك عميل OAuth حالي

إذا كان لديك معرّف عميل OAuth تم إثبات ملكيته لتطبيق منشور، يمكنك استخدام معرّف عميل OAuth الحالي لاختبار واجهات برمجة التطبيقات Home APIs.

لا يلزم التسجيل في Google Home Developer Console لاختبار واجهات برمجة التطبيقات الخاصة بالمنزل واستخدامها. ومع ذلك، سيظلّ عليك الحصول على تسجيل Developer Console معتمَد لنشر تطبيقك، حتى إذا كان لديك عميل OAuth تم التحقّق منه من عملية دمج أخرى.

تنطبق الاعتبارات التالية:

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

ملاحظة مهمة: لا تتوفّر حاليًا إمكانية التسجيل في Google Home Developer Console.

بالنسبة إلى تطبيقات Google Cloud التي لا تزال في انتظار إكمال عملية التحقّق من OAuth، لن يتمكّن المستخدمون من إكمال عملية OAuth إلى حين اكتمال عملية التحقّق. ستتعذّر محاولات منح الأذونات وسيظهر الخطأ التالي:

Access blocked: <Project Name> has not completed the Google verification process.