Google드라이브파일 시스템
단일 Google 드라이브 폴더에 파일을 저장합니다. 각 디렉터리는 구성된 루트 아래의 Drive 폴더에 매핑되며 경로는 POSIX 의미 체계를 사용합니다(예:/notes/todo.txt). 인터페이스에 대한 자세한 내용은 다음을 참조하세요.Workspace파일 시스템 인터페이스.
설치설치에 대한 직접 링크
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/google-drive
pnpm add @mastra/google-drive
yarn add @mastra/google-drive
bun add @mastra/google-drive
용법용법에 대한 직접 링크
Workspace에 GoogleDriveFilesystem을 추가하고 Agent에 할당합니다:
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { GoogleDriveFilesystem } from '@mastra/google-drive'
const workspace = new Workspace({
filesystem: new GoogleDriveFilesystem({
folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
accessToken: process.env.GOOGLE_DRIVE_ACCESS_TOKEN!,
}),
})
const agent = new Agent({
id: 'drive-agent',
name: 'Drive Agent',
model: 'openai/gpt-5-mini',
workspace,
})
입증입증에 대한 직접 링크
다음 인증 옵션 중 하나를 제공하십시오.
accessToken: 미리 획득한 OAuth 액세스 토큰입니다. 인증된 ID와 공유된 폴더를 토큰이 볼 수 있도록https://www.googleapis.com/auth/drive범위를 사용합니다.getAccessToken: 토큰을 반환하는 콜백입니다. 토큰을 외부에서 새로 고칠 때 유용합니다.serviceAccount: Google 서비스 계정입니다. 서비스 계정 이메일과 대상 폴더를 공유합니다.
서비스 계정서비스 계정에 대한 직접 링크
서비스 계정 인증은 백엔드 Agent에 권장되는 옵션입니다. 사용자 동의 흐름과 토큰 새로 고침 처리가 필요하지 않습니다. 서비스 계정 JSON 키 파일에서 두 값, 즉 client_email과 private_key만 있으면 됩니다.
서비스 계정 설정서비스 계정 설정에 대한 직접 링크
- Google Cloud Console을 열고 프로젝트를 선택하거나 생성합니다.
- APIs & Services > Library로 이동하여 Google Drive API를 검색한 다음 Enable을 선택합니다.
- APIs & Services > Credentials로 이동하여 Create credentials > Service account를 선택하고 양식을 작성합니다. Drive 권한은 IAM 역할이 아니라 폴더 공유를 통해 부여되므로 역할은 비워 두어도 됩니다.
- 새 서비스 계정을 열고 Keys 탭에서 Add key > Create new key > JSON을 선택합니다. 브라우저에서 JSON 키 파일을 다운로드합니다.
- JSON 파일에서
client_email값을 복사합니다. 이 주소와 Drive 폴더를 공유합니다.
서비스 계정과 드라이브 폴더 공유서비스 계정과 드라이브 폴더 공유에 대한 직접 링크
서비스 계정은 자체 Google ID입니다. 명시적으로 공유하기 전까지는 드라이브에서 아무 것도 볼 수 없습니다.
- Google Drive에서 대상 폴더를 엽니다.
- Share를 선택합니다.
- 서비스 계정의
client_email주소를 붙여넣습니다. - 역할을 Editor(읽기 및 쓰기용) 또는 Viewer(읽기 전용 액세스용)로 설정합니다. Send를 선택합니다.
- URL에서 폴더 ID를 복사합니다.
https://drive.google.com/drive/folders/<folderId>에서/folders/다음 부분입니다.
서비스 계정은 표준 '내 드라이브' 폴더에 파일을 만들 수 없습니다. 서비스 계정에는 개인 드라이브 스토리지 할당량이 없으므로 서비스 계정이 생성하는 모든 파일은 할당량 보유 주체가 소유해야 합니다. 개인 드라이브 폴더만 공유하는 경우 읽기 작업은 작동하지만 할당량 오류로 인해 쓰기가 실패합니다.
쓰기 액세스가 필요하면 폴더를 shared drive(이전 명칭: Team Drive)로 이동하고 서비스 계정을 해당 공유 드라이브의 구성원으로 추가합니다. 공유 드라이브는 서비스 계정이 생성한 파일에 필요한 저장용량 할당량을 제공합니다. 개인 드라이브 폴더에 대한 읽기 전용 작업에는 이러한 제한이 없습니다.
파일 시스템 구성파일 시스템 구성에 대한 직접 링크
JSON 파일의 client_email과 private_key를 환경에 복사합니다:
GOOGLE_DRIVE_FOLDER_ID=1AbCdEfGhIjKlMnOpQrStUvWxYz
GOOGLE_DRIVE_CLIENT_EMAIL=my-bot@my-project.iam.gserviceaccount.com
# Wrap the value in quotes — the key contains newlines that must be preserved.
GOOGLE_DRIVE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkq...\n-----END PRIVATE KEY-----\n"
import { GoogleDriveFilesystem } from '@mastra/google-drive'
const filesystem = new GoogleDriveFilesystem({
folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
serviceAccount: {
clientEmail: process.env.GOOGLE_DRIVE_CLIENT_EMAIL!,
privateKey: process.env.GOOGLE_DRIVE_PRIVATE_KEY!,
},
})
전체 JSON 파일을 복사하거나 project_id, client_id, private_key_id, token_uri 같은 다른 필드를 전달할 필요는 없습니다. 이러한 필드는 사용되지 않습니다. clientEmail과 privateKey만 필수입니다. privateKeyId, scopes, subject는 선택 사항입니다. scopes의 기본값은 ['https://www.googleapis.com/auth/drive']이며, 서비스 계정이 자신과 공유된 폴더를 보는 데 필요한 범위입니다. 더 제한적인 drive.file 범위는 애플리케이션이 직접 생성한 파일에만 액세스를 허용하므로 서비스 계정과 공유된 폴더에서는 404 Not Found가 반환됩니다.
GoogleDriveFilesystem은 서명하기 전에 privateKey 문자열을 자동으로 정규화합니다. JSON으로 래핑된 값에서 이스케이프된 따옴표를 포함해 바깥쪽 따옴표를 제거하고, 리터럴 \n 시퀀스를 실제 줄바꿈으로 변환합니다. 또한 \r\n 줄 끝을 정규화하고 후행 쉼표를 제거합니다. 따라서 .env 로더가 값을 처리하는 방식과 관계없이 키가 작동합니다.
문제 해결문제 해결에 대한 직접 링크
404 File not found: <folderId>: 서비스 계정에 폴더 액세스 권한이 없습니다. 폴더가 올바른client_email주소와 공유되었으며 폴더 ID가 URL과 일치하는지 확인하세요.- 쓰기 시
storageQuotaExceeded: 해당 폴더가 개인 "내 드라이브"에 있습니다. 폴더를 공유 드라이브로 이동하고 서비스 계정을 구성원으로 추가하세요. error:1E08010C:DECODER routines::unsupported:privateKey값의 형식이 잘못되었습니다. 값에 전체 PEM 블록이 포함되어 있고 줄바꿈이 유지되는지 확인하세요(리터럴\n도 사용할 수 있음).
읽기 전용 모드읽기 전용 모드에 대한 직접 링크
쓰기 작업(writeFile, appendFile, deleteFile, copyFile, moveFile, mkdir, rmdir)을 차단하려면 readOnly: true를 전달합니다.
const filesystem = new GoogleDriveFilesystem({
folderId,
accessToken,
readOnly: true,
})
생성자 매개변수생성자 매개변수에 대한 직접 링크
folderId:
accessToken?:
getAccessToken?:
serviceAccount?:
id?:
readOnly?:
instructions?:
속성속성에 대한 직접 링크
id:
name:
provider:
readOnly:
행동 양식행동 양식에 대한 직접 링크
GoogleDriveFilesystem은 다음을 구현합니다.WorkspaceFilesystem interface, providing all standard filesystem methods:
readFile(path, options?)- 파일 콘텐츠 다운로드writeFile(path, content, options?)- 파일 업로드 또는 덮어쓰기appendFile(path, content)- 파일을 읽고 다시 업로드하여 콘텐츠 추가deleteFile(path, options?)- 파일 삭제copyFile(src, dest, options?)- Drivefiles.copyAPI를 사용하여 파일 복사moveFile(src, dest, options?)- 상위 폴더를 변경하여 폴더 간에 파일 이동mkdir(path, options?)- 폴더 생성rmdir(path, options?)- 폴더 제거readdir(path, options?)- 폴더 콘텐츠 목록 조회(recursive및extension필터링 지원)stat(path)- 파일 또는 폴더의 Drive 메타데이터 반환exists(path)- 파일 또는 폴더가 존재하는지 확인
메모메모에 대한 직접 링크
- Google Drive에서는 폴더에 이름이 같은 여러 파일을 둘 수 있습니다.
GoogleDriveFilesystem은 첫 번째로 일치하는 항목을 선택하여 경로를 해석하므로 경로 기반 조회를 사용할 때는 각 폴더 내에서 이름을 고유하게 유지하세요. writeFile은recursive가 설정되지 않았거나(기본값)true인 경우 상위 폴더를 자동으로 생성합니다. 상위 폴더가 이미 존재하도록 요구하려면recursive: false를 설정합니다.WriteOptions의expectedMtime이 적용됩니다. 저장된modifiedTime이 다르면 낙관적 동시성을 지원하기 위해StaleFileError와 함께 쓰기가 거부됩니다.- 이 Provider는 내장
fetch를 통해 Drive REST 엔드포인트(https://www.googleapis.com/drive/v3및https://www.googleapis.com/upload/drive/v3)를 사용합니다. 추가 종속성은 필요하지 않습니다.