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

승인 범위

사용자는 자신의 데이터에 액세스하거나 자신을 대신하여 작업을 실행하는 스크립트 프로젝트를 승인해야 합니다. 사용자가 승인이 필요한 스크립트를 처음 실행하면 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는 스크립트의 코드를 검사하여 스크립트에 필요한 범위를 자동으로 확인합니다. 대부분의 스크립트에서는 이 방법으로 충분하며 시간을 절약할 수 있지만 게시된 부가기능, 웹 앱, Google Chat 앱, Google 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 동의 화면을 통해 사용자는 승인하려는 개별 OAuth 범위를 지정할 수 있습니다. 세분화된 OAuth 권한을 통해 사용자는 각 스크립트와 공유할 계정 데이터를 더 세부적으로 관리할 수 있습니다. 예를 들어 이메일과 캘린더 범위에 대한 권한을 요청하는 스크립트를 개발한다고 가정해 보세요. 사용자가 Google Calendar 기능에만 스크립트를 사용하고 Gmail에는 사용하지 않기를 원할 수 있습니다. 세부적인 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("[email protected]", "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("[email protected]", "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("[email protected]", "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 클라이언트 인증을 통과해야 합니다. 자세한 내용은 다음 가이드를 참조하세요.

제한된 범위

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

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