เชื่อมต่อแอป Chat กับบริการและเครื่องมืออื่นๆ

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

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

  1. ตรวจหาเมื่อต้องมีการให้สิทธิ์หรือการกำหนดค่า
  2. แสดงการ์ดการให้สิทธิ์พื้นฐานที่แจ้งให้ผู้ใช้ ลงชื่อเข้าใช้หรือกำหนดค่าบริการ
  3. เปลี่ยนเส้นทางไปยัง URI การดำเนินการเสร็จสมบูรณ์เพื่อให้ Google Chat ลองโต้ตอบเดิมอีกครั้งโดยอัตโนมัติหลังจากที่ผู้ใช้ดำเนินการ ให้สิทธิ์เสร็จสมบูรณ์

สถาปัตยกรรมของวิธีที่แอป Google Chat ตรวจสอบสิทธิ์กับบริการของบุคคลที่สาม

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

HTTP

แอป Google Chat ที่รับและตอบสนองต่อการโต้ตอบของผู้ใช้ หากต้องการสร้าง ให้ทำตามการเริ่มต้นใช้งาน HTTP

Apps Script

แอป Google Chat ที่รับและตอบสนองต่อการโต้ตอบของผู้ใช้ หากต้องการสร้าง ให้ทำตามการเริ่มต้นใช้งาน Apps Script อย่างรวดเร็ว

ตรวจหาว่าต้องมีการให้สิทธิ์

เมื่อโต้ตอบกับแอปใน Chat ผู้ใช้อาจไม่ได้รับอนุญาตให้เข้าถึงทรัพยากรที่ได้รับการปกป้องด้วยเหตุผลหลายประการ เช่น เหตุผลต่อไปนี้

  • ยังไม่ได้สร้างโทเค็นเพื่อการเข้าถึงเพื่อเชื่อมต่อกับบริการของบุคคลที่สาม หรือโทเค็นหมดอายุแล้ว
  • โทเค็นเพื่อการเข้าถึงไม่ครอบคลุมทรัพยากรที่ขอ
  • โทเค็นเพื่อการเข้าถึงไม่ครอบคลุมขอบเขตที่คำขอต้องระบุ

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

หากคุณสร้างใน Apps Script คุณสามารถใช้ไลบรารี OAuth2 สำหรับ Google Apps Script (หรือเวอร์ชัน OAuth1) ซึ่งฟังก์ชัน hasAccess จะตรวจสอบว่าผู้ใช้ได้ให้สิทธิ์เข้าถึง บริการหรือไม่ อีกทางหนึ่ง เมื่อใช้คำขอ UrlFetchApp.fetch คุณสามารถตั้งค่าพารามิเตอร์ muteHttpExceptions เป็น true เพื่อตรวจสอบ โค้ดตอบกลับและเนื้อหาในออบเจ็กต์ HttpResponse ที่ส่งคืน

แจ้งผู้ใช้ด้วยบัตรการให้สิทธิ์พื้นฐาน

เมื่อแอป Chat ตรวจพบว่าต้องมีการให้สิทธิ์หรือ การกำหนดค่า ให้ส่งคืนAuthorizationErrorการตอบกลับเพื่อแสดง การ์ดการให้สิทธิ์พื้นฐานแบบส่วนตัวแก่ผู้ใช้

รูปภาพต่อไปนี้แสดงตัวอย่างบัตรการให้สิทธิ์พื้นฐานของ Google

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

หากต้องการแจ้งให้ผู้ใช้ทราบด้วยบัตรการให้สิทธิ์พื้นฐาน ให้แสดงออบเจ็กต์ AuthorizationError ดังนี้

HTTP

ส่งคืนการตอบกลับ JSON ต่อไปนี้

{
  "basic_authorization_prompt": {
    "authorization_url": "<var>AUTHORIZATION_URL</var>",
    "resource": "<var>RESOURCE_DISPLAY_NAME</var>"
  }
}

Apps Script

CardService.newAuthorizationException()
    .setAuthorizationUrl('<var>AUTHORIZATION_URL</var>')
    .setResourceDisplayName('<var>RESOURCE_DISPLAY_NAME</var>')
    .throwException();

แทนที่ค่าต่อไปนี้

  • AUTHORIZATION_URL: HTTPS URL สำหรับเว็บแอปที่จัดการการตรวจสอบสิทธิ์ การให้สิทธิ์ หรือการกำหนดค่า
  • RESOURCE_DISPLAY_NAME: ชื่อที่แสดงสำหรับ ทรัพยากรหรือบริการที่ได้รับการปกป้อง ชื่อนี้จะแสดงต่อผู้ใช้ใน ข้อความแจ้งการให้สิทธิ์ เช่น หากRESOURCE_DISPLAY_NAMEของคุณคือ Example Account ข้อความแจ้งจะระบุว่าแอปต้องได้รับการอนุมัติเพื่อเข้าถึง Example Accountของคุณ

ดำเนินการตามคำขอการกำหนดค่าให้เสร็จสมบูรณ์

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

สำหรับทริกเกอร์เหล่านี้ แอป Chat จะได้รับ URI การเปลี่ยนเส้นทางเมื่อดำเนินการเสร็จสมบูรณ์ (configCompleteRedirectUri / completeRedirectUri) ใน เพย์โหลดของเหตุการณ์

  • ข้อความ: chat.messagePayload.configCompleteRedirectUri
  • เพิ่มลงในพื้นที่ทำงาน: chat.addedToSpacePayload.configCompleteRedirectUri
  • คำสั่งแอป: chat.appCommandPayload.configCompleteRedirectUri

คุณต้องเข้ารหัส URI การเปลี่ยนเส้นทางนี้ใน <var>AUTHORIZATION_URL</var> และ เปลี่ยนเส้นทางเบราว์เซอร์ของผู้ใช้ไปยัง URI นี้หลังจากขั้นตอนการให้สิทธิ์เสร็จสมบูรณ์ การเปลี่ยนเส้นทางไปยัง URL นี้จะส่งสัญญาณไปยัง Google Chat ว่าคำขอการให้สิทธิ์หรือ การกำหนดค่าได้รับการดำเนินการแล้ว

เมื่อเปลี่ยนเส้นทางผู้ใช้ไปยัง URI การเปลี่ยนเส้นทางเมื่อเสร็จสมบูรณ์ที่ระบุในเพย์โหลดของเหตุการณ์เดิมได้สำเร็จ Google Chat จะทำตามขั้นตอนต่อไปนี้

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

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

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

ตรวจสอบสิทธิ์ผู้ใช้ Chat นอก Chat

เมื่อลิงก์ไปยัง URL ภายนอก Chat (เช่น เว็บคอลแบ็ก OAuth) คุณมักจะต้องเชื่อมโยงเซสชันเว็บภายนอกกับข้อมูลประจำตัวผู้ใช้ใน Chat เราขอแนะนำให้คุณปกป้องเว็บแอปปลายทางด้วยการลงชื่อเข้าใช้ด้วย Google

ใช้โทเค็นข้อมูลประจำตัว ที่ออกให้ระหว่างการลงชื่อเข้าใช้เพื่อรับรหัสผู้ใช้ sub การอ้างสิทธิ์มีรหัส Google ที่ไม่ซ้ำกันของผู้ใช้ และเชื่อมโยงกับชื่อทรัพยากรผู้ใช้ (chat.user.name) จาก Google Chat ได้

หากต้องการเชื่อมโยงsubการอ้างสิทธิ์กับชื่อทรัพยากร users/{user} ของ Google Chat ให้เพิ่ม users/ ไว้หน้าค่าการอ้างสิทธิ์ sub เช่น subค่าการอ้างสิทธิ์ ของ 123 จะสอดคล้องกับ users/123 ในออบเจ็กต์เหตุการณ์ที่ส่งไปยังแอปแชท

ตัวอย่างโค้ด

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

แอป Chat ที่ไม่ใช่ส่วนเสริม: เชื่อมต่อแอป Chat กับบริการและเครื่องมืออื่นๆ

หากคุณดูแลแอป Chat ที่ไม่ใช่ส่วนเสริมของ Google Workspace แอป Chat จะขอการกำหนดค่าโดยใช้ actionResponse ประเภท REQUEST_CONFIG และอ่าน configCompleteRedirectUrl จากออบเจ็กต์ระดับบนสุด Event

หากต้องการอัปเกรดแอป Chat ที่ไม่ใช่ส่วนเสริมเป็นเฟรมเวิร์กส่วนเสริมของ Google Workspace โปรดดูหัวข้อแปลงแอป Google Chat เป็นส่วนเสริมของ Google Workspace

ขอการกำหนดค่าจากผู้ใช้ในแอป Chat ที่ไม่ใช่ส่วนเสริม

ในแอป Chat ที่ไม่ใช่ ส่วนเสริม ให้แสดง URL การกำหนดค่าแก่ผู้ใช้ในรูปแบบต่อไปนี้ 

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}

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

ส่งคำขอกำหนดค่าในแอป Chat ที่ไม่ใช่ส่วนเสริม

การโต้ตอบทุกครั้งของ MESSAGE, ADDED_TO_SPACE และ APP_COMMAND Event ที่แอป แชทที่ไม่ใช่ส่วนเสริม ได้รับจะมีฟิลด์ระดับบนสุด configCompleteRedirectUrl เข้ารหัส URL นี้ใน URL การกำหนดค่าและเปลี่ยนเส้นทางผู้ใช้ไปยัง URL นี้เมื่อดำเนินการเสร็จสิ้น เพื่อให้ Google Chat ลบพรอมต์ แปลงข้อความต้นฉบับเป็นสาธารณะ และส่งเหตุการณ์การโต้ตอบเดิมไปยังแอป Chat ของคุณอีกครั้ง

ดูตัวอย่างการใช้งานได้ที่ตัวอย่างแอปการเชื่อมต่อ Node.js และตัวอย่างแอปการตรวจสอบสิทธิ์ MyProfile ของ Python ใน GitHub