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 في الوقت المناسب. لمزيد من المعلومات، يُرجى الاطّلاع على حالة التقرير.

تتتبّع لوحة بيانات الجودة هذه البيانات كل ساعة باستخدام مقياسَين مختلفَين: الدقة الإجمالية وأدنى مجموعة من الأنواع/السمات.

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

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

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

تحتسب لوحة البيانات الدقة استنادًا إلى فترة زمنية مدتها ساعة واحدة. إذا كان عدد العيّنات الإجمالي في الساعة أقل من 100 عيّنة (S_Total < 100)، يتم ضبط دقة تلك الساعة على غير متوفّرة.

طريقة العرض 1: الدقة الإجمالية (المتوسط العالمي)

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

• طريقة الاحتساب: إجمالي دقة الحالة على جميع الأجهزة / إجمالي عدد الحالات على جميع الأجهزة

طريقة العرض 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، ويضمن مزامنة الجهاز لحالته باستمرار للحفاظ على دقة واجهة المستخدم ومحرّك التشغيل الآلي.