بنود عامة
س: أين وبلغة ما يجب تنفيذ البنية الأساسية للتسليم من السحابة الإلكترونية إلى السحابة الإلكترونية؟
ج: طالما أنّها متوافقة مع بروتوكول SSL (TLS) الحديث وOAuth 2.0، يمكنك تنفيذ بنيتك الأساسية على أيّ نظام أساسي وبأيّ لغة تختارها. ننصحك بنشر الخدمة بالقرب من بقية البنية الأساسية قدر الإمكان، لتحسين الموثوقية وتقليل وقت الاستجابة لتنفيذها على أجهزة المستخدمين الفعلية.
س: هل يجب أن تكون أرقام تعريف الأجهزة فريدة؟
أ: يجب أن تكون المعرّفات فريدة. إذا لم يكن لديك معرّفات فريدة في خدمتك، يجب أن تكون فريدة على مستوى كل مستخدم على الأقل. تخيل مستخدمًا لديه منازل متعدّدة، تم دمج كلتا المنزلَين مع حساب المستخدم نفسه. يجب ألّا يؤدي طلب إشعال مصباح في منزل إلى إشعال مصباح يحمل رقم التعريف نفسه في منزل آخر.
س: هل يجب أن تكون أسماء الأجهزة فريدة؟
ج: لا يجب أن تكون الأسماء فريدة، ولكن مع مرور الوقت، قد نشجّع المستخدمين على تحسين الأسماء السيئة بعد الإعداد لتوفير تجربة أفضل للمستخدم.
في ما يلي دليل سريع للتسمية:
- يجب أن تكون الأسماء عبارة عن كلمات يمكن للمستخدمين قولها.
- نحن نتعرّف على مجموعات فرعية من السلاسل، لذا إذا كان لديك "مصباح ملون من acme"، سنردّ أيضًا على "مصباح acme".
- ننصحك باستخدام اسم وصفي للمنتج واسم واحد أو أكثر من الأسماء التي يحدّدها المستخدم.
- لا يحتاج المستخدمون إلى منح المصابيح أسماء الغرف، لأنّنا نوفّر غرفًا لذلك. يجب أن يكون لها أسماء فريدة لكل غرفة، ولكن يمكنهم دائمًا استخدام الجمع لتحديد كل شيء (على سبيل المثال، المصباحان في شمعدانات المكتب هما "مصباح الشمال" و"مصباح الشرق"، ولكن يمكن التحكّم فيهما باسم "مصابيح" فقط).
س: ما هو معدّل تحديث حالة الجهاز؟
أ: يتم استرداد الحالة المؤقتة عند تنفيذ QUERY أو EXECUTE، وهما إجراءان يبدأهما المستخدم. إذا سأل المستخدم "هل المصباح مضاء؟" أو أراد زيادة سطوع المصباح، سنحتاج إلى إجراء طلب بحث لمعرفة الحالة الحالية.
س: هل من الممكن تعديل قاعدة بيانات Home Graph مباشرةً باستخدام الحالة الحالية للجهاز؟
ج: نعم، استخدِم طلب البيانات من واجهة برمجة التطبيقات Report State.
ربط الحسابات وOAuth
س: هل نحتاج إلى ربط الحساب؟
ج: نعم، يجب ربط الحساب لربط أجهزة المستخدمين بخدمات السحابة الإلكترونية الخاصة بمقدّم الخدمة.
س: بالنسبة إلى بروتوكول OAuth، ننتهي صلاحية رموز الوصول كل 15.213 ساعة، هل هذا مناسب؟
ج: نعم، ولكن يُرجى إجراء الاختبار باستخدام مهلة انتهاء صلاحية قصيرة نسبيًا، مثلاً من 10 إلى 20 دقيقة. من المفترض أن يُعيد عميل OAuth تحميل الرموز المميّزة حسب الحاجة، وسيثبت الاختبار باستخدام وقت انتهاء صلاحية قصير أنّ هذا الإجراء يعمل على ما يرام.
مكان ووقت الاستماع إلى الموسيقى
س: متى تحدث المزامنة؟
ج: تحدث المزامنة فور اكتمال عملية OAuth وبعد إجراء مكالمة طلب المزامنة.
س: لماذا لا يعمل SYNC؟
أ: هناك عدد من الأسباب الشائعة لعدم نجاح ذلك.
يتم إرسال أنواع الأجهزة غير الصحيحة.
- على سبيل المثال، نتوقع
action.devices.types.LIGHT، ولكن يتم إرسالaction.devices.types.Light.
- على سبيل المثال، نتوقع
إرسال أنواع أجهزة غير متوافقة
- على سبيل المثال، إذا أرسلت
action.devices.types.FLASHLIGHT، لن تتمكّن من استخدام هذه الميزة.
- على سبيل المثال، إذا أرسلت
يتم إرسال حقول غير صالحة أو غير متوافقة.
- على سبيل المثال، لديك حقل غير مذكور في مواصفاتنا.
هناك مشكلة أخرى في التنسيق في ردّ SYNC.
- تحقّق من الأقواس.
إذا كنت تواجه مشكلة في ربط الحساب
- يُرجى التأكّد من أنّك تتلقّى رمز مميّز صالحًا للوصول في عنوان Auth لطلب SYNC.
يستغرق جهازك وقتًا طويلاً جدًا في الاستجابة لطلب المزامنة.
- يُرجى التأكّد من الردّ على طلب المزامنة في غضون 5 ثواني.
س: هل يمكن استخدام حالة "في انتظار الردّ"؟
ج: نفضّل بشدة الحصول على ردّ يشير إلى نجاح أو تعذّر الإجراء، بدلاً من "في انتظار المراجعة"، إذا كانت أجهزتك متاحة في الوقت الفعلي. يُرجى التواصل معنا إذا كنت بحاجة إلى ردّ "في انتظار المراجعة"، لأنّنا ندرك أنّ بعض الأجهزة التي تعمل بطاقة منخفضة وغير المستندة إلى الوقت الفعلي قد تتطلّب ردًا في انتظار المراجعة ونموذج تنفيذ غير متزامن.
الاختبار والإرسال
س: هل يمكننا إعداد بيئة تطوير في السحابة الإلكترونية؟
ج: نعم، يمكنك اختبار بيئة السحابة الإلكترونية والإعدادات غير المُطلقة.
س: لا يظهر "الإجراء" في قسم "التحكّم في المنزل" في تطبيق Google Home. ما الذي يحدث؟
أ: أكِّد أنّك مطوّر لهذا المشروع.
حالة التقرير
س: هل هناك متطلبات مسبقة لتنفيذ ميزة "الإبلاغ عن حالة"؟
ج: يجب أن يستخدم المشروع واجهة برمجة التطبيقات Smart Home API وأن يتيح بروتوكول OAuth2 وأن يحتوي على سمات تتضمّن حالات يتم الإبلاغ عنها.
س: كم مرة يجب الإبلاغ عن حالة الجهاز؟
أ: تهمّ Google الحالة الانتقالية والحالة النهائية. ومع ذلك، إذا حدثت تغييرات كثيرة في الحالة خلال فترة زمنية قصيرة (على سبيل المثال، فتح مستخدم الثلاجة وإغلاقها ثلاث مرات في الدقيقة أو تحريك مفتاح باهٍ)، لن نحتاج سوى إلى الحالة النهائية التي تم الإبلاغ عنها.
س: هل يجب إرسال حالة الجهاز الكاملة عند إجراء مكالمات "إعداد تقارير عن الحالة"؟
ج: لا تتوفّر تعديلات الحالة الجزئية، لذا يجب أن تتضمّن طلبات Report State دائمًا جميع البيانات لسمة معيّنة تم تعديلها. إذا كانت سمتان ستؤديان إلى اختلاف، يجب الإبلاغ عنهما معًا.
س: هل يمكن لشركة Google الاستعلام عن جهازي للحصول على الحالة (أي إجراء استطلاع للجهاز)؟
أ: هذه آلية احتياطية لا ننصح بها. إذا احتجنا إلى التراجع عن الاستعلام عن الجهاز بشكل متكرر لهؤلاء المستخدمين، لا يمكننا ضمان الحمل الإضافي الذي سيحدث. ويعود سبب ذلك إلى مساحات العرض المرئية الجديدة. بالإضافة إلى مشكلة التحميل غير المعروفة، ستؤدي هذه المشكلة إلى تقليل تجربة المستخدم. نعتقِد أنّ Report State مهم جدًا للمنصة.
س: ما هي السمات التي تتيح حاليًا استخدام "حالة التقرير"؟
أ: تتوفّر جميع السمات العامة التي لها حالات مرتبطة بها. يجب أيضًا الإبلاغ عن أي تغيير في حالة "الاتصال بالإنترنت" للجهاز.
يُرجى العلم أنّ "المشاهد" لا تتضمّن حالات. ومع ذلك، قد تؤدي هذه الإجراءات إلى تغيير حالات الأجهزة. إذا كان أي جهاز في Google Home Graph يتغيّر حالته، يجب الإبلاغ عن ذلك.
س: هل تتطلّب حالة التقرير إرسال طابع زمني؟
أ: لا نطلب طابعًا زمنيًا، لأنّ الحالة الأخيرة المُرسَلة ستلغي الطلبات السابقة.
س: هل أحتاج إلى الإبلاغ عن الحالة بشكل منفصل إذا كنت أرسل الحالة في Query و/أو Execute؟
ج: لا يخزِّن Home Graph سوى الحالة التي يتم إرسالها من خلال Report State. لا تُستخدَم الحالة التي يتم عرضها كردّ على نوايتي EXECUTE وQUERY إلا في الردود الصوتية التي يتم عرضها للمستخدم، ولا يتم تخزينها. نتيجةً لذلك، يجب استدعاء Report State حتى إذا سبق أن تم عرض الحالة الجديدة للجهاز كردّ على طلب EXECUTE أو QUERY.
س: ما هي العواقب المترتّبة على عدم تنفيذ ميزة "حالة التقرير" بالكامل خلال الموعد النهائي المحدّد؟
ج: سيؤدي ذلك إلى تقليل تجربة المستخدم، على سبيل المثال في Google Home app (GHA) والمساحات المرئية. سيؤدي ذلك إلى إرسال العديد من نوايا QUERY لاستطلاع الحالة، ولا يمكننا ضمان ما إذا كان ذلك سيؤدي إلى زيادة في الحمل على السحابة الإلكترونية للشريك.
س: كيف يمكنني اختبار عملية تنفيذ "حالة التقرير"؟
ج: استخدِم عارِض الرسم البياني للمنزل، وهي أداة اختبار ذاتي تعرض حالات الجهاز الحالية المخزّنة في Home Graph.
س: هل يمكننا استخدام مَعلمة requestId عشوائية لحالة التقرير؟
ج: ننصح الشركاء باستخدام مَعلمة requestId نفسها التي تلقّوها من طلب EXECUTE إذا تم بدء Report State من خلال طلب EXECUTE، وإلا يمكنك استخدام مَعلمة requestId عشوائية.
س: إذا كان لدى المستخدم أجهزة متعددة وتغيّرت حالة أحدها، هل علينا الإبلاغ عن آخر حالة لجميع الأجهزة؟
ج: لا، ما عليك سوى الإبلاغ عن حالة هذا الجهاز المحدّد.
أفضل الممارسات
س: ما هو نوع وقت الاستجابة المقبول؟
أ: أقل من 200 مللي ثانية هو مثالي، ويكون الوقت بين 2 و5 ثوانٍ مقبولًا. إذا كان وقت الاستجابة يتراوح بين 5 ثوانٍ تقريبًا، يُرجى التواصل معنا.
س: كيف يمكنني جعل مكبّر الصوت المشغَّل بالصوت يستجيب بشكل صحيح عندما يكون غير متصل بالإنترنت؟
أ: عرض حالة "غير متصلة بالإنترنت" للأجهزة غير المتصلة بالإنترنت نعرض العبارة "غير متوفّر في الوقت الحالي" كنص للتحويل الصوتي لهذا الخطأ. لمزيد من المعلومات، يُرجى الاطّلاع على الأخطاء والاستثناءات.