กล้องติดปืน

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

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

คุณประกาศขอบเขตในไฟล์ Manifest โดยใช้สตริง URL ในระหว่างขั้นตอนการให้สิทธิ์ Apps Script จะแสดงคำอธิบายขอบเขตที่มนุษย์อ่านได้แก่ผู้ใช้ ตัวอย่างเช่น ส่วนเสริม Google Workspace อาจใช้ขอบเขต "อ่านข้อความปัจจุบัน" ซึ่งเขียนในไฟล์ Manifest เป็น https://www.googleapis.com/auth/gmail.addons.current.message.readonly ในระหว่างขั้นตอนการให้สิทธิ์ ส่วนเสริมที่มีขอบเขตนี้จะขอให้ผู้ใช้อนุญาตส่วนเสริมเพื่อดูข้อความอีเมลเมื่อส่วนเสริมทำงานอยู่

ขอบเขตการดู

คุณดูขอบเขตที่โปรเจ็กต์สคริปต์ต้องการในปัจจุบันได้โดยทำตามขั้นตอนต่อไปนี้

  1. เปิดโปรเจ็กต์สคริปต์
  2. ทางด้านซ้าย ให้คลิกภาพรวม
  3. ดูขอบเขตในส่วน "ขอบเขต OAuth ของโครงการ"

คุณยังดูขอบเขตปัจจุบันของโปรเจ็กต์สคริปต์ในไฟล์ Manifest ของโปรเจ็กต์ในช่อง oauthScopes ได้ แต่จะดูก็ต่อเมื่อคุณตั้งค่าขอบเขตเหล่านั้นเป็นอย่างชัดแจ้งเท่านั้น

การตั้งค่าขอบเขตที่ชัดเจน

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

เช่น Apps Script อาจกำหนดขอบเขต https://mail.google.com ที่ผ่อนปรนมากให้โปรเจ็กต์สคริปต์ส่วนเสริมโดยค่าเริ่มต้น เมื่อผู้ใช้ให้สิทธิ์โปรเจ็กต์สคริปต์ที่มีขอบเขตนี้ โปรเจ็กต์จะได้รับสิทธิ์เข้าถึงบัญชี Gmail ของผู้ใช้อย่างเต็มรูปแบบ สำหรับส่วนเสริมที่เผยแพร่ คุณต้องแทนที่ขอบเขตนี้ด้วยชุดที่จำกัดมากขึ้นซึ่งจะครอบคลุมความต้องการของส่วนเสริม และไม่ต้องเพิ่มขอบเขตใดๆ อีก

คุณตั้งค่าขอบเขตที่โปรเจ็กต์สคริปต์จะใช้อย่างชัดเจนได้โดยแก้ไขไฟล์ไฟล์ Manifest ช่องไฟล์ Manifest oauthScopes เป็นอาร์เรย์ของขอบเขตทั้งหมดที่ส่วนเสริมใช้ หากต้องการกำหนดขอบเขตของโปรเจ็กต์ ให้ทำดังนี้

  1. ดูขอบเขตที่ส่วนเสริมใช้อยู่ในปัจจุบัน ระบุสิ่งที่ต้องทำการเปลี่ยนแปลง เช่น การใช้ขอบเขตที่แคบลง
  2. เปิดไฟล์ Manifest ของส่วนเสริม
  3. ค้นหาฟิลด์ระดับบนสุดที่มีป้ายกำกับ oauthScopes แต่หากไม่มี คุณก็เพิ่มได้
  4. ช่อง oauthScopes จะระบุอาร์เรย์ของสตริง หากต้องการตั้งค่าขอบเขตที่โปรเจ็กต์ใช้ ให้แทนที่เนื้อหาของอาร์เรย์นี้ด้วยขอบเขตที่คุณต้องการใช้ เช่น สําหรับส่วนเสริมของ Google Workspace ที่ขยายการใช้งานของ Gmail คุณอาจมีสิ่งต่อไปนี้

    {
      ...
      "oauthScopes": [
        "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
        "https://www.googleapis.com/auth/userinfo.email"
      ],
      ...
    }
    
  5. บันทึกการเปลี่ยนแปลงในไฟล์ Manifest

การยืนยัน OAuth

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

ขอบเขตที่จำกัด

บางขอบเขตมีการจำกัดและขึ้นอยู่กับกฎเพิ่มเติมที่จะช่วยปกป้องข้อมูลผู้ใช้ หากต้องการเผยแพร่ Gmail หรือส่วนเสริมของ Editor ที่ใช้ขอบเขตที่จำกัด 1 รายการขึ้นไป ส่วนเสริมต้องเป็นไปตามข้อจำกัดที่ระบุไว้ทั้งหมดก่อนจึงจะเผยแพร่ได้

ตรวจสอบรายการขอบเขตที่จำกัดทั้งหมดก่อนพยายามเผยแพร่ หากส่วนเสริมของคุณใช้อย่างใดอย่างหนึ่งไปใช้ คุณต้องปฏิบัติตามข้อกำหนดเพิ่มเติมสำหรับขอบเขต API เฉพาะก่อนการเผยแพร่

ขอบเขตของปฏิทิน

ด้านล่างนี้คือขอบเขตที่ใช้บ่อยสำหรับส่วนเสริมของ Google Workspace ที่ขยายการใช้งานของ Google ปฏิทิน

ขอบเขต
เข้าถึงข้อมูลเมตาของเหตุการณ์ https://www.googleapis.com/auth/calendar.addons.execute

ต้องระบุหากส่วนเสริมเข้าถึงข้อมูลเมตาของกิจกรรมในปฏิทิน อนุญาตให้ส่วนเสริมเข้าถึงข้อมูลเมตาของเหตุการณ์

อ่านข้อมูลเหตุการณ์ที่ผู้ใช้สร้างขึ้น https://www.googleapis.com/auth/calendar.addons.current.event.read

ต้องระบุหากส่วนเสริมจำเป็นต้องอ่านข้อมูลเหตุการณ์ที่ผู้ใช้สร้างขึ้น อนุญาตให้ส่วนเสริมเข้าถึงข้อมูลเหตุการณ์ที่ผู้ใช้สร้างขึ้น ข้อมูลนี้ใช้ได้เฉพาะเมื่อตั้งค่า ช่องไฟล์ Manifest addOns.calendar.eventAccess เป็น READ หรือ READ_WRITE

เขียนข้อมูลเหตุการณ์ที่ผู้ใช้สร้างขึ้น https://www.googleapis.com/auth/calendar.addons.current.event.write

ต้องระบุหากส่วนเสริมต้องเขียนข้อมูลเหตุการณ์ที่ผู้ใช้สร้างขึ้น อนุญาตให้ส่วนเสริมแก้ไขข้อมูลเหตุการณ์ที่ผู้ใช้สร้างขึ้น ข้อมูลนี้ใช้ได้เฉพาะเมื่อตั้งค่า ช่องไฟล์ Manifest addOns.calendar.eventAccess เป็น WRITE หรือ READ_WRITE

ขอบเขตไดรฟ์

ด้านล่างนี้คือขอบเขตที่ใช้บ่อยสำหรับส่วนเสริม Google Workspace ที่ขยายการใช้งานของ Google ไดรฟ์

ขอบเขต
อ่านข้อมูลเมตาของรายการที่เลือก https://www.googleapis.com/auth/drive.addons.metadata.readonly

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

สิทธิ์เข้าถึงต่อไฟล์ https://www.googleapis.com/auth/drive.file

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

ดู ตัวอย่างการขอสิทธิ์เข้าถึงไฟล์สำหรับไฟล์ที่เลือก

ขอบเขตส่วนเสริมของ Gmail

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

ด้านล่างนี้คือขอบเขตที่ใช้บ่อยสำหรับส่วนเสริมของ Google Workspace ที่ขยายการใช้งานของ Gmail คุณต้องเพิ่มขอบเขตที่มีป้ายกำกับว่าจำเป็นลงในไฟล์ Manifest ของส่วนเสริม Google Workspace หากส่วนเสริมขยายการใช้งาน Gmail

อย่าลืมเปลี่ยนขอบเขต https://mail.google.com ที่กว้างมากในส่วนเสริมด้วยชุดขอบเขตที่แคบลงซึ่งจะทำให้มีการโต้ตอบกับส่วนเสริมของคุณได้ตามต้องการ

ขอบเขต
สร้างฉบับร่างใหม่ https://www.googleapis.com/auth/gmail.addons.current.action.compose

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

อ่านข้อมูลเมตาของข้อความที่เปิดอยู่ https://www.googleapis.com/auth/gmail.addons.current.message.metadata

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

ต้องระบุหากส่วนเสริมใช้ข้อมูลเมตาในทริกเกอร์การดำเนินการเขียน สำหรับ การดำเนินการเขียน จำเป็นต้องใช้ขอบเขตนี้หากทริกเกอร์การเขียนจำเป็นต้องเข้าถึงข้อมูลเมตา ในทางปฏิบัติ ขอบเขตนี้ช่วยให้การเขียนรายชื่อผู้รับเข้าถึง (ถึง:, สำเนา: และสำเนาลับ:) ของอีเมลฉบับร่างตอบกลับได้

อ่านเนื้อหาข้อความที่เปิดอยู่ https://www.googleapis.com/auth/gmail.addons.current.message.action

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

อ่านเนื้อหาของชุดข้อความที่เปิดอยู่ https://www.googleapis.com/auth/gmail.addons.current.message.readonly

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

อ่านเนื้อหาและข้อมูลเมตาของข้อความทั้งหมด https://www.googleapis.com/auth/gmail.readonly

อ่านข้อมูลเมตาและเนื้อหาของอีเมล รวมถึงข้อความที่เปิดอยู่ ต้องระบุหากคุณต้องการอ่านข้อมูลเกี่ยวกับข้อความอื่นๆ เช่น เมื่อดำเนินการค้นหาหรืออ่านชุดข้อความอีเมลทั้งหมด

โทเค็นเพื่อการเข้าถึง

เพื่อปกป้องข้อมูลผู้ใช้ ขอบเขต Gmail ที่ใช้ในส่วนเสริม Google Workspace จะให้สิทธิ์เข้าถึงข้อมูลผู้ใช้ชั่วคราวเท่านั้น หากต้องการเปิดใช้การเข้าถึงชั่วคราว คุณต้องเรียกใช้ฟังก์ชัน GmailApp.setCurrentMessageAccessToken(accessToken) โดยใช้โทเค็นเพื่อการเข้าถึงเป็นอาร์กิวเมนต์ คุณต้องรับโทเค็นเพื่อการเข้าถึงจากออบเจ็กต์เหตุการณ์การดำเนินการ

ตัวอย่างต่อไปนี้แสดงตัวอย่างการตั้งค่าโทเค็นเพื่อการเข้าถึงเพื่ออนุญาตให้เข้าถึงข้อมูลเมตาของข้อความ ขอบเขตเดียวที่จำเป็นสำหรับตัวอย่างนี้คือ https://www.googleapis.com/auth/gmail.addons.current.message.metadata

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

ขอบเขตของเครื่องมือแก้ไข

ด้านล่างนี้คือขอบเขตที่ใช้บ่อยสำหรับส่วนเสริม Google Workspace ที่ขยายการใช้งานเอกสาร ชีต และสไลด์

ขอบเขต
การเข้าถึงไฟล์เอกสารในปัจจุบัน https://www.googleapis.com/auth/documents.currentonly

ต้องระบุหากส่วนเสริมเข้าถึง API เอกสาร Apps Script ให้สิทธิ์เข้าถึงเนื้อหาในเอกสารที่เปิดอยู่ชั่วคราว

สิทธิ์เข้าถึงไฟล์ชีตในปัจจุบัน https://www.googleapis.com/auth/spreadsheets.currentonly

ต้องระบุหากส่วนเสริมเข้าถึง Apps Script Sheets API ให้สิทธิ์เข้าถึงเนื้อหาของสเปรดชีตที่เปิดอยู่ชั่วคราว

การเข้าถึงไฟล์สไลด์ในปัจจุบัน https://www.googleapis.com/auth/presentations.currentonly

ต้องระบุหากส่วนเสริมเข้าถึง API สไลด์ Apps Script ให้สิทธิ์เข้าถึงเนื้อหาของงานนำเสนอที่เปิดอยู่ชั่วคราว

สิทธิ์เข้าถึงต่อไฟล์ https://www.googleapis.com/auth/drive.file

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

ขอบเขตอื่นๆ

ส่วนเสริมอาจต้องใช้ขอบเขตเพิ่มเติมหากใช้บริการ Apps Script อื่นๆ ในกรณีส่วนใหญ่ คุณสามารถอนุญาตให้ Apps Script ตรวจหาขอบเขตเหล่านี้และอัปเดตไฟล์ Manifest โดยอัตโนมัติได้ เมื่อแก้ไขรายการขอบเขตของไฟล์ Manifest โปรดอย่านำขอบเขตใดๆ ออก เว้นแต่ว่าคุณจะแทนที่ด้วยขอบเขตอื่นที่เหมาะสมกว่า เช่น ขอบเขตที่แคบลง

ต่อไปนี้เป็นรายการขอบเขต Apps Script ที่มักจะใช้ร่วมกับส่วนเสริม Google Workspace

ขอบเขต
อ่านอีเมลของผู้ใช้ https://www.googleapis.com/auth/userinfo.email

อนุญาตให้โปรเจ็กต์อ่านอีเมลของผู้ใช้ปัจจุบัน

อนุญาตให้โทรหาบริการภายนอก https://www.googleapis.com/auth/script.external_request

อนุญาตให้โปรเจ็กต์ส่งคำขอ UrlFetch ซึ่งจำเป็นหากโปรเจ็กต์ใช้ไลบรารี OAuth2 สำหรับ Apps Script

อ่านภาษาและเขตเวลาของผู้ใช้ https://www.googleapis.com/auth/script.locale

อนุญาตให้โปรเจ็กต์เรียนรู้ภาษาและเขตเวลาของผู้ใช้ปัจจุบัน โปรดดูรายละเอียดที่ การเข้าถึงภาษาและเขตเวลาของผู้ใช้

สร้างทริกเกอร์ https://www.googleapis.com/auth/script.scriptapp

อนุญาตให้โปรเจ็กต์สร้าง ทริกเกอร์

แสดงตัวอย่างลิงก์ของบุคคลที่สาม https://www.googleapis.com/auth/workspace.linkpreview

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

สร้างทรัพยากรของบุคคลที่สาม https://www.googleapis.com/auth/workspace.linkcreate

ต้องระบุหากส่วนเสริมสร้างทรัพยากรในบริการของบุคคลที่สาม อนุญาตให้โปรเจ็กต์อ่านข้อมูลที่ผู้ใช้ส่งไปยังแบบฟอร์มการสร้างทรัพยากร และแทรกลิงก์ไปยังทรัพยากรนั้นในแอปพลิเคชัน Google Workspace ดูข้อมูลเพิ่มเติมได้ที่ สร้างทรัพยากรของบุคคลที่สามจากเมนู @