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) كمعاملات ناجحة. وصل الأمر إلى الجهاز وتمت تلبية الغرض منه على الرغم من التحذير.

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

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

يقيس المقياس وقت استجابة طلبات البحث/التنفيذ (النسبة المئوية الـ 90) ≤ 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 غير سليم أو استخدام القيمة null بدلاً من "" لقيمة السلسلة.

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