กล้องติดปืน

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

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

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

กําลังดูขอบเขต

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

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

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

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

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

ตัวอย่างเช่น 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

มีขอบเขต 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

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

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

ขอบเขต 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 และในกรณีที่ส่วนเสริมเข้าถึง Docs, Sheets, Slides หรือ Drive API ให้สิทธิ์เข้าถึงไฟล์ที่สร้างหรือเปิดแอปโดยแอปโดยใช้ บริการไดรฟ์ขั้นสูงของ Apps Script อย่างไรก็ตาม การดําเนินการนี้ไม่อนุญาตให้ใช้การดําเนินการที่คล้ายกันโดยใช้บริการไดรฟ์พื้นฐาน ระบบจะให้สิทธิ์ไฟล์ทีละไฟล์และ ถูกเพิกถอนเมื่อผู้ใช้ยกเลิกการให้สิทธิ์แอป

ขอบเขตอื่นๆ

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

โปรดดูรายการขอบเขตสคริปต์ Apps ที่มักใช้กับส่วนเสริมของ 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 ขณะที่ผู้ใช้กําลังโต้ตอบกับโปรเจ็กต์ ดูข้อมูลเพิ่มเติมได้ที่ แสดงตัวอย่างลิงก์ด้วยชิปอัจฉริยะ