بنود عامة
س: أين وبأي لغة يجب أن ننفّذ البنية الأساسية لخدمة Cloud-to-cloud؟
ج: يمكنك تنفيذ البنية الأساسية على أي منصة وبأي لغة تختارها، شرط أن تتوافق مع بروتوكول SSL (أو 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، يجب إرسال تقرير بذلك.
س: هل تتطلّب ميزة "حالة التقرير" إرسال طابع زمني؟
ج: لا نشترط توفُّر طابع زمني، إذ ستلغي الحالة الأخيرة التي تم إرسالها الحالات السابقة.
س: هل عليّ إرسال حالة الطلب بشكل منفصل إذا كنت أرسلها في طلب البحث و/أو التنفيذ؟
ج: لا يخزّن 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، وإلا يمكنك استخدام رقم تعريف عشوائي.
س: إذا كان لدى المستخدم أجهزة متعددة وتم تغيير حالة أحدها، هل علينا إرسال آخر حالة لجميع الأجهزة؟
ج: لا، عليك فقط الإبلاغ عن حالة هذا الجهاز المحدّد.
أفضل الممارسات
س: ما هو مستوى التأخير المقبول؟
ج: أقل من 1000 ملي ثانية هو الوقت المثالي، أما الوقت بين ثانيتين و5 ثوانٍ فهو مقبول. إذا كان وقت الاستجابة يبلغ حوالي 5 ثوانٍ، يُرجى التواصل معنا.
س: كيف يمكنني جعل مكبّر الصوت الذي يتم تفعيله صوتيًا يستجيب بشكل صحيح عندما يكون غير متصل بالإنترنت؟
ج: لعرض حالة الأجهزة غير المتصلة بالإنترنت. نعرض الرسالة "غير متوفّر في الوقت الحالي" كنص مسموع لهذا الخطأ. لمزيد من المعلومات، اطّلِع على الأخطاء والاستثناءات.