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

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

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

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

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

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

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

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

الانتقال إلى لوحة التحكم

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

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

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

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

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

ما الذي يحدد "الفشل"؟

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

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

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

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

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

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

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

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

2. وقت استجابة التنفيذ (الإجراء)

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

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

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

اقتراحات معمارية للتوجيه الجغرافي

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

1. موازنة الحمل على المستوى العالمي (GLB)

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

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

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

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

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

   • التنفيذ: تأكَّد من أنّ "مزوّد نظام أسماء النطاقات" (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 غير سليم أو استخدام قيمة فارغة بدلًا من "" لقيمة السلسلة.

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

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

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

الحلّ:

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

429 تم استنفاد المورد

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

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

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

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

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

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

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

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

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

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

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

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

العرض 2: أقل مجموعة من النوع/السمة

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

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

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

تحدث الاختلافات عندما لا تتطابق الحالة المخزّنة في Home Graph مع نتائج طلب `QUERY` في الوقت الفعلي.

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

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` وطلب "الإبلاغ عن الحالة" للجهاز نفسه.

الحلّ: تأكَّد من أنّ بنية البيانات متطابقة في كلا المسارَين. إذا تم تضمين سمة في 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` وآخر قيمة لطلب "الإبلاغ عن الحالة".

الحلّ: تأكَّد من تفعيل "الإبلاغ عن الحالة" كلما تغيّرت حالة الجهاز وأنّ كلًا من "الإبلاغ عن الحالة" و`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.

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

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