跳至主要內容

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 access token。請使用 https://www.googleapis.com/auth/drive scope，讓 token 能夠查看與已驗證身分共享的資料夾。
  • getAccessToken：傳回 token 的 callback，適合在外部重新整理 token 時使用。
  • serviceAccount：Google service account。請與 service account 電郵地址共享目標資料夾。

Service account
Service account 的直接連結

對後端 Agent 而言，建議使用 service account 驗證。此方式毋須使用者同意流程，亦毋須處理 token 重新整理。你只需要 service account JSON key 檔案中的兩個值：client_email 及 private_key。

設定 service account
設定 service account 的直接連結
  1. 開啟 Google Cloud Console，然後選擇或建立項目。
  2. 前往 APIs & Services > Library，搜尋 Google Drive API，然後選擇 Enable。
  3. 前往 APIs & Services > Credentials，選擇 Create credentials > Service account，然後填妥表格。角色可以留空：Drive 權限是透過共享資料夾授予，而非 IAM 角色。
  4. 開啟新的 service account，前往 Keys 分頁，然後選擇 Add key > Create new key > JSON。瀏覽器會下載 JSON key 檔案。
  5. 從 JSON 檔案複製 client_email 值。你將使用此地址共享 Drive 資料夾。
與 service account 共享 Drive 資料夾
與 service account 共享 Drive 資料夾 的直接連結

Service account 是獨立的 Google 身分。在你明確與它共享內容之前，它無法查看 Drive 中的任何內容。

  1. 在 Google Drive 開啟目標資料夾。
  2. 選擇 Share。
  3. 貼上 service account 的 client_email 地址。
  4. 將角色設為 Editor（可讀寫）或 Viewer（唯讀存取），然後選擇 Send。
  5. 從 URL 複製資料夾 ID。它是 https://drive.google.com/drive/folders/<folderId> 中 /folders/ 之後的部分。
注意

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

如需寫入權限，請將資料夾放在共用雲端硬碟（前稱 Team Drive）內，並將 service account 加為該共用雲端硬碟的成員。共用雲端硬碟會提供 service account 所建立檔案需要的儲存配額。

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

GoogleDriveFilesystem 會在簽署前自動將 privateKey 字串標準化。它會移除外層引號（包括以 JSON 包裝的值內已逸出的引號），並將字面值 \n 序列轉換為真正的換行。它亦會將 \r\n 換行符號標準化，並移除結尾逗號。無論你的 .env 載入器如何處理該值，key 都能正常運作。

疑難排解
疑難排解 的直接連結
  • 404 File not found: <folderId>：Service account 無權存取該資料夾。請確認資料夾已與確切的 client_email 地址共享，且資料夾 ID 與 URL 相符。
  • 寫入時出現 storageQuotaExceeded：資料夾位於個人「My Drive」中。請將資料夾移至共用雲端硬碟，並將 service account 加為成員。
  • error:1E08010C:DECODER routines::unsupported：privateKey 值格式錯誤。請確認該值包含完整 PEM block，且換行得以保留（字面值 \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 access token。

getAccessToken?:

() => string | Promise<string>
傳回最新 OAuth access token 的 callback。每次有請求需要授權時都會呼叫。

serviceAccount?:

{ clientEmail: string; privateKey: string; privateKeyId?: string; scopes?: string[]; subject?: string }
透過 OAuth 2.0 JWT 流程產生 access token 所使用的 service account 憑證。

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?) - 透過更換 parent，在資料夾之間移動檔案
  • 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 endpoint（https://www.googleapis.com/drive/v3 及 https://www.googleapis.com/upload/drive/v3），毋須其他 dependency。
On this page