กำหนดค่า Google Chat API

แอป Google Chat แต่ละแอปที่คุณสร้างต้องมีโปรเจ็กต์ Google Cloud ของตัวเองที่เปิดใช้และกำหนดค่า Chat API ไว้

หากต้องการเรียก API แบบอ่านอย่างเดียวด้วยการตรวจสอบสิทธิ์ผู้ใช้ เช่น การรับพื้นที่ทำงานและการแสดงข้อความ คุณเพียงแค่ต้องเปิดใช้ API และสร้างไคลเอ็นต์ OAuth

หากต้องการเรียก API เพื่อสร้าง อัปเดต และลบ หรือเพื่อติดตั้งใช้งานและทดสอบแอป Chat แบบอินเทอร์แอกทีฟ (สร้างเป็นส่วนเสริมของ Google Workspace ที่ขยายการทำงานของ Chat) คุณต้องกำหนดค่า Chat API ด้วย การตั้งค่าการกำหนดค่า Chat API เป็นที่ที่คุณระบุรายละเอียดทั้งหมดเกี่ยวกับ แอปใน Chat รวมถึงชื่อที่แสดง อวาตาร์ ปลายทางการติดตั้งใช้งาน และฟีเจอร์แบบอินเทอร์แอกทีฟ

ข้อกำหนดเบื้องต้น

• บัญชี Google Workspace แบบ Business หรือ Enterprise ที่มีสิทธิ์เข้าถึง Google Chat
• สร้างโปรเจ็กต์ Google Cloud
• กำหนดค่าหน้าจอขอความยินยอม OAuth
• เปิดใช้ Google Chat API

เลือกชื่อที่แสดง รูปโปรไฟล์ และคำอธิบายสำหรับแอปใน Chat

เมื่อเปิดใช้ Chat API คุณจะกำหนดค่ารายละเอียดเกี่ยวกับแอป Chat ที่ปรากฏต่อผู้ใช้ใน Chat ได้ ซึ่งรวมถึงชื่อที่แสดง รูปโปรไฟล์ และคำอธิบาย รายละเอียดเหล่านี้จะปรากฏใน Chat เท่านั้น หากต้องการเผยแพร่แอปใน Chat ไปยัง Marketplace คุณต้องระบุรายละเอียดที่จะปรากฏในข้อมูล Marketplace ของแอปใน Chat ด้วย

ก่อนกำหนดค่าแอปใน Chat ให้เตรียมข้อมูลต่อไปนี้

ชื่อ รูปโปรไฟล์ และคำอธิบายของแอปใน Chat จะแสดงต่อผู้ใช้ใน UI ของ Chat สำหรับคำขอเขียน Chat API บางรายการ Chat จะใช้ข้อมูลนี้เพื่อระบุแหล่งที่มาของการดำเนินการที่แอปใน Chat ทำใน Chat

ตัวอย่างเช่น หากคุณเรียกใช้เมธอด spaces.create() Chat จะใส่ชื่อแอป Chat ไว้ในคำอธิบายว่าใครเป็นผู้สร้างพื้นที่ทำงาน ดังที่แสดงในรูปภาพต่อไปนี้

หากต้องการโต้ตอบกับแอปใน Chat ผู้ใช้จะเห็นหรือใช้ข้อมูลนี้ในลักษณะต่อไปนี้ด้วย

• @พูดถึงแอปใน Chat เพื่อเพิ่มแอปไปยังพื้นที่ทำงานหรือส่งข้อความถึงแอป
• ค้นหาและเริ่มส่งข้อความส่วนตัวกับแอปใน Chat ในเมนูแอป ข้อความส่วนตัวจะแสดงชื่อและรูปโปรไฟล์ของแอปใน Chat
• ผู้ใช้สามารถเรียกดูแอปใน Chat และดูชื่อ รูปโปรไฟล์ และคำอธิบายได้จากช่องสำหรับเขียน

กำหนดค่าแอปใน Chat ในคอนโซล Google Cloud

เมื่อมีรายละเอียดแอป Chat แล้ว ให้เปิดโปรเจ็กต์ที่อยู่ในระบบคลาวด์และกำหนดค่า Chat API โดยทำดังนี้

1. ในคอนโซล Google Cloud ให้ไปที่หน้า Chat API แล้วคลิกหน้าการกำหนดค่า

   ไปที่หน้าการกำหนดค่า Chat API

2. ในส่วนข้อมูลแอปพลิเคชัน ให้กรอกข้อมูลในช่องชื่อแอป URL ของรูปโปรไฟล์ และคำอธิบาย

3. ไม่บังคับ: จากเมนูไวยากรณ์มาร์กอัป ให้เลือกไวยากรณ์มาร์กอัปเริ่มต้น (Markdown หรือ Chat) สำหรับข้อความของแอปใน Chat ดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดรูปแบบข้อความและวิธีที่ Chat กำหนดไวยากรณ์มาร์กอัปสำหรับคำขอ API ได้ที่หัวข้อจัดรูปแบบข้อความ

4. ในส่วนฟีเจอร์แบบอินเทอร์แอกทีฟ ให้กำหนดค่าว่าจะให้แอป Chat ตอบสนองต่อการโต้ตอบของผู้ใช้หรือไม่ โดยทำดังนี้

   หากต้องการสร้างแอปใน Chat แบบอินเทอร์แอกทีฟ ให้เปิดเปิดใช้ฟีเจอร์แบบอินเทอร์แอกทีฟ แล้วทำตามขั้นตอนต่อไปนี้

   1. ในส่วนฟังก์ชันการทำงาน ให้ทำดังนี้
      • ไม่บังคับ: เลือกรองรับหน้าแรกของแอปเพื่อแสดงการ์ดหน้าแรกในแท็บหน้าแรกของข้อความส่วนตัวแบบ 1:1 กับแอปใน Chat
      • เลือกเข้าร่วมพื้นที่ทำงานและการสนทนากลุ่มเพื่อให้แอปใน Chat พร้อมให้ติดตั้งและใช้งาน โดยค่าเริ่มต้น ผู้ใช้จะติดตั้งและส่งข้อความด้วยแอปใน Chat ในพื้นที่ทำงานเฉพาะระหว่างผู้ใช้กับแอปใน Chat ได้ นอกจากนี้ ผู้ใช้ยังเพิ่มและโต้ตอบกับแอปใน Chat ในพื้นที่ทำงานที่มีผู้ใช้หลายคนได้ด้วย

   2. ในส่วนการตั้งค่าการเชื่อมต่อ ให้เลือกสถาปัตยกรรมที่ต้องการใช้เพื่อรับออบเจ็กต์เหตุการณ์จาก Chat ดังนี้

      • หากต้องการใช้บริการ HTTP ให้เลือก HTTP endpoint URL แล้วระบุ URL
      • หากต้องการใช้โปรเจ็กต์ Google Apps Script ให้เลือก Apps Script และระบุรหัสการติดตั้งใช้งานสำหรับโปรเจ็กต์
      • หากต้องการใช้ตัวแทน Dialogflow ให้เลือก Dialogflow แล้วเลือก Dialogflow CX หรือ Dialogflow ES จากนั้นระบุชื่อทรัพยากรของตัวแทน
      • หากต้องการใช้ Pub/Sub ให้เลือก Cloud Pub/Sub แล้วป้อนชื่อหัวข้อ

   3. ไม่บังคับ: หากต้องการกำหนดเส้นทางออบเจ็กต์เหตุการณ์ไปยังปลายทางหรือฟังก์ชันที่เฉพาะเจาะจง ให้ไปที่การตั้งค่าการเชื่อมต่อ > ทริกเกอร์ แล้วระบุหรืออัปเดตปลายทางหรือฟังก์ชัน Callback สำหรับทริกเกอร์ Chat ต่อไปนี้

      • หน้าแรกของแอป (หากเปิดใช้รองรับหน้าแรกของแอป): ผู้ใช้เปิดแท็บหน้าแรกในข้อความส่วนตัวแบบ 1:1 กับแอปใน Chat
      • เพิ่มไปยังพื้นที่ทำงาน: ผู้ใช้เพิ่มแอป Chat ไปยังการสนทนากลุ่มหรือพื้นที่ทำงาน หรือติดตั้งแอป Chat สำหรับข้อความแบบ 1:1
      • ข้อความ: ผู้ใช้ส่งข้อความไปยังแอปใน Chat เช่น ผู้ใช้ส่งข้อความส่วนตัวไปยังแอปใน Chat หรือ @พูดถึงแอปใน Chat ในพื้นที่ทำงานที่มีผู้ใช้หลายคน
      • นำออกจากพื้นที่ทำงาน: ผู้ใช้ถอนการติดตั้งหรือนำแอปใน Chat ออกจากพื้นที่ทำงาน
      • คำสั่งแอป: ผู้ใช้เรียกใช้คำสั่งด่วน คำสั่งเครื่องหมายทับ หรือการดำเนินการกับข้อความจากแอปใน Chat

   4. ไม่บังคับ: เพิ่มฟีเจอร์แบบอินเทอร์แอกทีฟอื่นๆ เช่น พรอมต์เริ่มต้น, คำสั่ง (คำสั่งด่วน คำสั่งเครื่องหมายทับ และการดำเนินการกับข้อความ) หรือการแสดงตัวอย่างลิงก์

   5. ในส่วนระดับการเข้าถึง ให้ระบุอีเมลของคุณเพื่อให้ติดตั้งและทดสอบแอปใน Chat ได้ก่อนที่จะเผยแพร่ไปยัง Google Workspace Marketplace คุณสามารถระบุบุคคลได้สูงสุด 5 คน หรือ Google Groups อย่างน้อย 1 กลุ่มจากองค์กร Google Workspace ของคุณ

5. ไม่บังคับ: ในส่วนบันทึก ให้เลือกช่องทำเครื่องหมายบันทึกข้อผิดพลาดไปยัง Logging เพื่อใช้ Google Cloud Logging โปรดดูข้อมูลเพิ่มเติมที่หัวข้อบันทึกข้อผิดพลาดในการค้นหาสำหรับแอปใน Chat

6. คลิกบันทึก

หลังจากบันทึกการกำหนดค่าแล้ว ทุกคนที่คุณระบุไว้ในการตั้งค่าระดับการเข้าถึงของ Chat API จะติดตั้ง ทดสอบ หรือใช้แอปใน Chat ได้ หากต้องการเริ่มทดสอบและแก้ไขข้อบกพร่องของแอปใน Chat โปรดดูหัวข้อทดสอบฟีเจอร์แบบอินเทอร์แอกทีฟสำหรับแอปใน Google Chat

กำหนดค่าแอปใน Chat โดยใช้ API ส่วนเสริมของ Google Workspace

แทนที่จะกำหนดค่าแอปใน Chat ด้วยตนเองในคอนโซล Google Cloud คุณสามารถใช้โปรเจ็กต์ที่อยู่ในระบบคลาวด์ Google Cloud ที่ลงทะเบียนในเวอร์ชันตัวอย่างสำหรับนักพัฒนาซอฟต์แวร์ Google Workspace เพื่ออ่านและอัปเดตการกำหนดค่าสำหรับแอปใน Chat ที่สร้างเป็นส่วนเสริมของ Google Workspace โดยใช้ทรัพยากร chatAppConfig ใน Google Workspace add-ons API แบบเป็นโปรแกรมได้

chatAppConfig เป็นทรัพยากร Singleton ที่มีอยู่เสมอสำหรับโปรเจ็กต์ที่อยู่ในระบบคลาวด์แต่ละโปรเจ็กต์ ก่อนที่คุณจะบันทึกการกำหนดค่าเป็นครั้งแรก ทรัพยากรจะมีการกำหนดค่าที่ว่างเปล่า (ซึ่งเป็นสิ่งที่ GetChatAppConfig แสดงผลด้วยหากคุณอ่านทรัพยากรก่อนการบันทึกครั้งแรก) เนื่องจากมีทรัพยากรอยู่แล้ว คุณจึงไม่จำเป็นต้องสร้างแยกต่างหาก โดยใช้ UpdateChatAppConfig ทั้งเพื่อบันทึกการกำหนดค่าเริ่มต้นและอัปเดตการกำหนดค่าที่มีอยู่

ข้อกำหนดเบื้องต้นและการตรวจสอบสิทธิ์

ก่อนเรียกใช้ GetChatAppConfig หรือ UpdateChatAppConfig ให้ทำตามข้อกำหนดเบื้องต้นต่อไปนี้ให้เสร็จสมบูรณ์

1. ลงทะเบียนโปรเจ็กต์ Google Cloud ในโปรแกรมตัวอย่างสำหรับนักพัฒนาซอฟต์แวร์ Google Workspace
2. เปิดใช้ API ส่วนเสริมของ Google Workspace (gsuiteaddons.googleapis.com) ในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ คุณสามารถเลือกเปิดใช้ Google Chat API (chat.googleapis.com) ได้หากต้องการดูหรืออัปเดตการกำหนดค่าแอปใน Chat ในคอนโซล Google Cloud หรือเรียกใช้ Chat API
3. ตรวจสอบสิทธิ์ในฐานะผู้ใช้ที่เป็นมนุษย์ด้วยข้อมูลเข้าสู่ระบบ OAuth 2.0 ที่มีขอบเขต https://www.googleapis.com/auth/cloud-platform ไม่รองรับการตรวจสอบสิทธิ์บัญชีบริการสำหรับเมธอด chatAppConfig
4. ตรวจสอบว่าผู้ใช้ที่ตรวจสอบสิทธิ์แล้วมีสิทธิ์ Identity and Access Management (IAM) ที่จำเป็นในโปรเจ็กต์ Cloud เป้าหมาย โดยทำดังนี้
   • gsuiteaddons.chatAppConfigs.get และ chat.bots.get เพื่ออ่านการกำหนดค่า (GetChatAppConfig)
   • gsuiteaddons.chatAppConfigs.update และ chat.bots.update เพื่ออัปเดตการกำหนดค่า (UpdateChatAppConfig)
5. หากคุณใช้ไลบรารีของไคลเอ็นต์ ให้ดาวน์โหลดไลบรารีของไคลเอ็นต์เวอร์ชันตัวอย่างสำหรับนักพัฒนาซอฟต์แวร์ด้วยบัญชีเวอร์ชันตัวอย่างสำหรับนักพัฒนาซอฟต์แวร์ที่ลงทะเบียนไว้

อัปเดตการกำหนดค่าแอปใน Chat

หากต้องการกำหนดค่าแอปใน Chat เป็นครั้งแรกหรืออัปเดตการกำหนดค่าที่มีอยู่ ให้ส่งคำขอ PATCH (UpdateChatAppConfig) ไปยังทรัพยากร Singleton chatAppConfig สำหรับโปรเจ็กต์ที่อยู่ในระบบคลาวด์

• สำหรับการบันทึกครั้งแรกในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ซึ่งมี chatAppConfig ที่ว่างเปล่า คุณต้องระบุ displayName (3-25 อักขระ) และ description (1-40 อักขระ) หากคุณละเว้น 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"
    ]
  }
}

แทนที่ข้อมูลต่อไปนี้ใน URL, ส่วนหัว และเนื้อหาของคำขอ

• PROJECT_NUMBER: หมายเลขโปรเจ็กต์ที่เป็นตัวเลขของโปรเจ็กต์ที่อยู่ในระบบคลาวด์ซึ่งโฮสต์แอปใน Chat ของคุณ
• ACCESS_TOKEN: โทเค็นเพื่อการเข้าถึง OAuth 2.0 ของผู้ใช้ที่ได้รับสิทธิ์ด้วยขอบเขต https://www.googleapis.com/auth/cloud-platform
• USER_EMAIL: อีเมลหรือ Google Group จากองค์กร Google Workspace ของคุณเพื่อเพิ่มลงในรายการที่อนุญาตสำหรับการทดสอบแอปใน Chat (เช่น อีเมลของคุณเอง)
• ฟิลด์กำหนดค่าตัวอย่างในเนื้อหาคำขอ (เช่น displayName, description, avatarUri และ interactiveFeatureConfig รวมถึงการกำหนดค่าปลายทาง, คำสั่ง, รูปแบบ URL ของตัวอย่างลิงก์ และผู้ใช้หลักในการทดสอบ) ที่มีค่าสำหรับแอปใน Chat ของคุณ โปรดดูรายละเอียดเกี่ยวกับฟิลด์และตัวเลือกปลายทางที่รองรับทั้งหมดที่หัวข้อข้อมูลอ้างอิง REST ของ projects.chatAppConfig และprojects.chatAppConfig.patch

ดูการกำหนดค่าแอปใน Chat

หากต้องการอ่านการกำหนดค่าแอปใน Chat ปัจจุบันสำหรับโปรเจ็กต์ที่อยู่ในระบบคลาวด์ ให้เรียกใช้ GetChatAppConfig คุณสามารถส่งพารามิเตอร์การค้นหา view (ChatAppConfigView) ที่ไม่บังคับได้ ดังนี้

• BASIC (ค่าเริ่มต้น): แสดงผลข้อมูลเมตาพื้นฐานโดยไม่มี interactiveFeatureConfig
• FULL: แสดงผลฟิลด์กำหนดค่าทั้งหมด รวมถึง interactiveFeatureConfig

หากยังไม่ได้บันทึกการกำหนดค่าแอปใน Chat สำหรับโปรเจ็กต์ที่อยู่ในระบบคลาวด์ เมธอดจะแสดงผลออบเจ็กต์ ChatAppConfig ที่ว่างเปล่า

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

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();

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 SDK
• แอปใน Chat จะไม่ใช้ชื่อและโลโก้ที่คุณกำหนดค่าไว้สำหรับแอปพลิเคชัน Google Workspace อื่นๆ ในออบเจ็กต์ addons.common ของไฟล์ Manifest
• สำหรับส่วนเสริมที่เผยแพร่ไปยัง Google Workspace Marketplace คุณจะบันทึกฉบับร่างของการเปลี่ยนแปลงการตั้งค่าการกำหนดค่า Google Chat API ไม่ได้ หลังจากอัปเดตและบันทึกการตั้งค่าการกำหนดค่า Chat API แล้ว แอปใน Chat ที่อัปเดตจะพร้อมใช้งานสำหรับผู้ใช้ที่มีอยู่ทั้งหมดทันที หากต้องการอัปเดตข้อมูลใน Marketplace คุณสามารถสร้างฉบับร่างก่อนส่งการเปลี่ยนแปลงได้
• หากคุณสร้างส่วนเสริมโดยใช้ Apps Script ให้ทำดังนี้
  • คุณต้องใช้รหัสการติดตั้งใช้งาน Apps Script เดียวกับที่ใช้สำหรับการกำหนดค่าส่วนเสริมที่เหลือ
  • คุณไม่สามารถใช้เครื่องมือแก้ไข Apps Script เพื่อติดตั้งการติดตั้งใช้งานทดสอบใน Chat ได้ แต่คุณต้องติดตั้งแอปจาก UI ของ Chat โดยตรง
• หากคุณสร้างส่วนเสริมโดยใช้บริการ HTTP ให้ละเว้นรายละเอียดการกำหนดค่าแอปใน Chat ในไฟล์ Manifest projects.deployments ที่คุณสร้างโดยใช้ API ส่วนเสริมของ Google Workspace การติดตั้งใช้งาน HTTP ที่คุณระบุใน SDK ของ Google Workspace Marketplace จะใช้สำหรับแอปพลิเคชัน Google Workspace อื่นๆ เท่านั้น แต่ให้กำหนดค่าแอปใน Chat ในคอนโซล Google Cloud หรือใช้ทรัพยากร chatAppConfig ใน API ส่วนเสริมของ Google Workspace แทน

ให้สิทธิ์ผู้อื่นในการกำหนดค่า Chat API

คุณสามารถให้สิทธิ์ผู้ใช้บางรายเข้าถึงหน้าการกำหนดค่าแอปใน Chat ได้โดยให้บทบาทเจ้าของแอปใน Chat หรือบทบาทผู้มีสิทธิ์ดูแอปใน Chat ใน Google Cloud Identity Access Management (IAM) ผู้ใช้ที่มีบทบาทเหล่านี้จะไม่สามารถไปยังหน้าการกำหนดค่าแอปใน Chat โดยใช้แดชบอร์ด API และบริการ แต่จะเข้าถึงหน้าการกำหนดค่าได้โดยไปยังคอนโซล Google Cloud สำหรับโปรเจ็กต์ที่อยู่ในระบบคลาวด์ซึ่งโฮสต์แอปใน Chat ดังนี้

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

โดยที่ PROJECT_ID คือรหัสโปรเจ็กต์ของโปรเจ็กต์ Google Cloud ที่โฮสต์แอปใน Chat

หัวข้อที่เกี่ยวข้อง

• เลือกสถาปัตยกรรมแอปใน Chat
• รับและตอบสนองต่อการโต้ตอบของผู้ใช้
• ทดสอบฟีเจอร์แบบอินเทอร์แอกทีฟสำหรับแอป Google Chat