عیب‌یابی خطاهای یکپارچه‌سازی

ابر به ابر    Matter

Google Cloud ابزارهایی را برای پایش قابلیت اطمینان پروژه‌هایتان با Google Cloud Monitoring و اشکال‌زدایی مشکلات با گزارش‌های خطای Google Cloud Logging دراختیارتان قرار می‌دهد. هرگاه هنگام برآورده کردن هدف کاربر خطایی رخ دهد، خط لوله Google Home Analytics آن خطا را در سنجه‌های شما ثبت می‌کند و گزارش خطایی در گزارش‌های پروژه شما منتشر می‌کند.

دو مرحله برای عیب‌یابی خطاهای شما وجود دارد:

  1. وضعیت پروژه‌هایتان را با سنجه‌های خانه هوشمند پایش کنید.
  2. با بررسی شرح‌های دقیق خطا در گزارش‌های خطا، مشکلات را بررسی کنید.

این فرایند برای یکپارچه‌سازی محلی بااستفاده از Local Home SDK مشابه است. پس‌از تسلط بر جریان عیب‌یابی، می‌توانید به‌راحتی بین سنجه‌ها و گزارش‌های وقایع جابه‌جا شوید و درباره خطاهایتان اطلاعات آماری کسب کنید.

به‌صورت اختیاری، می‌توانید «کنش» خود را با هم‌رسانی کردن آن با کاربران دیگر آزمایش کنید. مطمئن شوید که خطاها و استثناها را به‌درستی مدیریت می‌کنید.

خطاهای پایش

برای دسترسی به سنجه‌های پروژه، می‌توانید از Google Cloud Monitoring dashboards استفاده کنید. چند نمودار کلیدی وجود دارد که به‌ویژه برای پایش کیفیت و اشکال‌زدایی مفید هستند:

  • نمودار نرخ موفقیت اولین نموداری است که هنگام نظارت بر قابلیت اطمینان پروژه‌هایتان باید از آن شروع کنید. افت در این نمودار می‌تواند نشان‌دهنده قطعی برای بخشی یا کل پایگاه کاربر شما باشد. توصیه می‌کنیم پس‌از هر تغییر یا به‌روزرسانی در پروژه خود، این نمودار را به‌دقت برای هرگونه بی‌نظمی زیر نظر بگیرید.
  • نمودار تأخیر صدک ۹۵ شاخص مهمی برای نحوه عملکرد ادغام Cloud-to-cloud برای کاربران شما است. نوسانات ناگهانی در این نمودار ممکن است نشان دهد که سیستم‌های شما نمی‌توانند با درخواست‌ها همگام شوند. توصیه می‌شود این نمودار را به‌طور دوره‌ای بررسی کنید تا رفتارهای غیرمنتظره را ببینید.
  • نمودارهای تفکیک خطا برای عیب‌یابی مشکلات در ادغام‌های شما بسیار مفید هستند. برای هر خطایی که در نمودار درصد موفقیت شما برجسته شده است، یک کد خطا در تفکیک خطا نمایش داده می‌شود. می‌توانید خطاهای پرچم‌گذاری‌شده توسط Google Home platform و نحوه عیب‌یابی آن‌ها را در جدول زیر ببینید.

کدهای خطای رایج پلاتفرم

در اینجا چند کد خطای رایج که ممکن است در گزارش‌های پروژه خود مشاهده کنید آمده است تا مشکلات شناسایی‌شده توسط Google Home platform را تشخیص دهید. برای اطلاعات عیب‌یابی، به جدول زیر مراجعه کنید. برای مشاهده فهرست کامل کدهای خطا، به خطاها و استثناها مراجعه کنید.

کد خطا شرح شریک اقدام‌پذیر
AGENT_ISSUE مشکلی کلی با عامل ابری شریک پیش آمد.

استثناها یا خرابی‌های مدیریت‌نشده را در گزارش‌های انجام تعهد بررسی کنید. 		بله
AGENT_UNAVAILABLE_ERROR ‫Google نتوانست به نشانی وب اجرای شریک دسترسی پیدا کند.

مطمئن شوید که سرور شما آنلاین است، دیوار آتش Google را مسدود نمی‌کند، و نشانی وب صحیح است. 		بله
COMMAND_FAILED هنگام اجرای فرمان، خطای عمومی رخ داد.

گزارش‌های انجام تعهد خود را برای requestId خاص بررسی کنید تا علت ریشه‌ای را پیدا کنید. 		بله
EXECUTION_BACKEND_FAILURE_URL_ERROR ‫Google از اجرای شما خطای ‎HTTP 4xx (به‌جز ۴۰۱) دریافت کرد.

گزارش‌های سرور وب خود را برای پاسخ‌های 403، 404، یا 400 بررسی کنید. 		بله
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 پایه‌بار پاسخ JSON توسط Google تجزیه نشد.

پاسختان را ازنظر خطاهای نحوی، نبودن قلاب، یا نویسه‌های نامعتبر بررسی کنید. 		بله
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 وجود دارد که همیشه گزارش‌ها را به پروژه شما ارسال می‌کنند. باید پُرسمان‌هایی برای فیلتر کردن گزارش‌هایتان بنویسید و گزارش‌های موردنیازتان را پیدا کنید. پُرسمان‌ها می‌توانند براساس محدوده زمانی، منبع، شدت گزارش، یا ورودی‌های سفارشی باشند.

پُرسمان گزارش‌های Cloud

می‌توانید از دکمه‌های پُرسمان برای کمک به ساختن فیلترهای سفارشی استفاده کنید.

ساختن پُرسمان‌های Cloud Log

برای مشخص کردن محدوده زمانی، روی دکمه انتخاب محدوده زمانی کلیک کنید و یکی از گزینه‌های ارائه‌شده را انتخاب کنید. با این کار، گزارش‌ها فیلتر می‌شود و گزارش‌هایی که در بازه زمانی انتخاب‌شده ایجاد شده‌اند نشان داده می‌شود.

برای مشخص کردن منبع، روی منو کرکره‌ای منبع کلیک کنید، سپس پروژه کنش «دستیار 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 ما را بررسی کنید:

قبلی
ثبت ابر