跳至主要內容

GoogleDriveFilesystem

將檔案儲存在單一 Google Drive 資料夾中。每個目錄都會對應到已設定根目錄下的 Drive 資料夾，路徑則採用 POSIX 語意（例如 /notes/todo.txt）。介面詳情請參閱 WorkspaceFilesystem 介面。

安裝
「安裝」的直接連結

npm install @mastra/google-drive

使用方式
「使用方式」的直接連結

將 GoogleDriveFilesystem 加入 Workspace，並指派給 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 存取 Token。使用 https://www.googleapis.com/auth/drive scope，讓 Token 能查看與已驗證身分共用的資料夾。
  • getAccessToken：傳回 Token 的回呼函式，適合在外部重新整理 Token 時使用。
  • serviceAccount：Google 服務帳戶。請將目標資料夾與服務帳戶電子郵件地址共用。

服務帳戶
「服務帳戶」的直接連結

對後端 Agent 而言，建議使用服務帳戶身分驗證。它不需要使用者同意流程，也不需要處理 Token 更新。你只需要服務帳戶 JSON 金鑰檔案中的兩個值：client_email 和 private_key。

設定服務帳戶
「設定服務帳戶」的直接連結
  1. 開啟 Google Cloud Console，選取或建立專案。
  2. 前往 APIs & Services > Library，搜尋 Google Drive API，然後選取 Enable。
  3. 前往 APIs & Services > Credentials，依序選取 Create credentials > Service account，並完成表單。角色可以留空，因為 Drive 權限是透過共用資料夾授予，而不是透過 IAM 角色。
  4. 開啟新的服務帳戶，前往 Keys 分頁，依序選取 Add key > Create new key > JSON。瀏覽器會下載 JSON 金鑰檔案。
  5. 從 JSON 檔案複製 client_email 值。這就是與 Drive 資料夾共用時使用的地址。
與服務帳戶共用 Drive 資料夾
「與服務帳戶共用 Drive 資料夾」的直接連結

服務帳戶具有獨立的 Google 身分。除非你明確與它共用，否則它無法查看 Drive 中的任何內容。

  1. 在 Google Drive 中開啟目標資料夾。
  2. 選取 Share。
  3. 貼上服務帳戶的 client_email 地址。
  4. 將角色設為 Editor（讀寫）或 Viewer（唯讀存取），然後選取 Send。
  5. 從 URL 複製資料夾 ID。它是 https://drive.google.com/drive/folders/<folderId> 中 /folders/ 後面的區段。
警告

服務帳戶無法在標準的「My Drive」資料夾中建立檔案。服務帳戶沒有個人 Drive 儲存空間配額，因此它建立的任何檔案都必須由具有配額的實體擁有。如果只共用個人 Drive 資料夾，讀取操作可以正常執行，但寫入操作會因配額錯誤而失敗。

若要提供寫入權限，請將資料夾放在共用雲端硬碟（舊稱 Team Drive）中，並將服務帳戶加入該共用雲端硬碟成為成員。共用雲端硬碟能提供服務帳戶建立檔案所需的儲存空間配額。

針對個人 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']，這是服務帳戶查看與其共用資料夾所需的 scope。範圍較小的 drive.file scope 只能存取應用程式自行建立的檔案，因此與服務帳戶共用的資料夾會傳回 404 Not Found。

GoogleDriveFilesystem 會在簽署前自動正規化 privateKey 字串。它會移除前後引號，包括 JSON 包裝值中的逸出引號，並將字面值 \n 序列轉換為實際換行。它也會正規化 \r\n 行尾，並移除結尾逗號。無論 .env 載入器如何處理該值，金鑰都可正常運作。

疑難排解
「疑難排解」的直接連結
  • 404 File not found: <folderId>：服務帳戶沒有該資料夾的存取權。確認資料夾已與完全相符的 client_email 地址共用，且資料夾 ID 與 URL 相符。
  • 寫入時發生 storageQuotaExceeded：資料夾位於個人的「My Drive」中。請將資料夾移至共用雲端硬碟，並將服務帳戶加入成為成員。
  • error:1E08010C:DECODER routines::unsupported：privateKey 值的格式不正確。確認該值包含完整 PEM 區塊，且換行已保留（可使用字面值 \n）。

唯讀模式
「唯讀模式」的直接連結

傳入 readOnly: true，即可封鎖寫入操作（writeFile、appendFile、deleteFile、copyFile、moveFile、mkdir、rmdir）。

const filesystem = new GoogleDriveFilesystem({
  folderId,
  accessToken,
  readOnly: true,
})

建構函式參數
「建構函式參數」的直接連結

folderId:

string
作為 Workspace 根目錄的 Google Drive 資料夾 ID。所有路徑都會在此資料夾內解析。

accessToken?:

string
具備該資料夾存取權的 OAuth 存取 Token。

getAccessToken?:

() => string | Promise<string>
傳回新 OAuth 存取 Token 的回呼函式。每次需要授權的要求都會呼叫此函式。

serviceAccount?:

{ clientEmail: string; privateKey: string; privateKeyId?: string; scopes?: string[]; subject?: string }
透過 OAuth 2.0 JWT 流程簽發存取 Token 所使用的服務帳戶認證資訊。

id?:

string
= `google-drive:${folderId}`
此檔案系統執行個體的唯一識別碼

readOnly?:

boolean
= false
設為 true 時，會封鎖所有寫入操作。

instructions?:

InstructionsOption
覆寫傳回 Tool 說明的預設指示。

屬性
「屬性」的直接連結

id:

string
檔案系統執行個體識別碼

name:

string
Provider 名稱（'GoogleDriveFilesystem'）。

provider:

string
Provider 識別碼（'google-drive'）。

readOnly:

boolean | undefined
檔案系統是否處於唯讀模式

方法
「方法」的直接連結

GoogleDriveFilesystem 實作 WorkspaceFilesystem 介面，並提供所有標準檔案系統方法：

  • readFile(path, options?) - 下載檔案內容
  • writeFile(path, content, options?) - 上傳或覆寫檔案
  • appendFile(path, content) - 讀取檔案並重新上傳，以附加內容
  • deleteFile(path, options?) - 刪除檔案
  • copyFile(src, dest, options?) - 使用 Drive files.copy API 複製檔案
  • moveFile(src, dest, options?) - 透過更換上層資料夾，在資料夾間移動檔案
  • mkdir(path, options?) - 建立資料夾
  • rmdir(path, options?) - 移除資料夾
  • readdir(path, options?) - 列出資料夾內容（支援 recursive 和 extension 篩選）
  • stat(path) - 傳回檔案或資料夾的 Drive 中繼資料
  • exists(path) - 檢查檔案或資料夾是否存在

注意事項
「注意事項」的直接連結

  • Google Drive 允許同一個資料夾中存在多個同名檔案。GoogleDriveFilesystem 會選取第一個相符項目來解析路徑，因此依賴路徑查詢時，請讓每個資料夾內的名稱保持唯一。
  • 當 recursive 未設定（預設值）或設為 true 時，writeFile 會自動建立上層資料夾。設為 recursive: false，即可要求上層資料夾必須已存在。
  • 系統會遵循 WriteOptions 上的 expectedMtime。當儲存的 modifiedTime 不同時，寫入會因 StaleFileError 而遭到拒絕，以支援樂觀並行控制。
  • 此 Provider 僅透過內建 fetch 存取 Drive REST 端點（https://www.googleapis.com/drive/v3 和 https://www.googleapis.com/upload/drive/v3），不需要其他 dependency。
On this page