Google Cloud ابزارهایی را برای شما فراهم میکند تا با استفاده از Google Cloud Monitoring قابلیت اطمینان پروژههای خود را رصد کنید و با استفاده از گزارشهای خطای Google Cloud Logging مشکلات را اشکالزدایی کنید. هر زمان که در انجام اهداف کاربر، خطایی رخ دهد، Google Home Analytics pipeline آن خطا را در معیارهای شما ثبت میکند و یک گزارش خطا در گزارشهای پروژه شما منتشر میکند.
برای رفع خطاهای خود، دو مرحله وجود دارد:
- وضعیت پروژههای خود را با معیارهای خانه هوشمند رصد کنید.
- با بررسی توضیحات دقیق خطا در گزارشهای خطا، مشکلات را بررسی کنید.
در صورت تمایل، میتوانید با به اشتراک گذاشتن اکشن خود با سایر کاربران، آن را آزمایش کنید. مطمئن شوید که خطاها و استثنائات را به طور مناسب مدیریت میکنید .
خطاهای مانیتورینگ
شما میتوانید Google Cloud Monitoring dashboard برای دسترسی به معیارهای پروژه خود استفاده کنید. برخی نمودارهای کلیدی وجود دارند که به ویژه برای نظارت بر کیفیت و اشکالزدایی مفید هستند:
- نمودار نرخ موفقیت اولین نموداری است که هنگام نظارت بر قابلیت اطمینان پروژههای خود از آن شروع میکنید. افت در این نمودار میتواند نشاندهنده قطعی برق برای بخشی یا تمام پایگاه کاربری شما باشد. توصیه میکنیم پس از هر تغییر یا بهروزرسانی در پروژه خود، این نمودار را از نزدیک برای یافتن هرگونه بینظمی رصد کنید.
- نمودار تأخیر صدک ۹۵، شاخص مهمی برای نحوه عملکرد یکپارچهسازی Cloud-to-cloud شما برای کاربرانتان است. نوسانات ناگهانی در این نمودار ممکن است نشان دهد که سیستمهای شما قادر به پاسخگویی به درخواستها نیستند. بررسی دورهای این نمودار برای مشاهده هرگونه رفتار غیرمنتظره توصیه میشود.
- نمودارهای تفکیک خطا (Error breakdown charts) بیشترین کاربرد را در عیبیابی مشکلات مربوط به یکپارچهسازیهای شما دارند. برای هر خطایی که در نمودار درصد موفقیت شما مشخص شده است، یک کد خطا در تفکیک خطای شما نمایش داده میشود. میتوانید خطاهای علامتگذاری شده توسط Google Home platform و نحوه عیبیابی آنها را در جدول زیر مشاهده کنید.
کدهای خطای رایج پلتفرم
در اینجا برخی از کدهای خطای رایج که ممکن است در گزارشهای پروژه خود مشاهده کنید، برای شناسایی مشکلاتی که توسط Google Home platform شناسایی شدهاند، آورده شده است. برای اطلاعات عیبیابی به جدول زیر مراجعه کنید. برای لیست کامل کدهای خطا، به بخش خطاها و استثنائات مراجعه کنید.
| کد خطا | توضیحات | شریک قابل اقدام |
|---|---|---|
AGENT_ISSUE | یک مشکل کلی با نماینده ابری شریک رخ داده است. Check for unhandled exceptions or crashes in your fulfillment logs. | بله |
AGENT_UNAVAILABLE_ERROR | گوگل نتوانست به آدرس اینترنتی (URL) مربوط به تکمیل سفارش شریک دسترسی پیدا کند. مطمئن شوید که سرور شما آنلاین است، فایروال گوگل را مسدود نمیکند و URL صحیح است. | بله |
BACKEND_FAILURE_URL_TIMEOUT | درخواست گوگل هنگام تلاش برای دسترسی به سرویس شما به پایان رسید. تأیید کنید که سرویس شما آنلاین است، اتصالات را میپذیرد و ظرفیت آن بیش از حد نیست. علاوه بر این، تأیید کنید که دستگاه هدف روشن، آنلاین و همگامسازی شده است. | |
BACKEND_FAILURE_URL_UNREACHABLE | گوگل از سرویس شما کد خطای HTTP 5xx دریافت کرده است. از requestId در Google Cloud Logging برای بررسی گزارشهای خدمات خانه هوشمند خود استفاده کنید. خرابیهای سرور، وقفههای زمانی یا خطاهای 502/503 Gateway را بررسی کنید. | |
COMMAND_FAILED | یک خطای عمومی در حین اجرای یک دستور رخ داده است. برای یافتن علت اصلی، گزارشهای تکمیل درخواست (compliance logs) خود را برای requestId خاص بررسی کنید. | بله |
EXECUTION_BACKEND_FAILURE_URL_ERROR | گوگل از سمت شما خطای HTTP 4xx (غیر از ۴۰۱) دریافت کرده است. لاگهای وب سرور خود را برای یافتن پاسخهای ۴۰۳، ۴۰۴ یا ۴۰۰ بررسی کنید. | بله |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED | آدرس اینترنتی تکمیل سفارش توسط robots.txt یا فیلترهای امنیتی مسدود شده است. مطمئن شوید که نقطه پایانی تکمیل سفارش شما برای خزندهها/سرویسهای گوگل قابل دسترسی است. | بله |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE | گوگل از سرویس تکمیل سفارش شما خطای HTTP 5xx دریافت کرده است. اطمینان حاصل کنید که سرویس URL نقطه پایانی پایدار، صحیح و قابل دسترسی عمومی است، سرویس در حال اجرا است. بررسیهای سلامت و مدیریت تلاش مجدد را اضافه کنید. خرابیهای سرور، وقفههای زمانی یا خطاهای 502/503 Gateway را بررسی کنید. | بله |
EXECUTION_BAILOUT_INVALID_RESPONSE | پاسخ JSON آنقدر ناقص بود که پردازش متوقف شد. از یک اعتبارسنج JSON استفاده کنید تا مطمئن شوید پاسخ شما دقیقاً از طرحوارههای Intent پیروی میکند. | بله |
EXECUTION_GAL_BAD_3P_RESPONSE | پیوند حساب به دلیل فرمت نامعتبر در پاسخ توکن انجام نشد. تأیید کنید که قالب پاسخ سرور OAuth شما با الزامات گوگل مطابقت دارد. | بله |
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES | حساب کاربری فاقد مجوزهای لازم برای این اقدام است. دامنههای درخواستشده در طول OAuth را بررسی کنید و مطمئن شوید که با ویژگیهای مورد نیاز مطابقت دارند. | بله |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P | ابر شریک نشان میدهد که کاربر حساب خود را لغو اتصال کرده است. مطمئن شوید که نگاشت agentUserId شما پایدار است و پاک نشده است. | بله |
EXECUTION_GAL_NOT_FOUND | توکنهای دسترسی و بهروزرسانی کاربر که در گوگل ذخیره شدهاند، نامعتبر هستند یا نمیتوان آنها را بهروزرسانی کرد و این امر مانع از احراز هویت و دسترسی به سرویس همکار میشود. اطمینان حاصل کنید که توکنها معتبر و همگامسازی شده باقی میمانند، تغییرات وضعیت حساب را به طور مناسب مدیریت کنید و در صورت تأیید لغو توکنها، از کاربران بخواهید که حساب را دوباره متصل کنند. | بله |
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P | این ادغام در سمت شریک در حالت فقط خواندنی است. بررسی کنید که آیا حساب کاربر به حالت تعلیق درآمده یا در حالت نگهداری «فقط مشاهده» است. | بله |
EXECUTION_GAL_UNLINKED_BY_3P | این حساب کاربری به طور پیشگیرانه توسط سرویس شخص ثالث قطع ارتباط شد. بررسی کنید که چرا اتصال کاربر قطع شده است (برای مثال، تنظیم مجدد امنیت). اطمینان حاصل کنید که سرور OAuth شریک به درستی به درخواستهای refresh_token گوگل پاسخ میدهد تا توکنهای دسترسی جدید را به طور یکپارچه صادر کند. | بله |
EXECUTION_INVALID_JSON | گوگل نتوانست محتوای پاسخ JSON را تجزیه کند. Check for syntax errors, missing brackets, or invalid characters in your response. | بله |
INVALID_AUTH_TOKEN | گوگل از سرویس شما کد خطای HTTP 401 دریافت کرده است. توکن دسترسی منقضی نشده است، اما سرویس شما آن را نامعتبر کرده است. برای بررسی گزارشهای سرویس خانه هوشمند خود، از requestId در Google Cloud Logging استفاده کنید. | |
INVALID_JSON | ساختار پاسخ نامعتبر است (برای مثال، فیلدهای اجباری وجود ندارد). پاسخ خود را با طرحوارههای JSON مربوط به Intent اعتبارسنجی کنید. | بله |
MALFORMED_JSON | ساختار JSON دچار مشکل است (برای مثال، رشتهها یا اشیاء بسته نشده). مطمئن شوید که درخواست شما از یک کتابخانه استاندارد JSON برای سریالسازی پاسخها استفاده میکند. | بله |
NOT_IMPLEMENTED | نیت یا ویژگی درخواستی توسط شریک اجرا نشده است. فقط ویژگیهایی را در پاسخ SYNC خود بگنجانید که به طور کامل پیادهسازی کردهاید. | بله |
OPEN_AUTH_FAILURE | توکن دسترسی کاربر منقضی شده است و گوگل قادر به بهروزرسانی آن نیست، یا گوگل کد خطای HTTP 401 را از سرویس شما دریافت کرده است. اگر میزان افزایش این کد را مشاهده میکنید، بررسی کنید که آیا میزان افزایش خطاهای مربوط به اهداف خانه هوشمند یا درخواستهای توکن بهروزرسانی نیز مشاهده میکنید یا خیر. | |
PARTNER_RESPONSE_INVALID_ERROR_CODE | رشته errorCode برگردانده شده در لیست پشتیبانی شده گوگل نیست.خطاهای داخلی خود را در فهرست خطاهای رسمی ثبت کنید. | بله |
PARTNER_RESPONSE_INVALID_PAYLOAD | فیلد payload در پاسخ، یک شیء JSON معتبر نیست.ساختار ریشهای پاسخ تکمیل سفارش خود را بررسی کنید. | بله |
PARTNER_RESPONSE_INVALID_STATUS | status پاسخ نه موفقیتآمیز بود، نه خطا، نه آفلاین.مطمئن شوید که هر نتیجهی دستگاه در پاسخ شما شامل یک رشتهی وضعیت معتبر باشد. | بله |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES | این پاسخ شامل نتایج مربوط به همه دستورات/دستگاههای درخواستی نبود. ساختار پاسخ خود را با مستندات توسعهدهنده Google Home اعتبارسنجی کنید. مطمئن شوید که پاسخ به دلیل خطای داخلی سرور کوتاه نشده یا بدنه خالی برنمیگرداند. هر مورد در آرایه commands درخواست باید یک ورودی پاسخ مربوطه داشته باشد. | بله |
PARTNER_RESPONSE_MISSING_DEVICE | دستگاه خاصی که گوگل درخواست کرده بود از پاسخ حذف شده بود. مطمئن شوید که پاسخ شما شامل تمام ID ارائه شده در درخواست ارسالی (request payload) باشد. | بله |
PARTNER_RESPONSE_MISSING_PAYLOAD | پاسخ، فیلد اجباری payload را ندارد.مطمئن شوید که شیء JSON سطح بالای شما شامل یک کلید payload باشد. | بله |
PARTNER_RESPONSE_NOT_OBJECT | کل پاسخ را نمیتوان به عنوان یک شیء JSON تجزیه کرد. کاراکترهای انتهایی یا محتوای غیر JSON را در بدنه پاسخ HTTP خود بررسی کنید. مطمئن شوید که payload.commands[] یک شیء JSON مناسب با شناسهها، وضعیتها و حالتهای اختیاری است. | بله |
REQUEST_ID_NOT_FOUND | گوگل نتوانست شناسه ردیابی داخلی مربوط به درخواست را پیدا کند. معمولاً یک خطای داخلی پلتفرم است؛ موارد ناگهانی را زیر نظر داشته باشید و با پشتیبانی تماس بگیرید. | بله |
RESOURCE_UNAVAILABLE | منبع درخواستی (دستگاه یا ویژگی) در دسترس نیست. بررسی کنید که آیا دستگاه "مشغول" است یا موقتاً غیرفعال شده است. | بله |
RESPONSE_TIMEOUT | سرویس ارسال نتوانست ظرف ۹ ثانیه پاسخ دهد. تأخیر در بکاند را بهینه کنید؛ کوئریهای کند پایگاه داده یا تأخیر شبکه منطقهای را بررسی کنید. | بله |
RESPONSE_UNAVAILABLE | هیچ پاسخی از آدرس اینترنتی تکمیل سفارش شریک دریافت نشد. تأیید کنید که سرویس شما در حال اجرا است و نقطه پایانی دچار خرابی نمیشود. | بله |
TIMEOUT | هنگام پردازش intent، یک وقفه کلی رخ داد. گزارشهای مربوط به وقفههای زمانی سرویس داخلی بین ابر و هابهای دستگاه خود را بررسی کنید. | بله |
جستجوی گزارشها
وقتی با استفاده از معیارها در نظارت بر ادغامهای خود مهارت پیدا کردید، گام بعدی عیبیابی خطاهای خاص با استفاده از Cloud Logging است. یک گزارش خطا، ورودی شبیه JSON با فیلدهایی حاوی اطلاعات مفیدی مانند زمان، کد خطا و جزئیات مربوط به هدف اولیه خانه هوشمند است.
چندین سیستم در Google Cloud وجود دارد که همیشه گزارشها را به پروژه شما ارسال میکنند. شما باید برای فیلتر کردن گزارشهای خود و یافتن موارد مورد نیاز، پرسوجوهایی بنویسید . پرسوجوها میتوانند بر اساس محدوده زمانی (Time Range )، منبع (Resource) ، شدت گزارش (log Severity) یا ورودیهای سفارشی باشند.
شما میتوانید از دکمههای پرسوجو برای ساخت فیلترهای سفارشی خود استفاده کنید.
برای مشخص کردن یک محدوده زمانی ، روی دکمه انتخاب محدوده زمانی کلیک کنید و یکی از گزینههای ارائه شده را انتخاب کنید. این کار لاگها را فیلتر میکند و آنهایی را که در محدوده زمانی انتخاب شده ایجاد میشوند، نشان میدهد.
برای مشخص کردن یک منبع ، روی منوی کشویی Resource کلیک کنید، سپس Google Assistant Action Project را انتخاب کنید. این کار یک فیلتر در کوئری شما اضافه میکند تا گزارشهایی را که از پروژه شما سرچشمه میگیرند، نشان دهد.
از دکمهی Severity برای فیلتر کردن بر اساس سطوح اضطراری ، اطلاعات ، اشکالزدایی و سایر سطوح گزارش شدت استفاده کنید.
همچنین میتوانید از فیلد Query در Logs Explorer برای وارد کردن ورودیهای سفارشی استفاده کنید. موتور جستجوی مورد استفاده توسط این فیلد، هم از جستجوهای اولیه مانند تطبیق رشته و هم از انواع پیشرفتهتر جستجوها از جمله مقایسهکنندهها ( <, >=, != ) و عملگرهای بولی ( AND, OR, NOT ) پشتیبانی میکند.
For example, the custom entry below would return errors that originate from a LIGHT device type:
resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"
برای یافتن مثالهای بیشتر برای پرسوجوی مؤثر از لاگها، به کتابخانه پرسوجو مراجعه کنید.
تست رفع مشکلات
پس از شناسایی خطاها و اعمال بهروزرسانیها برای رفع آنها، توصیه میکنیم اصلاحات خود را با Google Home Test Suite به طور کامل آزمایش کنید. ما یک راهنمای کاربر در مورد نحوه استفاده Test Suite ارائه میدهیم که شما را در آزمایش مؤثر تغییرات راهنمایی میکند.
منابع یادگیری
این سند مراحل عیبیابی خطاها در عملکرد خانه هوشمند شما را ارائه میدهد. همچنین میتوانید برای کسب اطلاعات بیشتر در مورد اشکالزدایی، به آزمایشگاههای کد ما مراجعه کنید:
- اشکالزدایی خانه هوشمند Codelab : راهنمای شروع سریع برای اشکالزدایی ادغام ابری خانه هوشمند
- اشکالزدایی کدلب خانگی محلی : راهنمای شروع سریع برای اشکالزدایی ادغام محلی خانه هوشمند.