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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يُعدّ وقت الاستجابة مؤشرًا مهمًا على مدى سرعة استجابة عملية الدمج للمستخدم النهائي. تتتبّع لوحة البيانات وقت الاستجابة عند الشريحة المئوية التسعين (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 لإيقاف الإبلاغ عن الأجهزة القديمة بعد تلقّي Intent DISCONNECT، يجب أن تتوقف خدمتك السحابية عن نشر التغييرات إلى Google باستخدام طلب المزامنة وإبلاغ الحالة.

‫429 Resource Exhausted

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

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

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

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

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

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

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

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، لم يتم تلقّي أي Report State لهذا الجهاز (الحالة فارغة والطابع الزمني الذي تم الإبلاغ عنه هو epoch)، على الرغم من أنّ نتائج QUERY توفّر الحالة الحالية. يشير ذلك إلى أنّه لا يتم تشغيل تحديثات الحالة أو أنّها لا تصل إلى HomeGraph أو أنّ الجهاز لا يبلغ بنجاح عن عمليات الانتقال في حالة الاتصال أو حالة التشغيل.

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