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 شناسایی شدهاند، آورده شده است. برای اطلاعات عیبیابی به جدول زیر مراجعه کنید. برای لیست کامل کدهای خطا، به بخش خطاها و استثنائات مراجعه کنید.
| کد خطا | توضیحات | شریک قابل اقدام |
|---|---|---|
ACTION_NOT_AVAILABLE | این دستور برای وضعیت فعلی دستگاه نامعتبر است (برای مثال، "تنظیم دما" در حالی که دستگاه خاموش است). ویژگیهای دستگاه و منطق وضعیت فعلی را در تکمیل سفارش خود تأیید کنید. | بله |
AGENT_ISSUE | یک مشکل کلی با نماینده ابری شریک رخ داده است. در گزارشهای تکمیل سفارش خود، استثنائات یا خرابیهای مدیریت نشده را بررسی کنید. | بله |
AGENT_UNAVAILABLE_ERROR | گوگل نتوانست به آدرس اینترنتی (URL) مربوط به تکمیل سفارش شریک دسترسی پیدا کند. مطمئن شوید که سرور شما آنلاین است، فایروال گوگل را مسدود نمیکند و URL صحیح است. | بله |
APP_LAUNCH_FAILED | برنامه 3P در دستگاه هدف اجرا نشد. شناسه برنامه (appId) را بررسی کنید و مطمئن شوید که برنامه روی سختافزار هدف پشتیبانی میشود. | بله |
AUTH_EXPIRED | توکن دسترسی OAuth منقضی شده و قابل بهروزرسانی نیست. چرخش توکن بهروزرسانی را بررسی کنید و مطمئن شوید که کاربر دسترسی را لغو نکرده باشد. | بله |
BACKEND_FAILURE_URL_TIMEOUT | درخواست گوگل هنگام تلاش برای دسترسی به سرویس شما به پایان رسید. تأیید کنید که سرویس شما آنلاین است، اتصالات را میپذیرد و ظرفیت آن بیش از حد نیست. علاوه بر این، تأیید کنید که دستگاه هدف روشن، آنلاین و همگامسازی شده است. | |
BACKEND_FAILURE_URL_UNREACHABLE | گوگل از سرویس شما کد خطای HTTP 5xx دریافت کرده است. برای بررسی گزارشهای سرویس خانه هوشمند خود، از requestId در Google Cloud Logging استفاده کنید. | |
CHANNEL_SWITCH_FAILED | دستگاه قادر به تغییر به کانال رسانه درخواستی نبود. نام/شماره کانالها و وضعیت اشتراک کاربر را تأیید کنید. | بله |
CHARGER_ISSUE | دستگاه مشکل سختافزاری در سیستم شارژ خود را گزارش میدهد. شریک باید تلهمتری سطح سختافزار و سلامت باتری را بررسی کند. | بله |
CHECK_PARTNER_APP | این خطا از کاربر میخواهد که برای رفع آن، برنامهی همکار را باز کند. از این کد برای خطاهایی که نیاز به تعامل پیچیده با رابط کاربری دارند (مثلاً بهروزرسانیهای میانافزار) استفاده کنید. | بله |
COMMAND_FAILED | یک خطای عمومی در حین اجرای یک دستور رخ داده است. برای یافتن علت اصلی، گزارشهای تکمیل درخواست (compliance logs) خود را برای requestId خاص بررسی کنید. | بله |
COMMAND_INSERT_FAILED | گوگل قادر به صفبندی یا پردازش دستور برای دستگاه نبود. عملکرد نوشتن در پایگاه داده یا منطق صفبندی دستورات داخلی را بررسی کنید. | بله |
DEVICE_NOT_FOUND | شناسه دستگاه در درخواست در سمت همکار وجود ندارد. مطمئن شوید که فضای ابری شما هنگام اضافه یا حذف دستگاهها توسط کاربر، requestSync را فعال میکند. | بله |
ERROR_STATUS | پاسخ، وضعیت نامشخص «خطا» بدون کد را نشان میداد. همیشه یک رشته errorCode خاص را برای بهبود TTS کاربر و دادههای داشبورد اضافه کنید. | بله |
EXECUTION_BACKEND_FAILURE_URL_ERROR | گوگل از سمت شما خطای HTTP 4xx (غیر از ۴۰۱) دریافت کرده است. لاگهای وب سرور خود را برای یافتن پاسخهای ۴۰۳، ۴۰۴ یا ۴۰۰ بررسی کنید. | بله |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED | آدرس اینترنتی تکمیل سفارش توسط robots.txt یا فیلترهای امنیتی مسدود شده است. مطمئن شوید که نقطه پایانی تکمیل سفارش شما برای خزندهها/سرویسهای گوگل قابل دسترسی است. | بله |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE | گوگل از سرویس تکمیل سفارش شما خطای HTTP 5xx دریافت کرده است. خرابیهای سرور، وقفههای زمانی یا خطاهای ۵۰۲/۵۰۳ 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_READ_ONLY_MODE_FOR_3P | این ادغام در سمت شریک در حالت فقط خواندنی است. بررسی کنید که آیا حساب کاربر به حالت تعلیق درآمده یا در حالت نگهداری «فقط مشاهده» است. | بله |
EXECUTION_GAL_UNLINKED_BY_3P | این حساب کاربری به طور پیشگیرانه توسط سرویس شخص ثالث قطع ارتباط شد. بررسی کنید که چرا اتصال کاربر قطع شده است (برای مثال، تنظیم مجدد امنیت). | بله |
EXECUTION_INVALID_JSON | گوگل نتوانست محتوای پاسخ JSON را تجزیه کند. خطاهای نحوی، براکتهای گمشده یا کاراکترهای نامعتبر را در پاسخ خود بررسی کنید. | بله |
FAULTY_BATTERY | سختافزار دستگاه گزارش میدهد که باتری در حال از کار افتادن یا تمام شدن است. با استفاده از TTS یا برنامه، به کاربر دستور دهید باتری فیزیکی را تعویض کند. | بله |
FUNCTION_NOT_SUPPORTED | حالت یا عملکرد درخواستی توسط دستگاه پشتیبانی نمیشود. مطمئن شوید که پاسخ SYNC شما به طور دقیق قابلیتهای دستگاه را منعکس میکند. | بله |
HARD_ERROR | خرابی غیرگذرا که بدون مداخله دستی برطرف نمیشود. از این مورد برای خرابیهای دائمی سختافزار یا وضعیتهای غیرقابل بازیابی حساب کاربری استفاده کنید. | بله |
INVALID_AUTH_TOKEN | گوگل از سرویس شما کد خطای HTTP 401 دریافت کرده است. توکن دسترسی منقضی نشده است، اما سرویس شما آن را نامعتبر کرده است. برای بررسی گزارشهای سرویس خانه هوشمند خود، از requestId در Google Cloud Logging استفاده کنید. | |
INVALID_JSON | ساختار پاسخ نامعتبر است (برای مثال، فیلدهای اجباری وجود ندارد). پاسخ خود را با استفاده از Intent JSON Schemas اعتبارسنجی کنید. | بله |
LOCK_FAILURE | قفل هوشمند نتوانست به حالت درخواستی منتقل شود. گرفتگیهای فیزیکی، کمبود برق یا خرابی موتور روی سختافزار قفل را بررسی کنید. | بله |
MALFORMED_JSON | ساختار JSON دچار مشکل است (برای مثال، رشتهها یا اشیاء بسته نشده). مطمئن شوید که درخواست شما از یک کتابخانه استاندارد JSON برای سریالسازی پاسخها استفاده میکند. | بله |
MISSING_STATE | پاسخ QUERY شامل وضعیت دستگاه درخواستی نبود. اطمینان حاصل کنید که تمام ویژگیهای تعریفشده در SYNC در هر پاسخ QUERY لحاظ شدهاند. | بله |
NETWORK_PROFILE_NOT_RECOGNIZED | مشخصات شبکه درخواستی برای دستگاه ناشناخته است. بررسی کنید که رشته نام پروفایل با پروفایلهای پشتیبانیشده در پاسخ SYNC مطابقت داشته باشد. | بله |
NOT_IMPLEMENTED | نیت یا ویژگی درخواستی توسط شریک اجرا نشده است. فقط ویژگیهایی را در پاسخ SYNC خود بگنجانید که به طور کامل پیادهسازی کردهاید. | بله |
OAUTH_RECONNECT_CALL_TO_ACTION | اعلانی را برای کاربر فعال میکند تا حساب خود را دوباره متصل کند. از این مورد زمانی استفاده کنید که جلسه کاربر نامعتبر شده و نیاز به تأیید مجدد دستی OAuth دارد. | بله |
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 | این پاسخ شامل نتایج مربوط به همه دستورات/دستگاههای درخواستی نبود. هر آیتم در آرایه commands درخواست باید یک ورودی پاسخ متناظر داشته باشد. | بله |
PARTNER_RESPONSE_MISSING_DEVICE | دستگاه خاصی که گوگل درخواست کرده بود از پاسخ حذف شده بود. مطمئن شوید که پاسخ شما شامل تمام ID ارائه شده در درخواست ارسالی (request payload) باشد. | بله |
PARTNER_RESPONSE_MISSING_PAYLOAD | پاسخ، فیلد اجباریِ payload را ندارد.مطمئن شوید که شیء JSON سطح بالای شما شامل یک کلید payload باشد. | بله |
PARTNER_RESPONSE_NOT_OBJECT | کل پاسخ را نمیتوان به عنوان یک شیء JSON تجزیه کرد. کاراکترهای انتهایی یا محتوای غیر JSON را در بدنه پاسخ HTTP خود بررسی کنید. | بله |
PROTOCOL_ERROR | خطایی در پروتکل ارتباطی اصلی رخ داده است. مشکلات مربوط به هدر HTTP یا خطاهای SSL/TLS handshake را بررسی کنید. | بله |
RELINK_REQUIRED | کاربر برای ادامه استفاده از ادغام، باید حساب خود را دوباره متصل کند. مطمئن شوید که سرور شما این کد را زمانی که توکن بهروزرسانی بهطور دائم نامعتبر است، برمیگرداند. | بله |
REQUEST_ID_NOT_FOUND | گوگل نتوانست شناسه ردیابی داخلی مربوط به درخواست را پیدا کند. معمولاً یک خطای داخلی پلتفرم است؛ موارد ناگهانی را زیر نظر داشته باشید و با پشتیبانی تماس بگیرید. | بله |
RESOURCE_UNAVAILABLE | منبع درخواستی (دستگاه یا ویژگی) در دسترس نیست. بررسی کنید که آیا دستگاه "مشغول" است یا موقتاً غیرفعال شده است. | بله |
RESPONSE_TIMEOUT | سرویس ارسال نتوانست ظرف ۹ ثانیه پاسخ دهد. تأخیر در بکاند را بهینه کنید؛ کوئریهای کند پایگاه داده یا تأخیر شبکه منطقهای را بررسی کنید. | بله |
RESPONSE_UNAVAILABLE | هیچ پاسخی از آدرس اینترنتی تکمیل سفارش شریک دریافت نشد. تأیید کنید که سرویس شما در حال اجرا است و نقطه پایانی دچار خرابی نمیشود. | بله |
SCENE_CANNOT_BE_APPLIED | صحنه درخواستی قابل فعالسازی نیست (برای مثال، دستگاههای موجود نیستند). سلامت داخلی صحنههای کاربر را در ابر شریک بررسی کنید. | بله |
STREAM_UNPLAYABLE | پخش جریانی دوربین نمیتواند شروع شود یا ناموفق بوده است. سیگنالدهی WebRTC/HLS را تأیید کنید و مطمئن شوید که URL جریان معتبر است. | بله |
TIMEOUT | هنگام پردازش intent، یک وقفه کلی رخ داد. گزارشهای مربوط به وقفههای زمانی سرویس داخلی بین ابر و هابهای دستگاه خود را بررسی کنید. | بله |
TRANSIENT_ERROR | خطای گذرا، خطایی است که خود به خود برطرف میشود. معمولاً این خطاها به صورت قطع شدن اتصال به یک دستگاه یا سرویس یا عدم امکان برقراری اتصالات جدید به سرور ظاهر میشوند. | |
UNABLE_TO_LOCATE_DEVICE | دستگاه با استفاده از ویژگی Locator پیدا نشد (برای مثال، پینگ ناموفق بود). اتصال محلی دستگاه (وایفای/بلوتوث) را بررسی کنید. | بله |
UNABLE_TO_RING_DEVICE | با دستگاه تماس گرفته شد اما نتوانست عملکرد زنگ/هشدار خود را فعال کند. وضعیت هشدار/بلندگو و میزان صدای سختافزار را بررسی کنید. | بله |
UNABLE_TO_SILENCE_DEVICE | دستگاه نمیتوانست هشدار/زنگ فعال خود را متوقف کند. بررسی خرابیهای ارتباطی بین ابر و دستگاه فیزیکی. | بله |
UNEXPECTED_ERROR_CHECK_DEVICE_APP | خطایی پیشبینی نشده رخ داد؛ کاربر باید برنامه همکار را بررسی کند. به عنوان یک راهنمای جامع برای خطاهایی که معادل خاصی از پشتیبانی گوگل ندارند، استفاده کنید. | بله |
UNKNOWN_ERROR | یک نقص عمومی بدون جزئیات بیشتر ارائه شده. سعی کنید این کد را با کدهای خطای خاصتری جایگزین کنید تا عیبیابی بهبود یابد. | بله |
UNLOCK_FAILURE | قفل هوشمند نتوانست به حالت «قفل نشده» برسد. مشکلات سختافزاری، باتری ضعیف یا ورودیهای پین نامعتبر را بررسی کنید. | بله |
جستجوی گزارشها
وقتی با استفاده از معیارها در نظارت بر ادغامهای خود مهارت پیدا کردید، گام بعدی عیبیابی خطاهای خاص با استفاده از Cloud Logging است. یک گزارش خطا، ورودی شبیه JSON با فیلدهایی حاوی اطلاعات مفیدی مانند زمان، کد خطا و جزئیات مربوط به هدف اولیه خانه هوشمند است.
چندین سیستم در Google Cloud وجود دارد که همیشه گزارشها را به پروژه شما ارسال میکنند. شما باید برای فیلتر کردن گزارشهای خود و یافتن موارد مورد نیاز، پرسوجوهایی بنویسید . پرسوجوها میتوانند بر اساس محدوده زمانی (Time Range )، منبع (Resource) ، شدت گزارش (log Severity) یا ورودیهای سفارشی باشند.
شما میتوانید از دکمههای پرسوجو برای ساخت فیلترهای سفارشی خود استفاده کنید.
برای مشخص کردن یک محدوده زمانی ، روی دکمه انتخاب محدوده زمانی کلیک کنید و یکی از گزینههای ارائه شده را انتخاب کنید. این کار لاگها را فیلتر میکند و آنهایی را که در محدوده زمانی انتخاب شده ایجاد میشوند، نشان میدهد.
برای مشخص کردن یک منبع ، روی منوی کشویی Resource کلیک کنید، سپس Google Assistant Action Project را انتخاب کنید. این کار یک فیلتر در کوئری شما اضافه میکند تا گزارشهایی را که از پروژه شما سرچشمه میگیرند، نشان دهد.
از دکمهی Severity برای فیلتر کردن بر اساس سطوح Emergency ، Info ، Debug و سایر سطوح گزارش شدت استفاده کنید.
همچنین میتوانید از فیلد Query در 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 ارائه میدهیم که شما را در آزمایش مؤثر تغییرات راهنمایی میکند.
منابع یادگیری
این سند مراحل عیبیابی خطاها در عملکرد خانه هوشمند شما را ارائه میدهد. همچنین میتوانید برای کسب اطلاعات بیشتر در مورد اشکالزدایی، به آزمایشگاههای کد ما مراجعه کنید:
- اشکالزدایی خانه هوشمند Codelab : راهنمای شروع سریع برای اشکالزدایی ادغام ابری خانه هوشمند
- اشکالزدایی کدلب خانگی محلی : راهنمای شروع سریع برای اشکالزدایی ادغام محلی خانه هوشمند.