پیکربندی کردن «میانای برنامه‌سازی کاربردی Google Chat»

هر برنامه Google Chat که ایجاد می‌کنید به پروژه Google Cloud خود با Chat API فعال و پیکربندی‌شده نیاز دارد.

برای انجام تماس‌های API فقط خواندنی با اصالت‌سنجی کاربر، مثل دریافت فضاها و فهرست کردن پیام‌ها، فقط باید میانای برنامه‌سازی کاربردی را فعال کنید و کارخواه OAuth ایجاد کنید.

برای انجام دادن فراخوانی‌های API ایجاد، به‌روزرسانی، و حذف، یا برای استقرار و آزمایش کردن برنامه Chat تعاملی (ساخته‌شده به‌عنوان برافزای Google Workspace که Chat را گسترش می‌دهد)، باید Chat API را نیز پیکربندی کنید. تنظیمات پیکربندی Chat API جایی است که همه جزئیات مربوط به برنامه Chat را مشخص می‌کنید، ازجمله نام نمایشی، چهرک، نقطه‌های پایان استقرار، و ویژگی‌های تعاملی.

پیش‌نیازها

• حساب «کسب‌وکار» یا «سازمانی» Google Workspace با دسترسی به Google Chat.
• ایجاد پروژه Google Cloud.
• صفحه کسب رضایت OAuth را پیکربندی کنید.
• «میانای برنامه‌سازی کاربردی Google Chat» را فعال کنید.

نام نمایشی، چهرک، و شرحی برای برنامه Chat خود انتخاب کنید

وقتی Chat API را فعال می‌کنید، جزئیات مربوط به برنامه Chat خود را که برای کاربران در Chat نمایش داده می‌شود پیکربندی می‌کنید، ازجمله نام نمایشی، چهره‌نما، و شرح. این جزئیات فقط در Chat نشان داده می‌شود. برای انتشار برنامه Chat در «بازار»، باید جزئیاتی را که در فهرستگان بازار برنامه Chat شما نمایش داده می‌شود نیز مشخص کنید.

قبل‌از پیکربندی برنامه Chat، اطلاعات زیر را آماده کنید:

فیلد	شرح	قالب
نام برنامه	نام نمایشی برنامه Chat.	حداکثر ۲۵ نویسه الفباعددی
نشانی وب چهرک	تصویری که به‌عنوان چهرک برنامه Chat نمایش داده می‌شود.	نشانی وب HTTPS که به تصویر گرافیکی مربعی (PNG یا JPEG) اشاره می‌کند. اندازه توصیه‌شده ۲۵۶ در ۲۵۶ پیکسل یا بیشتر است.
شرح	شرح مختصری از هدف برنامه Chat.	حداکثر ۴۰ نویسه الفباعددی

نام، چهره‌نما، و شرح برنامه Chat در میانای کاربری Chat به کاربران نمایش داده می‌شود. برای برخی‌از درخواست‌های نوشتاری Chat API،‏ Chat از این اطلاعات برای نسبت دادن کنش‌هایی که برنامه Chat در Chat انجام می‌دهد استفاده می‌کند.

برای مثال، اگر روش spaces.create() را فراخوانی کنید، Chat نام برنامه Chat را در شرح فردی که فضا را ایجاد کرده است اضافه می‌کند، همان‌طور که در تصویر زیر نشان داده شده است:

شکل ۱. پیام ارجاعی که Chat وقتی از روش spaces.create() برای ایجاد فضا به‌نمایندگی از کاربر استفاده می‌شود نمایش می‌دهد.

برای تعامل با برنامه‌های Chat، کاربران این اطلاعات را نیز به روش‌های زیر می‌بینند یا استفاده می‌کنند:

• برای افزودن برنامه Chat به فضا یا ارسال پیام به آن، از @نامبری برنامه Chat استفاده کنید.
• پیام مستقیمی را با برنامه Chat پیدا و شروع کنید. در منو برنامه‌ها، پیام‌های مستقیم نام و چهره‌نمای برنامه Chat را نمایش می‌دهد.
• کاربران می‌توانند از نوار نوشتن، برنامه‌های Chat را مرور کنند و نام، چهرک، و شرح آن‌ها را ببینند.

برنامه Chat را در کنسول Google Cloud پیکربندی کنید

وقتی جزئیات برنامه Chat را دارید، پروژه Cloud خود را باز کنید و Chat API را پیکربندی کنید:

1. در کنسول Google Cloud، به صفحه Chat API بروید و روی صفحه پیکربندی کلیک کنید:

   رفتن به صفحه «پیکربندی Chat API»

2. در بخش اطلاعات برنامه، فیلدهای نام برنامه، نشانی وب چهرک، و شرح را تکمیل کنید.

3. در بخش ویژگی‌های تعاملی، پیکربندی کنید که آیا برنامه Chat شما به تعامل‌های کاربر پاسخ می‌دهد یا نه:

   توجه: اگر برنامه Chat شما فقط با Chat API تماس می‌گیرد و تعاملات کاربر را دریافت یا به آن‌ها پاسخ نمی‌دهد، فعال کردن ویژگی‌های تعاملی را خاموش بگذارید و به مرحله بعد بروید.

   برای ساختن برنامه Chat تعاملی، فعال کردن ویژگی‌های تعاملی را روشن کنید و موارد زیر را تکمیل کنید:

   1. در بخش عملکرد:
      • اختیاری: صفحه اصلی برنامه پشتیبانی را انتخاب کنید تا کارت صفحه اصلی در زبانه صفحه اصلی پیام‌های مستقیم دونفره با برنامه Chat نمایش داده شود.
      • پیوستن به فضاها و مکالمه‌های گروهی را انتخاب کنید تا برنامه Chat برای نصب و استفاده دردسترس قرار گیرد. به‌طور پیش‌فرض، کاربران می‌توانند برنامه Chat را در فضایی اختصاصی بین کاربر و برنامه Chat نصب کنند و با آن پیام ارسال کنند. کاربران همچنین می‌توانند برنامه Chat را در فضاهای دارای چند نفر اضافه کنند و با آن تعامل داشته باشند.

   2. در بخش تنظیمات اتصال، معماری موردنظرتان را برای استفاده در دریافت اشیا رویداد از Chat انتخاب کنید:

      • برای استفاده از سرویس HTTP، نشانی وب نقطه پایان HTTP را انتخاب کنید و نشانی وب ارائه دهید.
      • برای استفاده از پروژه Google Apps Script، Apps Script را انتخاب کنید و شناسه استقرار پروژه را ارائه دهید.
      • برای استفاده از عامل Dialogflow، Dialogflow را انتخاب کنید، Dialogflow CX یا Dialogflow ES را انتخاب کنید، و نام منبع عامل را ارائه دهید.
      • برای استفاده از Pub/Sub، گزینه Cloud Pub/Sub را انتخاب کنید و نام موضوع را وارد کنید.
      هشدار: اگر شناسه استقرار Apps Script ازقبل پر شده باشد، پروژه Cloud به یک برافزای Google Workspace موجود متصل می‌شود. اگر شناسه استقرار را در Chat API به‌روزرسانی کنید، شناسه استقرار برای برافزایتان به‌روزرسانی می‌شود و می‌تواند روی فهرستگان شما در Google Workspace Marketplace تأثیر بگذارد. برای مرور پیکربندی برافزا، به پیکربندی برنامه در کیت توسعه نرم‌افزار Google Workspace Marketplace مراجعه کنید.

   3. اختیاری: برای مسیریابی کردن اشیای رویداد به نقاط پایانی یا عملکردهای خاص، به تنظیمات اتصال > محرک‌ها بروید و نقاط پایانی یا عملکردهای تماس برگشتی را برای محرک‌های گپ زیر ارائه یا به‌روزرسانی کنید:

      توجه: برای «دستورگان برنامه‌ها»، اگر محرک‌ها را به‌روز نکنید، باید کارکردهای فراخوانی برگشتی پیش‌فرضی را که در این بخش تکمیل شده است (مثل onMessage، onAddedToSpace، onRemovedFromSpace، onAppCommand، و onAppHome) پیاده‌سازی کنید.
      • صفحه اصلی برنامه (اگر پشتیبانی از صفحه اصلی برنامه فعال باشد): کاربر زبانه صفحه اصلی را در پیام مستقیم دونفره با برنامه Chat باز می‌کند.
      • به فضا اضافه شد: کاربری برنامه Chat را به مکالمه گروهی یا فضا اضافه می‌کند، یا برنامه Chat را برای پیام‌های دونفره نصب می‌کند.
      • پیام: کاربر پیامی به برنامه Chat ارسال می‌کند. برای مثال، کاربر پیامی مستقیم به برنامه Chat ارسال می‌کند یا برنامه Chat را در فضایی با چند نفر @نامبری می‌کند.
      • برداشته‌شده از فضا: کاربری برنامه Chat را از فضایی حذف نصب یا برمی‌دارد.
      • فرمان برنامه: کاربر فرمان سریع، فرمان خط مورب، یا کنش پیام را از برنامه Chat فرا می‌خواند.

   4. اختیاری: ویژگی‌های تعاملی دیگری مثل پیام‌واره‌های آغازگر، فرمان‌ها (فرمان‌های سریع، فرمان‌های خط مورب، و کنش‌های پیام)، یا پیش‌نمایش‌های پیوند اضافه کنید.

   5. در بخش رؤیت‌پذیری، نشانی ایمیلتان را مشخص کنید تا بتوانید برنامه Chat را نصب و آزمایش کنید قبل‌از اینکه در Google Workspace Marketplace منتشر کنید. می‌توانید حداکثر پنج نفر یا یک یا چند «گروه Google» را از سازمان Google Workspace خود مشخص کنید.

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

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

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

ملاحظات مربوط به برافزاهای موجود Google Workspace

برنامه‌های گپ در مقایسه با برافزاهای Google Workspace که برنامه‌های دیگر Google Workspace را گسترش می‌دهند، به پیکربندی متفاوتی نیاز دارند. اگر برافزای شما برنامه‌های دیگر Google Workspace را گسترش می‌دهد، الزامات زیر را برای پیکربندی برنامه Chat درنظر بگیرید:

• هم افراد و هم سرپرستان Google Workspace باید بتوانند برافزای شما را از Marketplace نصب کنند. این تنظیمات نصب را در کیت توسعه نرم‌افزار Google Workspace Marketplace پیکربندی می‌کنید.
• برنامه‌های گپ از نام و نشانی‌ای که برای سایر برنامه‌های Google Workspace در addons.common شیء مانیفست پیکربندی می‌کنید استفاده نمی‌کنند.
• برای برافزاهایی که در Google Workspace Marketplace منتشر می‌شوند، نمی‌توانید پیش‌نویس تغییرات تنظیمات پیکربندی Google Chat API را ذخیره کنید. پس‌از به‌روزرسانی و ذخیره کردن تنظیمات پیکربندی Chat API، برنامه Chat به‌روزرسانی‌شده بلافاصله برای همه کاربران موجود دردسترس قرار می‌گیرد. برای به‌روزرسانی فهرستگان «بازار»، می‌توانید پیش‌از ارسال هرگونه تغییر، پیش‌نویسی ایجاد کنید.
• اگر برافزایتان را بااستفاده از Apps Script ساخته‌اید:
  • باید از همان شناسه استقرار Apps Script که برای بقیه پیکربندی برافزایتان استفاده می‌کنید استفاده کنید.
  • نمی‌توانید از ویرایشگر Apps Script برای نصب استقرار آزمایشی در Chat استفاده کنید. درعوض، باید آن‌ها را مستقیماً از «میانای کاربر Chat» نصب کنید.
• اگر برافزایتان را بااستفاده از سرویس HTTP ساخته‌اید، جزئیات پیکربندی برنامه Chat را در مانیفست و استقرارها که بااستفاده از «میانای برنامه‌سازی کاربردی برافزاهای Google Workspace» ایجاد می‌کنید حذف کنید. استقرارهای HTTP که در کیت توسعه نرم‌افزار Google Workspace Marketplace مشخص می‌کنید فقط برای سایر برنامه‌های Google Workspace استفاده می‌شود.

به افراد دیگر اجازه دهید «میانای برنامه‌سازی کاربردی Chat» را پیکربندی کنند

می‌توانید با اعطای نقش مالک برنامه‌های Chat یا بیننده برنامه‌های Chat مدیریت هویت و دسترسی‌ها (IAM) در Google Cloud، به کاربران خاص دسترسی دهید به صفحه پیکربندی برنامه Chat دسترسی داشته باشند. کاربران دارای این نقش‌ها نمی‌توانند بااستفاده از داشبورد میاناهای برنامه‌سازی کاربردی و سرویس‌ها به صفحه پیکربندی برنامه‌های Chat پیمایش کنند، اما می‌توانند با پیمایش به کنسول Google Cloud برای پروژه Cloud میزبان برنامه Chat، به صفحه پیکربندی دسترسی پیدا کنند، به این صورت:

https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

که در آن PROJECT_ID شناسه پروژه پروژه Google Cloud میزبان برنامه Chat است.

کاربران دارای نقش‌های پروژه نیز می‌توانند به صفحه پیکربندی برنامه دسترسی داشته باشند.

کاربران دارای نقش‌های سفارشی که حاوی اجازه‌های resourcemanager.projects.(get|update) هستند نمی‌توانند به پیکربندی برنامه Chat دسترسی داشته باشند. برای نقش‌های سفارشی، به‌جای آن از اجازه‌های chat.bots.(get|update) استفاده کنید.

موضوعات مرتبط

• انتخاب معماری برنامه Chat
• دریافت و پاسخ به تعاملات کاربر
• آزمایش ویژگی‌های تعاملی برای برنامه‌های Google Chat

برنامه‌های Chat که برافزا نیستند: پیکربندی Google Chat API

اگر برنامه Chat را که برافزای Google Workspace نیست نگهداری می‌کنید، پیکربندی شما از یک نقطه پایانی واحد برای همه رویدادهای تعاملی به‌جای راه‌اندازهای هر رویداد استفاده می‌کند:

1. در کنسول Google Cloud، به صفحه پیکربندی میانای برنامه‌سازی کاربردی Chat بروید:

   رفتن به صفحه «پیکربندی Chat API»

2. در بخش ویژگی‌های تعاملی، فعال کردن ویژگی‌های تعاملی را روشن کنید.

3. ساخت این برنامه Chat به‌عنوان برافزای Google Workspace را لغو انتخاب کنید. کادر گفتگویی باز می‌شود که از شما می‌خواهد تأیید کنید. در چارگوش گفتگو، روی غیرفعال کردن کلیک کنید.

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

5. در بخش تنظیمات اتصال، یک نقطه پایان واحد برای برنامه Chat خود مشخص کنید (نشانی وب نقطه پایان HTTP، شناسه استقرار Apps Script، نام موضوع Cloud Pub/Sub، یا Dialogflow).

6. فرمان‌های اختیاری، پیش‌نمایش‌های پیوند، رؤیت‌پذیری، و گزارش‌های را پیکربندی کنید، سپس روی ذخیره کردن کلیک کنید.

برای ارتقا دادن برنامه Chat که برافزا نیست به برافزای Google Workspace که Google Chat را گسترش می‌دهد، تبدیل برنامه Google Chat به برافزای Google Workspace را ببینید.