Google Home Vitals (السحابة الإلكترونية)

تساعدك هذه المجموعة من لوحات البيانات والتنبيهات في الحفاظ بشكل استباقي على تكامل عالي الجودة مع منظومة Google Home المتكاملة. تلتزم Google بتقديم الدعم للشركاء في تطوير منظومة متكاملة عالية الجودة لجميع العملاء.

تتضمّن لوحة البيانات ثلاثة أقسام، يغطّي كل منها جزءًا رئيسيًا يساهم في جودة عملية الدمج بشكل عام.

1. مقاييس الشركاء في Google: تقيس هذه المقاييس سلامة المكالمات من Google إلى الخلفية السحابية.

2. سلامة النظام - مقاييس الشريك إلى Google: تقيس سلامة المكالمات من نظامك إلى Google.

3. سلامة الجهاز - دقة الحالة: تقيس هذه السمة دقة الحالات المخزّنة في أنظمة Google والتي تُستخدم للرد على طلبات المستخدمين.

عندما لا تستوفي المقاييس القيم المستهدَفة، يتم تمييزها باللون الأحمر للإشارة إلى مشكلة قد تؤثّر في تجربة المستخدم. تقدّم المعلومات التالية تفاصيل عن كل هدف وسبب أهميته للمستخدمين.

إذا لم ينقلك الزر التالي مباشرةً إلى لوحة البيانات، يمكنك الوصول إليها من خلال اختيار صفحة نظرة عامة، ثم لوحات البيانات، ثم اختيار لوحة بيانات مقاييس Google Home الحيوية (السحابة الإلكترونية) من قائمة لوحات البيانات الخاصة بي لعرض لوحة البيانات.

الانتقال إلى لوحة البيانات

مقاييس "من Google إلى الشريك"

يقيس مقياس نسبة نجاح الطلب/التنفيذ >=%99.5 عدد المرات التي يتم فيها تنفيذ طلبات المستخدمين بشكل صحيح، ما يساعد في تجنُّب ردود "مساعد Google"، مثل "لا يمكنني الوصول إلى الجهاز" أو تأكيد طلب لم يتم تنفيذه بعد بشكل غير صحيح.

ما الذي يحدّد حالة "نجاح"؟

يتم وضع علامة "ناجحة" على المعاملة إذا تلقّت منصة Google Home ردًا صالحًا يشير إلى أنّه تم تنفيذ الإجراء المطلوب أو تم استرداد الحالة المطلوبة.

يتم احتساب الاستجابات التي تتضمّن استثناءات غير حظر (على سبيل المثال، الحالة SUCCESS مصحوبة بالاستثناء lowBattery) كمعاملات ناجحة. وصل الأمر إلى الجهاز وتم تنفيذ الغرض على الرغم من التحذير.

ما الذي يحدّد حالة "تعذُّر"؟

تُعدّ الأخطاء التي تم العثور عليها في رموز الأخطاء الشائعة في المنصات والمصنّفة على أنّها تتطلّب إجراءً من الشريك "حالات تعذّر" عند احتساب معدّلات النجاح في طلبات البحث والتنفيذ. بالإضافة إلى ذلك، فإنّ الأخطاء التي تم العثور عليها في الأخطاء والاستثناءات هي أيضًا "إخفاقات"، باستثناء ما يلي:

يقيس المقياس وقت الاستجابة لطلب البحث/التنفيذ (p90) <= 1000 ملي ثانية وقت انتظار الإجراء المطلوب ويساعد في ضمان عدم اضطرار المستخدمين إلى الانتظار لفترة طويلة، مثلاً، الانتظار لبضع ثوانٍ لإطفاء الضوء.

مقاييس وقت الاستجابة

يُعدّ وقت الاستجابة مؤشرًا مهمًا على مدى سرعة استجابة عملية الدمج للمستخدم النهائي. تتتبّع لوحة البيانات وقت الاستجابة عند الشريحة المئوية التسعين (P90)، والذي يمثّل تجربة المستخدمين "الأبطأ" (على سبيل المثال، يعني P90 البالغ 800 ملي ثانية أنّه يتم تلقّي% 90 من الطلبات في 800 ملي ثانية أو أقل).

تقيس Google وقت الاستجابة بشكل مختلف عند التحقّق من الحالة مقارنةً بأوامر الجهاز لضمان الدقة الفنية.

1. وقت استجابة طلب البحث (استفهامي)

يقيس هذا المقياس وقت الذهاب والعودة Cloud-to-cloud عندما تطلب Google الحالة الحالية لجهاز.

• البداية: ترسل Google طلب action.devices.QUERY إلى عنوان URL الخاص بخدمة التنفيذ.
• فترة القياس: هي الوقت الذي يستغرقه خادمك السحابي في تلقّي استجابة HTTP الكاملة ومعالجتها وإرسالها مرة أخرى إلى Google.
• النهاية: تتلقّى Google حمولة الاستجابة النهائية وتؤكّد استلامها من خدمتك.

2. وقت استجابة EXECUTE (الإجراء)

يقيس هذا المقياس وقت تأكيد استلام الأمر عندما ترسل Google طلب تحكّم إلى أحد الأجهزة.

• البداية: ترسل Google طلب action.devices.EXECUTE إلى عنوان URL الخاص بخدمة التنفيذ.
• فترة القياس: هي الوقت الذي يستغرقه السحابة الإلكترونية لتلقّي الأمر وإرجاع ردّ إقرار.
• وقت الانتهاء: تتلقّى Google الردّ الذي يتضمّن الحالة SUCCESS أو PENDING أو OFFLINE.
• النطاق الفني: يقيس هذا المقياس وقت "إقرار الاستجابة" بين سحابة Google وسحابتك. ولا تقيس هذه المقاييس الوقت الذي يستغرقه الجهاز المادي (مثل المصباح الكهربائي) لإكمال تغيير الحالة المادية، لأنّ ذلك غالبًا ما يتضمّن وقت استجابة شبكة متداخلة محلية خارج مسار السحابة الإلكترونية إلى السحابة الإلكترونية.

خيارات تقليل وقت الاستجابة

اقتراحات بشأن تصميم خدمة التوجيه الجغرافي

إذا لم يكن تنفيذ Anycast IP ممكنًا، ننصحك بالبدائل الفعّالة من حيث التكلفة التالية لضمان أن يتلقّى المستخدمون الخدمة من أقرب مركز بيانات إقليمي.

1. موازنة الحمل الشاملة (GLB)

   بدلاً من التوجيه الثابت، استخدِم موازن حمل التطبيقات العالمية (المتاحة من معظم موفّري الخدمات السحابية الرئيسيين).

   • طريقة العمل: يمكنك ضبط نقطة دخول شاملة واحدة (عنوان URL) تقع على حافة الشبكة. يرصد موازن التحميل تلقائيًا المصدر الجغرافي للطلب من مجموعات التنفيذ في Google، ويوجه الزيارات إلى الخلفية السليمة الأقرب إليك على مستوى المنطقة.

   • الميزة: يوفّر ذلك أداءً أفضل لبروتوكول Anycast مع تقليل كبير في تعقيد التكوين والتكلفة.

2. نظام أسماء النطاقات الذي يرصد الموقع الجغرافي (GeoDNS)

   • طريقة العمل: اضبط مزوّد نظام أسماء النطاقات (DNS) للتعامل بشكل نهائي مع عنوان URL الخاص بتنفيذ الطلب إلى عناوين IP مختلفة استنادًا إلى الموقع الجغرافي لطلب بحث نظام أسماء النطاقات.

   • التنفيذ: تأكَّد من أنّ مزوّد نظام أسماء النطاقات (DNS) مُحسَّن لنقاط الخروج من Google. عندما تحلّ خدمات التنفيذ الإقليمية من Google (على سبيل المثال، في الولايات المتحدة أو الاتحاد الأوروبي أو آسيا) نطاقك، ستتلقّى عنوان IP لمركز البيانات في تلك المنطقة المحدّدة.

استراتيجيات التحسين على مستوى التطبيق

بالإضافة إلى التوجيه على مستوى البنية الأساسية، يمكنك تنفيذ الاستراتيجيات التالية على مستوى التطبيق لتقليل وقت الاستجابة عند معالجة الطلبات.

1. طريقة الخادم الوكيل "الترامبولين"

   إذا كان عليك الاحتفاظ بمركز بيانات أساسي، استخدِم خوادم وكيل إقليمية خفيفة الوزن (Trampolines) للتعامل مع المصافحة الأولية.

   1. يصل Google إلى عنوان URL العالمي.

   2. يتلقّى الطلب وكيل إقليمي (على سبيل المثال، دالة Nginx أو Lambda بسيطة).

   3. يعيد الخادم الوكيل توجيه الحمولة عبر شبكة أساسية داخلية عالية السرعة إلى قاعدة البيانات الأساسية.

   الميزة: يؤدي ذلك إلى تقليل وقت "المصافحة عبر بروتوكول TCP"، وهو غالبًا أكبر عامل يساهم في وقت الاستجابة للطلبات التي يتم إرسالها من مسافات بعيدة.

2. تلميحات منطقة رمز الدخول المميز

   أثناء عملية ربط الحساب (OAuth)، يمكن لنظامك تحديد المنطقة الرئيسية للمستخدم.

   التنفيذ: ترميز معرّف منطقة في access_token الذي تم إصداره إلى Google عندما ترسل Google طلب تنفيذ، يمكن لبوابة الدفع فحص الرمز المميّز على الفور وتوجيه الطلب إلى المجموعة الإقليمية الصحيحة بدون الحاجة إلى البحث في قاعدة البيانات.

سلامة النظام - مقاييس الشريك إلى Google

يساعد الحفاظ على معدّل نجاح أكبر من أو يساوي%99.5 في ضمان صحة حالات الأجهزة في Google Home، وإضافة الأجهزة وإزالتها، وتشغيل عمليات التشغيل الآلي، وظهور أحداث السجلّ في علامة التبويب "النشاط" في Google Home app (GHA).

يتم احتساب "معدّل النجاح" استنادًا إلى رموز استجابة HTTP التي تعرضها Google عند إرسال تحديثات الحالة من السحابة الإلكترونية. لضمان عدم معاقبة الشركاء على مشاكل البنية الأساسية من جهة Google، يستبعد المقياس الأخطاء الداخلية في Google من عدد الأخطاء. يمكن العثور على طلبات البيانات من واجهة برمجة التطبيقات المضمّنة في عملية الاحتساب في مرجع HomeGraph API.

ما الذي يحدّد حالة "نجاح"؟

‫2xx (تمت العملية بنجاح): تم تلقّي تعديل الحالة ومعالجته بنجاح من خلال Home Graph.

ما الذي يحدّد حالة "تعذُّر"؟

تمثّل رموز الخطأ 4xx (خطأ الشريك) حالات تعذّر وتشير إلى وجود مشكلة في الطلب المرسَل من السحابة الإلكترونية. تشمل الرموز الشائعة ما يلي:

‫400 طلب غير صالح

السبب: تعذّر على الخادم معالجة الطلب بسبب بنية غير صالحة. تشمل الأسباب الشائعة عدم صحة تنسيق JSON أو استخدام القيمة null بدلاً من "" لقيمة السلسلة.

الحل: تأكَّد من أنّ نص الطلب هو JSON صالح (بدون بنية غير صالحة أو قيم فارغة لحقول السلسلة)، وتأكَّد من أنّ agentUserId يتطابق مع القيمة من رد SYNC.

‫404 لم يتم العثور على الصفحة

السبب: لم يتم العثور على deviceId أو agentUserId في HomeGraph (لم تتم المزامنة بعد أو تم إلغاء الربط أو لا يتطابق المعرّف).

الحلّ:

1. تأكَّد من أنّ agentUserId تتطابق مع القيمة المقدَّمة في ردّ SYNC.
2. استخدِم Home Graph SYNC API لتحديد ما إذا كان الخطأ 404 Not Found ناتجًا عن جهاز أو مستخدم غير متوفّر في HomeGraph.
3. احرص على تشغيل requestSync بعد إضافة جهاز أو حساب أو إزالته أو إعادة تسميته أو تعديله لضمان بقاء الحالة محدّثة.
4. التعامل بشكل سليم مع أغراض DISCONNECT لإيقاف الإبلاغ عن الأجهزة القديمة بعد تلقّي الغرض DISCONNECT، على الخدمة السحابية التوقّف عن نشر التغييرات على Google باستخدام طلب المزامنة وإرسال الحالة.

‫429 Resource Exhausted

السبب: تجاوزت عملية الدمج الحصة المخصّصة لها.

الحلّ: اطّلِع على التعليمات في القسم "الخطوة 2أ: تصحيح أخطاء مشاكل الحصة" في لوحة البيانات لإدارة الحصة. يمكنك أيضًا الرجوع إلى حصص وحدود المنزل الذكي للحصول على مزيد من المعلومات.

سلامة الجهاز - دقة الحالة

يساعد استيفاء معيار دقة الحالة >=%99.5 أو تجاوزه في ضمان ظهور نتائج صحيحة للمستخدمين عند عرض حالات الأجهزة أو استخدام ميزات الذكاء الاصطناعي، مثل ميزة "اسأل Google Home". إذا كانت دقة الحالة منخفضة، قد لا يتم تشغيل عمليات التشغيل الآلي وقد لا تظهر إدخالات السجلّ في علامة التبويب "النشاط" الخاصة بـ GHA في الوقت المناسب. لمزيد من المعلومات، يُرجى الاطّلاع على Report State. يُرجى العِلم: يجب استيفاء معيار دقة الحالة في جميع السمات المتوافقة.

1. مكوّنات الدقة

يتم استخراج المقياس من "عينات" يمكن فيها لمحرّك بحث Google التحقّق من الحالة المُبلغ عنها مقارنةً بنتيجة معروفة للنية. للحصول على مقياس صحة النموذج الفنية، يتم تقييم الدقة على مسارين مختلفين:

• الدقة المستندة إلى طلب البحث: يتم التحقّق منها عندما يستفسر مستخدم أو نظام بشكل نشط عن الحالة الحالية لجهاز.
• الدقة المستندة إلى التنفيذ: يتم التحقّق منها من خلال تقييم حالة الجهاز بعد تنفيذ الأمر التي يتم إرسالها مرة أخرى بعد طلب التحكّم.

2. مقاييس لوحة البيانات (الاحتساب كل ساعة)

تحتسب لوحة البيانات الدقة استنادًا إلى فترة زمنية مدتها ساعة واحدة. لضمان الثقة الإحصائية وتجنُّب فرض عقوبات على عمليات الدمج التي تتضمّن تشويشًا منخفض الإشارة، تفرض Google حدًا أدنى لحجم الزيارات. إذا جمعت سمة وجهاز معيّنَين أقل من 100 عيّنة إجمالية خلال فترة 5 أيام متتالية، سيتم اعتبار دقتها غير مهمة إحصائيًا وسيتم ضبطها على غير متوفّرة.

عندما يتوفّر حجم عيّنات كافٍ خلال ساعة معيّنة في كلا المسارين، يتم احتساب دقة خط الأساس لكل ساعة في ولاية معيّنة كمتوسط للنسبتين المئويتين المستقلتين:

دقة الحالة كل ساعة = (دقة طلب البحث % + دقة التنفيذ %) / 2

يتم تعريف كل مسار على النحو التالي:

• نسبة دقة طلب البحث = (عينات طلب البحث الدقيقة كل ساعة) / (إجمالي عينات طلب البحث كل ساعة)
• نسبة دقة التنفيذ = (عينات التنفيذ الدقيقة كل ساعة) / (إجمالي عينات التنفيذ كل ساعة)

نتيجة دقة السمة (يتم احتسابها لكل سمة) = مجموع(العيّنات الدقيقة للاستعلام + العيّنات الدقيقة للتنفيذ) / مجموع(إجمالي عيّنات الاستعلام + إجمالي عيّنات التنفيذ)

بما أنّ "نتيجة الجودة" تقيِّم الحد الأدنى الصارم للأداء في جميع أنحاء نظامك المتكامل، يجب أن تستوفي كل سمة مؤهَّلة ومتاحة على حدة هدف "دقة الحالة" الذي يبلغ ‎99.5% أو أكثر (هذه النسبة ليست متوسطًا بين السمات).

يمنع هذا العرض الأجهزة ذات الحجم الكبير والتي تتمتّع بدقة ممتازة من إخفاء المشاكل المتعلّقة بالدقة على الأجهزة ذات الحجم المنخفض. يمكن للشركاء الذين يشعرون بالقلق من أنّ السمات غير المستخدَمة بشكل كافٍ ستؤدي إلى خفض نقاطهم أن يطمئنوا إلى أنّ السمات التي نادرًا ما يتم استخدامها تتم حمايتها تلقائيًا من خلال الحد الأدنى من فحص حجم الزيارات، ولن يتم احتسابها في أدنى نقاط للنوع والسمة ما لم تستوفِ الحد الأدنى المطلوب للعينة.

3- تحسين دقة حالة الجهاز وسلامته

تحدث التناقضات عندما لا تتطابق الحالة المخزّنة في &quot;رسم بياني للمنزل&quot; مع نتائج طلب بحث في الوقت الفعلي.

أخطاء "الحقل غير متوفر"

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD"
    deviceId: "curtain"
    deviceType: "action.devices.types.CURTAIN"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-13T12:20:26Z"
    queryReportStateDifferences: {
      queryState: "open_close    {
        open_percent: 0.0
        missing open_direction
      }"
      reportState: "open_close   {
        open_state {
          open_percent: 100.0
          open_direction: "LEFT"
        }
      }"
    }
    reportedTime: "2022-05-13T07:14:35Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T12:20:26Z"
    stateName: "open_state"
    traitName: "TRAIT_OPEN_CLOSE"
  }
  

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD"
    deviceId: "sensor"
    deviceType: "action.devices.types.SENSOR"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-28T10:40:33Z"
    queryReportStateDifferences: {
      queryState: "temperature_setting {
         thermostat_mode: "off"
         thermostat_temperature_ambient: 20.0
         active_thermostat_mode: "none"
      }"
      reportState: "temperature_setting {
         thermostat_mode: "off"
         active_thermostat_mode: "none"
      }"
    }
    reportedTime: "2024-09-20T15:00:00Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-28T10:40:33Z"
    stateName: "thermostat_temperature_ambient"
    traitName: "TRAIT_TEMPERATURE_SETTING"
  }
  

السبب: عند ظهور الخطأ DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD أو DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD، تختلف مجموعة حقول الحمولة بين ردّ QUERY وطلب Report State للجهاز نفسه.

الحلّ: تأكَّد من تطابق بنية البيانات في كلا المسارين. إذا تم تضمين سمة في SYNC، يجب أن تكون الحقول المقابلة لها متوفّرة ومتسقة في كل من التقارير الاستباقية وطلبات البحث التفاعلية.

أخطاء "غير دقيقة"

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_INACCURATE"
    deviceId: "outlet"
    deviceType: "action.devices.types.OUTLET"
    isMissingField: false
    isOffline: false
    queriedTime: "2026-04-12T16:02:58Z"
    queryReportStateDifferences: {
      queryState: "on_off    {
        on: false
      }"
      reportState: "on_off   {
        on: true
      }"
    }
    reportedTime: "2025-03-10T01:56:44Z"
    requestId: "abc"
    result: "INACCURATE"
    snapshotTime: "2026-04-12T16:02:58Z"
    stateName: "on"
    traitName: "TRAIT_ON_OFF"
  }
  

السبب: بالنسبة إلى الخطأ DETAILED_ACCURACY_RESULT_INACCURATE، هناك تفاوت بين القيمة المعروضة في استجابة QUERY وقيمة Report State الأخيرة.

الحلّ: تأكَّد من تفعيل Report State عند تغيير حالة الجهاز ومن أنّ Report State وQUERY يوفّران دائمًا القيم نفسها الحديثة وجميع الحقول المطلوبة للحفاظ على اتّساق البيانات.

"reportStateLog": {
   "isMissingField": false,
   "snapshotTime": "2026-04-13T07:56:21Z",
   "traitName": "TRAIT_ON_OFF",
   "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE",
   "executionReportStateDifferences": {
      "expectedPostExecutionDeviceState": {
         "onOff": {
         "on": false
         }
      },
      "preExecutionDeviceState": {
         "onOff": {
         "on": true
         }
      },
      "executionCommand": {
         "requestId": "test001",
         "beginTimestamp": "2026-04-13T07:56:20Z",
         "action": {
         "trait": "TRAIT_ON_OFF",
         "actionType": "ONOFF_OFF"
         },
         "status": {
         "statusType": "SUCCESS_STATUS"
         },
         "endTimestamp": "2026-04-13T07:56:21Z",
         "executionType": "PARTNER_CLOUD"
      },
      "reportState": {}
   },
   "accuracy": "MISSING_REPORT_STATE",
   "deviceType": "action.devices.types.LIGHT",
   "agentId": "abc",
   "stateName": "on",
   "result": "MISSING_REPORT_STATE"
   }
  

السبب: عند ظهور الخطأ DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE، يعني ذلك أنّ الشريك نفّذ الأمر بنجاح، ولكنّه لم يرسل حالة الجهاز المعدَّلة إلى Google.

الحل: أرسِل دائمًا تحديثًا لـ Report State بعد تنفيذ الأمر، لكي يتلقّى Home Graph حالة الجهاز الجديدة.

eportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED"
    deviceId: "switch"
    deviceType: "action.devices.types.SWITCH"
    isMissingField: false
    isOffline: true
    queriedTime: "2026-04-13T13:53:26Z"
    queryReportStateDifferences: {
      queryState: "online    {
        online: false
      }
      "
      reportState: ""
    }
    reportedTime: "1970-01-01T00:00:00Z"
    requestId: "test001"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T13:53:26Z"
    stateName: "online"
    traitName: "TRAIT_ONLINE"
   }
  

السبب: بالنسبة إلى الخطأ DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED، لم يتم تلقّي أي ReportState لهذا الجهاز (الحالة فارغة والطابع الزمني الذي تم الإبلاغ عنه هو epoch)، على الرغم من أنّ نتائج QUERY توفّر الحالة الحالية. يشير ذلك إلى أنّه لا يتم تشغيل تعديلات الحالة أو أنّها لا تصل إلى HomeGraph، أو أنّ الجهاز لا يبلغ بنجاح عن عمليات الانتقال في حالة الاتصال أو حالة التشغيل.

الحلّ: تأكَّد من تفعيل Report State وإرساله بنجاح عند حدوث جميع تغييرات الحالة. تأكَّد من أنّ منطق الخلفية يعالج تحديثات الحالة بشكل صحيح، ويؤكّد نجاح عملية التسليم إلى Google HomeGraph، ويضمن مزامنة الجهاز لحالته باستمرار للحفاظ على دقة واجهة المستخدم ومحرّك التشغيل الآلي.