ساختن برنامه Google Chat با Google Apps Script

این صفحه نحوه ساختن برنامه Google Chat بااستفاده از Google Apps Script را توضیح می‌دهد. برنامه Chat به شما امکان می‌دهد مستقیماً پیام ارسال کنید و با تکرار پیام‌هایتان پاسخ می‌دهد.

نمودار زیر معماری و الگوی پیام‌رسانی را نشان می‌دهد:

در نمودار قبلی، کاربری که با برنامه Chat مبتنی بر Apps Script تعامل دارد، جریان اطلاعات زیر را دارد:

1. کاربری پیامی را به برنامه Chat ارسال می‌کند، چه در پیام مستقیم یا در فضای Chat.
2. منطق برنامه Chat که در Apps Script پیاده‌سازی شده است و در Google Cloud قرار دارد، پیام را دریافت و پردازش می‌کند.
3. درصورت تمایل، منطق برنامه Chat می‌تواند با سرویس‌های Google Workspace، مثل «تقویم» یا «کاربرگ‌نگار»، یا دیگر سرویس‌های Google، مثل Google Maps یا YouTube ادغام شود.
4. منطق برنامه Chat پاسخی را به سرویس برنامه Chat در Chat ارسال می‌کند.
5. پاسخ به کاربر ارائه می‌شود.

اهداف اصلی

• محیط را راه‌اندازی کنید.
• دستورگان را راه‌اندازی کنید.
• برنامه Chat را پیکربندی کنید.
• برنامه Chat را آزمایش کنید.

پیش‌نیازها

• حساب «کسب‌وکار» یا «سازمان» Google Workspace با دسترسی به Google Chat.
• پروژه Google Cloud. برای ایجاد پروژه، ایجاد پروژه Google Cloud را ببینید.

راه‌اندازی محیط

پروژه Cloud خود را در کنسول Google Cloud باز کنید

اگر پروژه Cloud که قصد دارید برای این نمونه استفاده کنید ازقبل باز نشده است، آن را باز کنید:

1. در کنسول Google Cloud، به صفحه انتخاب پروژه بروید.

   انتخاب پروژه Cloud

2. پروژه Google Cloud موردنظرتان را برای استفاده انتخاب کنید. یا روی ایجاد پروژه کلیک کنید و دستورالعمل‌های روی صفحه را دنبال کنید. اگر پروژه Google Cloud ایجاد کنید، ممکن است لازم باشد صدور صورت‌حساب را برای پروژه روشن کنید.

روشن کردن Chat API

قبل‌از استفاده از Google API، باید آن‌ها را در پروژه Google Cloud فعال کنید. می‌توانید یک یا چند میانای برنامه‌سازی کاربردی را در یک پروژه Google Cloud روشن کنید.

• در کنسول Google Cloud،‏ Google Chat API را فعال کنید.

  فعال کردن میانای برنامه‌سازی کاربردی

پیکربندی صفحه کسب رضایت OAuth

همه برنامه‌هایی که از OAuth 2.0 استفاده می‌کنند به پیکربندی صفحه کسب رضایت نیاز دارند. پیکربندی صفحه رضایت OAuth برنامه‌تان تعیین می‌کند چه چیزی به کاربران و بازبینان برنامه نمایش داده شود و برنامه‌تان را ثبت می‌کند تا بتوانید بعداً آن را منتشر کنید.

1. در «کنسول Google API»، به «منو» > پلاتفرم Google Auth > نمانام‌سازی بروید.

   رفتن به نمانام‌سازی

2. اگر قبلاً پلاتفرم Google Auth را پیکربندی کرده‌اید، می‌توانید تنظیمات «صفحه رضایت OAuth» زیر را در نمانام‌سازی، مخاطب، و دسترسی به داده پیکربندی کنید. اگر پیامی با این مضمون دیدید که پلاتفرم Google Auth هنوز پیکربندی نشده است، روی شروع به کار کلیک کنید:
1. در بخش اطلاعات برنامه، در قسمت نام برنامه، نامی برای برنامه وارد کنید.
2. در ایمیل پشتیبانی کاربر، نشانی ایمیل پشتیبانی را انتخاب کنید تا کاربران بتوانند درصورت داشتن سؤال درباره رضایتشان با شما تماس بگیرند.
3. روی بعدی کلیک کنید.
4. در بخش مخاطبان، داخلی را انتخاب کنید.
5. روی بعدی کلیک کنید.
6. در بخش اطلاعات تماس، نشانی ایمیلی را وارد کنید که بتوانید ازطریق آن از هرگونه تغییر در پروژه‌تان مطلع شوید.
7. روی بعدی کلیک کنید.
8. در بخش پایان، خط‌مشی داده‌های کاربر سرویس‌های Google API را مرور کنید و اگر موافقید، با «خط‌مشی داده‌های کاربر سرویس‌های Google API» موافقم را انتخاب کنید.
9. روی ادامه کلیک کنید.
10. روی ایجاد کردن کلیک کنید.
3. فعلاً می‌توانید از افزودن دامنه‌ها صرف‌نظر کنید. در آینده، وقتی برنامه‌ای برای استفاده در خارج از سازمان Google Workspace خود ایجاد می‌کنید، باید نوع کاربر را به خارجی تغییر دهید. سپس گستره‌های مجوزی را که برنامه‌تان نیاز دارد اضافه کنید. برای کسب اطلاعات بیشتر، راهنمای کامل پیکربندی رضایت OAuth را ببینید.

راه‌اندازی دستورگان

برای راه‌اندازی کردن اسکریپت، از الگوی برنامه Chat در صفحه شروع به کار Apps Script استفاده می‌کنید.

ایجاد پروژه Apps Script

1. از صفحه شروع به کار Apps Script، به برافزاهای Google Workspace بروید و روی الگوی برنامه Chat کلیک کنید:

   باز کردن الگوی برنامه Chat

2. در پروژه جدید Apps Script که باز می‌شود، نام پروژه را وارد کنید:

   1. روی پروژه بی‌عنوان کلیک کنید.

   2. در عنوان پروژه، Quickstart app را تایپ کنید.

   3. روی تغییر نام کلیک کنید.

در آینده، اگر بخواهید از Google APIs خاصی استفاده کنید یا برنامه‌تان را منتشر کنید، باید پروژه Cloud خود را با پروژه Apps Script خود مرتبط کنید. برای این راهنما، نیازی به انجام این کار ندارید. برای کسب اطلاعات بیشتر، به راهنمای پروژه‌های Google Cloud مراجعه کنید.

ایجاد استقرار آزمایشی

برای این پروژه Apps Script به شناسه استقرار نیاز دارید تا بتوانید در مرحله بعد از آن استفاده کنید.

برای دریافت شناسه استقرار اصلی، کارهای زیر را انجام دهید:

1. در پروژه Apps Script برنامه Chat، روی استقرار > استقرارهای آزمایشی کلیک کنید.
2. شناسه استقرار Head را برای استفاده در مرحله بعدی کپی کنید و روی تمام کلیک کنید.

پیکربندی برنامه Chat

برای پیکربندی برنامه Google Chat، مراحل زیر را دنبال کنید:

1. در کنسول میانای برنامه‌سازی کاربردی، Google Chat API را جستجو کنید، و روی Google Chat API کلیک کنید.
2. روی مدیریت کلیک کنید.

3. روی پیکربندی کلیک کنید و برنامه Chat را راه‌اندازی کنید:

   1. در فیلد نام برنامه، Quickstart app را وارد کنید.
   2. در فیلد نشانی وب چهرک، https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png را وارد کنید.
   3. در فیلد شرح، Quickstart app را وارد کنید.
   4. در بخش عملکرد، پیوستن به فضاها و مکالمه‌های گروهی را انتخاب کنید.
   5. در بخش تنظیمات اتصال، پروژه Apps Script را انتخاب کنید.
   6. در فیلد شناسه استقرار، شناسه استقرار Head را که قبلاً کپی کرده‌اید جای‌گذاری کنید.
   7. در بخش نمایان بودن، افراد و گروه‌های خاص در دامنه‌تان را انتخاب کنید و ایمیلتان را وارد کنید.

4. روی ذخیره کلیک کنید.

برنامه Chat آماده پاسخ دادن به پیام‌ها است.

آزمایش کردن برنامه Chat

برای آزمایش برنامه Chat، فضای پیام مستقیمی را با برنامه Chat باز کنید و پیامی ارسال کنید:

1. Google Chat را بااستفاده از حساب Google Workspace که هنگام اضافه کردن خودتان به‌عنوان آزمایش‌کننده معتمد ارائه کردید باز کنید.

   رفتن به Google Chat

2. روی گپ جدید کلیک کنید.
3. در فیلد افزودن ۱ یا چند نفر، نام برنامه Chat خود را تایپ کنید.

4. برنامه Chat خود را از نتایج انتخاب کنید. پیام مستقیمی باز می‌شود.

   توجه: اگر برنامه Chat خود را در فهرست نتایج نمی‌بینید، مطمئن شوید که حساب Google Workspace خود را در تنظیمات رؤیت‌پذیری صفحه پیکربندی Chat API در کنسول Google API گنجانده‌اید.

5. در پیام مستقیم جدید با برنامه، Hello را تایپ کنید و enter را فشار دهید.

   برنامه Chat بابت افزودن آن از شما تشکر می‌کند و پیامتان را تکرار می‌کند.

برای افزودن آزمایش‌کنندگان معتمد و کسب اطلاعات بیشتر درباره آزمایش کردن ویژگی‌های تعاملی، به آزمایش کردن ویژگی‌های تعاملی برای برنامه‌های Google Chat مراجعه کنید.

عیب‌یابی

وقتی برنامه Google Chat یا کارت خطایی را برمی‌گرداند، میانای Chat پیامی با این مضمون نشان می‌دهد: «مشکلی پیش آمد.» یا «نمی‌توانیم درخواستتان را پردازش کنیم.» گاهی اوقات میانای کاربری Chat هیچ پیام خطایی نمایش نمی‌دهد، اما برنامه Chat یا کارت نتیجه غیرمنتظره‌ای تولید می‌کند؛ برای مثال، ممکن است پیام کارت ظاهر نشود.

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

مرتب‌سازی

برای جلوگیری از تحمیل هزینه به حساب Google Cloud شما برای منابع استفاده‌شده در این آموزش، توصیه می‌کنیم پروژه Cloud را حذف کنید.

احتیاط: حذف کردن پروژه تأثیرات زیر را دارد:

• همه چیز در پروژه حذف می‌شود. اگر از پروژه موجودی برای این آموزش استفاده کرده‌اید، وقتی آن را حذف می‌کنید، کارهای دیگری را هم که در پروژه انجام داده‌اید حذف می‌کنید.
• شناسه‌های پروژه سفارشی ازدست رفته‌اند. وقتی این پروژه را ایجاد کردید، ممکن است شناسه پروژه سفارشی‌ای ایجاد کرده باشید که بخواهید در آینده از آن استفاده کنید. برای حفظ نشانی‌های وبی که از شناسه پروژه استفاده می‌کنند، مثل نشانی وب در appspot.com، منابع انتخاب‌شده را در پروژه حذف کنید و کل پروژه را حذف نکنید.

اگر قصد دارید چندین آموزش گام‌به‌گام و شروع سریع را کاوش کنید، استفاده مجدد از پروژه‌ها می‌تواند به شما کمک کند از فراتر رفتن از محدودیت‌های سهمیه پروژه جلوگیری کنید.

1. در «کنسول Google API»، به صفحه مدیریت منابع بروید. روی منو > IAM و سرپرست > مدیریت منابع کلیک کنید.

   رفتن به «مدیر منابع»

2. در فهرست پروژه‌ها، پروژه‌ای را که می‌خواهید حذف شود انتخاب کنید و سپس روی حذف کلیک کنید.
3. در چارگوش گفتگو، شناسه پروژه را تایپ کنید و سپس روی خاموش کردن کلیک کنید تا پروژه حذف شود.

مراحل بعدی

• ایجاد کارت‌های تعاملی–پیام‌های کارتی از چیدمان تعریف‌شده، عناصر میانای کاربر تعاملی مانند دکمه‌ها، و رسانه‌های غنی مانند تصاویر پشتیبانی می‌کنند. از پیام‌های کارتی برای ارائه اطلاعات دقیق، جمع‌آوری اطلاعات از کاربران، و راهنمایی کاربران برای انجام مرحله بعدی استفاده کنید.
• پاسخ دادن به فرمان‌ها – فرمان‌ها به کاربران کمک می‌کنند ویژگی‌های کلیدی برنامه Chat شما را پیدا و از آن‌ها استفاده کنند.
• راه‌اندازی کادرهای گفتگو – کادرهای گفتگو واسط‌های پنجره‌ای و کارت‌محور هستند که برنامه‌تان می‌تواند برای تعامل با کاربر باز کند. چند کارت را می‌توان به‌صورت متوالی به‌هم متصل کرد که به کاربران کمک می‌کند فرایندهای چندمرحله‌ای را تکمیل کنند، مانند پر کردن داده‌های فرم.
• Codelab: آماده‌اید تا برنامه Chat پیشرفته‌تری بسازید؟ بازخورد را ببینید برنامه Chat از codelab ساختن برنامه برای Google Chat با Gemini.

برنامه‌های گپ که برافزا نیستند: ساختن برنامه Google Chat با Google Apps Script

برای ساختن برنامه Chat که برافزای Google Workspace نیست با Apps Script، این مراحل را برای ایجاد کردن اسکریپت از الگو و پیکربندی کردن برنامه Chat که برافزا نیست دنبال کنید.

ایجاد کردن دستورات از الگو

1. باز کردن الگوی برنامه Chat

2. روی پروژه بدون عنوان کلیک کنید، Quickstart app را تایپ کنید، و روی تغییر نام کلیک کنید.

   در آینده، اگر بخواهید از Google APIs خاصی استفاده کنید یا برنامه‌تان را منتشر کنید، باید پروژه Cloud خود را با پروژه Apps Script مرتبط کنید. برای این راهنما، نیازی به انجام این کار ندارید. برای کسب اطلاعات بیشتر، راهنمای پروژه‌های Google Cloud را ببینید.

3. در پروژه Apps Script برنامه Chat، روی پیاده‌سازی > پیاده‌سازی‌های آزمایشی کلیک کنید.

4. شناسه استقرار Head را برای استفاده در مرحله بعد کپی کنید و روی تمام کلیک کنید.

پیکربندی برنامه Chat که برافزا نیست

برنامه Chat را که برافزا نیست از «کنسول API» پیکربندی کنید:

1. در کنسول API، Google Chat API را جستجو کنید و روی Google Chat API کلیک کنید.
2. روی مدیریت کلیک کنید.

3. روی پیکربندی کلیک کنید و برنامه Chat را که برافزا نیست راه‌اندازی کنید:

   1. ساختن این برنامه Chat به‌عنوان برافزای Google Workspace را پاک کنید. کادر گفتگویی باز می‌شود و از شما می‌خواهد تأیید کنید. در کادر گفتگو، روی غیرفعال کردن کلیک کنید.
   2. در فیلد نام برنامه، Quickstart app را وارد کنید.
   3. در فیلد نشانی وب چهرک، https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png را وارد کنید.
   4. در فیلد شرح، Quickstart app را وارد کنید.
   5. در بخش عملکرد، پیوستن به فضاها و مکالمه‌های گروهی را انتخاب کنید.
   6. در بخش تنظیمات اتصال، Apps Script را انتخاب کنید.
   7. در فیلد شناسه استقرار، شناسه استقرار Head را که قبلاً کپی کرده‌اید جای‌گذاری کنید.
   8. در بخش نمایان بودن، افراد و گروه‌های خاص در دامنه‌تان را انتخاب کنید و ایمیلتان را وارد کنید.

4. روی ذخیره کلیک کنید.