편집기 부가기능의 승인 범위

사용자는 자신의 데이터에 액세스하거나 자신을 대신하여 작업을 수행하는 부가기능 및 기타 애플리케이션을 승인해야 합니다. 사용자가 부가기능을 처음 실행하면 부가기능 UI에 승인 흐름을 시작하는 승인 프롬프트가 표시됩니다.

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

URL 문자열을 사용하여 매니페스트에서 범위를 선언합니다. 승인 흐름 중에 Apps Script는 사용자에게 사람이 읽을 수 있는 범위 설명을 제공합니다. 예를 들어 부가기능은 매니페스트에 https://www.googleapis.com/auth/documents.currentonly로 작성된 '현재 문서 읽기' 범위를 사용할 수 있습니다. 승인 흐름 중에 이 범위가 있는 부가기능은 사용자에게 부가기능이 이 애플리케이션이 설치된 문서를 보고 관리 하도록 허용해 달라고 요청합니다.

Apps Script가 다양한 서비스에 사용하는 범위는 관련 API에서 사용하는 범위와 겹칩니다. 예를 들어 Apps Script's 캘린더 서비스는 캘린더 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 필드는 문자열 배열을 지정합니다. 프로젝트에서 사용하는 범위를 설정하려면 이 배열의 콘텐츠를 사용하려는 범위로 바꿉니다. 예를 들어 Sheets를 확장하는 편집기 부가기능의 경우 다음과 같이 할 수 있습니다.

     {
   ...
   "oauthScopes": [
     "https://www.googleapis.com/auth/script.container.ui",
     "https://www.googleapis.com/auth/spreadsheets"
   ],
   ...
 }

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

OAuth 확인

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

제한된 범위

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

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

Visual Studio Code용 Google Workspace 개발자 도구 확장 프로그램 은 범위의 설명, 민감한지 또는 제한되는지 여부를 비롯한 모든 범위에 관한 진단 정보를 제공합니다.

편집기 부가기능 범위

편집기 부가기능을 빌드할 때 필요한 범위는 부가기능 코드에서 사용하는 Google Apps Script 서비스 및 메서드에 따라 결정됩니다. 예를 들어 Google Sheets 부가기능은 여러 Sheets에서 정보를 읽기 위해 https://www.googleapis.com/auth/spreadsheets.readonly 범위가 필요할 수 있습니다.

Apps Script는 스크립트 프로젝트에 코드를 추가할 때 사용하는 서비스에 필요한 범위를 자동으로 결정합니다. 편집기 부가기능의 경우 범위를 직접 결정하고 명시적으로 설정하는 대신 이 자동 범위 수집에 의존하는 경우가 많습니다.

범위를 명시적으로 설정하지 않고 편집기 부가기능이 열려 있는 편집기 파일만 읽거나 쓰는 경우 스크립트 프로젝트 파일 중 하나에 다음 주석을 추가합니다.

/**
 * @OnlyCurrentDoc
 */

이 주석은 Apps Script에 설정된 편집기 파일 범위를 currentonly로 좁히도록 지시합니다. 예를 들어 Sheets 부가기능 스크립트 프로젝트 파일에 이 주석을 추가하면 부가기능에 Google Drive에 있을 수 있는 다른 Sheets가 아닌 열려 있는 Sheet에서만 작동할 수 있는 권한이 필요하다고 지정하는 것입니다. 반대로 Sheets 부가기능에서 사용자가 열지 않은 Sheet의 데이터를 읽거나 써야 하는 경우에는 이 주석을 사용해서는 안 됩니다.