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

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

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

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

پیش‌نیازها

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

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

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

فیلد شرح قالب
نام برنامه نام نمایشی برنامه Chat. حداکثر ۲۵ نویسه الفباعددی
نشانی وب چهرک تصویری که به‌عنوان چهرک برنامه Chat شما نمایش داده می‌شود. نشانی وب اچ‌تی‌تی‌پی‌اس که به تصویر گرافیکی مربعی (PNG یا JPEG) اشاره می‌کند. اندازه توصیه‌شده ۲۵۶ در ۲۵۶ پیکسل یا بیشتر است.
شرح شرح کوتاهی از برنامه Chat که وقتی کاربران برنامه‌ها را در Chat جستجو می‌کنند نمایش داده می‌شود. حداکثر ۴۰ نویسه الفباعددی
شرح طولانی اختیاری. شرحی از کارهایی که برنامه Chat می‌تواند انجام دهد، که وقتی کاربران مکالمه‌ای را با برنامه Chat شروع می‌کنند یا صفحه اصلی جلسات را برای نماینده‌ای باز می‌کنند، نمایش داده می‌شود. به‌عنوان بخشی از برنامه پیش‌نمای توسعه‌دهندگان نرم‌افزار دردسترس است. درحال‌حاضر فقط هنگام به‌روزرسانی پیکربندی برنامه بااستفاده از کنسول Google Cloud پشتیبانی می‌شود و ازطریق Google Workspace add-ons API پشتیبانی نمی‌شود. حداکثر ۲۵۰ نویسه

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

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

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

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

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

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

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

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

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

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

  3. اختیاری: فیلد شرح طولانی را تکمیل کنید (به‌عنوان بخشی از برنامه پیش‌نمای توسعه‌دهندگان نرم‌افزار Google Workspace دردسترس است).

  4. اختیاری: از منو نحو نشانه‌گذاری، نحو نشانه‌گذاری پیش‌فرض (Markdown یا Chat) را برای پیام‌های برنامه Chat خود انتخاب کنید. برای کسب اطلاعات بیشتر درباره قالب‌بندی نوشتار و نحوه تعیین نحو نشانه‌گذاری برای درخواست‌های API توسط Chat، به قالب‌بندی پیام‌ها مراجعه کنید.

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

    برای ساختن برنامه 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 را انتخاب کنید و نام موضوع را وارد کنید.
    3. اختیاری: برای هدایت اشیای رویداد به نقاط پایانی یا توابع خاص، به تنظیمات اتصال > راه‌اندازها بروید و نقاط پایانی یا توابع فراخوانی متقابل را برای راه‌اندازهای Chat زیر ارائه یا به‌روز کنید:

      • صفحه اصلی برنامه (اگر پشتیبانی از صفحه اصلی برنامه فعال باشد): کاربر برگه صفحه اصلی را در پیام مستقیم دونفره با برنامه Chat باز می‌کند.
      • افزوده‌شده به فضا: کاربر برنامه Chat را به مکالمه گروهی یا فضا اضافه می‌کند، یا برنامه Chat را برای پیام‌های دونفره نصب می‌کند.
      • پیام: کاربر پیامی به برنامه Chat ارسال می‌کند. برای مثال، کاربر پیام مستقیمی به برنامه Chat ارسال می‌کند یا در فضایی با چند نفر، برنامه Chat را @نامبری می‌کند.
      • برداشته‌شده از فضا: کاربر برنامه Chat را از فضا حذف نصب یا برمی‌دارد.
      • فرمان برنامه: کاربر فرمان سریع، فرمان خط مورب، یا کنش پیام را از برنامه Chat فراخوانی می‌کند.
    4. اختیاری: ویژگی‌های تعاملی دیگری مثل جلسه‌ها، پیام‌واره‌های آغازگر، فرمان‌ها (فرمان‌های سریع، فرمان‌های خط مورب، و کنش‌های پیام)، یا پیش‌نمایش‌های پیوند اضافه کنید.

    5. در بخش نمایان بودن، این برنامه Chat را برای افراد و گروه‌های خاص دردسترس قرار دهید و نشانی ایمیل افراد یا «گروه‌های Google» را در سازمان Google Workspace خود وارد کنید:

      • برای نصب و آزمایش کردن برنامه توسط خودتان، نشانی ایمیل خودتان را وارد کنید.
      • برای هم‌رسانی کردن برنامه Chat داخلی در سراسر تیم یا کل سازمانتان بدون انتشار در Marketplace، یک یا چند «گروه Google» وارد کنید. گروه‌ها محدودیت عضو ندارند. اگر برنامه‌تان chat.app.* گستره درخواست می‌کند، همچنان باید برنامه را برای تأیید سرپرست منتشر کنید.
      • اگر سرپرستتان نصب‌های Marketplace را به برنامه‌های موجود در فهرست مجاز محدود کند، کنسول Google Cloud این فیلد را به پنج نشانی ایمیل کاربر مجزا برای توسعه محدود می‌کند. نمایان بودن گروه فقط پس‌از اینکه سرپرست برنامه را به فهرست مجاز اضافه کند اعمال می‌شود.
  6. اختیاری: در بخش گزارش‌ها، چارگوش انتخاب ثبت خطاها در Logging را انتخاب کنید تا از Google Cloud Logging استفاده کنید. برای اطلاعات بیشتر، به گزارش‌های خطای پُرسمان برای برنامه‌های Chat مراجعه کنید.

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

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

پیکربندی برنامه Chat بااستفاده از Google Workspace add-ons API

به‌جای پیکربندی دستی برنامه Chat در کنسول Google Cloud، می‌توانید از پروژه Google Cloud خود که در برنامه پیش‌نمایش توسعه‌دهندگان Google Workspace ثبت شده است استفاده کنید تا پیکربندی برنامه Chat ساخته‌شده به‌عنوان برافزای Google Workspace را بااستفاده از منبع chatAppConfig در Google Workspace add-ons API به‌صورت برنامه‌نویسی‌شده بخوانید و به‌روز کنید.

chatAppConfig منبعی تک‌عضوی است که همیشه برای هر پروژه Cloud وجود دارد. قبل‌از اینکه پیکربندی را برای اولین‌بار ذخیره کنید، منبع حاوی پیکربندی خالی است (که همچنین همان چیزی است که GetChatAppConfig درصورت خواندن منبع قبل‌از اولین ذخیره برمی‌گرداند). چون منبع ازقبل وجود دارد، لازم نیست آن را جداگانه ایجاد کنید—از UpdateChatAppConfig هم برای ذخیره پیکربندی اولیه و هم برای به‌روزرسانی پیکربندی موجود استفاده کنید.

پیش‌نیازها و اصالت‌سنجی

قبل‌از فراخوانی GetChatAppConfig یا UpdateChatAppConfig، پیش‌نیازهای زیر را تکمیل کنید:

  1. پروژه Google Cloud خود را در برنامه پیش‌نمای توسعه‌دهندگان Google Workspace ثبت‌نام کنید.
  2. میانای برنامه‌سازی کاربردی برافزاهای Google Workspace (gsuiteaddons.googleapis.com) را در پروژه Cloud خود فعال کنید. درصورت تمایل، می‌توانید Google Chat API (chat.googleapis.com) را فعال کنید اگر می‌خواهید پیکربندی برنامه Chat را در کنسول Google Cloud مشاهده یا به‌روز کنید یا Chat API را فراخوانی کنید.
  3. با اعتبارنامه OAuth 2.0 که شامل گستره https://www.googleapis.com/auth/cloud-platform است، به‌عنوان کاربر انسانی اصالت‌سنجی کنید. اصالت‌سنجی حساب سرویس برای روش‌های chatAppConfig پشتیبانی نمی‌شود.
  4. مطمئن شوید کاربر اصالت‌سنجی‌شده اجازه‌های لازم «مدیریت هویت و دسترسی‌ها» (IAM) را در پروژه Cloud هدف داشته باشد:
    • gsuiteaddons.chatAppConfigs.get و chat.bots.get برای خواندن پیکربندی (GetChatAppConfig).
    • gsuiteaddons.chatAppConfigs.update و chat.bots.update برای به‌روزرسانی پیکربندی (UpdateChatAppConfig).
  5. اگر از کتابخانه کارخواه استفاده می‌کنید، کتابخانه کارخواه «پیش‌نمایش توسعه‌دهندگان نرم‌افزار» را با حساب ثبت‌شده «پیش‌نمایش توسعه‌دهندگان نرم‌افزار» بارگیری کنید.

به‌روزرسانی پیکربندی برنامه Chat

برای پیکربندی برنامه Chat برای اولین‌بار یا به‌روزرسانی پیکربندی موجود، درخواست PATCH (UpdateChatAppConfig) را به منبع تک‌عضوی chatAppConfig برای پروژه Cloud خود ارسال کنید:

  • برای ذخیره اولیه در «پروژه ابری» با chatAppConfig خالی، displayName (۳ تا ۲۵ نویسه) و description (۱ تا ۴۰ نویسه) لازم است. اگر interactiveFeatureConfig را در ذخیره اولیه حذف کنید، برنامه Chat به‌عنوان غیرتعاملی پیکربندی می‌شود.
  • برای به‌روزرسانی‌های بعدی، از پارامتر پُرسمان اختیاری updateMask برای مشخص کردن فیلدهای جداشده با کاما برای به‌روزرسانی استفاده کنید (یا updateMask را برای به‌روزرسانی همه فیلدهای ارائه‌شده حذف کنید). به‌روزرسانی فیلد تکراری (appCommands، urlPatterns، یا allowlistedTestingPrincipals) کل فهرست را جایگزین می‌کند.
PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "name": "projects/PROJECT_NUMBER/chatAppConfig",
  "displayName": "Cymbal Assistant",
  "description": "Helps manage tasks and schedules",
  "avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
  "state": "ACTIVE",
  "errorLoggingEnabled": true,
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "interactiveFeatureConfig": {
    "supportsMultiuserSpaces": false,
    "connectionConfig": {
      "httpEndpointConfig": {
        "commonUrl": "https://example.com/chat"
      }
    },
    "appCommands": [
      {
        "commandType": "SLASH_COMMAND",
        "commandId": 1,
        "command": "/help",
        "description": "Show available commands",
        "dialogEnabled": false
      }
    ],
    "urlPatterns": [
      {
        "hostPattern": "example.com",
        "pathPrefix": "tasks/"
      }
    ],
    "allowlistedTestingPrincipals": [
      "USER_EMAIL"
    ]
  }
}

موارد زیر را در نشانی وب، سرایند، و بدنه درخواست جایگزین کنید:

  • PROJECT_NUMBER: شماره پروژه عددی پروژه Cloud که میزبان برنامه Chat شما است.
  • ACCESS_TOKEN: کد دسترسی OAuth 2.0 کاربر که با گستره https://www.googleapis.com/auth/cloud-platform مجاز شده است.
  • USER_EMAIL: نشانی ایمیل یا «گروه Google» از سازمان Google Workspace شما برای قرار دادن در فهرست مجاز برای آزمایش برنامه Chat (برای مثال، نشانی ایمیل خودتان).
  • فیلدهای پیکربندی نمونه در متن درخواست (مانند displayName، description، avatarUri، و interactiveFeatureConfig، ازجمله پیکربندی نقطه پایانی، فرمان‌ها، الگوهای نشانی وب پیش‌نمایش پیوند، و اصول آزمایش) با مقادیر برنامه Chat شما. برای جزئیات مربوط به همه فیلدهای پشتیبانی‌شده و گزینه‌های نقطه پایانی، به مرجع REST‏ projects.chatAppConfig و projects.chatAppConfig.patch مراجعه کنید.

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

برای خواندن پیکربندی فعلی برنامه Chat برای پروژه Cloud، GetChatAppConfig را فراخوانی کنید. می‌توانید پارامتر پُرسمان اختیاری view (ChatAppConfigView) را ارسال کنید:

  • BASIC (پیش‌فرض): فراداده‌های اصلی را بدون interactiveFeatureConfig برمی‌گرداند.
  • FULL: همه فیلدهای پیکربندی را برمی‌گرداند، ازجمله interactiveFeatureConfig.

اگر پیکربندی برنامه Chat هنوز برای پروژه Cloud ذخیره نشده باشد، این روش شیء ChatAppConfig خالی برمی‌گرداند.

HTTP

GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN

Node.js

const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;

const client = new GSuiteAddOnsClient();

async function getChatAppConfig() {
  const [response] = await client.getChatAppConfig({
    name: 'projects/PROJECT_NUMBER/chatAppConfig',
    view: 'FULL',
  });
  console.log(JSON.stringify(response, null, 2));
}

getChatAppConfig();

Python

from google.cloud import gsuiteaddons_v1

client = gsuiteaddons_v1.GSuiteAddOnsClient()

request = gsuiteaddons_v1.GetChatAppConfigRequest(
    name="projects/PROJECT_NUMBER/chatAppConfig",
    view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)

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

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

  • هم افراد و هم سرپرستان Google Workspace باید بتوانند برافزای شما را از Marketplace نصب کنند. این تنظیمات نصب را در کیت توسعه نرم‌افزار Marketplace پیکربندی می‌کنید.
  • برنامه‌های Chat از نام و نشان‌واره‌ای که برای دیگر برنامه‌های Google Workspace در شیء addons.common از مانیفست پیکربندی می‌کنید استفاده نمی‌کنند.
  • برای برافزاهایی که در Google Workspace Marketplace منتشر شده‌اند، نمی‌توانید پیش‌نویس تغییرات را در تنظیمات پیکربندی Google Chat API ذخیره کنید. پس‌از به‌روزرسانی و ذخیره کردن تنظیمات پیکربندی Chat API، برنامه Chat به‌روزشده بلافاصله برای همه کاربران موجود دردسترس قرار می‌گیرد. برای به‌روزرسانی فهرستگان Marketplace، می‌توانید قبل‌از ارسال هرگونه تغییر، پیش‌نویس ایجاد کنید.
  • اگر برافزایتان را بااستفاده از Apps Script ساخته‌اید:
  • اگر برافزایتان را بااستفاده از سرویس HTTP ساخته‌اید، جزئیات پیکربندی برنامه Chat را در مانیفست projects.deployments که بااستفاده از Google Workspace add-ons API ایجاد می‌کنید حذف کنید. استقرارهای HTTP که در Google Workspace Marketplace SDK مشخص می‌کنید فقط برای دیگر برنامه‌های Google Workspace استفاده می‌شود. درعوض، برنامه Chat خود را در کنسول Google Cloud یا بااستفاده از منبع chatAppConfig در میانای برنامه‌سازی کاربردی برافزاهای Google Workspace پیکربندی کنید.

به افراد دیگر اجازه دهید Chat API را پیکربندی کنند

می‌توانید با اعطای نقش «مدیریت هویت و دسترسی‌ها» (IAM) در Google Cloud «مالک برنامه‌های Chat» یا «بیننده برنامه‌های Chat» به کاربران خاص، به آن‌ها اجازه دسترسی به صفحه پیکربندی برنامه Chat را بدهید. کاربران دارای این نقش‌ها نمی‌توانند بااستفاده از داشبورد APIs & Services به صفحه پیکربندی برنامه‌های 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 را میزبانی می‌کند.

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

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

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

    رفتن به صفحه پیکربندی 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 مراجعه کنید.