ขอบเขตการให้สิทธิ์

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

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

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

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

ขอบเขตบางอย่างรวมถึงขอบเขตอื่นๆ เช่น เมื่อได้รับอนุญาต ขอบเขต https://www.googleapis.com/auth/spreadsheets จะอนุญาตสิทธิ์การอ่านและเขียนไปยัง สเปรดชีต

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

ดูขอบเขต

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

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

กำหนดขอบเขตอย่างชัดเจน

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

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

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

  1. เปิดโปรเจ็กต์สคริปต์
  2. คลิกการตั้งค่าโปรเจ็กต์ ทางด้านซ้าย
  3. เลือกช่องทำเครื่องหมายแสดงไฟล์ Manifest "appsscript.json" ในเครื่องมือแก้ไข
  4. คลิกโปรแกรมตัดต่อ ทางด้านซ้าย
  5. คลิกไฟล์ appsscript.json ทางด้านซ้าย
  6. ค้นหาฟิลด์ระดับบนสุดที่มีป้ายกำกับว่า oauthScopes หากไม่มี ให้เพิ่ม
  7. ฟิลด์ oauthScopes ระบุอาร์เรย์ของสตริง หากต้องการตั้งค่าขอบเขตที่โปรเจ็กต์ใช้ ให้แทนที่เนื้อหาของอาร์เรย์นี้ด้วยขอบเขตที่คุณต้องการให้ใช้ เช่น 
          {
        ...
        "oauthScopes": [
          "https://www.googleapis.com/auth/spreadsheets.readonly",
          "https://www.googleapis.com/auth/userinfo.email"
        ],
       ...
      }
  8. คลิกบันทึก ที่ด้านบน

จัดการสิทธิ์ OAuth แบบละเอียด

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

ส่วนต่อไปนี้จะอธิบายวิธีหลักๆ ในการจัดการสิทธิ์ OAuth แบบละเอียด

กำหนดให้ต้องขอสิทธิ์สำหรับขอบเขตที่จำเป็นโดยอัตโนมัติ

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

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

  • requireScopes(authMode, oAuthScopes) ใช้วิธีนี้สำหรับโฟลว์การดำเนินการที่ต้องอาศัยขอบเขตอย่างน้อย 1 รายการ แต่ไม่ใช่ขอบเขตทั้งหมด ที่สคริปต์ของคุณใช้
  • requireAllScopes(authMode): ใช้วิธีนี้หากโฟลว์การดำเนินการขึ้นอยู่กับขอบเขตทั้งหมดที่สคริปต์ของคุณใช้

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงวิธีเรียกใช้เมธอด requireScopes(authMode, oAuthScopes) และ requireAllScopes(authMode) สคริปต์ใช้ขอบเขตสำหรับ Gmail, ชีต และ ปฏิทิน ฟังก์ชัน sendEmail() ต้องการเฉพาะขอบเขตสำหรับ Gmail และ ชีต ส่วนฟังก์ชัน createEventSendEmail() ต้องการขอบเขตทั้งหมดที่สคริปต์ใช้

// This function requires the Gmail and Sheets scopes.
function sendEmail() {
  // Validates that the user has granted permission for the Gmail and Sheets scopes.
  // If not, the execution ends and prompts the user for authorization.
  ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
    'https://mail.google.com/',
    'https://www.googleapis.com/auth/spreadsheets'
  ]);

  // Sends an email.
  GmailApp.sendEmail("dana@example.com", "Subject", "Body");
  Logger.log("Email sent successfully!");

  // Opens a spreadsheet and sheet to track the sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Email Tracker")

  // Gets the last row of the sheet.
  const lastRow = sheet.getLastRow();

  // Adds "Sent" to column E of the last row of the spreadsheet.
  sheet.getRange(lastRow, 5).setValue("Sent");
  Logger.log("Sheet updated successfully!");
}

// This function requires all scopes used by the script (Gmail,
// Calendar, and Sheets).
function createEventSendEmail() {
  // Validates that the user has granted permission for all scopes used by the
  // script. If not, the execution ends and prompts the user for authorization.
  ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);

  // Creates an event.
  CalendarApp.getDefaultCalendar().createEvent(
    "Meeting",
    new Date("November 28, 2024 10:00:00"),
    new Date("November 28, 2024 11:00:00")
  );
  Logger.log("Calendar event created successfully!");

  // Sends an email.
  GmailApp.sendEmail("dana@example.com", "Subject 2", "Body 2");
  Logger.log("Email sent successfully!");

  // Opens a spreadsheet and sheet to track the created meeting and sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Email and Meeting Tracker")
  // Gets the last row
  const lastRow = sheet.getLastRow();

  // Adds "Sent" to column E of the last row
  sheet.getRange(lastRow, 5).setValue("Sent");
  // Adds "Meeting created" to column F of the last row
  sheet.getRange(lastRow, 6).setValue("Meeting created");
  Logger.log("Sheet updated successfully!");
}

สร้างประสบการณ์การใช้งานที่กำหนดเองสำหรับขอบเขตที่ขาดหายไป

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

  • getAuthorizationInfo(authMode, oAuthScopes): ใช้วิธีนี้เพื่อตรวจสอบสถานะสิทธิ์สำหรับขอบเขตที่เฉพาะเจาะจง
  • getAuthorizationInfo(authMode): ใช้วิธีนี้เพื่อตรวจสอบสถานะสิทธิ์สำหรับขอบเขตทั้งหมดที่สคริปต์ของคุณใช้

หากต้องการดูรายละเอียดสิทธิ์จากออบเจ็กต์ข้อมูลการให้สิทธิ์ เช่น รายการ ของขอบเขตที่ได้รับอนุญาตและ URL สำหรับขอสิทธิ์ที่ขาดหายไป ให้ใช้วิธีการจากคลาส AuthorizationInfo

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงวิธีเรียกใช้เมธอด getAuthorizationInfo(authMode, oAuthScopes) เพื่อข้ามฟีเจอร์ที่เฉพาะเจาะจง ภายในโฟลว์การดำเนินการที่ยังไม่ได้รับขอบเขตที่จำเป็น ซึ่งจะ ช่วยให้ขั้นตอนการดำเนินการที่เหลือดำเนินต่อไปได้โดยไม่ต้องแจ้งให้ขอ สิทธิ์ขอบเขตที่ขาดหายไป

// This function uses the Gmail scope and skips the email
// capabilities if the scope for Gmail hasn't been granted.
function myFunction() {
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL, ['https://mail.google.com/']);
  if (authInfo.getAuthorizationStatus() === ScriptApp.AuthorizationStatus.NOT_REQUIRED) {
    GmailApp.sendEmail("dana@example.com", "Subject", "Body");
    Logger.log("Email sent successfully!");
  } else {
    const scopesGranted = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL).getAuthorizedScopes();
    console.warn(`Authorized scopes: ${scopesGranted} not enough to send mail, skipping.`);
  }
  // Continue the rest of the execution flow...
}

ตรวจสอบว่าการเรียกใช้ทริกเกอร์มีสิทธิ์

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

ตัวอย่าง

// This function requires scope Sheets.
function trackFormSubmissions(e){
  // Opens a spreadsheet to track the sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Submission Tracker")

  // Gets the last row of the sheet.
  const lastRow = sheet.getLastRow();

  // Adds email address of user that submitted the form
  // to column E of the last row of the spreadsheet.
  sheet.getRange(lastRow, 5).setValue(e.name);
  Logger.log("Sheet updated successfully!");
}


function installTrigger(){
  // Validates that the user has granted permissions for trigger
  // installation and execution. If not, trigger doesn't get
  // installed and prompts the user for authorization.
  ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
    'https://www.googleapis.com/auth/script.scriptapp',
    'https://www.googleapis.com/auth/spreadsheets',
    'https://www.googleapis.com/auth/forms.currentonly'
  ]);
  ScriptApp.newTrigger('trackFormSubmission')
    .forForm(FormApp.getActiveForm())
    .onFormSubmit()
    .create();
}

การยืนยัน OAuth

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

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

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

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