با Google Apps Script یک برنامه Google Chat بسازید

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

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

معماری یک برنامه چت اجرا شده با Apps Script.

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

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

اهداف

  • محیط خود را تنظیم کنید.
  • اسکریپت را تنظیم کنید
  • برنامه چت را منتشر کنید.
  • برنامه چت را تست کنید.

پیش نیازها

محیط خود را تنظیم کنید

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

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

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

    یک پروژه Cloud را انتخاب کنید

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

Chat API را روشن کنید

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

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

  1. در کنسول Google Cloud، به منو > APIs & Services > صفحه رضایت OAuth بروید.

    به صفحه رضایت OAuth بروید

  2. برای نوع User Internal را انتخاب کنید، سپس روی Create کلیک کنید.
  3. فرم ثبت نام برنامه را تکمیل کنید، سپس روی ذخیره و ادامه کلیک کنید.

  4. در حال حاضر، می‌توانید از افزودن دامنه‌ها صرفنظر کنید و روی ذخیره و ادامه کلیک کنید. در آینده، وقتی برنامه‌ای را برای استفاده خارج از سازمان Google Workspace خود ایجاد می‌کنید، باید نوع کاربر را به خارجی تغییر دهید و سپس محدوده‌های مجوز مورد نیاز برنامه خود را اضافه کنید.

  5. خلاصه ثبت برنامه خود را مرور کنید. برای ایجاد تغییرات، روی ویرایش کلیک کنید. اگر ثبت برنامه خوب به نظر می رسد، روی بازگشت به داشبورد کلیک کنید.

اسکریپت را تنظیم کنید

برای تنظیم اسکریپت، از یک الگو استفاده می کنید و سپس پروژه Cloud خود را در Apps Script تنظیم می کنید.

اسکریپت را از قالب ایجاد کنید

  1. به صفحه شروع برنامه ها اسکریپت بروید.
  2. روی الگوی برنامه چت کلیک کنید. شاید لازم باشد برای دیدن این الگو به پایین اسکرول کنید.
  3. روی پروژه Untitled کلیک کنید، Quickstart app تایپ کنید و روی تغییر نام کلیک کنید.

شماره پروژه Cloud را کپی کنید

  1. در کنسول Google Cloud، به منو > IAM & Admin > تنظیمات بروید.

    به تنظیمات IAM و Admin بروید

  2. در قسمت Project number مقدار را کپی کنید.

پروژه Cloud پروژه Apps Script را تنظیم کنید

  1. در پروژه برنامه Chat Apps Script، روی تنظیمات پروژه کلیک کنید نماد تنظیمات پروژه .
  2. در پروژه Google Cloud Platform (GCP) ، روی تغییر پروژه کلیک کنید.
  3. در شماره پروژه GCP ، شماره پروژه Google Cloud را جای‌گذاری کنید.
  4. روی تنظیم پروژه کلیک کنید.

اکنون کد برنامه کاربردی دارید که می‌توانید آن را امتحان کنید (همانطور که در مراحل زیر توضیح داده شد) و سپس آن را سفارشی کنید تا نیازهای خود را برآورده کنید.

وقتی الگوی Apps Script را باز می‌کنید، مطمئن شوید که به حساب Google صحیح وارد شده‌اید. حساب جاری گاهی اوقات می تواند بدون اینکه متوجه شوید به حساب پیش فرض شما تغییر کند.

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

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

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

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

برنامه چت را منتشر کنید

برنامه چت را از کنسول Google Cloud منتشر کنید.

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

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

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

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

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

برنامه چت را تست کنید

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

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

    به Google Chat بروید

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

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

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

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

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

عیب یابی

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

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

پاک کن

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

  1. در کنسول Google Cloud، به صفحه مدیریت منابع بروید. > IAM & Admin > Manage Resources کلیک کنید.

    به Resource Manager بروید

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

مراحل بعدی

  • ایجاد کارت‌های تعاملی – پیام‌های کارت از طرح‌بندی تعریف‌شده، عناصر رابط کاربری تعاملی مانند دکمه‌ها و رسانه‌های غنی مانند تصاویر پشتیبانی می‌کنند. از پیام های کارت برای ارائه اطلاعات دقیق، جمع آوری اطلاعات از کاربران و راهنمایی کاربران برای برداشتن گام بعدی استفاده کنید.
  • پشتیبانی از دستورات اسلش – دستورات اسلش به شما این امکان را می دهد که دستورات خاصی را که کاربران می توانند به برنامه شما بدهند با تایپ دستوری که با اسلش رو به جلو ( / ) شروع می شود، مانند /help ، ثبت و تبلیغ کنید.
  • راه‌اندازی دیالوگ‌ها - دیالوگ‌ها رابط‌های پنجره‌ای و مبتنی بر کارت هستند که برنامه شما می‌تواند برای تعامل با کاربر باز کند. چندین کارت را می توان به صورت متوالی به هم متصل کرد، که به کاربران کمک می کند فرآیندهای چند مرحله ای، مانند پر کردن داده های فرم را تکمیل کنند.
  • Codelab: برای ایجاد یک برنامه چت پیشرفته تر آماده هستید؟ برنامه چت بازخورد را از codelab Build apps for Google Chat with Gemini ببینید.
،

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

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

معماری یک برنامه چت اجرا شده با Apps Script.

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

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

اهداف

  • محیط خود را تنظیم کنید.
  • اسکریپت را تنظیم کنید
  • برنامه چت را منتشر کنید.
  • برنامه چت را تست کنید.

پیش نیازها

محیط خود را تنظیم کنید

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

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

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

    یک پروژه Cloud را انتخاب کنید

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

Chat API را روشن کنید

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

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

  1. در کنسول Google Cloud، به منو > APIs & Services > صفحه رضایت OAuth بروید.

    به صفحه رضایت OAuth بروید

  2. برای نوع User Internal را انتخاب کنید، سپس روی Create کلیک کنید.
  3. فرم ثبت نام برنامه را تکمیل کنید، سپس روی ذخیره و ادامه کلیک کنید.

  4. در حال حاضر، می‌توانید از افزودن دامنه‌ها صرفنظر کنید و روی ذخیره و ادامه کلیک کنید. در آینده، وقتی برنامه‌ای را برای استفاده خارج از سازمان Google Workspace خود ایجاد می‌کنید، باید نوع کاربر را به خارجی تغییر دهید و سپس محدوده‌های مجوز مورد نیاز برنامه خود را اضافه کنید.

  5. خلاصه ثبت برنامه خود را مرور کنید. برای ایجاد تغییرات، روی ویرایش کلیک کنید. اگر ثبت برنامه خوب به نظر می رسد، روی بازگشت به داشبورد کلیک کنید.

اسکریپت را تنظیم کنید

برای تنظیم اسکریپت، از یک الگو استفاده می کنید و سپس پروژه Cloud خود را در Apps Script تنظیم می کنید.

اسکریپت را از قالب ایجاد کنید

  1. به صفحه شروع برنامه ها اسکریپت بروید.
  2. روی الگوی برنامه چت کلیک کنید. شاید لازم باشد برای دیدن این الگو به پایین اسکرول کنید.
  3. روی پروژه Untitled کلیک کنید، Quickstart app تایپ کنید و روی تغییر نام کلیک کنید.

شماره پروژه Cloud را کپی کنید

  1. در کنسول Google Cloud، به منو > IAM & Admin > تنظیمات بروید.

    به تنظیمات IAM و Admin بروید

  2. در قسمت Project number مقدار را کپی کنید.

پروژه Cloud پروژه Apps Script را تنظیم کنید

  1. در پروژه برنامه Chat Apps Script، روی تنظیمات پروژه کلیک کنید نماد تنظیمات پروژه .
  2. در پروژه Google Cloud Platform (GCP) ، روی تغییر پروژه کلیک کنید.
  3. در شماره پروژه GCP ، شماره پروژه Google Cloud را جای‌گذاری کنید.
  4. روی تنظیم پروژه کلیک کنید.

اکنون کد برنامه کاربردی دارید که می‌توانید آن را امتحان کنید (همانطور که در مراحل زیر توضیح داده شد) و سپس آن را سفارشی کنید تا نیازهای خود را برآورده کنید.

وقتی الگوی Apps Script را باز می‌کنید، مطمئن شوید که به حساب Google صحیح وارد شده‌اید. حساب جاری گاهی اوقات می تواند بدون اینکه متوجه شوید به حساب پیش فرض شما تغییر کند.

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

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

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

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

برنامه چت را منتشر کنید

برنامه چت را از کنسول Google Cloud منتشر کنید.

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

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

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

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

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

برنامه چت را تست کنید

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

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

    به Google Chat بروید

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

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

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

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

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

عیب یابی

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

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

پاک کن

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

  1. در کنسول Google Cloud، به صفحه مدیریت منابع بروید. > IAM & Admin > Manage Resources کلیک کنید.

    به Resource Manager بروید

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

مراحل بعدی

  • ایجاد کارت‌های تعاملی – پیام‌های کارت از طرح‌بندی تعریف‌شده، عناصر رابط کاربری تعاملی مانند دکمه‌ها و رسانه‌های غنی مانند تصاویر پشتیبانی می‌کنند. از پیام های کارت برای ارائه اطلاعات دقیق، جمع آوری اطلاعات از کاربران و راهنمایی کاربران برای برداشتن گام بعدی استفاده کنید.
  • پشتیبانی از دستورات اسلش – دستورات اسلش به شما این امکان را می دهد که دستورات خاصی را که کاربران می توانند به برنامه شما بدهند با تایپ دستوری که با اسلش رو به جلو ( / ) شروع می شود، مانند /help ، ثبت و تبلیغ کنید.
  • راه‌اندازی دیالوگ‌ها - دیالوگ‌ها رابط‌های پنجره‌ای و مبتنی بر کارت هستند که برنامه شما می‌تواند برای تعامل با کاربر باز کند. چندین کارت را می توان به صورت متوالی به هم متصل کرد، که به کاربران کمک می کند فرآیندهای چند مرحله ای، مانند پر کردن داده های فرم را تکمیل کنند.
  • Codelab: برای ایجاد یک برنامه چت پیشرفته تر آماده هستید؟ برنامه چت بازخورد را از codelab Build apps for Google Chat with Gemini ببینید.