이 페이지는 Cloud Translation API를 통해 번역되었습니다.

승인 범위

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

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

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

승인 흐름 중에 Apps Script는 사용자에게 필요한 범위에 관한 사람이 읽을 수 있는 설명을 표시합니다. 예를 들어 스크립트에 스프레드시트에 대한 읽기 전용 액세스 권한이 필요한 경우 매니페스트의 범위는 https://www.googleapis.com/auth/spreadsheets.readonly일 수 있습니다. 승인 흐름 중에 이 범위의 스크립트는 사용자에게 이 애플리케이션이 'Google Sheets를 볼 수 있도록' 허용해 달라고 요청합니다.

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

Apps Script IDE에서 직접 스크립트를 실행하는 등 스크립트가 실행되는 일부 노출 영역의 경우 사용자에게 세분화된 OAuth 동의 화면이 표시됩니다. 이렇게 하면 사용자가 모든 권한을 한 번에 부여하는 대신 부여할 특정 권한을 선택할 수 있습니다. 세분화된 OAuth 권한을 처리하도록 스크립트를 설계하는 것이 중요합니다.

범위 보기

다음을 실행하여 스크립트 프로젝트에 현재 필요한 범위를 확인할 수 있습니다.

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

명시적 범위 설정

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

Apps Script는 프로젝트에 매우 관대한 범위를 자동으로 할당하는 경우가 있습니다. 이는 스크립트가 필요 이상으로 사용자에게 요청한다는 의미일 수 있으며 이는 좋지 않은 관행입니다. 게시된 스크립트의 경우 광범위한 범위를 스크립트의 요구사항만 충족하는 더 제한적인 세트로 대체해야 합니다.

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

스크립트 프로젝트를 엽니다.
왼쪽에서 프로젝트 설정 을 클릭합니다.
편집기에 'appsscript.json' 매니페스트 파일 표시 체크박스를 선택합니다.
왼쪽에서 편집기 를 클릭합니다.
왼쪽에서 appsscript.json 파일을 클릭합니다.
oauthScopes로 라벨이 지정된 최상위 필드를 찾습니다. 이 옵션이 표시되지 않으면 추가할 수 있습니다.
oauthScopes 필드는 문자열 배열을 지정합니다. 프로젝트에서 사용하는 범위를 설정하려면 이 배열의 콘텐츠를 사용하려는 범위로 바꿉니다. 예를 들면 다음과 같습니다.
```
      {
        ...
        "oauthScopes": [
          "https://www.googleapis.com/auth/spreadsheets.readonly",
          "https://www.googleapis.com/auth/userinfo.email"
        ],
       ...
      }
```
상단에서 저장 을 클릭합니다.

세분화된 OAuth 권한 처리

세분화된 OAuth 동의 화면을 사용하면 사용자가 승인할 개별 OAuth 범위를 지정할 수 있습니다. 세분화된 OAuth 권한을 사용하면 각 스크립트와 공유할 계정 데이터를 더 세부적으로 제어할 수 있습니다. 예를 들어 이메일 및 캘린더 범위의 권한을 모두 요청하는 스크립트를 개발한다고 가정해 보겠습니다. 사용자는 Gmail이 아닌 Google Calendar의 기능에만 스크립트를 사용하고 싶어 할 수 있습니다. 세분화된 OAuth 권한을 사용하면 사용자는 Gmail이 아닌 캘린더 권한만 부여하도록 선택할 수 있습니다.

다음 섹션에서는 세분화된 OAuth 권한을 처리하는 주요 방법을 설명합니다.

필요한 범위에 대한 권한 자동 요구

실행 흐름이 작동하려면 범위에 대한 권한이 필요한 경우 사용자가 해당 권한을 부여해야 사용할 수 있습니다. 스크립트는 사용자가 이미 권한을 부여했는지 확인하고 부여하지 않은 경우 자동으로 권한을 요청할 수 있습니다.

ScriptApp 클래스의 다음 메서드를 사용하면 필수 범위에 대한 권한을 검증하고 누락된 권한을 요청하는 승인 메시지를 자동으로 렌더링할 수 있습니다.

requireScopes(authMode, oAuthScopes): 이 메서드는 스크립트에서 사용하는 모든 범위가 아닌 하나 이상의 범위에 종속되는 실행 흐름에 사용합니다.
requireAllScopes(authMode): 실행 흐름이 스크립트에서 사용하는 모든 범위에 종속되는 경우 이 메서드를 사용합니다.

예

다음 예는 requireScopes(authMode, oAuthScopes) 및 requireAllScopes(authMode) 메서드를 호출하는 방법을 보여줍니다. 이 스크립트는 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(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...
}

OAuth 확인

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

제한된 범위

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

게시하기 전에 제한된 범위의 전체 목록을 검토하세요. 앱에서 이러한 API를 사용하는 경우 게시 전에 특정 API 범위에 대한 추가 요구사항을 준수해야 합니다.