กล้องติดปืน

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

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

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