للجمهور العام
س: أين وبأي لغة يجب أن ننفّذ البنية الأساسية لخدمة "التنفيذ من السحابة إلى السحابة"؟
ج: طالما أنّها تتوافق مع بروتوكول أمان طبقة النقل (TLS) الحديث وOAuth 2.0، يمكنك تنفيذ البنية الأساسية على أي منصة وبأي لغة تختارها. ننصحك بنشرها بالقرب من بقية البنية الأساسية قدر الإمكان، وذلك لتحسين الموثوقية وتقليل وقت الاستجابة عند تنفيذها على أجهزة المستخدمين الفعليين.
س: هل يجب أن تكون أرقام تعريف الأجهزة فريدة؟
ج: يجب أن تكون المعرّفات فريدة. إذا لم تكن المعرّفات فريدة على مستوى خدمتك، يجب أن تكون فريدة على مستوى كل مستخدم على الأقل. لنفترض أنّ أحد المستخدمين لديه عدة منازل، وأنّ كلا المنزلين يتضمّنان عمليات ربط بالحساب نفسه. عند طلب تشغيل مصباح في منزل معيّن، يجب ألا يؤدي ذلك إلى تشغيل مصباح يحمل رقم التعريف نفسه في منزل آخر.
س: هل يجب أن تكون أسماء الأجهزة فريدة؟
ج: لا يشترط أن تكون الأسماء فريدة، ولكن بمرور الوقت، قد نشجّع المستخدمين على تحسين الأسماء غير المناسبة بعد الإعداد للحصول على تجربة أفضل.
في ما يلي دليل سريع حول التسمية:
- يجب أن تكون الأسماء من النوع الذي يمكن للمستخدمين قوله.
- نحن نتعرّف على مجموعات فرعية من السلاسل، لذا إذا كان لديك "مصباح ملون من Acme"، سنرد أيضًا على طلب البحث "مصباح من Acme".
- ننصحك بتوفير اسم وصفي للمنتج واسم واحد أو أكثر من الأسماء التي يحدّدها المستخدم.
- لا يحتاج المستخدمون إلى منح الأضواء أسماء غرف، لأنّ لدينا غرفًا لذلك؛ يجب أن يكون لكل ضوء اسم فريد في الغرفة، ولكن يمكن دائمًا استخدام صيغة الجمع للتحكّم في كل شيء (على سبيل المثال، المصباحان في الشمعدانات الجدارية في المكتب هما "الضوء الشمالي" و"الضوء الشرقي"، ولكن يمكن التحكّم فيهما باسم "الأضواء" فقط).
س: ما هو معدّل تعديل حالة الجهاز؟
ج: يتم استرداد الحالة المؤقتة عند تنفيذ طلب بحث أو تنفيذ، وهما إجراءان يبدأهما المستخدم. إذا سأل المستخدم "هل الضوء مضاء؟" أو أراد زيادة سطوع الضوء، علينا إجراء طلب بحث لمعرفة الحالة الحالية.
س: هل يمكن تعديل قاعدة بيانات 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.
يستغرق الردّ على طلب المزامنة وقتًا طويلاً جدًا.
- يُرجى التأكّد من الردّ على طلب SYNC في غضون 5 ثوانٍ.
س: هل يمكن أن تكون الحالة "في انتظار المراجعة"؟
ج: نفضل تلقّي ردّ بنجاح أو تعذُّر، بدلاً من الردّ في انتظار المراجعة، إذا كانت أجهزتك متاحة في الوقت الفعلي. يُرجى التواصل معنا إذا كنت تعتقد أنّك بحاجة إلى ردّ "معلّق"، لأنّنا ندرك أنّ بعض الأجهزة المنخفضة الطاقة وغير المتزامنة قد تتطلّب ردًا معلّقًا ونموذج تنفيذ غير متزامن.
الاختبار والإرسال
س: هل يمكننا إعداد بيئة سحابية للتطوير؟
ج: نعم، يمكنك اختبار بيئة وإعدادات سحابية لم يتم إطلاقهما.
س: لا يظهر الإجراء الخاص بي في قسم "التحكّم في المنزل" في تطبيق Google Home. ما السبب؟
ج: تأكَّد من أنّك مطوِّر لهذا المشروع.
حالة التقرير
س: هل هناك شروط مسبقة لتنفيذ Report State؟
ج: يجب أن يستخدم المشروع Smart Home API، وأن يتيح استخدام OAuth2، وأن يتضمّن سمات يمكن الإبلاغ عن حالاتها.
س: كم مرة يجب إرسال Report State على الجهاز؟
ج: تهتمّ Google بالانتقال والحالة النهائية. ومع ذلك، إذا حدثت العديد من التغييرات في الحالة خلال فترة زمنية قصيرة (على سبيل المثال، إذا فتح المستخدم الثلاجة وأغلقها ثلاث مرات في دقيقة واحدة أو حرّك مفتاح التعتيم)، لن نحتاج إلا إلى الحالة النهائية التي تم تسجيلها.
س: هل يجب إرسال حالة الجهاز الكاملة عند إجراء مكالمات Report State؟
ج: لا تتوافق التعديلات الجزئية على الحالة، لذا يجب أن تتضمّن طلبات Report State دائمًا جميع البيانات الخاصة بسمة معيّنة تم تعديلها. إذا كان من شأن سمات معيّنة أن تؤدي إلى عدم اتساق، يجب الإبلاغ عنها معًا.
س: هل يمكن أن ترسل Google طلبًا إلى جهازي للحصول على الحالة (أي إرسال طلب إلى الجهاز)؟
الجواب: هذه آلية احتياطية لا ننصح باستخدامها. إذا احتجنا إلى الرجوع إلى خيار طلب البيانات من الجهاز بشكل متكرر لهؤلاء المستخدمين، لا يمكننا ضمان حجم الحمل الإضافي. وتأتي الحاجة إلى ذلك من المنصات المرئية الجديدة. بالإضافة إلى مشكلة التحميل غير المعروفة، ستنخفض جودة تجربة المستخدم. ونرى أنّ Report State عنصر أساسي في المنصة.
س: ما هي السمات التي تتيح استخدام Report State حاليًا؟
ج: تتوفّر جميع السمات العامة التي تتضمّن حالات مرتبطة بها. يجب أيضًا الإبلاغ عن أي تغيير في حالة الجهاز على الإنترنت.
يُرجى العِلم أنّ "المشاهد" لا تتضمّن حالات. ومع ذلك، قد تؤدي إلى تغيير في حالة الأجهزة. إذا تغيّرت حالة أي جهاز في Google Home Graph، يجب إرسال تقرير بذلك.
س: هل يتطلّب Report State إرسال طابع زمني؟
ج: لا نشترط توفير طابع زمني، لأنّ الحالة الأخيرة التي يتم إرسالها ستلغي الحالات السابقة.
س: هل عليّ إرسال حالة الطلب بشكل منفصل إذا كنت أرسلها في "الطلب" و/أو "التنفيذ"؟
ج: لا يخزّن Home Graph سوى الحالة التي يتم إرسالها عبر Report State. يتم استخدام الحالة التي يتم عرضها كاستجابة لطلبات EXECUTE وQUERY فقط في الردود الصوتية للمستخدم، ولا يتم تخزينها. نتيجةً لذلك، يجب استدعاء Report State حتى إذا تم عرض الحالة الجديدة للجهاز كاستجابة لطلب EXECUTE أو QUERY.
س: ما هي العواقب المترتبة على عدم تنفيذ Report State بالكامل خلال الموعد النهائي المحدّد؟
ج: سيؤدي ذلك إلى تدهور تجربة المستخدم، مثلاً في Google Home app (GHA) ومساحات العرض المرئية. سيعني ذلك إرسال العديد من طلبات البحث عن الحالة، ولا يمكننا ضمان أنّ ذلك لن يؤدي إلى زيادة الحمل على السحابة الإلكترونية الخاصة بالشريك.
س: كيف يمكنني اختبار تنفيذ Report State؟
ج: استخدِم أداة عرض الرسم البياني للمنزل، وهي أداة اختبار ذاتية الخدمة تعرض لك حالات الأجهزة الحالية المخزَّنة في Home Graph.
س: هل يمكننا استخدام requestId عشوائي لـ Report State؟
ج: ننصح الشركاء باستخدام رقم التعريف نفسه الذي تلقّوه من طلب EXECUTE إذا تم تشغيل Report State من خلال طلب EXECUTE، وإلا يمكنك استخدام رقم تعريف عشوائي.
س: إذا كان لدى المستخدم أجهزة متعددة وتم تغيير حالة أحدها، هل علينا إرسال تقرير عن آخر حالة لجميع الأجهزة؟
ج: لا، عليك الإبلاغ عن حالة هذا الجهاز المحدّد فقط.
أفضل الممارسات
س: ما هو وقت الاستجابة المقبول؟
ج: من الأفضل أن يكون وقت الاستجابة أقل من 200 مللي ثانية، أما إذا كان بين ثانيتين و5 ثوانٍ، فيُعدّ ذلك مقبولاً. إذا كان معدّل التأخير يبلغ حوالي 5 ثوانٍ، يُرجى التواصل معنا.
س: كيف يمكنني التأكّد من أنّ مكبّر الصوت الذي يتم تفعيله صوتيًا يستجيب بشكل صحيح عندما يكون غير متصل بالإنترنت؟
ج: لعرض حالة الأجهزة غير المتصلة بالإنترنت. نعرض الرسالة "غير متوفّر في الوقت الحالي" كنص مسموع لهذا الخطأ. لمزيد من المعلومات، يُرجى الاطّلاع على الأخطاء والاستثناءات.