این مجموعه داشبوردها و هشدارها به شما کمک میکند تا به طور فعال، یکپارچگی با کیفیت بالا را با اکوسیستم گوگل هوم حفظ کنید. گوگل متعهد به حمایت از شرکا در توسعه یک اکوسیستم با کیفیت بالا برای همه مشتریان است.
این داشبورد سه بخش دارد که هر کدام یک بخش کلیدی را پوشش میدهند که به کیفیت یکپارچهسازی کلی کمک میکند.
معیارهای گوگل برای شرکا - سلامت تماسها از گوگل به بکاند ابری شما را اندازهگیری میکند.
سلامت سیستم - شریک Google Metrics - سلامت تماسهای سیستم شما به گوگل را اندازهگیری میکند.
سلامت دستگاه - دقت وضعیت - دقت وضعیتهای ذخیره شده در سیستمهای گوگل را که برای ارائه درخواستهای کاربران استفاده میشوند، اندازهگیری میکند.
وقتی معیارها به مقادیر هدف خود نمیرسند، با رنگ قرمز برجسته میشوند تا مشکلی را که میتواند بر تجربه کاربر تأثیر بگذارد، نشان دهند. اطلاعات زیر جزئیاتی در مورد هر هدف و دلیل اهمیت آن برای کاربران شما ارائه میدهد.
اگر دکمه زیر شما را مستقیماً به داشبورد هدایت نکرد، میتوانید با انتخاب صفحه مرور کلی ، انتخاب داشبوردها و سپس از لیست داشبوردهای من، داشبورد Google Home Vitals (Cloud) را برای مشاهده داشبورد خود انتخاب کنید.
معیارهای همکاری گوگل
معیار « نرخ موفقیت پرسوجو/اجرا >= 99.5%» میزان موفقیت اجرای صحیح دستورات کاربران را اندازهگیری میکند، که به جلوگیری از پاسخهای دستیار مانند «من نمیتوانم به دستگاه دسترسی پیدا کنم» یا تأیید نادرست دستوری که اجرا نشده است، کمک میکند.
چه چیزی «موفقیت» را تعریف میکند؟
اگر پلتفرم گوگل هوم پاسخ معتبری دریافت کند که نشان دهد اقدام مورد نظر انجام شده یا وضعیت درخواستی بازیابی شده است، یک تراکنش به عنوان موفقیتآمیز علامتگذاری میشود.
پاسخهایی که شامل استثنائات غیر مسدودکننده هستند (برای مثال، وضعیت SUCCESS همراه با استثنای lowBattery ) به عنوان تراکنشهای موفق شمرده میشوند. دستور به دستگاه رسیده و هدف با وجود هشدار برآورده شده است.
چه چیزی «شکست» را تعریف میکند؟
خطاهای موجود در کدهای خطای پلتفرم مشترک که به عنوان Partner Actionable علامتگذاری شدهاند، هنگام محاسبه نرخ موفقیت QUERY و EXECUTE به عنوان "خطا" در نظر گرفته میشوند. علاوه بر این، خطاهای موجود در Errors و Exceptions نیز به جز موارد استثنای زیر، "خطا" محسوب میشوند:
| استثنائات شکست | ||
|---|---|---|
| مدت زمان حداکثر اثرات نور | armLevelNeeded | حالت خاموش |
| از قبل مسلح | کیسه پر | lockToRange |
| قبلاًAtMax | حداقل مدت زمان اثرات نوری | باتری کم |
| قبلاًAtMin | بنپر | حداکثر سرعت رسیده |
| قبلاًبسته شده | لغومسلح کردنمحدود شده | حداقل سرعت رسیده |
| از قبل خلع سلاح شده | باتری مرده | پشتیبانی نمیشود |
| قبلاً متصل شده است | درجهخارج از محدوده | آفلاین |
| قبلاًInState | اختلال در دستگاه شناسایی شد | درصد خارج از محدوده |
| قبلاً قفل شده است | دستگاه نصب نشده | محدوده خیلی نزدیک |
| قبلاً خاموش | دستگاه آماده نیست | پیوند مجددالزامی |
| از قبل روشن | دستگاهآفلاین | remoteSetDisabled |
| از قبل باز است | دستگاه خاموش | ایمنیخاموش کردن |
| قبلاًمتوقف شده | فقط گسستهباز کردنبستن | هدف قبلاً رسیده است |
| از قبل شروع شده | تابع پشتیبانی نمیشود | تلاشهای ناموفق زیادی |
| قبلاً متوقف شده است | در حالت خودکار | مقدارخارج از محدوده |
| قبلاً باز شده | inEcoMode |
معیار تأخیر درخواست/اجرا (p90) <= 1000ms ، زمان انتظار برای اقدام درخواستی را اندازهگیری میکند و به کاربران کمک میکند تا مدت زمان زیادی منتظر نمانند، مثلاً چند ثانیه برای خاموش شدن چراغ خود منتظر نمانند.
معیارهای تأخیر
تأخیر، شاخص مهمی از میزان پاسخگویی یکپارچهسازی شما به کاربر نهایی است. داشبورد، تأخیر صدک نودم (P90) را ردیابی میکند که نشان دهنده تجربه "کندترین" کاربران شما است (برای مثال، P90 برابر با ۸۰۰ میلیثانیه به این معنی است که ۹۰٪ درخواستها در ۸۰۰ میلیثانیه یا کمتر پاسخ داده میشوند).
گوگل برای اطمینان از دقت فنی، میزان تأخیر را برای بررسی وضعیت در مقایسه با دستورات دستگاه، به طور متفاوتی اندازهگیری میکند.
۱. تأخیر پرسوجو (پرسشی)
این مقدار Cloud-to-cloud را زمانی که گوگل وضعیت فعلی دستگاه را درخواست میکند، اندازهگیری میکند.
- شروع: گوگل یک درخواست
action.devices.QUERYرا به آدرس اینترنتی (URL) تکمیل درخواست شما ارسال میکند. - بازه اندازهگیری: مدت زمانی که طول میکشد تا ابر شما پاسخ کامل HTTP را دریافت، پردازش و به گوگل ارسال کند.
- پایان: گوگل آخرین بارِ پاسخ را از سرویس شما دریافت و تأیید میکند.
۲. اجرای تأخیر (عمل)
این، زمان تأیید فرمان را هنگامی که گوگل یک درخواست کنترل به یک دستگاه ارسال میکند، اندازهگیری میکند.
- شروع: گوگل یک درخواست
action.devices.EXECUTEرا به URL تکمیل سفارش شما ارسال میکند. - پنجره اندازهگیری: مدت زمانی که طول میکشد تا فضای ابری شما دستور را دریافت کرده و پاسخ تأیید را برگرداند.
- پایان: گوگل پاسخ وضعیت
SUCCESS،PENDINGیاOFFLINEرا دریافت میکند. - محدوده فنی: این معیار، زمان «پاسخ تأیید» (Response Ack) بین ابر گوگل و ابر شما را اندازهگیری میکند. این معیار، مدت زمانی را که طول میکشد تا سختافزار فیزیکی (مثلاً یک لامپ) تغییر حالت فیزیکی را تکمیل کند، اندازهگیری نمیکند، زیرا این امر اغلب شامل تأخیر شبکه مش محلی در خارج از مسیر ابر به ابر میشود.
گزینههای کاهش تأخیر
توصیههای معماری برای مسیریابی جغرافیایی
اگر پیادهسازی Anycast IP امکانپذیر نباشد، گزینههای مقرونبهصرفه زیر را توصیه میکنیم تا اطمینان حاصل شود که کاربران توسط نزدیکترین مرکز داده منطقهای سرویسدهی میشوند.
متعادلسازی بار سراسری (GLB)
به جای مسیریابی ایستا، از یک متعادلکننده بار سراسری برنامه (که از اکثر ارائهدهندگان اصلی ابر موجود است) استفاده کنید.
نحوه کار: شما یک نقطه ورود سراسری (URL) را که در لبه شبکه قرار میگیرد، پیکربندی میکنید. متعادلکننده بار به طور خودکار منشأ جغرافیایی درخواست را از خوشههای تکمیل گوگل تشخیص میدهد و ترافیک را به نزدیکترین backend سالم منطقهای شما هدایت میکند.
مزیت: این امر عملکرد Anycast را با پیچیدگی پیکربندی و هزینه بسیار پایینتری فراهم میکند.
DNS آگاه از موقعیت جغرافیایی (GeoDNS)
نحوه کار: ارائه دهنده DNS خود را پیکربندی کنید تا URL تکمیل درخواست شما را بر اساس موقعیت جغرافیایی درخواست DNS به آدرسهای IP مختلف تبدیل کند.
پیادهسازی: اطمینان حاصل کنید که ارائهدهنده DNS شما برای نقاط خروجی گوگل بهینه شده است. هنگامی که سرویسهای منطقهای گوگل (به عنوان مثال، در ایالات متحده، اتحادیه اروپا یا آسیا) دامنه شما را حل و فصل میکنند، آدرس IP مربوط به مرکز داده در آن منطقه خاص را دریافت خواهند کرد.
استراتژیهای بهینهسازی در لایه کاربرد
فراتر از مسیریابی در سطح زیرساخت، میتوانید استراتژیهای زیر را در لایه برنامه پیادهسازی کنید تا تأخیر در پردازش درخواست را کاهش دهید.
روش پروکسی "ترامپولین"
اگر باید یک مرکز داده اصلی را نگهداری کنید، از سرورهای پروکسی سبک منطقهای (ترامپولینها) برای مدیریت handshake اولیه استفاده کنید.
گوگل به آدرس اینترنتی جهانی شما برخورد میکند.
یک پروکسی منطقهای (برای مثال، یک تابع سبک Nginx یا Lambda) درخواست را دریافت میکند.
پروکسی، بار داده را از طریق شبکه داخلی و پرسرعت شما به پایگاه داده اصلی ارسال میکند.
مزیت: این کار زمان "TCP Handshake" را کاهش میدهد، که اغلب بزرگترین عامل تأخیر در درخواستهای راه دور است.
نکات مربوط به منطقه توکن دسترسی
در طول فرآیند اتصال حساب کاربری (OAuth)، سیستم شما میتواند منطقهی سکونت کاربر را شناسایی کند.
پیادهسازی: یک شناسه منطقه را در
access_tokenصادر شده به گوگل کدگذاری کنید. هنگامی که گوگل یک درخواست تکمیل ارسال میکند، دروازه شما میتواند بلافاصله توکن را بررسی کرده و درخواست را بدون نیاز به جستجوی پایگاه داده به خوشه منطقهای صحیح هدایت کند.
سلامت سیستم - شریک معیارهای گوگل
حفظ نرخ موفقیت >= 99.5% به شما کمک میکند تا از صحت وضعیت دستگاهها در Google Home، اضافه و حذف شدن دستگاهها، فعال شدن اتوماسیونها و نمایش رویدادهای تاریخچه در تب فعالیت Google Home app (GHA) اطمینان حاصل کنید.
نرخ موفقیت بر اساس کدهای پاسخ HTTP که توسط گوگل هنگام ارسال بهروزرسانیهای وضعیت توسط ابر شما بازگردانده میشود، محاسبه میشود. برای اطمینان از اینکه شرکا به دلیل مشکلات زیرساختی سمت گوگل جریمه نشوند، این معیار خطاهای داخلی گوگل را از تعداد شکستها حذف میکند. فراخوانیهای API که در محاسبه لحاظ شدهاند، در مرجع API HomeGraph یافت میشوند.
چه چیزی «موفقیت» را تعریف میکند؟
2xx (موفق): بهروزرسانی وضعیت با موفقیت دریافت و توسط Home Graph پردازش شد.
چه چیزی «شکست» را تعریف میکند؟
4xx (خطای همکار) نشاندهندهی خطاها و مشکلاتی در درخواست ارسالی از فضای ابری شما است. کدهای رایج عبارتند از:
درخواست بد ۴۰۰
علت: سرور به دلیل سینتکس نامعتبر قادر به پردازش درخواست نبود. دلایل رایج شامل JSON ناقص یا استفاده از null به جای "" برای یک مقدار رشتهای است.
راه حل: مطمئن شوید که بدنه درخواست از نوع JSON معتبر است (ساختار ناقص یا مقادیر تهی برای فیلدهای رشتهای وجود ندارد) و تأیید کنید که agentUserId با مقدار پاسخ SYNC مطابقت دارد.
۴۰۴ یافت نشد
علت: deviceId یا agentUserId در HomeGraph یافت نشد (هنوز همگامسازی نشده، از قبل لینک آن جدا شده، یا عدم تطابق شناسه).
راه حل:
- مطمئن شوید که
agentUserIdبا مقدار ارائه شده در پاسخ SYNC شما مطابقت دارد. - از API همگامسازی صفحه اصلی گراف (Home Graph SYNC API) برای تعیین اینکه آیا خطای ۴۰۴ «یافت نشد» (404 Not Found) ناشی از گم شدن دستگاه یا کاربر در صفحه اصلی گراف (HomeGraph) است یا خیر، استفاده کنید.
- مطمئن شوید که
requestSyncپس از افزودن، حذف، تغییر نام یا بهروزرسانی دستگاه یا حساب کاربری فعال میکنید تا از بهروز ماندن وضعیت اطمینان حاصل شود. - برای جلوگیری از گزارش دستگاههای قدیمی، به درستی از Intentهای
DISCONNECTاستفاده کنید. پس از دریافت IntentDISCONNECT، سرویس ابری شما باید با Request Sync و Report State، انتشار تغییرات در گوگل را متوقف کند.
۴۲۹ منابع تمام شده
دلیل: ادغام شما از سهمیه اختصاص داده شده خود فراتر رفته است.
راه حل: برای مدیریت سهمیه، به دستورالعملهای بخش «مرحله ۲الف: رفع مشکلات سهمیه» در داشبورد مراجعه کنید. همچنین میتوانید برای اطلاعات بیشتر به سهمیهها و محدودیتهای خانه هوشمند مراجعه کنید.
سلامت دستگاه - دقت وضعیت
رسیدن به دقت وضعیت >= 99.5% یا فراتر رفتن از آن، به کاربران کمک میکند تا هنگام مشاهده وضعیت دستگاه یا استفاده از ویژگیهای هوش مصنوعی مانند «از خانه بپرس» نتایج صحیحی را مشاهده کنند. اگر دقت وضعیت پایین باشد، ممکن است اتوماسیونها فعال نشوند و ورودیهای تاریخچه در زمان مناسب در برگه فعالیت GHA ظاهر نشوند. برای اطلاعات بیشتر، به «گزارش وضعیت» مراجعه کنید.
داشبورد کیفیت، این موضوع را به صورت ساعتی با استفاده از دو معیار مجزا پیگیری میکند: دقت کلی و کمترین نوع/ویژگی ترکیبی .
۱. اجزای دقت
این معیار از «نمونههایی» گرفته شده است که در آنها گوگل میتواند وضعیت گزارششده را در برابر یک نتیجهی هدف شناختهشده تأیید کند.
۲. معیارهای داشبورد (محاسبه ساعتی)
داشبورد دقت را بر اساس یک بازه ۱ ساعته محاسبه میکند. اگر یک ساعت کمتر از ۱۰۰ نمونه کلی داشته باشد (S_Total < 100)، دقت آن ساعت روی N/A تنظیم میشود.
نمای ۱: دقت کلی (میانگین جهانی)
این نشان دهنده دقت کلی ادغام شما در تمام انواع دستگاهها و ویژگیهای ترکیبی است. این یک میانگین وزنی از سلامت کل اکوسیستم شما را ارائه میدهد.
- محاسبه : دقت کل حالت در تمام دستگاهها / مجموع کل حالت در تمام دستگاهها.
نمای ۲: پایینترین ترکیب نوع/صفت
این، غیرقابل اعتمادترین دسته خاص در یکپارچهسازی شما را شناسایی میکند. این کار مانع از آن میشود که دستگاههای با حجم بالا که کیفیت بالایی دارند، دستگاههای با حجم پایین که کیفیت پایینی دارند را پنهان کنند. به عنوان مثال، اگر حجم بالایی از چراغها با دقت حالت بالای ۹۹.۵٪ دارید، اما حجم کمی از سوئیچها با دقت حالت پایین دارید، این امر بهبود مورد نیاز در سوئیچهایی را که ممکن است در مقدار متوسط از دست بروند، برجسته میکند.
- محاسبه : حداقل دقت حالت / مجموع حالت برای همه ترکیبات ویژگی/دستگاه.
۳. بهبود دقت سلامت و وضعیت دستگاه
اختلافات زمانی رخ میدهند که وضعیت ذخیره شده در نمودار خانه با نتایج یک پرس و جوی (QUERY) در زمان واقعی مطابقت نداشته باشد.
خطاهای "فیلد گمشده"
مثال DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD
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" }
مثال DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD
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 ، مجموعه فیلدهای payload بین پاسخ QUERY و درخواست Report State شما برای همان دستگاه متفاوت است.
راه حل: اطمینان حاصل کنید که ساختار داده در هر دو مسیر یکسان است. اگر یک ویژگی در SYNC گنجانده شده است، فیلدهای مربوط به آن باید هم در گزارشهای پیشگیرانه و هم در پرسوجوهای واکنشی وجود داشته و سازگار باشند.
خطاهای «نادرست»
مثال DETAILED_ACCURACY_RESULT_INACURATE
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 همیشه مقادیر دقیقاً یکسان و بهروز و تمام فیلدهای مورد نیاز را برای حفظ ثبات دادهها ارائه میدهند.
مثال DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE
"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 ، شریک دستور را با موفقیت اجرا کرد، اما وضعیت دستگاه بهروزرسانیشده را به گوگل گزارش نداد.
راه حل: همیشه بعد از اجرای دستور، یک بهروزرسانی Report State ارسال کنید تا Home Graph وضعیت جدید دستگاه را دریافت کند.
مثال DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED
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 ، هیچ گزارشی از وضعیت برای این دستگاه دریافت نشده است (وضعیت خالی است و مهر زمانی گزارش شده در epoch است)، با وجود اینکه نتایج QUERY وضعیت فعلی را ارائه میدهد. این نشان میدهد که بهروزرسانیهای وضعیت یا فعال نمیشوند، یا به HomeGraph نمیرسند، یا دستگاه با موفقیت گذارها را در اتصال یا وضعیت عملیاتی خود گزارش نمیدهد.
راه حل: اطمینان حاصل کنید که گزارش وضعیت (Report State) برای همه تغییرات وضعیت فعال شده و با موفقیت ارسال میشود. تأیید کنید که منطق backend به درستی بهروزرسانیهای وضعیت را مدیریت میکند، موفقیت تحویل به Google HomeGraph را تأیید میکند و اطمینان حاصل میکند که دستگاه به طور مداوم وضعیت خود را همگامسازی میکند تا رابط کاربری و موتور اتوماسیون دقیق باقی بمانند.