เชื่อมต่อส่วนเสริมของ Google Workspace กับบริการของบุคคลที่สาม

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

หากส่วนเสริมของ Google Workspace เชื่อมต่อกับบริการหรือ API ของบุคคลที่สามที่ต้องได้รับสิทธิ์ ส่วนเสริมจะแจ้งให้ผู้ใช้ลงชื่อเข้าใช้และให้สิทธิ์เข้าถึงได้

หน้านี้อธิบายวิธีตรวจสอบสิทธิ์ผู้ใช้โดยใช้ขั้นตอนการให้สิทธิ์ (เช่น OAuth) ซึ่งประกอบด้วยขั้นตอนต่อไปนี้

  1. ตรวจหาเมื่อต้องมีการให้สิทธิ์
  2. แสดงอินเทอร์เฟซของการ์ดที่แจ้งให้ผู้ใช้ลงชื่อเข้าใช้บริการ
  3. รีเฟรชส่วนเสริมเพื่อให้ผู้ใช้เข้าถึงบริการหรือทรัพยากรที่มีการป้องกันได้

หากส่วนเสริมต้องการเพียงข้อมูลประจําตัวของผู้ใช้ คุณจะตรวจสอบสิทธิ์ผู้ใช้ได้โดยตรงโดยใช้รหัส Google Workspace หรืออีเมล หากต้องการใช้อีเมลสําหรับการตรวจสอบสิทธิ์ โปรดดูการตรวจสอบคําขอ JSON หากคุณสร้างส่วนเสริมโดยใช้ Google Apps Script โปรดไปที่เอกสารประกอบ Apps Script เพื่อดูข้อมูลเกี่ยวกับการเชื่อมต่อส่วนเสริมกับบริการของบุคคลที่สาม

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

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

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

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

แจ้งให้ผู้ใช้ลงชื่อเข้าใช้บริการของคุณ

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

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

สร้างและส่งคืนการ์ดลงชื่อเข้าใช้

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

บัตรอนุมัติเบื้องต้น

ภาพต่อไปนี้แสดงตัวอย่างบัตรการอนุมัติพื้นฐานของ Google

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

หากต้องการใช้บัตรให้สิทธิ์พื้นฐาน ให้แสดงผลการตอบกลับ JSON ต่อไปนี้

{
  "basic_authorization_prompt": {
    "authorization_url": "AUTHORIZATION_REDIRECT",
    "resource": "RESOURCE_DISPLAY_NAME"
  }
}

แทนที่รายการต่อไปนี้

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

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

กำหนดการอนุมัติบัตร

หากต้องการแก้ไขข้อความแจ้งการให้สิทธิ์ คุณสามารถสร้างบัตรที่กำหนดเองสำหรับการลงชื่อเข้าใช้ของบริการได้

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

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

บัตรการให้สิทธิ์ที่กำหนดเองสำหรับ Cymbal Labs ซึ่งมีโลโก้ รายละเอียด และปุ่มลงชื่อเข้าใช้ของบริษัท

หากต้องการใช้ตัวอย่างการ์ดที่กำหนดเองนี้ ให้แสดงผลการตอบสนอง JSON ต่อไปนี้

{
  "custom_authorization_prompt": {
    "action": {
      "navigations": [
        {
          "pushCard": {
            "sections": [
              {
                "widgets": [
                  {
                    "image": {
                      "imageUrl": "LOGO_URL",
                      "altText": "LOGO_ALT_TEXT"
                    }
                  },
                  {
                    "divider": {}
                  },
                  {
                    "textParagraph": {
                      "text": "DESCRIPTION"
                    }
                  },
                  {
                    "buttonList": {
                      "buttons": [
                        {
                          "text": "Sign in",
                          "onClick": {
                            "openLink": {
                              "url": "AUTHORIZATION_REDIRECT",
                              "onClose": "RELOAD",
                              "openAs": "OVERLAY"
                            }
                          },
                          "color": {
                            "red": 0,
                            "green": 0,
                            "blue": 1,
                            "alpha": 1,
                          }
                        }
                      ]
                    }
                  },
                  {
                    "textParagraph": {
                      "text": "TEXT_SIGN_UP"
                    }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  }
}

แทนที่รายการต่อไปนี้

  • LOGO_URL: URL สำหรับโลโก้หรือรูปภาพ ต้องเป็น URL สาธารณะ
  • LOGO_ALT_TEXT: ข้อความแสดงแทนสำหรับโลโก้หรือรูปภาพ เช่น Cymbal Labs Logo
  • DESCRIPTION: คำกระตุ้นให้ดำเนินการ (Call-To-Action) เพื่อให้ผู้ใช้ลงชื่อเข้าใช้ เช่น Sign in to get started
  • วิธีอัปเดตปุ่มลงชื่อเข้าใช้
    • AUTHORIZATION_REDIRECT: URL สำหรับเว็บแอปที่จัดการการให้สิทธิ์
    • ไม่บังคับ: หากต้องการเปลี่ยนสีปุ่ม ให้อัปเดตค่าทศนิยม RGBA ของช่อง color
  • TEXT_SIGN_UP: ข้อความที่แจ้งให้ผู้ใช้สร้างบัญชีในกรณีที่ยังไม่มีบัญชี เช่น New to Cymbal Labs? <a href=\"https://www.example.com/signup\">Sign up</a> here