승인 범위

사용자는 자신의 데이터에 액세스하거나 자신을 대신하여 작업을 실행하는 스크립트 프로젝트를 승인해야 합니다. 사용자가 승인이 필요한 스크립트를 처음 실행하면 UI에 승인 흐름을 시작하라는 메시지가 표시됩니다.

이 흐름 중에 UI는 스크립트가 요청하는 권한을 사용자에게 알려줍니다. 예를 들어 스크립트에서 이메일 메시지를 읽거나 캘린더 일정을 만들 권한을 요청할 수 있습니다. 스크립트 프로젝트는 이러한 개별 권한을 OAuth 범위로 정의합니다.

대부분의 스크립트의 경우 Apps Script에서 필요한 범위를 자동으로 감지합니다. 언제든지 스크립트에서 사용하는 범위를 볼 수 있습니다. URL 문자열을 사용하여 매니페스트에서 범위를 명시적으로 설정할 수도 있습니다. 애드온과 같은 게시된 애플리케이션은 가능한 가장 좁은 범위를 사용해야 합니다.

승인 흐름 중에 Apps Script는 필요한 범위에 대한 사람이 읽을 수 있는 설명을 표시합니다. 예를 들어 스크립트에 스프레드시트에 대한 읽기 전용 액세스가 필요한 경우 매니페스트에 https://www.googleapis.com/auth/spreadsheets.readonly 범위가 포함될 수 있습니다. 승인 메시지에서 사용자에게 'Google 스프레드시트 보기'를 요청합니다.

일부 범위에는 다른 범위가 포함됩니다. 예를 들어 https://www.googleapis.com/auth/spreadsheets에 대한 승인된 액세스를 통해 스프레드시트에 대한 읽기 및 쓰기 액세스가 허용됩니다.

Apps Script IDE와 같은 일부 표시 경로의 경우 사용자에게 세분화된 OAuth 동의 화면이 표시됩니다. 이 화면을 통해 사용자는 모든 권한을 한 번에 부여하는 대신 부여할 특정 권한을 선택할 수 있습니다. 세분화된 OAuth 권한을 처리하도록 스크립트를 설계합니다.

범위 보기

스크립트 프로젝트에 필요한 범위를 확인하려면 다음 단계를 따르세요.

스크립트 프로젝트를 엽니다.
왼쪽에서 개요 를 클릭합니다.
프로젝트 OAuth 범위에서 범위를 확인합니다.

명시적 범위 설정

Apps Script는 함수 호출을 위해 코드를 스캔하여 필요한 범위를 자동으로 결정합니다. 대부분의 스크립트에서는 이 방법으로 충분하지만 게시된 부가기능, 웹 앱, Chat 앱, Chat API 호출의 경우에는 더 직접적인 제어를 사용해야 합니다.

Apps Script는 때때로 허용 범위가 넓은 범위를 자동으로 할당합니다. 이는 스크립트가 필요한 것보다 많은 액세스 권한을 사용자에게 요청할 수 있음을 의미합니다. 게시된 스크립트의 경우 광범위한 범위를 스크립트의 요구사항을 충족하는 제한된 범위로 대체합니다.

매니페스트 파일을 수정하여 스크립트 프로젝트에서 사용하는 범위를 명시적으로 설정할 수 있습니다. oauthScopes 매니페스트 필드는 프로젝트에서 사용하는 범위의 배열입니다. 프로젝트의 범위를 설정하려면 다음 단계를 따르세요.

스크립트 프로젝트를 엽니다.
왼쪽에서 프로젝트 설정 을 클릭합니다.
편집기에 'appsscript.json' 매니페스트 파일 표시 체크박스를 선택합니다.
왼쪽에서 편집기 를 클릭합니다.
왼쪽에서 appsscript.json 파일을 클릭합니다.
oauthScopes이라는 최상위 필드를 찾습니다. 이 값이 없으면 추가할 수 있습니다.

oauthScopes 배열의 콘텐츠를 프로젝트에서 사용할 범위로 바꿉니다. 예를 들면 다음과 같습니다.

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

상단에서 저장 을 클릭합니다.

세분화된 OAuth 권한 처리

세분화된 OAuth 동의 화면은 스크립트를 직접 실행하는 사용자를 위해 Apps Script IDE에 처음 출시되었습니다. 동의 화면은 시간이 지남에 따라 매크로, 트리거, 부가기능과 같은 다른 표시 경로에 점진적으로 출시됩니다. 자세한 내용은 Google Apps Script IDE 실행의 세부적인 OAuth 동의를 참고하세요.

세분화된 OAuth 동의 화면을 통해 사용자는 승인할 개별 OAuth 범위를 지정할 수 있습니다. 이를 통해 사용자는 각 스크립트와 공유하는 계정 데이터를 세부적으로 관리할 수 있습니다. 예를 들어 스크립트에서 이메일 및 캘린더 범위를 요청하는 경우 사용자는 Gmail이 아닌 캘린더 권한을 부여할 수 있습니다.

다음 섹션에서는 세부적인 OAuth 권한을 처리하는 방법을 설명합니다.

필요한 범위에 대한 권한을 자동으로 요구

실행 흐름에 특정 범위가 필요한 경우 사용자에게 해당 권한을 부여하도록 요구할 수 있습니다. 스크립트에서 권한을 확인하고 누락된 경우 자동으로 요청할 수 있습니다.

ScriptApp 클래스의 다음 메서드는 권한을 검증하고 승인 프롬프트를 렌더링합니다.

requireScopes(authMode, oAuthScopes): 특정 범위에 의존하는 흐름에 이 메서드를 사용합니다.
requireAllScopes(authMode): 실행 흐름이 모든 프로젝트 범위에 의존하는 경우 이 메서드를 사용합니다.

예

다음 예는 requireScopes() 및 requireAllScopes()를 호출하는 방법을 보여줍니다. 스크립트에서는 Gmail, Sheets, Calendar의 범위를 사용합니다. sendEmail() 함수에는 Gmail 및 Sheets의 범위만 필요하지만 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 확인

Google 사용자 데이터에 대한 액세스를 허용하는 특정 OAuth 범위는 민감합니다. 스크립트 프로젝트에서 사용자 데이터에 대한 액세스를 허용하는 범위를 사용하는 경우 웹 앱 또는 부록으로 공개적으로 게시하려면 프로젝트가 OAuth 클라이언트 인증을 통과해야 합니다. 자세한 내용은 다음 가이드를 참조하세요.

제한된 범위

민감한 범위 외에도 특정 범위는 제한됨으로 분류되며 사용자 데이터를 보호하는 데 도움이 되는 추가 규칙이 적용됩니다. 제한된 범위를 사용하는 앱을 게시하는 경우 모든 사양을 준수해야 합니다.

게시하기 전에 제한된 범위의 전체 목록을 검토하세요. 규정을 준수하는 앱은 특정 API 범위의 추가 요구사항을 따라야 합니다.

가능하면 제한된 범위를 사용하지 않아 검토 프로세스를 간소화하세요. 비공개 앱의 경우 제한된 범위를 자유롭게 사용할 수 있습니다.