تمت ترجمة هذه الصفحة بواسطة 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

لتفعيل مركز البث لاسترجاع السجلات المحلية:

إعداد 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 APIs حدًا أقصى يبلغ 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.