인증 및 설정
Google Drive 통합은 OAuth 2.0 인증을 통해 포괄적인 파일 스토리지 및 관리 기능을 제공합니다. 에이전트는 개인 Drive 계정과 Google Workspace 조직의 공유 팀 드라이브(공유 드라이브)와 상호작용할 수 있습니다. 이 통합은 문서, 스프레드시트, 프레젠테이션, 이미지, 비디오 및 PDF를 포함한 모든 주요 파일 유형을 지원합니다.필요한 API 범위
- drive: 팀 드라이브를 포함한 Drive의 모든 파일에 대한 완전한 접근 권한.
- drive.file: 애플리케이션에서 생성하거나 열은 파일에만 접근.
- drive.readonly: 파일 보기 및 다운로드에 대한 읽기 전용 접근 권한.
- drive.metadata: 파일 콘텐츠 접근 없이 파일 메타데이터에 대한 접근.
- drive.appdata: 애플리케이션별 데이터 폴더에 대한 접근.
사용 가능한 작업
모든 필요한 권한이 구성되면 툴킷은 다음 작업을 활성화합니다.파일 작업
- 파일 업로드: 메타데이터(이름, 설명, MIME 유형)와 함께 에이전트 워크스페이스에서 Drive로 파일을 업로드합니다.
- 파일 다운로드: 로컬 처리 또는 분석을 위해 파일을 검색합니다.
- 파일 목록: 이름, 유형, 소유자 또는 수정 날짜별로 필터링하여 파일과 폴더를 탐색합니다.
- 파일 검색: 쿼리 매개변수를 사용하여 파일 이름과 콘텐츠에서 전체 텍스트 검색.
- 파일 가져오기: 권한, 소유자 및 버전 기록을 포함한 상세 파일 메타데이터를 검색합니다.
- 파일 업데이트: 파일 ID를 변경하지 않고 파일 콘텐츠 또는 메타데이터를 수정합니다.
- 파일 삭제: 파일을 휴지통으로 이동하거나 영구적으로 삭제합니다.
- 파일 복원: 휴지통에서 파일을 복구합니다.
- 파일 내보내기: Google Workspace 파일을 표준 형식으로 변환(Docs에서 PDF, Sheets에서 Excel 등).
폴더 관리
- 폴더 생성: 구성을 위한 사용자 정의 이름으로 새 폴더를 생성합니다.
- 파일 이동: 상위 참조를 업데이트하여 폴더 간에 파일을 재배치합니다.
- 파일 복사: 새 이름이나 다른 위치에 파일을 복제합니다.
- 폴더 내용 목록: 특정 폴더 내의 모든 파일을 검색합니다.
- 폴더 경로 가져오기: 모든 폴더의 전체 경로 계층 구조를 결정합니다.
공유 및 권한
- 파일 공유: 구성 가능한 권한(보기, 댓글, 편집)으로 공유 링크를 생성합니다.
- 권한 생성: 특정 사용자 또는 그룹에게 파일 접근을 부여합니다.
- 권한 업데이트: 기존 접근 권한을 수정합니다.
- 권한 제거: 사용자 또는 공유 링크의 접근을 취소합니다.
- 권한 목록 가져오기: 파일에 접근할 수 있는 모든 사용자와 그룹을 봅니다.
- 링크 만료 설정: 공유 링크의 자동 만료를 구성합니다.
- 다운로드 제한: 보기자가 다운로드, 인쇄 또는 콘텐츠 복사를 방지합니다.
고급 작업
- 파일 메타데이터 가져오기: 생성 날짜, 수정 날짜, 크기, 소유자, MIME 유형, 섬네일을 검색합니다.
- 파일 감시: 파일 변경에 대한 알림을 설정합니다(webhook).
- 파일 리비전 가져오기: 버전 기록에 접근하고 이전 버전을 복원합니다.
- 댓글 추가: Google Docs, Sheets, Slides 파일에 댓글을 게시합니다.
- 일괄 작업: 단일 API 호출에서 여러 파일 작업을 수행합니다.
구성 옵션
- 기본 폴더: 기본 업로드 위치를 특정 폴더 또는 팀 드라이브로 설정합니다.
- 파일 크기 제한: 최대 업로드 크기를 구성합니다(API 제한: 파일당 5GB).
- 삭제된 파일 포함: 목록/검색 결과에 삭제된 파일을 포함할지 여부.
- 팀 드라이브 지원: Workspace 계정의 팀 드라이브(공유 드라이브) 접근을 활성화합니다.
- 코퍼스: 검색 범위 - 사용자의 Drive, 팀 드라이브 또는 모든 도메인.
사용 사례
- 문서 백업: 버전 관리와 함께 프로젝트 워크스페이스에서 중요한 파일을 Drive로 자동 백업합니다.
- 파일 구성: 콘텐츠나 메타데이터를 기반으로 업로드된 파일을 적절한 폴더로 자동 분류하고 이동합니다.
- 콘텐츠 배포: 보고서를 업로드하고, 공유 링크를 생성하며, 이메일을 통해 이해관계자에게 배포합니다.
- 협업 워크플로우: 초안을 팀 드라이브에 업로드하고, 팀과 공유하며, 댓글과 리비전을 추적합니다.
- 데이터 마이그레이션: Drive를 중간 매체로 사용하여 스토리지 시스템 간에 파일을 대량 전송합니다.
- 미디어 라이브러리 관리: 메타데이터 태깅과 검색으로 이미지, 비디오 및 자산을 구성합니다.
- 문서 처리 파이프라인: 파일을 다운로드하고, Python/Node.js로 처리하며, 결과를 Drive로 다시 업로드합니다.
모범 사례
- 파일 ID 사용: 중복으로 인한 모호함을 방지하기 위해 이름 대신 ID로 파일을 참조합니다.
- 재개 가능 업로드 구현: 5MB 이상 파일에는 중단을 처리하기 위해 재개 가능 업로드 프로토콜을 사용합니다.
- 일괄 요청: API 호출을 줄이고 성능을 향상시키기 위해 여러 작업을 결합합니다.
- 할당량 모니터링: 일일 할당량 제한에 대한 API 사용량을 추적합니다(계정 유형에 따라 다름).
- 폴더로 구성: 대규모 파일 컬렉션에는 평면 구조 대신 명확한 폴더 계층 구조를 사용합니다.
- 적절한 권한 설정: 파일 공유 시 최소 권한 원칙을 사용합니다.
일반적인 문제 및 해결 방법
- 업로드 시간 초과: 대용량 파일의 경우 재개 가능 업로드를 사용하고 재시도 로직을 구현합니다.
- 권한 거부: OAuth 중 사용자가 drive 범위를 부여했는지 확인합니다. 파일 소유권과 권한을 확인합니다.
- 중복 파일: Drive는 동일한 이름의 여러 파일을 허용합니다. ID로 검색하거나 쿼리에 상위 폴더를 포함합니다.
- 속도 제한: 재시도를 위해 지수 백오프를 구현합니다. 자주 접근되는 메타데이터의 캐싱을 고려합니다.