Google Drive API 범위 선택

이 문서에는 Google Drive API 관련 승인 및 인증 정보가 포함되어 있습니다. 이 문서를 읽기 전에 인증 및 승인 알아보기에서 Google Workspace의 일반 인증 및 승인 정보를 읽어보세요.

승인을 위한 OAuth 2.0 구성

앱을 승인하려면 Google Drive API에서 Google Cloud 콘솔과 앱이라는 두 위치에서 OAuth 범위를 정의해야 합니다.

Google Cloud 콘솔에서 앱의 OAuth 동의 화면 구성에 필요한 범위를 선언해야 합니다. 이는 앱이 요청할 수 있는 최고 수준의 권한입니다. 이는 Google에 대한 공식 요청으로, 선언된 범위는 Google에서 동의 화면에 사용자에게 표시하는 범위입니다. 이를 통해 사용자는 앱이 액세스를 요청하는 데이터와 작업을 정확히 파악할 수 있습니다.

OAuth 동의 화면을 구성하고 범위를 선택 하여 사용자와 앱 검토자에게 표시되는 정보를 정의하고 나중에 게시할 수 있도록 앱을 등록합니다.

앱에서 API를 시작할 때 해당 세션에 필요한 특정 범위를 명시적으로 요청해야 합니다. Google Cloud 콘솔은 앱이 요청할 수 있는 최고 수준의 권한을 정의하지만 코드는 특정 사용자의 실제 권한을 결정합니다. 이를 통해 앱은 특정 작업에 필요한 권한만 요청할 수 있습니다.

앱의 코드 내에서 하나 이상의 OAuth 범위를 배열로 한 번에 선언할 수 있습니다.

다음 코드 샘플에서는 여러 OAuth 범위를 선언하는 방법을 보여줍니다.

자바

List<String> SCOPES = Arrays.asList(
  DriveScopes.DRIVE_FILE,
  DriveScopes.DRIVE_METADATA_READONLY
);

Python

SCOPES = [
  "https://www.googleapis.com/auth/drive.file",
  "https://www.googleapis.com/auth/drive.metadata.readonly",
]

Node.js

const SCOPES = [
  'https://www.googleapis.com/auth/drive.file',
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

전체 코드 샘플에서 범위가 선언되고 사용되는 방식을 보려면 빠른 시작을 참고하세요.

Drive API 범위

앱에 부여된 액세스 수준을 정의하려면 승인 범위 를 식별하고 선언해야 합니다. 승인 범위는 Google Workspace 앱 이름, 액세스하는 데이터 유형, 액세스 수준이 포함된 OAuth 2.0 URI 문자열입니다. 범위는 사용자의 Google 계정 데이터를 비롯한 Google Workspace 데이터로 작업하기 위한 앱의 요청입니다.

앱이 설치되면 사용자에게 앱에서 사용하는 범위를 확인하라는 메시지가 표시됩니다. 일반적으로 가능한 한 가장 좁은 범위의 범위를 선택하고 앱에 필요하지 않은 범위를 요청하지 않아야 합니다. 사용자는 제한적이고 명확하게 설명된 범위에 더 쉽게 액세스 권한을 부여합니다.

가능하면 파일별 액세스 권한을 부여하고 앱에 필요한 특정 기능에 대한 액세스를 좁히는 민감하지 않은 범위를 사용하세요.

민감하지 않은 범위

다음 Drive API 범위는 대부분의 사용 사례에 권장됩니다.

범위 코드 설명
https://www.googleapis.com/auth/drive.appdata
https://www.googleapis.com/auth/drive.appfolder		 Google Drive에서 앱의 자체 구성 데이터를 보고 관리합니다.
https://www.googleapis.com/auth/drive.install 앱이 '연결 프로그램' 또는 '새로 만들기' 메뉴에 옵션으로 표시되도록 허용합니다.
https://www.googleapis.com/auth/drive.file Google Picker API 또는 앱의 파일 선택 도구를 사용하는 동안 앱으로 열거나 사용자가 앱과 공유하는 새 Drive 파일을 만들거나 기존 파일을 수정합니다.

민감한 범위

범위 코드 설명
https://www.googleapis.com/auth/drive.apps.readonly Drive에 액세스할 수 있는 권한이 부여된 앱을 봅니다.

제한된 범위

범위 코드 설명
https://www.googleapis.com/auth/drive 모든 Drive 파일을 보고 관리합니다.
https://www.googleapis.com/auth/drive.readonly 모든 Drive 파일을 보고 다운로드합니다.
https://www.googleapis.com/auth/drive.activity Drive에 있는 파일의 작업 기록을 보고 추가합니다.
https://www.googleapis.com/auth/drive.activity.readonly Drive에 있는 파일의 작업 기록을 봅니다.
https://www.googleapis.com/auth/drive.meet.readonly Google Meet에서 생성 또는 수정한 Drive 파일을 봅니다.
https://www.googleapis.com/auth/drive.metadata Drive에 있는 파일의 메타데이터를 보고 관리합니다.
https://www.googleapis.com/auth/drive.metadata.readonly Drive에 있는 파일의 메타데이터를 봅니다.
https://www.googleapis.com/auth/drive.scripts Google Apps Script 스크립트의 동작을 수정합니다.

위 표의 범위는 다음 정의에 따라 민감도를 나타냅니다.

앱에서 다른 Google API에 액세스해야 하는 경우 이러한 범위도 추가할 수 있습니다. Google API 범위에 대한 자세한 내용은 OAuth 2.0을 사용하여 Google API에 액세스를 참고하세요.

특정 OAuth 2.0 범위에 대한 자세한 내용은 Google API의 OAuth 2.0 범위를 참고하세요.

제한된 범위의 자격 요건

특정 애플리케이션 유형만 Google Drive에 제한된 범위를 사용할 수 있습니다. 자격을 갖추려면 앱이 다음 카테고리 중 하나에 속해야 합니다.

  1. 백업 및 동기화: 사용자의 Drive 파일의 로컬 동기화 또는 자동 백업을 제공하는 플랫폼별 앱 및 웹 앱입니다.

  2. 생산성 및 교육: Drive 파일, 메타데이터 또는 권한과의 상호작용이 포함될 수 있는 기본 사용자 인터페이스가 있는 앱입니다. 이러한 앱에는 작업 관리, 메모 작성, 워크그룹 커뮤니케이션, 클래스룸 공동작업 앱이 포함됩니다.

  3. 보고 및 보안: 파일이 공유되거나 액세스되는 방식에 관한 사용자 또는 고객 통계를 제공하는 앱입니다.

제한된 범위를 계속 사용하려면 제한된 범위 인증을 위해 앱을 준비해야 합니다 범위 인증.

제한된 범위에서 기존 앱 마이그레이션

Drive 앱에서 제한된 범위를 사용하는 경우 민감하지 않은 Drive API 범위로 마이그레이션하는 것이 좋습니다. drive.file과 같은 민감하지 않은 범위를 사용하면 파일별 액세스 권한을 부여하고 앱에 필요한 특정 기능에 대한 액세스를 좁힐 수 있습니다.

많은 앱이 변경 없이 파일별 액세스로 전환할 수 있습니다.

자체 파일 선택 도구를 사용하는 경우 다양한 범위를 완전히 지원하는 Google Picker API로 전환하는 것이 좋습니다.

Drive 파일 범위의 이점

Google Picker API와 함께 drive.file OAuth 범위를 사용하면 앱의 사용자 환경과 안전을 모두 최적화할 수 있습니다.

drive.file OAuth 범위를 사용하면 사용자가 앱과 공유할 파일을 선택할 수 있습니다. 이를 통해 사용자는 파일에 대한 앱의 액세스가 제한되고 더 안전하다는 확신을 갖고 더 많은 제어 권한을 가질 수 있습니다. 반대로 모든 Drive 파일에 대한 광범위한 액세스를 요구하면 사용자가 앱과 상호작용하지 않을 수 있습니다.

다음은 drive.file 범위를 사용해야 하는 몇 가지 이유입니다.

  • 유용성: drive.file 범위는 모든 Drive API REST 리소스와 호환되므로 더 넓은 OAuth 범위를 사용하는 것과 동일한 방식으로 사용할 수 있습니다.

  • 기능: Google Picker API는 Drive UI와 유사한 인터페이스를 제공합니다. 여기에는 Drive 파일의 미리보기와 썸네일을 보여주는 여러 뷰와 인라인 모달 창이 포함되어 있으므로 사용자는 기본 앱을 종료하지 않아도 됩니다.

  • 편의성: 앱은 Google Picker 파일에 필터를 사용할 때 특정 Drive 파일 유형 (예: Google Docs, Sheets, 사진)에 필터를 적용할 수 있습니다.

  • 간단한 인증: drive.file은 민감하지 않으므로 더 간소화된 인증 절차를 사용할 수 있습니다.

갱신 토큰 안전하게 저장

Drive API를 사용하여 비공개 데이터에 액세스하려면 앱에서 해당 API에 대한 액세스 권한을 부여하는 액세스 토큰을 가져와야 합니다. 단일 액세스 토큰은 요청하는 범위에 따라 여러 API에 대한 다양한 수준의 액세스 권한을 부여할 수 있습니다.

액세스 토큰은 수명이 짧으므로 Drive API에 장기적으로 액세스하려면 갱신 토큰을 사용해야 합니다. 갱신 토큰을 사용하면 앱에서 새 액세스 토큰을 요청할 수 있습니다.

갱신 토큰을 안전한 장기 저장소에 저장하고 유효한 동안 계속 사용하세요.

자세한 내용은 OAuth 2.0을 사용하여 Google API에 액세스를 참고하세요.