본문으로 건너뛰기

GCS파일 시스템

Google Cloud Storage에 파일을 저장합니다. 인터페이스에 대한 자세한 내용은 다음을 참조하세요.WorkspaceFilesystem Interface.

설치
설치에 대한 직접 링크

npm install @mastra/gcs

용법
용법에 대한 직접 링크

Workspace에 GCSFilesystem을 추가하고 Agent에 할당합니다:

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { GCSFilesystem } from '@mastra/gcs'

const workspace = new Workspace({
  filesystem: new GCSFilesystem({
    bucket: 'my-gcs-bucket',
    projectId: 'my-project-id',
    credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})

애플리케이션 기본 자격 증명 사용
애플리케이션 기본 자격 증명 사용에 대한 직접 링크

gcloud CLI가 구성된 Google Cloud 환경에서 실행하는 경우 자격 증명을 생략할 수 있습니다:

import { GCSFilesystem } from '@mastra/gcs'

const filesystem = new GCSFilesystem({
  bucket: 'my-gcs-bucket',
  // Uses Application Default Credentials automatically
})

애플리케이션 기본 자격 증명(ADC)다음 순서로 자격 증명을 자동으로 검색합니다.

  1. GOOGLE_APPLICATION_CREDENTIALS 환경 변수(서비스 계정 키 파일 경로)
  2. GCP(Compute Engine, Cloud Run, GKE 등)에서 실행할 때의 기본 서비스 계정
  3. 사용자 자격 증명: gcloud auth application-default login(로컬 개발용)

키 파일 경로 사용
키 파일 경로 사용에 대한 직접 링크

서비스 계정 키 파일의 경로를 전달할 수도 있습니다.

import { GCSFilesystem } from '@mastra/gcs'

const filesystem = new GCSFilesystem({
  bucket: 'my-gcs-bucket',
  projectId: 'my-project-id',
  credentials: '/path/to/service-account-key.json',
})

생성자 매개변수
생성자 매개변수에 대한 직접 링크

bucket:

string
GCS 버킷 이름

projectId?:

string
GCS 프로젝트 ID입니다. 서비스 계정 자격 증명을 사용할 때 필요합니다.

credentials?:

object | string
서비스 계정 키 JSON 객체 또는 키 파일 경로입니다. 제공하지 않으면 애플리케이션 기본 자격 증명을 사용합니다.

prefix?:

string
모든 키에 적용할 선택적 접두사(하위 디렉터리처럼 작동)

id?:

string
= 자동 생성
이 파일 시스템 인스턴스의 고유 식별자

displayName?:

string
UI에 표시할 사용자 친화적인 이름

icon?:

FilesystemIcon
UI에 사용할 아이콘 식별자

description?:

string
UI에 표시할 이 파일 시스템의 간단한 설명

readOnly?:

boolean
= false
true이면 모든 쓰기 작업이 차단됩니다

endpoint?:

string
사용자 지정 API 엔드포인트 URL입니다. 에뮬레이터를 사용하는 로컬 개발에 사용됩니다.

속성
속성에 대한 직접 링크

id:

string
파일 시스템 인스턴스 식별자

name:

string
Provider 이름('GCSFilesystem')

provider:

string
Provider 식별자('gcs')

bucket:

string
GCS 버킷 이름

readOnly:

boolean | undefined
파일 시스템이 읽기 전용 모드인지 여부

행동 양식
행동 양식에 대한 직접 링크

GCSFilesystem은 다음을 구현합니다.WorkspaceFilesystem interface, providing all standard filesystem methods:

  • readFile(path, options?)- 파일 내용 읽기
  • writeFile(path, content, options?)- 파일에 콘텐츠 쓰기
  • appendFile(path, content)- 파일에 콘텐츠 추가
  • deleteFile(path, options?)- 파일 삭제
  • copyFile(src, dest, options?)- 파일 복사
  • moveFile(src, dest, options?)- 파일 이동 또는 이름 바꾸기
  • mkdir(path, options?)- 디렉토리 생성
  • rmdir(path, options?)- 디렉토리 제거
  • readdir(path, options?)- 디렉토리 내용 나열
  • exists(path)- 경로가 존재하는지 확인
  • stat(path)- 파일 또는 디렉터리 메타데이터 가져오기

init()
init에 대한 직접 링크

파일 시스템을 초기화합니다. 버킷 액세스 및 자격 증명을 확인합니다.

await filesystem.init()

getInfo()
getinfo에 대한 직접 링크

이 파일 시스템 인스턴스에 대한 메타데이터를 반환합니다.

const info = filesystem.getInfo()
// { id: '...', name: 'GCSFilesystem', provider: 'gcs', status: 'ready' }

getMountConfig()
getmountconfig에 대한 직접 링크

이 파일 시스템 유형 마운트를 지원하는 샌드박스에 대한 마운트 구성을 반환합니다.

const config = filesystem.getMountConfig()
// { type: 'gcs', bucket: 'my-bucket', ... }

E2B 샌드박스에 탑재
E2B 샌드박스에 탑재에 대한 직접 링크

GCSFilesystem은 E2B 샌드박스에 마운트되어 버킷을 로컬 디렉터리로 액세스할 수 있습니다.

import { Workspace } from '@mastra/core/workspace'
import { GCSFilesystem } from '@mastra/gcs'
import { E2BSandbox } from '@mastra/e2b'

const workspace = new Workspace({
  mounts: {
    '/data': new GCSFilesystem({
      bucket: 'my-gcs-bucket',
      projectId: 'my-project-id',
      credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})

마운트에 관한 자세한 내용은 E2BSandbox 레퍼런스를 참조하세요.

On this page