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

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

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

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

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

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