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

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

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

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

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

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

1. เปิดโปรเจ็กต์สคริปต์
2. คลิกการตั้งค่าโปรเจ็กต์ settingsทางด้านซ้าย
3. เลือกช่องทำเครื่องหมายแสดงไฟล์ Manifest "appsscript.json" ในเครื่องมือแก้ไข
4. คลิกโปรแกรมตัดต่อ code ทางด้านซ้าย
5. คลิกไฟล์ appsscript.json ทางด้านซ้าย
6. ค้นหาฟิลด์ระดับบนสุดที่มีป้ายกำกับว่า oauthScopes หากไม่มี ให้เพิ่ม
7. แทนที่เนื้อหาของอาร์เรย์ oauthScopes ด้วยขอบเขตที่คุณต้องการให้โปรเจ็กต์ใช้ เช่น

         {
           ...
           "oauthScopes": [
             "https://www.googleapis.com/auth/spreadsheets.readonly",
             "https://www.googleapis.com/auth/userinfo.email"
           ],
          ...
         }

8. คลิกบันทึก save ที่ด้านบน

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

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

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

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

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

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

วิธีการต่อไปนี้จากคลาส ScriptApp จะตรวจสอบสิทธิ์และแสดงข้อความแจ้งการให้สิทธิ์

• requireScopes(authMode, oAuthScopes): ใช้วิธีนี้สำหรับโฟลว์ที่ต้องใช้ขอบเขตที่เฉพาะเจาะจง
• requireAllScopes(authMode): ใช้วิธีนี้หากโฟลว์การดำเนินการขึ้นอยู่กับขอบเขตของโปรเจ็กต์ทั้งหมด

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงวิธีเรียกใช้ requireScopes() และ requireAllScopes() สคริปต์ใช้ขอบเขตสำหรับ 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() เพื่อข้ามฟีเจอร์ ในกรณีที่ผู้ใช้ไม่ได้ให้ขอบเขตที่จำเป็น ซึ่งจะช่วยให้ขั้นตอนการดำเนินการที่เหลือดำเนินต่อไปได้โดยไม่ต้องแจ้งให้ขอสิทธิ์ขอบเขตที่ขาดหายไป

// 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 ก่อน จึงจะเผยแพร่เป็นเว็บแอปหรือส่วนเสริมต่อสาธารณะได้ ดูข้อมูลเพิ่มเติมได้ที่คู่มือต่อไปนี้

• การยืนยันไคลเอ็นต์ OAuth สำหรับ Apps Script
• แอปที่ไม่ผ่านการตรวจสอบ
• คำถามที่พบบ่อยเกี่ยวกับการยืนยัน OAuth
• บริการ Google API: นโยบายข้อมูลผู้ใช้

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

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

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

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