این بخش مشکلات رایجی را که ممکن است هنگام ساختن و آزمایش کردن برنامه‌های Chat با آن‌ها مواجه شوید شرح می‌دهد.
پیام کارت، کادر گفتگو، یا پیش‌نمایش پیوند به‌صورت موردانتظار پرداز یا کار نمی‌کند
برای دریافت راهنمایی درباره عیب‌یابی خطاهای کارت، عیب‌یابی و اصلاح کارت‌ها را ببینید.
برنامه پاسخ نمی‌دهد
اگر به برنامه Chat پیام دهید و پاسخ «برنامه پاسخ نمی‌دهد» دریافت کنید، پیکربندی برنامه Chat را تأیید کنید:
در «کنسول Google API»، روی منو > APIs و سرویس‌ها > APIs و سرویس‌های فعال > Google Chat API > پیکربندی کلیک کنید.
در بخش ویژگی‌های تعاملی، مطمئن شوید که تنظیمات برای عملکرد برنامه شما مناسب هستند. اگر برنامه Chat شما با کاربران تعامل دارد، حتماً فعال کردن ویژگی‌های تعاملی را روشن کنید:
- به‌طور پیش‌فرض، برنامه‌ها می‌توانند به پیام‌های مستقیم کاربران پاسخ دهند.
- اگر برنامه شما به پیام‌های موجود در فضاها و گپ‌های گروهی پاسخ می‌دهد، پیوستن به فضاها و مکالمه‌های گروهی را انتخاب کنید.
- در بخش تنظیمات اتصال، مطمئن شوید معماری و راه‌اندازها (مثل نشانی وب نقطه پایان HTTP، پروژه Apps Script شناسه استقرار و نام تابع، Cloud Pub/Sub نام موضوع، یا عامل Dialogflow) به‌درستی تنظیم شده باشند و برنامه شما مستقر شده باشد.
- در بخش رؤیت‌پذیری، مطمئن شوید که کاربران مناسب با نشانی ایمیل یا گروه در دامنه Google Workspace به برنامه دسترسی دارند. اگر برنامه با کیت توسعه نرم‌افزار Google Workspace Marketplace مستقر شده باشد، تنظیمات نمایان بودن لازم نیست زیرا تنظیمات Google Workspace Marketplace اولویت دارد.
اگر برنامه با کیت توسعه نرم‌افزار Google Workspace Marketplace منتشر شده است، تنظیمات Google Workspace Marketplace را مرور کنید.
روی ذخیره کلیک کنید.
دوباره به برنامه پیام دهید.
«میانای برنامه‌سازی کاربردی Google Chat» فقط برای کاربران Google Workspace دردسترس است
هنگام پیکربندی برنامه Chat، ممکن است خطای Google Chat API is only available to Google Workspace users را دریافت کنید. این پیام
به این معنی است که «حساب Google» که برای پیکربندی
Chat API استفاده کرده‌اید بخشی از سازمان Google Workspace نیست. برای ساختن برنامه Chat یا استفاده از Chat API، باید از حساب Google Workspace استفاده کنید.
توجه داشته باشید که کاربران Google Chat می‌توانند بدون حساب Google Workspace از برنامه‌های Chat استفاده کنند. برای کسب اطلاعات بیشتر درباره اینکه کاربران چگونه برنامه‌های Chat را پیدا و نصب می‌کنند، ساختن برنامه‌های تعاملی Google Chat را ببینید.
کاربران می‌توانند از فضاها مستثنا شوند
اگر سرپرست Google Workspace به کاربران اجازه ندهد سابقه Chat را روشن یا خاموش کنند، ممکن است مواقعی پیش بیاید که کاربران به‌دلیل تعارض بین تنظیم سطح کاربر که سابقه Chat را اجباراً روشن یا خاموش می‌کند و فضایی که تنظیم اجباری سطح سازمان را به‌ارث می‌برد نتوانند به فضا بپیوندند یا در آن بمانند.
برای مثال، اگر تنظیم سابقه گپ کاربری روی «روشن» اجباری باشد و تنظیم سابقه گپ فضایی روی «خاموش» اجباری باشد، آن کاربر ممکن است نتواند به فضا بپیوندد. علاوه‌براین، اگر کاربر قبل‌از تعارض به فضا پیوسته باشد و بعداز تعارض در فضا پیام پست کند، ممکن است از فضا برداشته شود.
در این سناریو و سناریوهای دیگری که بین تنظیمات سابقه تعارض وجود دارد، ممکن است Chat API نتواند عضویت ایجاد کند، یا ایجاد پیام با اصالت‌سنجی کاربر ممکن است کاربر اصالت‌سنجی‌شده با تنظیم سابقه Chat متعارض را از فضا بردارد.
برای کسب اطلاعات بیشتر، کاربران می‌توانند از فضاها کنار گذاشته شوند را در «مرکز راهنمایی سرپرست Google Workspace» ببینید.
عیب‌یابی سرویس «گپ پیشرفته» در Google Apps Script
صفحه Apps Script درباره خدمات پیشرفته Chat را ببینید.
کاربران نمی‌توانند برنامه Chat را به فضا اضافه کنند
اگر کاربران هنگام تلاش برای افزودن برنامه Chat به فضا با پیام خطای
This organization's administrator must allow users to install this Chat app
مواجه شدند، این خطا ممکن است به یکی از دلایل زیر ایجاد شده باشد:
- سازمان برنامه‌های Chat را غیرفعال کرده است.
- سازمان این برنامه Chat خاص را به فهرست مجاز سازمان اضافه نکرده است.
اگر کاربری هنگام تلاش برای تعامل با برنامه Chat با این پیام خطا مواجه شد، ممکن است دلیل آن این باشد که سازمان بدون فعال کردن واحد سازمانی اصلی، به واحد سازمانی فرعی دسترسی داده است.
برای کسب اطلاعات درباره نحوه حل کردن این مشکل، به اجازه دادن به کاربران برای نصب برنامه‌های Chat مراجعه کنید.
سرپرست باید محدوده مجوز OAuth موردنیاز را برای این کنش به برنامه اعطا کند
هنگام اصالت‌سنجی به‌عنوان برنامه Chat، ممکن است خطای زیر را دریافت کنید:
<HttpError 403 when requesting https://chat.googleapis.com/v1/spaces/{space}?alt=json returned "The administrator must grant the app the required OAuth authorization scope for this action.". Details: "The administrator must grant the app the required OAuth authorization scope for this action.">
این پیام خطا یعنی سرپرست Google Workspace هنوز
تأیید یک‌باره را به برنامه Chat برای استفاده از
محدوده‌های مجوز که با نام
https://www.googleapis.com/auth/chat.app.* شروع می‌شوند اعطا نکرده است.
برای رفع خطا:
- از سرپرست Google Workspace بخواهید
برنامه Chat شما را تأیید کند.
هنگام رسیدگی به این خطا در منطق برنامه Chat خود،
پیامی ارسال کنید که اعلام کند
برنامه Chat برای انجام کنش درخواستی به تأیید سرپرست نیاز دارد،
مثلاً:
To perform this action, I need approval. <https://support.google.com/a?p=chat-app-auth|Learn more>. - اگر روش Chat API از
https://www.googleapis.com/auth/chat.botحوزه مجوز پشتیبانی می‌کند، که به تأیید سرپرست نیاز ندارد، به‌جای آن از این روش استفاده کنید. برای بررسی اینکه یک روش از کدام محدوده‌های اصالت‌سنجی پشتیبانی می‌کند، به اصالت‌سنجی و اصالت‌سنجی درخواست‌های Google Chat API و برنامه‌های Google Chat مراجعه کنید.
عیب‌یابی خطاهای «تابع ابری»
اگر برنامه Chat با «توابع ابری» پیاده‌سازی شده است و کار نمی‌کند، بخش‌های زیر به عیب‌یابی و رفع مشکل کمک می‌کند.
بررسی گزارش‌های «تابع ابری»
به‌عنوان اولین گام، گزارش‌های Cloud Functions را ازنظر خطا بررسی کنید.
در «کنسول Google API»، به صفحه Cloud Functions بروید:
برای باز کردن گزارش‌ها، «عملکرد ابری» برنامه Chat را پیدا کنید، سپس روی نمایش کنش‌ها > مشاهده گزارش‌ها کلیک کنید.
«کاوشگر گزارش‌ها» باز می‌شود و پُرسمانی را اجرا می‌کند که گزارش‌های Cloud Function، ازجمله خطاها، را نشان می‌دهد.
اگر اطلاعات پیش‌فرض ثبت‌شده برای اشکال‌زدایی برنامه شما کافی نیست، می‌توانید ثبت گزارش اضافی از کد Cloud Function خود اضافه کنید. مشاهده و نوشتن گزارش‌های Cloud Function را ببینید.
بررسی خطاهای «تابع ابری»
علاوه‌بر گزارش‌ها، Cloud Function ممکن است خطاهای مواجه‌شده درحین اجرا را نیز گزارش کند.
در «کنسول Google API»، به صفحه Cloud Functions بروید:
روی Cloud Function برنامه Chat کلیک کنید.
در صفحه «جزئیات تابع»، خطاها در بخش خطاها فهرست می‌شوند.
برای عیب‌یابی بیشتر خطا، روی آن کلیک کنید.
رفع کردن خطاهای رایج Cloud Function
هنگام ساختن برنامه Chat با Cloud Functions، گاهی‌اوقات با خطاهای زیر مواجه می‌شوید.
تابع ChatApp در منطقه REGION_NAME در پروژه PROJECT_NAME ازقبل وجود دارد
هنگام پیاده‌سازی «تابع ابری»، ممکن است خطای Function
ChatApp in region REGION_NAME in project PROJECT_NAME already
exists را دریافت کنید. این پیام یعنی «تابع ابری» دیگری نام یکسانی با تابع ابری‌ای که
درحال استقرار آن هستید دارد. نام را تغییر دهید و تابع را دوباره
مستقر کنید. تأیید کنید که برنامه Chat از «نشانی اینترنتی راه‌انداز» برای
«کارکرد ابری» شما استفاده می‌کند، نه «نشانی اینترنتی راه‌انداز» «کارکرد ابری» ازپیش موجود.
یک یا چند کاربر نام‌برده‌شده در خط‌مشی متعلق به مشتری مجاز نیستند
هنگام استقرار «کارکرد ابری»، ممکن است خطای The operation
cannot be completed on the function: "One or more users named in the policy do
not belong to a permitted customer." را دریافت کنید. اگر این خطا را دریافت کردید و سپس به برنامه Chat پیام دادید، خطایی دریافت می‌کنید که می‌گوید برنامه پاسخ نمی‌دهد زیرا Google Chat نمی‌تواند به سروری که «کارکرد ابری» را میزبانی می‌کند دسترسی پیدا کند. این پیام یعنی کاربری به‌نام «allUsers» اجازه فراخوانی Cloud Function را ندارد.
اعطای نقش «فراخواننده Cloud Functions» به «allUsers» به این معنی است که Cloud
Function که برنامه را پشتیبانی می‌کند به‌صورت عمومی دردسترس است و بدون
اصالت‌سنجی قابل‌دسترسی است. برای آشنایی با نحوه واگذاری نقش، به
اعطای یک نقش واحد مراجعه کنید.
این خطا ممکن است به این معنی باشد که پروژه Google Cloud محدود به دامنه است. برای کسب اطلاعات بیشتر درباره محدودیت‌های دامنه، به محدود کردن هویت‌ها براساس دامنه مراجعه کنید.
برای رفع این مشکل، مطمئن شوید که «تابع ابری» شما فراخوانی‌های اصالت‌سنجی‌نشده را مجاز می‌کند. برای آشنایی با نحوه مجاز کردن فراخوانی‌های اصالت‌سنجی‌نشده برای «کارگان ابری» موجود، به مجاز کردن دسترسی عمومی (اصالت‌سنجی‌نشده) مراجعه کنید.
برنامه‌های گپی که برافزا نیستند: عیب‌یابی و رفع خطاهای برنامه Google Chat
مستندات زیر برای برنامه‌های Chat که برافزاهای Google Workspace نیستند اعمال می‌شود. برای انتقال برنامه Chat که برافزا نیست، تبدیل برنامه Chat به برافزای Google Workspace را ببینید.
اگر برنامه Chat که برافزا نیست با «برنامه پاسخ نمی‌دهد» پاسخ می‌دهد، تنظیمات زیر را در برگه پیکربندی «میانای برنامه‌سازی کاربردی Chat» در «کنسول Google API» بررسی کنید:
- در بخش وضعیت برنامه، مطمئن شوید که زنده - دردسترس کاربران را انتخاب کرده‌اید.
- در بخش ویژگی‌های تعاملی > تنظیمات اتصال، مطمئن شوید که نشانی وب نقطه پایان HTTP، Apps Script شناسه استقرار، نام موضوع Cloud Pub/Sub، یا عامل Dialogflow پیکربندی و مستقر شده باشد.