ผู้ใช้ต้องให้สิทธิ์ส่วนเสริมและแอปพลิเคชันอื่นๆ ที่เข้าถึงข้อมูลหรือดำเนินการในนามของผู้ใช้ เมื่อผู้ใช้เรียกใช้ ส่วนเสริมเป็นครั้งแรก UI ของ ส่วนเสริมจะแสดงข้อความแจ้งการให้สิทธิ์เพื่อเริ่ม ขั้นตอนการให้สิทธิ์
ในระหว่างขั้นตอนการทำงานนี้ พรอมต์จะแจ้งให้ผู้ใช้ทราบว่าแอปพลิเคชันต้องการ สิทธิ์ทำอะไร เช่น ส่วนเสริมอาจต้องการ สิทธิ์อ่านข้อความอีเมลของผู้ใช้หรือสร้างกิจกรรมในปฏิทินของผู้ใช้ โปรเจ็กต์สคริปต์ของส่วนเสริมจะกำหนดสิทธิ์แต่ละรายการเหล่านี้เป็นขอบเขต OAuth
คุณประกาศขอบเขตในไฟล์ Manifest โดยใช้สตริง URL
ในระหว่างโฟลว์การให้สิทธิ์ Apps Script จะแสดงคำอธิบายขอบเขตที่มนุษย์อ่านได้ต่อผู้ใช้ เช่น ส่วนเสริม Google Workspace อาจใช้ขอบเขต "อ่านข้อความปัจจุบัน" ซึ่งเขียนไว้ในไฟล์ Manifest เป็น https://www.googleapis.com/auth/gmail.addons.current.message.readonly ในระหว่างโฟลว์การให้สิทธิ์ ส่วนเสริมที่มีขอบเขตนี้จะขอให้ผู้ใช้อนุญาตให้ส่วนเสริมดูข้อความอีเมลเมื่อส่วนเสริมทำงาน
ขอบเขตที่ Apps Script ใช้สำหรับบริการต่างๆ จะทับซ้อนกับ ขอบเขตที่ API ที่เกี่ยวข้องใช้ เช่น บริการปฏิทินของ Apps Script ใช้ขอบเขตหลายอย่างที่เหมือนกับ Calendar API คุณสามารถ ค้นหาขอบเขตที่เมธอดบริการ Apps Script บางอย่างต้องการได้ในเอกสารอ้างอิงของ Apps Script
ดูขอบเขต
คุณดูขอบเขตที่โปรเจ็กต์สคริปต์ต้องใช้ในปัจจุบันได้โดยทำดังนี้
- เปิดโปรเจ็กต์สคริปต์
- คลิกภาพรวม ทางด้านซ้าย
- ดูขอบเขตในส่วน "ขอบเขต OAuth ของโปรเจ็กต์"
นอกจากนี้ คุณยังดูขอบเขตปัจจุบันของโปรเจ็กต์สคริปต์ได้ในไฟล์ Manifest ของโปรเจ็กต์
ในฟิลด์ oauthScopes
แต่จะดูได้ก็ต่อเมื่อคุณตั้งค่าขอบเขตเหล่านั้นอย่างชัดเจนเท่านั้น
ตั้งค่าขอบเขตที่ชัดเจน
Apps Script จะกำหนดขอบเขตที่สคริปต์ต้องการโดยอัตโนมัติ ด้วยการสแกนโค้ดเพื่อหาการเรียกฟังก์ชันที่ต้องใช้ขอบเขต สำหรับสคริปต์ส่วนใหญ่ การดำเนินการนี้ก็เพียงพอและช่วยประหยัดเวลา แต่สำหรับส่วนเสริมที่เผยแพร่แล้ว คุณควรควบคุมขอบเขตโดยตรงมากขึ้น
เช่น Apps Script อาจให้ขอบเขตที่อนุญาตมาก
แก่โปรเจ็กต์สคริปต์ส่วนเสริม
https://mail.google.comโดยค่าเริ่มต้น เมื่อผู้ใช้ให้สิทธิ์โปรเจ็กต์สคริปต์
ที่มีขอบเขตนี้ โปรเจ็กต์จะได้รับสิทธิ์เข้าถึงบัญชี Gmail ของผู้ใช้
อย่างเต็มรูปแบบ สำหรับส่วนเสริมที่เผยแพร่แล้ว คุณต้องแทนที่ขอบเขตนี้ด้วยชุดขอบเขตที่จำกัดมากขึ้นซึ่งครอบคลุมความต้องการของส่วนเสริมและไม่มีขอบเขตอื่น
คุณตั้งค่าขอบเขตที่โปรเจ็กต์สคริปต์ใช้ได้อย่างชัดเจนโดยการแก้ไขไฟล์Manifest ฟิลด์ Manifest
oauthScopes คืออาร์เรย์
ของขอบเขตทั้งหมดที่ส่วนเสริมใช้ หากต้องการตั้งค่าขอบเขตของโปรเจ็กต์ ให้ทำดังนี้
- ดูขอบเขตที่ส่วนเสริมใช้ พิจารณาว่าต้องทำการเปลี่ยนแปลงใดบ้าง เช่น การใช้ขอบเขตที่แคบลง
- เปิดไฟล์ Manifest ของส่วนเสริม
- ค้นหาฟิลด์ระดับบนสุดที่มีป้ายกำกับว่า
oauthScopesหากไม่มี คุณก็เพิ่มได้ ฟิลด์
oauthScopesระบุอาร์เรย์ของสตริง หากต้องการตั้งค่าขอบเขตที่โปรเจ็กต์ใช้ ให้แทนที่เนื้อหาของอาร์เรย์นี้ด้วยขอบเขตที่คุณต้องการให้ใช้ เช่น สำหรับส่วนเสริมของ Google Workspace ที่ขยาย Gmail คุณอาจมีสิ่งต่อไปนี้{ ... "oauthScopes": [ "https://www.googleapis.com/auth/gmail.addons.current.message.metadata", "https://www.googleapis.com/auth/userinfo.email" ], ... }บันทึกการเปลี่ยนแปลงไฟล์ Manifest
การยืนยัน OAuth
การใช้ขอบเขต OAuth ที่มีความละเอียดอ่อนบางอย่างอาจกำหนดให้ส่วนเสริมของคุณต้องผ่านการยืนยันไคลเอ็นต์ OAuth ก่อนจึงจะเผยแพร่ได้ ดูข้อมูลเพิ่มเติมได้ที่คู่มือต่อไปนี้
- การยืนยันไคลเอ็นต์ OAuth สำหรับ Apps Script
- แอปที่ไม่ผ่านการตรวจสอบ
- คำถามที่พบบ่อยเกี่ยวกับการยืนยัน OAuth
- บริการ Google API: นโยบายข้อมูลผู้ใช้
ขอบเขตที่จำกัด
ขอบเขตบางอย่างถูกจำกัดและอยู่ภายใต้กฎเพิ่มเติมที่ช่วยปกป้องข้อมูลผู้ใช้ หากคุณตั้งใจที่จะเผยแพร่ส่วนเสริม Gmail หรือ Editor ที่ใช้ขอบเขตที่ถูกจำกัดอย่างน้อย 1 รายการ ส่วนเสริมต้องเป็นไปตามข้อจำกัดที่ระบุทั้งหมด ก่อนจึงจะเผยแพร่ได้
โปรดดูรายการขอบเขตที่ถูกจำกัดทั้งหมด ก่อนที่จะพยายามเผยแพร่ หากส่วนเสริมใช้ API ใดๆ คุณต้องปฏิบัติตามข้อกำหนดเพิ่มเติมสำหรับขอบเขต API ที่เฉพาะเจาะจงก่อนเผยแพร่
ส่วนขยายเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์ Google Workspace สำหรับ Visual Studio Code จะให้ข้อมูลการวินิจฉัยสำหรับขอบเขตทั้งหมด ซึ่งรวมถึง คำอธิบายของขอบเขตและระบุว่าขอบเขตนั้นเป็นแบบละเอียดอ่อนหรือถูกจำกัดหรือไม่
เลือกขอบเขตสำหรับส่วนเสริมของ Google Workspace
ส่วนต่อไปนี้จะระบุขอบเขตที่ใช้กันโดยทั่วไปสำหรับ ส่วนเสริมของ Google Workspace
ขอบเขตของเอดิเตอร์
ขอบเขตที่ใช้บ่อยต่อไปนี้สำหรับส่วนเสริมของ Google Workspace จะขยาย Google เอกสาร, Google ชีต และ Google สไลด์
| ขอบเขต | |
|---|---|
| การเข้าถึงไฟล์เอกสารปัจจุบัน |
https://www.googleapis.com/auth/documents.currentonly
ต้องระบุหากส่วนเสริมเข้าถึง Google 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
ต้องระบุเพื่อให้ส่วนเสริมใช้
|
Gmail
โดยมีขอบเขตที่สร้างขึ้นสำหรับส่วนเสริมของ Google Workspace โดยเฉพาะเพื่อช่วยปกป้อง ข้อมูล Gmail ของผู้ใช้ เพิ่มขอบเขตเหล่านี้อย่างชัดเจนลงใน ไฟล์ Manifest ของส่วนเสริม พร้อมกับขอบเขตอื่นๆ ที่จำเป็น
ตารางต่อไปนี้แสดงขอบเขตที่ใช้บ่อยสำหรับส่วนเสริมของ Google Workspace ที่ ขยาย Gmail หากส่วนเสริมขยาย Gmail คุณต้องเพิ่มขอบเขตที่มีป้ายกำกับว่าต้องระบุลงใน ไฟล์ Manifest ของส่วนเสริม Google Workspace
แทนที่ขอบเขต https://mail.google.com ที่กว้างด้วยชุดขอบเขตที่แคบลง
ซึ่งอนุญาตให้มีการโต้ตอบที่ส่วนเสริมของคุณต้องการ
| ขอบเขต | |
|---|---|
| สร้างฉบับร่างใหม่ |
https://www.googleapis.com/auth/gmail.addons.current.action.compose
ต้องระบุหากส่วนเสริมใช้ ทริกเกอร์การดำเนินการเขียน อนุญาตให้ส่วนเสริมสร้างข้อความฉบับร่างและการตอบกลับใหม่ชั่วคราว ดูรายละเอียดได้ที่ การเขียนข้อความฉบับร่าง โดยมักใช้ขอบเขตนี้ กับ [compose actions] (/workspace/add-ons/gmail/extending-compose-ui) ต้องใช้โทเค็นเพื่อการเข้าถึง |
| อ่านข้อมูลเมตาของข้อความที่เปิด |
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
ต้องระบุหากส่วนเสริมต้องอ่าน
ข้อมูลเหตุการณ์ที่ผู้ใช้สร้างขึ้น อนุญาตให้ส่วนเสริมเข้าถึงข้อมูลเหตุการณ์ที่ผู้ใช้สร้างขึ้น
ข้อมูลนี้จะใช้ได้ก็ต่อเมื่อตั้งค่าฟิลด์ไฟล์ Manifest ของ
|
| เขียนข้อมูลเหตุการณ์ที่ผู้ใช้สร้างขึ้น |
https://www.googleapis.com/auth/calendar.addons.current.event.write
ต้องระบุหากส่วนเสริมต้องเขียน
ข้อมูลเหตุการณ์ที่ผู้ใช้สร้างขึ้น อนุญาตให้
ส่วนเสริมแก้ไขข้อมูลเหตุการณ์ที่ผู้ใช้สร้างขึ้น
ข้อมูลนี้จะใช้ได้ก็ต่อเมื่อตั้งค่าฟิลด์ไฟล์ Manifest ของ
|
ขอบเขตของ Google Chat
หากต้องการเรียกใช้ Google Chat API ให้ตรวจสอบสิทธิ์ในฐานะผู้ใช้ Google Chat หรือแอป Google Chat การตรวจสอบสิทธิ์แต่ละประเภทต้องใช้ขอบเขตที่แตกต่างกัน และไม่ใช่ว่าเมธอด Chat API ทั้งหมดจะรองรับการตรวจสอบสิทธิ์ของแอป
ดูข้อมูลเพิ่มเติมเกี่ยวกับขอบเขตของ Chat และประเภทการตรวจสอบสิทธิ์ได้ที่ Chat API ภาพรวมการตรวจสอบสิทธิ์และการให้สิทธิ์
ตารางต่อไปนี้แสดงเมธอดและขอบเขตของ Chat API ที่ใช้บ่อยตามประเภทการตรวจสอบสิทธิ์ที่รองรับ
| วิธีการ | รองรับการตรวจสอบสิทธิ์ของผู้ใช้ | รองรับการตรวจสอบสิทธิ์แอป | ขอบเขตการให้สิทธิ์ที่รองรับ | |
|---|---|---|---|---|
| ส่งข้อความ |
เมื่อใช้การตรวจสอบสิทธิ์ผู้ใช้ คุณจะทำสิ่งต่อไปนี้ได้
|
|||
| สร้างพื้นที่ทำงาน |
เมื่อใช้การตรวจสอบสิทธิ์ผู้ใช้ คุณจะทำสิ่งต่อไปนี้ได้
|
|||
| สร้างและเพิ่มสมาชิกไปยังพื้นที่ทำงาน | — |
เมื่อใช้การตรวจสอบสิทธิ์ผู้ใช้ คุณจะทำสิ่งต่อไปนี้ได้
|
||
| เพิ่มผู้ใช้ลงในพื้นที่ทำงาน |
เมื่อใช้การตรวจสอบสิทธิ์ผู้ใช้ คุณจะทำสิ่งต่อไปนี้ได้
|
|||
| แสดงกิจกรรมหรือเหตุการณ์จากพื้นที่ใน Chat | — |
เมื่อใช้การตรวจสอบสิทธิ์ผู้ใช้
คุณต้องใช้ขอบเขตสำหรับ
ประเภทเหตุการณ์ที่รวมอยู่ในคำขอ
|
||
ขอบเขตของ 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 Advanced Drive Service แต่จะไม่อนุญาตให้ดำเนินการที่คล้ายกันโดยใช้บริการไดรฟ์พื้นฐาน ระบบจะให้สิทธิ์ไฟล์เป็นแบบต่อไฟล์และจะเพิกถอนสิทธิ์เมื่อ ผู้ใช้ยกเลิกการให้สิทธิ์แอป ดู ตัวอย่างการขอสิทธิ์เข้าถึงไฟล์สำหรับไฟล์ที่เลือก |
โทเค็นเพื่อการเข้าถึง
ขอบเขต Gmail ที่ใช้ใน
ส่วนเสริมของ Google Workspace จะให้สิทธิ์เข้าถึงข้อมูลผู้ใช้ชั่วคราวเพื่อปกป้องข้อมูลผู้ใช้ หากต้องการเปิดใช้สิทธิ์เข้าถึงชั่วคราว
ให้เรียกใช้
GmailApp.setCurrentMessageAccessToken
โดยใช้โทเค็นเพื่อการเข้าถึงจาก
ออบเจ็กต์เหตุการณ์การดำเนินการ
โทเค็นเพื่อการเข้าถึงที่เปิดใช้ขอบเขต Gmail ไม่เหมือนกับ
โทเค็นเพื่อการเข้าถึงที่ ScriptApp.getOAuthToken แสดงผล ใช้โทเค็นที่ระบุไว้ใน
ออบเจ็กต์เหตุการณ์การดำเนินการ
ตัวอย่างต่อไปนี้แสดงการตั้งค่าโทเค็นเพื่อการเข้าถึงเพื่ออนุญาตให้เข้าถึงข้อมูลเมตาของข้อความ
ขอบเขตเดียวที่จำเป็นสำหรับตัวอย่างนี้คือ
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
อนุญาตให้โปรเจ็กต์ส่งคำขอ
|
| อ่านภาษาและเขตเวลาของผู้ใช้ |
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 ดูข้อมูลเพิ่มเติมได้ที่ สร้างแหล่งข้อมูลของบุคคลที่สามจากเมนู @ |