범위

사용자는 자신의 데이터에 액세스하거나 사용자를 대신하여 작업하는 부가기능 및 기타 애플리케이션을 승인해야 합니다. 사용자가 부가기능을 처음 실행하면 부가기능 UI에 승인 절차를 시작하기 위한 승인 메시지가 표시됩니다.

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

URL 문자열을 사용하여 매니페스트에서 범위를 선언합니다. 승인 흐름 중에 Apps Script는 사용자에게 사람이 읽을 수 있는 범위 설명을 표시합니다. 예를 들어 Google Workspace 부가기능은 매니페스트에 https://www.googleapis.com/auth/gmail.addons.current.message.readonly로 작성된 '현재 메시지 읽기' 범위를 사용할 수 있습니다. 승인 흐름 중에 이 범위의 부가기능은 사용자에게 부가기능이 실행 중일 때 이메일 메시지를 볼 수 있도록 허용할지 묻습니다.

참고: Apps Script가 다양한 서비스에 사용하는 범위는 관련 API에서 사용하는 범위와 겹칩니다. 예를 들어 Apps Script의 Calendar 서비스는 Calendar API와 동일한 범위를 많이 사용합니다. Apps Script 참조 문서에서 특정 Apps Script 서비스 메서드에 필요한 범위를 확인할 수 있습니다.

범위 보기

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

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

이러한 범위를 명시적으로 설정한 경우에만 프로젝트 매니페스트의 oauthScopes 필드에서 스크립트 프로젝트의 현재 범위를 볼 수도 있습니다.

명시적 범위 설정

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

예를 들어 Apps Script는 기본적으로 부가기능 스크립트 프로젝트에 매우 관대한 범위 https://mail.google.com를 부여할 수 있습니다. 사용자가 이 범위로 스크립트 프로젝트를 승인하면 프로젝트에 사용자의 Gmail 계정에 대한 전체 액세스 권한이 부여됩니다. 게시된 부가기능의 경우 이 범위를 부가기능의 요구사항만 충족하는 더 제한된 세트로 대체해야 합니다.

경고: 항상 가능한 한 최소 권한을 지닌 범위 집합을 사용하세요. 사용자 정보를 보호하기 위해 부가기능 및 기타 게시된 애플리케이션은 절대적으로 필요한 범위 권한보다 더 많은 범위 권한을 요청해서는 안 됩니다. 부가기능에 필요한 범위는 게시 부가기능 검토 과정에서 검토됩니다. 부가기능이 너무 광범위한 범위를 사용하는 경우 검토를 통과할 수 없습니다.

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

1. 현재 부가기능에서 사용하는 범위를 확인합니다. 더 좁은 범위 사용과 같이 어떤 변경사항을 적용해야 하는지 결정합니다.
2. 부가기능의 매니페스트 파일을 엽니다.
3. oauthScopes로 라벨이 지정된 최상위 필드를 찾습니다. 이 옵션이 없는 경우 추가할 수 있습니다.

4. oauthScopes 필드는 문자열 배열을 지정합니다. 프로젝트에 사용되는 범위를 설정하려면 이 배열의 콘텐츠를 사용하려는 범위로 바꿉니다. 예를 들어 Gmail을 확장하는 Google Workspace 부가기능의 경우 다음과 같은 항목이 있을 수 있습니다.

   {
     ...
     "oauthScopes": [
       "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
       "https://www.googleapis.com/auth/userinfo.email"
     ],
     ...
   }
   

5. 매니페스트 파일 변경사항을 저장합니다.

OAuth 확인

특정 민감한 OAuth 범위를 사용하려면 부가기능을 게시하기 전에 OAuth 클라이언트 인증을 거쳐야 할 수 있습니다. 자세한 내용은 다음 가이드를 참조하세요.

• Apps Script의 OAuth 클라이언트 인증
• 확인되지 않은 앱
• OAuth 인증 FAQ
• Google API 서비스: 사용자 데이터 정책

제한된 범위

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

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

참고: 가능하면 제한된 범위를 부가기능에 사용하지 마세요. 제한된 범위를 사용하지 않으면 공개 게시를 위한 부가기능 검토를 더 쉽게 통과할 수 있습니다. 비공개 부가기능에는 제한된 범위를 자유롭게 사용할 수 있습니다.

Google Workspace 부가기능의 범위 선택하기

다음 섹션에서는 Google Workspace 부가기능에 일반적으로 사용되는 범위를 제공합니다.

편집기 범위

다음은 Docs, Sheets, Slides를 확장하는 Google Workspace 부가기능에 자주 사용되는 범위입니다.

참고: currentonly 범위는 Apps Script 서비스 내에서만 사용할 수 있습니다. 여기에는 Apps Script 고급 서비스 또는 Google Workspace API 직접 호출이 포함되지 않습니다.

범위
현재 Docs 파일 액세스	https://www.googleapis.com/auth/documents.currentonly 부가기능이 Apps Script Docs API에 액세스하는 경우 필요합니다. 열려 있는 문서의 콘텐츠에 대한 임시 액세스 권한을 부여합니다.
현재 Sheets 파일 액세스	https://www.googleapis.com/auth/spreadsheets.currentonly 부가기능이 Apps Script Sheets API에 액세스하는 경우 필요합니다. 열려 있는 스프레드시트의 콘텐츠에 대한 임시 액세스 권한을 부여합니다.
현재 Slides 파일 액세스	https://www.googleapis.com/auth/presentations.currentonly 부가기능이 Apps Script Slides API에 액세스하는 경우 필요합니다. 공개 프레젠테이션 콘텐츠에 대한 임시 액세스 권한을 부여합니다.
파일별 액세스	https://www.googleapis.com/auth/drive.file 부가기능에서 onFileScopeGrantedTrigger를 사용하고 부가기능이 Docs, Sheets, Slides 또는 Drive API에 액세스하는 경우 필요합니다. Apps Script 고급 Drive 서비스를 사용하여 앱에서 만들거나 연 파일에 대한 파일별 액세스 권한을 부여합니다. 하지만 기본 Drive 서비스를 사용하여 유사한 작업을 사용할 수는 없습니다. 파일 승인은 파일별로 부여되며 사용자가 앱의 승인을 취소하면 취소됩니다.

Gmail

사용자 Gmail 데이터를 보호하기 위해 Google Workspace 부가기능용으로 특별히 만든 몇 가지 범위가 있습니다. 추가 기능 코드에 필요한 다른 모든 스코프와 함께 추가 기능 매니페스트에 이러한 스코프를 명시적으로 추가해야 합니다.

다음은 Gmail을 확장하는 Google Workspace 부가기능에 자주 사용되는 범위입니다. 부가기능이 Gmail을 확장하는 경우 필수로 표시된 범위는 Google Workspace 부가기능 매니페스트에 추가해야 합니다.

또한 부가기능의 매우 광범위한 https://mail.google.com 범위를 부가기능에 필요한 상호작용만 허용하는 더 좁은 범위로 대체해야 합니다.

범위
새 답안 만들기	https://www.googleapis.com/auth/gmail.addons.current.action.compose 부가기능에서 compose action triggers를 사용하는 경우 필요합니다. 부가기능이 일시적으로 새 답장 메시지와 답장을 만들 수 있습니다. 자세한 내용은 메시지 답장 작성을 참고하세요. 이 범위는 작성 작업과 함께 자주 사용됩니다. 액세스 토큰이 필요합니다.
열려 있는 메시지 메타데이터 읽기	https://www.googleapis.com/auth/gmail.addons.current.message.metadata 열려 있는 메일의 메타데이터 (예: 제목 또는 수신자)에 대한 임시 액세스 권한을 부여합니다. 메시지 콘텐츠 읽기를 허용하지 않으며 액세스 토큰이 필요합니다. 부가기능이 Compose 작업 트리거에서 메타데이터를 사용하는 경우 필요합니다. 구성 작업의 경우 구성 트리거에 메타데이터에 대한 액세스가 필요한 경우 이 범위가 필요합니다. 실제로 이 범위를 사용하면 작성 트리거가 답장 이메일 초안의 수신자 목록 (받는사람:, 참조:, 숨은참조:)에 액세스할 수 있습니다.
열려 있는 메일 콘텐츠 읽기	https://www.googleapis.com/auth/gmail.addons.current.message.action 부가기능 메뉴 항목이 선택되는 경우와 같이 사용자 상호작용 시 열려 있는 메일의 콘텐츠에 대한 액세스 권한을 부여합니다. 액세스 토큰이 필요합니다.
대화목록 콘텐츠 읽기	https://www.googleapis.com/auth/gmail.addons.current.message.readonly 공개된 메시지의 메타데이터 및 콘텐츠에 대한 임시 액세스 권한을 부여합니다. 또한 열려 있는 대화목록의 다른 메시지 콘텐츠에 대한 액세스 권한도 부여합니다. 액세스 토큰이 필요합니다.
메시지 콘텐츠 및 메타데이터 읽기	https://www.googleapis.com/auth/gmail.readonly 열린 메시지를 비롯한 모든 이메일 메타데이터 및 콘텐츠를 읽습니다. 검색 쿼리를 실행하거나 전체 메일 대화목록을 읽을 때와 같이 다른 메일에 관한 정보를 읽어야 하는 경우 필요합니다. 경고: 매우 광범위하고 제한된 범위입니다. 꼭 필요한 경우에만 사용하세요.

Google Calendar 범위

다음은 Google 캘린더를 확장하는 Google Workspace 부가기능에 자주 사용되는 범위입니다.

범위
이벤트 메타데이터 액세스	https://www.googleapis.com/auth/calendar.addons.execute 부가기능이 Calendar 일정 메타데이터에 액세스하는 경우 필요합니다. 부가기능이 이벤트 메타데이터에 액세스할 수 있도록 허용합니다.
사용자 생성 이벤트 데이터 읽기	https://www.googleapis.com/auth/calendar.addons.current.event.read 부가기능에서 사용자 생성 이벤트 데이터를 읽어야 하는 경우 필요합니다. 부가기능이 사용자 생성 이벤트 데이터에 액세스하도록 허용합니다. 이 데이터는 addOns.calendar.eventAccess 매니페스트 필드가 READ 또는 READ_WRITE로 설정된 경우에만 사용할 수 있습니다.
사용자 생성 이벤트 데이터 작성	https://www.googleapis.com/auth/calendar.addons.current.event.write 부가기능에서 사용자 생성 이벤트 데이터를 작성해야 하는 경우 필요합니다. 부가기능이 사용자 생성 이벤트 데이터를 수정할 수 있도록 허용합니다. 이 데이터는 addOns.calendar.eventAccess 매니페스트 필드가 WRITE 또는 READ_WRITE로 설정된 경우에만 사용할 수 있습니다.

Google Chat 범위

개발자 프리뷰: 특정 기능에 대한 사전 체험판을 제공하는 Google Workspace 개발자 프리뷰 프로그램의 일부로 제공됩니다.

Chat API를 호출하려면 Google Chat 사용자 또는 Chat 앱으로 인증해야 합니다. 각 유형의 인증에는 서로 다른 범위가 필요하며 일부 Chat API 메서드는 앱 인증을 지원하지 않습니다.

Chat 범위 및 인증 유형에 대해 자세히 알아보려면 Chat API 인증 및 승인 개요를 참고하세요.

다음 표에는 지원되는 인증 유형에 따라 자주 사용되는 Chat API 메서드와 범위가 나와 있습니다.

메서드	사용자 인증 지원	앱 인증 지원	지원되는 승인 범위
메시지 보내기			사용자 인증을 사용하면 다음과 같이 할 수 있습니다. chat.messages.create chat.messages chat.import 앱 인증을 사용하는 경우: chat.bot
스페이스 만들기			사용자 인증을 사용하면 다음과 같이 할 수 있습니다. chat.spaces.create chat.spaces chat.import 앱 인증 및 관리자 승인 (개발자 프리뷰에서 사용 가능): chat.app.spaces.create chat.app.spaces
스페이스 만들기 및 스페이스에 멤버 추가하기		—	사용자 인증을 사용하면 다음과 같이 할 수 있습니다. chat.spaces.create chat.spaces
스페이스에 사용자 추가하기			사용자 인증을 사용하면 다음과 같이 할 수 있습니다. chat.memberships chat.memberships.app chat.import 앱 인증 및 관리자 승인 (개발자 프리뷰에서 사용 가능): chat.app.memberships
Chat 스페이스의 활동 또는 일정 나열하기		—	사용자 인증을 사용하면 요청에 포함된 각 이벤트 유형에 대한 범위를 사용해야 합니다. 메시지에 관한 이벤트의 경우: chat.messages chat.messages.readonly 반응에 관한 이벤트의 경우: chat.messages.reactions chat.messages.reactions.readonly chat.messages chat.messages.readonly 멤버십 관련 이벤트의 경우: chat.memberships chat.memberships.readonly 스페이스에 관한 이벤트의 경우: chat.spaces chat.spaces.readonly

Google Drive 범위

다음은 Google Drive를 확장하는 Google Workspace 부가기능에 자주 사용되는 범위입니다.

범위
선택한 항목 메타데이터 읽기	https://www.googleapis.com/auth/drive.addons.metadata.readonly 사용자가 Drive에서 항목을 선택할 때 트리거되는 상황별 인터페이스를 부가기능에서 구현하는 경우 필요합니다. 부가기능이 사용자가 Google Drive에서 선택한 항목에 관한 제한된 메타데이터를 읽을 수 있습니다. 메타데이터는 항목의 ID, 제목, MIME 유형, 아이콘 URL, 부가기능에 항목에 액세스할 권한이 있는지 여부로 제한됩니다.
파일별 액세스	https://www.googleapis.com/auth/drive.file 개별 Drive 파일에 액세스해야 하는 부가기능의 경우 권장됩니다. Apps Script 고급 Drive 서비스를 사용하여 앱에서 만들거나 연 파일에 대한 파일별 액세스 권한을 부여합니다. 하지만 기본 Drive 서비스를 사용하여 유사한 작업을 사용할 수는 없습니다. 파일 승인은 파일별로 부여되며 사용자가 앱의 승인을 취소하면 취소됩니다. 선택한 파일의 파일 액세스 요청 예를 참고하세요.

액세스 토큰

사용자 데이터를 보호하기 위해 Google Workspace 부가기능에 사용되는 Gmail 범위는 사용자 데이터에 대한 임시 액세스 권한만 부여합니다. 임시 액세스를 사용 설정하려면 액세스 토큰을 인수로 사용하여 GmailApp.setCurrentMessageAccessToken(accessToken) 함수를 호출해야 합니다. 작업 이벤트 객체에서 액세스 토큰을 가져와야 합니다.

참고: Gmail 범위를 사용 설정하는 액세스 토큰은 ScriptApp.getOAuthToken()에서 반환하는 액세스 토큰과 동일하지 않습니다. 작업 이벤트 객체에 제공된 토큰을 사용해야 합니다.

다음은 메시지 메타데이터에 대한 액세스를 허용하도록 액세스 토큰을 설정하는 예를 보여줍니다. 이 예에 필요한 유일한 범위는 https://www.googleapis.com/auth/gmail.addons.current.message.metadata입니다.

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

기타 Google Workspace 범위

부가기능에서 다른 Google Workspace 또는 Apps Script 서비스를 사용하는 경우 추가 범위가 필요할 수 있습니다. 대부분의 경우 Apps Script가 이러한 범위를 감지하고 매니페스트를 자동으로 업데이트하도록 할 수 있습니다. 매니페스트의 범위 목록을 수정할 때는 더 적합한 대안(예: 더 좁은 범위)으로 대체하는 것이 아니라면 범위를 삭제하지 마세요.

다음 표에는 Google Workspace 부가기능에서 자주 사용하는 범위 목록이 나와 있습니다.

범위
사용자의 이메일 주소 읽기	https://www.googleapis.com/auth/userinfo.email 프로젝트가 현재 사용자의 이메일 주소를 읽을 수 있도록 허용합니다.
외부 서비스 호출 허용	https://www.googleapis.com/auth/script.external_request 프로젝트가 UrlFetch 요청을 할 수 있도록 허용합니다. 프로젝트에서 Apps Script용 OAuth2 라이브러리를 사용하는 경우에도 필요합니다.
사용자의 언어 및 시간대 읽기	https://www.googleapis.com/auth/script.locale 프로젝트가 현재 사용자의 언어 및 시간대를 학습할 수 있도록 허용합니다. 자세한 내용은 사용자 언어 및 시간대에 액세스를 참고하세요.
트리거 만들기	https://www.googleapis.com/auth/script.scriptapp 프로젝트에서 트리거를 만들 수 있습니다.
서드 파티 링크 미리보기	https://www.googleapis.com/auth/workspace.linkpreview 부가기능이 서드 파티 서비스의 링크를 미리 보는 경우 필요합니다. 사용자가 Google Workspace 애플리케이션과 상호작용하는 동안 프로젝트가 Google Workspace 애플리케이션 내의 링크를 볼 수 있도록 허용합니다. 자세한 내용은 스마트 칩을 사용한 링크 미리보기를 참고하세요.
서드 파티 리소스 만들기	https://www.googleapis.com/auth/workspace.linkcreate 부가기능이 서드 파티 서비스에서 리소스를 만드는 경우 필요합니다. 프로젝트가 사용자가 리소스 생성 양식에 제출한 정보를 읽고 Google Workspace 애플리케이션 내에 리소스 링크를 삽입할 수 있도록 허용합니다. 자세한 내용은 @ 메뉴에서 서드 파티 리소스 만들기를 참고하세요.