Google Cloud ابزارهایی را برای نظارت بر قابلیت اطمینان پروژه‌هایتان با Google Cloud Monitoring و اشکال‌زدایی مشکلات با Google Cloud Logging گزارش‌های خطا دراختیارتان قرار می‌دهد. هرگاه در برآورده کردن قصد کاربر خطایی رخ دهد، خط لوله Google Home Analytics آن خطا را در سنجه‌های شما ثبت می‌کند و گزارش خطایی در گزارش‌های پروژه‌تان منتشر می‌کند.
دو مرحله برای عیب‌یابی خطاهایتان وجود دارد:
- وضعیت پروژه‌هایتان را با سنجه‌های خانه هوشمند پایش کنید.
- با بررسی شرح دقیق خطاها در گزارش‌های خطا، مشکلات را بررسی کنید.
درصورت تمایل، می‌توانید «کنش» خود را با هم‌رسانی آن با کاربران دیگر آزمایش کنید. مطمئن شوید خطاها و استثناها را به‌درستی مدیریت می‌کنید.
خطاهای پایش
می‌توانید از Google Cloud Monitoring dashboards برای دسترسی به سنجه‌های پروژه‌تان استفاده کنید. چند نمودار کلیدی وجود دارد که به‌ویژه برای نظارت بر کیفیت و اشکال‌زدایی مفید هستند:
- نمودار نرخ موفقیت اولین نموداری است که هنگام پایش قابلیت اطمینان پروژه‌هایتان باید از آن شروع کنید. افت در این نمودار می‌تواند نشان‌دهنده قطعی برای بخشی یا کل پایگاه کاربر شما باشد. توصیه می‌کنیم پس‌از هر تغییر یا به‌روزرسانی در پروژه‌تان، این نمودار را به‌دقت برای هرگونه بی‌قاعدگی نظارت کنید.
- نمودار تأخیر صدک ۹۵ شاخص مهمی برای نحوه عملکرد ادغام Cloud-to-cloud برای کاربران شما است. نوسانات ناگهانی در این نمودار ممکن است نشان‌دهنده این باشد که سیستم‌های شما نمی‌توانند با درخواست‌ها همگام شوند. توصیه می‌شود این نمودار را به‌طور دوره‌ای بررسی کنید تا هرگونه رفتار غیرمنتظره را ببینید.
- نمودارهای تفکیک خطا برای عیب‌یابی مشکلات ادغام‌هایتان بسیار مفید هستند. برای هر خطایی که در نمودار درصد موفقیت شما برجسته شده است، یک کد خطا در تفکیک خطای شما نمایش داده می‌شود. می‌توانید خطاهای پرچم‌گذاری‌شده توسط Google Home platform (GHP) و نحوه عیب‌یابی آن‌ها را در جدول زیر ببینید.
کدهای خطای رایج پلاتفرم
در اینجا برخی‌از کدهای خطای رایج که ممکن است در گزارش‌های پروژه خود ببینید آورده شده است تا مشکلات شناسایی‌شده توسط GHP را تشخیص دهید. برای اطلاعات عیب‌یابی، به جدول زیر مراجعه کنید. برای مشاهده فهرست کامل کدهای خطا، خطاها و استثناها را ببینید.
| کد خطا | شرح | قابل‌اجرا توسط شریک |
|---|---|---|
AGENT_ISSUE |
مشکلی کلی در عامل ابری شریک رخ داد.
گزارش‌های اجرای خود را برای یافتن استثناهای مدیریت‌نشده یا ازکارافتادگی‌ها بررسی کنید. |
بله |
AGENT_UNAVAILABLE_ERROR |
Google نتوانست به نشانی وب اجرای شریک دسترسی پیدا کند.
مطمئن شوید سرورتان آنلاین است، دیوار آتش Google را مسدود نمی‌کند، و نشانی وب درست است. |
بله |
COMMAND_FAILED |
هنگام اجرای فرمان، خطای عمومی رخ داد.
گزارش‌های اجرای خود را برای requestId خاص بررسی کنید
تا علت ریشه‌ای را پیدا کنید.
|
بله |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google خطای HTTP 4xx (به‌جز 401) از اجرای شما دریافت کرد.
گزارش‌های سرور وب خود را برای پاسخ‌های ۴۰۳، ۴۰۴، یا ۴۰۰ بررسی کنید. |
بله |
EXECUTION_BACKEND_FAILURE_URL_TIMEOUT |
مهلت زمانی درخواست Google هنگام تلاش برای دسترسی به سرویس شما به‌پایان رسید.
بررسی کنید که سرویس شما آنلاین باشد، اتصال‌ها را بپذیرد، و بیش‌از ظرفیت نباشد. علاوه‌براین، مطمئن شوید دستگاه هدف روشن، آنلاین، و همگام‌سازی شده باشد. |
بله |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
نشانی وب تحقق هدف توسط robots.txt یا فیلترهای امنیتی مسدود شده است.
مطمئن شوید نقطه پایانی برآورده‌سازی شما برای خزنده‌ها/سرویس‌های Google قابل‌دسترسی باشد. |
بله |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google خطای HTTP 5xx از سرویس اجرای شما دریافت کرد.
مطمئن شوید سرویس نشانی وب نقطه پایان پایدار، صحیح، و به‌طور عمومی قابل‌دسترس باشد و سرویس درحال اجرا باشد. از requestId در
Google Cloud Logging برای بررسی گزارش‌های سرویس خانه هوشمندتان استفاده کنید.
بررسی‌های سلامت و مدیریت تکرار مجدد را اضافه کنید.
خرابی‌های سرور، پایان مهلت زمانی، یا خطاهای دروازه ۵۰۲/۵۰۳ را بررسی کنید.
|
بله |
EXECUTION_BAILOUT_INVALID_RESPONSE |
پاسخ JSON آنقدر بدشکل بود که پردازش لغو شد.
از اعتبارسنج JSON استفاده کنید تا مطمئن شوید پاسختان دقیقاً از طرحوارههای «هدف» پیروی می‌کند. |
بله |
EXECUTION_GAL_BAD_3P_RESPONSE |
پیوند دادن حساب به‌دلیل قالب نامعتبر در پاسخ کد انجام نشد.
تأیید کنید که قالب پاسخ سرور OAuth شما با الزامات Google مطابقت دارد. |
بله |
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES |
حساب کاربر اجازه‌های لازم برای این کنش را ندارد.
دامنه‌های درخواست‌شده درطول OAuth را بررسی کنید و مطمئن شوید با ویژگی‌های لازم مطابقت داشته باشند. |
بله |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P |
ابر شریک نشان می‌دهد که کاربر پیوند حسابش را لغو کرده است.
مطمئن شوید نگاشت agentUserId پایدار است و
پاک‌سازی نشده است.
|
بله |
EXECUTION_GAL_NOT_FOUND |
ژتون‌های بازآوری و دسترسی کاربر که در Google ذخیره شده‌اند نامعتبر هستند یا
نمی‌توانند بازآوری شوند، که این امر مانع از اصالت‌سنجی و دسترسی به
سرویس شریک می‌شود.
مطمئن شوید که توکن‌ها معتبر و همگام‌سازی‌شده باقی می‌مانند، تغییرات وضعیت حساب را به‌درستی مدیریت کنید، و اگر لغو شدن توکن‌ها تأیید شد، از کاربران بخواهید حساب را دوباره پیوند دهند. |
|
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P |
ادغام در سمت شریک در وضعیت محدود به خواندن است.
بررسی کنید که آیا حساب کاربر تعلیق شده است یا در حالت نگهداری «فقط مشاهده» است. |
بله |
EXECUTION_GAL_UNLINKED_BY_3P |
سرویس شخص ثالث به‌طور پیش‌گیرانه پیوند حساب را لغو کرده است.
دلیل قطع شدن اتصال کاربر را بررسی کنید (برای مثال، بازنشانی امنیتی). مطمئن شوید سرور OAuth شریک به‌درستی به درخواست‌های refresh_token Google برای صدور کد دسترسی جدید پاسخ می‌دهد.
|
بله |
EXECUTION_INVALID_JSON |
Google نتوانست بار داده پاسخ JSON را تجزیه کند.
پاسختان را ازنظر خطاهای نحوی، کروشه‌های جاافتاده، یا نویسه‌های نامعتبر بررسی کنید. |
بله |
INVALID_AUTH_TOKEN |
Google کد خطای HTTP 401 را از سرویس شما دریافت کرده است.
کد دسترسی منقضی نشده است اما سرویس شما آن را نامعتبر کرده است. از requestId در Google Cloud Logging برای بررسی گزارش‌های سرویس خانه هوشمندتان استفاده کنید.
|
|
INVALID_JSON |
ساختار پاسخ نامعتبر است (برای مثال، فیلدهای اجباری وجود ندارد).
پاسختان را با طرحوارههای JSON قصد اعتبارسنجی کنید. |
بله |
MALFORMED_JSON |
ساختار JSON خراب است (برای مثال، رشته‌ها یا اشیاء بسته نشده‌اند).
مطمئن شوید که تحقق شما از کتابخانه JSON استاندارد برای سریال‌سازی پاسخ‌ها استفاده می‌کند. |
بله |
NOT_IMPLEMENTED |
قصد یا ویژگی درخواست‌شده توسط شریک اجرا نشده است.
فقط ویژگی‌هایی را در پاسخ SYNC خود بگنجانید که
به‌طور کامل پیاده‌سازی کرده‌اید.
|
بله |
OPEN_AUTH_FAILURE |
کد دسترسی کاربر منقضی شده است و Google نمی‌تواند آن را بازآوری کند،
یا Google کد خطای HTTP 401 را از سرویس شما دریافت کرده است.
اگر نرخ این کد افزایش یافته است، بررسی کنید که آیا نرخ خطاهای مربوط به هدف‌های خانه هوشمند یا درخواست‌های ژتون بازآوری نیز افزایش یافته است یا نه. |
|
PARTNER_RESPONSE_INVALID_ERROR_CODE |
رشته errorCode برگردانده‌شده در فهرست پشتیبانی‌شده Google نیست.
خطاهای داخلی‌تان را به فهرست رسمی خطا نگاشت کنید. |
بله |
PARTNER_RESPONSE_INVALID_PAYLOAD |
فیلد payload در پاسخ، شیء JSON معتبری نیست.
ساختار ریشه پاسخ برآورده‌سازی را درستی‌سنجی کنید. |
بله |
PARTNER_RESPONSE_INVALID_STATUS |
پاسخ status «موفقیت»، «خطا»، یا «آفلاین» نبود.
مطمئن شوید هر نتیجه دستگاه در پاسخ شما شامل رشته وضعیت معتبری باشد. |
بله |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
پاسخ شامل نتایج برای همه فرمان‌ها/دستگاه‌های درخواست‌شده نبود.
ساختار پاسخ خود را با مستندات توسعه‌دهنده Google Home اعتبارسنجی کنید. مطمئن شوید که پاسخ به‌دلیل خطای سرور داخلی کوتاه نشده باشد یا بدنه خالی برنگرداند. هر مورد در آرایه commands درخواست باید ورودی پاسخ
متناظر داشته باشد.
|
بله |
PARTNER_RESPONSE_MISSING_DEVICE |
دستگاه خاصی که Google درخواست کرده بود از پاسخ حذف شد.
مطمئن شوید که پاسخ شما شامل همه ID ارائه‌شده در
بار داده درخواست باشد.
|
بله |
PARTNER_RESPONSE_MISSING_PAYLOAD |
فیلد اجباری payload در پاسخ وجود ندارد.
مطمئن شوید شیء JSON سطح بالای شما شامل کلید payload باشد.
|
بله |
PARTNER_RESPONSE_NOT_OBJECT |
کل پاسخ به‌عنوان شیء JSON تجزیه نشد.
نویسه‌های دنباله‌دار یا محتوای غیرJSON را در بدنه پاسخ HTTP بررسی کنید. مطمئن شوید payload.commands[] شیء JSON مناسبی
با شناسه‌ها، وضعیت، و حالت‌های اختیاری باشد.
|
بله |
REQUEST_ID_NOT_FOUND |
Google نتوانست شناسه پیگیری داخلی را برای این درخواست پیدا کند.
معمولاً خطای پلاتفرم داخلی است؛ برای جهش‌ها نظارت کنید و با پشتیبانی تماس بگیرید. |
بله |
RESOURCE_UNAVAILABLE |
منبع درخواستی (دستگاه یا ویژگی) دردسترس نیست.
بررسی کنید دستگاه «مشغول» یا موقتاً غیرفعال شده است یا نه. |
بله |
RESPONSE_TIMEOUT |
سرویس انجام سفارش نتوانست ظرف ۹ ثانیه پاسخ دهد.
تأخیر زیرینه را بهینه‌سازی کنید؛ پُرسمان‌های پایگاه داده کند یا تأخیر شبکه منطقه‌ای را بررسی کنید. |
بله |
RESPONSE_UNAVAILABLE |
پاسخی از نشانی وب اجرای شریک دریافت نشد.
مطمئن شوید سرویس شما درحال اجرا است و نقطه پایانی ازکار نمی‌افتد. |
بله |
TIMEOUT |
هنگام پردازش قصد، زمان پایان یافت.
گزارش‌های مربوط به وقفه زمانی سرویس داخلی بین فضای ابری و هاب‌های دستگاه را بررسی کنید. |
بله |
گزارش‌های جستجو
وقتی با نظارت بر ادغام‌هایتان بااستفاده از سنجه‌ها آشنا شدید، مرحله بعدی عیب‌یابی خطاهای خاص بااستفاده از Cloud Logging است. گزارش خطا ورودی‌ای شبیه JSON است که فیلدهای آن حاوی اطلاعات مفیدی مانند زمان، کد خطا، و جزئیات مربوط به قصد خانه هوشمند مبدأ است.
سیستم‌های متعددی در Google Cloud وجود دارد که گزارش‌ها را همیشه به پروژه‌تان ارسال می‌کنند. باید پرس‌وجوهایی برای فیلتر کردن گزارش‌هایتان بنویسید و گزارش‌های موردنیازتان را پیدا کنید. پرس‌وجوها می‌توانند براساس محدوده زمانی، منبع، شدت گزارش، یا ورودی‌های سفارشی باشند.
می‌توانید از دکمه‌های پُرسمان برای کمک به ساختن فیلترهای سفارشی استفاده کنید.
برای مشخص کردن محدوده زمانی، روی دکمه انتخاب محدوده زمانی کلیک کنید و یکی از گزینه‌های ارائه‌شده را انتخاب کنید. با این کار، گزارش‌ها فیلتر می‌شود و گزارش‌هایی که در محدوده زمانی انتخاب‌شده ایجاد شده‌اند نشان داده می‌شود.
برای مشخص کردن منبع، روی منو کرکره‌ای منبع کلیک کنید، سپس پروژه کنش دستیار Google را انتخاب کنید. این کار فیلتری در پُرسمان شما اضافه می‌کند تا گزارش‌هایی را که از پروژه شما منشأ می‌گیرند نشان دهد.
از دکمه شدت برای فیلتر کردن براساس اضطراری، اطلاعات، اشکال‌زدایی، و دیگر سطوح شدت گزارش استفاده کنید.
همچنین می‌توانید از فیلد «پرسمان» در Logs Explorer
برای وارد کردن ورودی‌های سفارشی استفاده کنید. موتور پرسمانی که این فیلد استفاده می‌کند از هر دو نوع پرسمان پشتیبانی می‌کند:
پرسمان‌های پایه مثل تطابق رشته، و انواع پیشرفته‌تر پرسمان ازجمله
مقایسه‌گرها (<, >=, !=) و عملگرهای بولی (AND, OR, NOT).
برای مثال، ورودی سفارشی زیر خطاهایی را برمی‌گرداند که
از نوع دستگاه LIGHT منشأ می‌گیرند:
resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"
برای پیدا کردن نمونه‌های بیشتر برای پُرسمان مؤثر گزارش‌ها، به کتابخانه پُرسمان مراجعه کنید.
آزمایش تصحیح‌ها
وقتی خطاها را شناسایی کردید و به‌روزرسانی‌ها را برای رفع آن‌ها اعمال کردید، توصیه می‌کنیم اصلاحاتتان را به‌طور کامل با Google Home Test Suite آزمایش کنید. راهنمای کاربری درباره نحوه استفاده از Test Suite ارائه می‌دهیم که شما را در آزمایش مؤثر تغییراتتان راهنمایی می‌کند.
منابع یادگیری
این سند مراحل عیب‌یابی خطاها در «کنش خانه هوشمند» را ارائه می‌دهد. همچنین می‌توانید برای کسب اطلاعات بیشتر درباره اشکال‌زدایی، codelabs ما را بررسی کنید:
- اشکال‌زدایی Codelab خانه هوشمند: راهنمای شروع سریع برای اشکال‌زدایی یکپارچه‌سازی ابری خانه هوشمند.
- اشکال‌زدایی Local Home Codelab: راهنمای شروع سریع برای اشکال‌زدایی ادغام محلی خانه هوشمند.