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