กล้องติดปืน

ผู้ใช้ต้องให้สิทธิ์ส่วนเสริมและแอปพลิเคชันอื่นๆ ที่เข้าถึงข้อมูลของตนหรือดำเนินการในนามของผู้ใช้ เมื่อผู้ใช้เรียกใช้ส่วนเสริมเป็นครั้งแรก 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 เหล่านี้ คุณต้องปฏิบัติตามข้อกำหนดเพิ่มเติมสำหรับขอบเขตนั้นๆ ของ API ก่อนเผยแพร่

เลือกขอบเขตสำหรับส่วนเสริมของ Google Workspace

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

ขอบเขตผู้แก้ไข

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

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

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

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

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

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

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

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

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

Gmail

มีขอบเขต 2-3 รายการที่สร้างขึ้นมาสำหรับส่วนเสริมของ 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

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

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

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

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

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

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

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

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

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

ขอบเขตของ Google ไดรฟ์

ด้านล่างนี้คือขอบเขตที่ใช้บ่อยสำหรับส่วนเสริมของ 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 จะให้สิทธิ์เข้าถึงข้อมูลผู้ใช้ชั่วคราวเท่านั้น หากต้องการเปิดใช้สิทธิ์เข้าถึงชั่วคราว คุณต้องเรียกใช้ฟังก์ชัน 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

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

ตารางต่อไปนี้แสดงรายการขอบเขตที่ส่วนเสริมของ 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 ดูข้อมูลเพิ่มเติมได้ที่ สร้างทรัพยากรของบุคคลที่สามจากเมนู @