> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# AzureBlobFilesystem

將檔案儲存在 Azure Blob Storage 容器中。介面詳情請參閱 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-TW/reference/workspace/filesystem)。

## 安裝

**npm**:

```bash
npm install @mastra/azure
```

**pnpm**:

```bash
pnpm add @mastra/azure
```

**Yarn**:

```bash
yarn add @mastra/azure
```

**Bun**:

```bash
bun add @mastra/azure
```

## 使用方式

將 `AzureBlobFilesystem` 加入 Workspace，並指派給 Agent：

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { AzureBlobFilesystem } from '@mastra/azure/blob'

const workspace = new Workspace({
  filesystem: new AzureBlobFilesystem({
    container: 'my-container',
    connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING,
  }),
})

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

### 帳戶金鑰

如果不想傳入完整連線字串，請使用帳戶名稱與帳戶金鑰：

```typescript
import { AzureBlobFilesystem } from '@mastra/azure/blob'

const filesystem = new AzureBlobFilesystem({
  container: 'my-container',
  accountName: process.env.AZURE_STORAGE_ACCOUNT_NAME,
  accountKey: process.env.AZURE_STORAGE_ACCOUNT_KEY,
})
```

### 共用存取簽章 Token

將共用存取簽章（SAS）Token 與 `accountName` 或 `endpoint` 搭配使用：

```typescript
import { AzureBlobFilesystem } from '@mastra/azure/blob'

const filesystem = new AzureBlobFilesystem({
  container: 'my-container',
  accountName: process.env.AZURE_STORAGE_ACCOUNT_NAME,
  sasToken: process.env.AZURE_STORAGE_SAS_TOKEN,
})
```

### DefaultAzureCredential

如果環境提供 Azure 身分認證，請使用 `DefaultAzureCredential`：

```typescript
import { AzureBlobFilesystem } from '@mastra/azure/blob'

const filesystem = new AzureBlobFilesystem({
  container: 'my-container',
  accountName: process.env.AZURE_STORAGE_ACCOUNT_NAME,
  useDefaultCredential: true,
})
```

使用 `DefaultAzureCredential` 時，請安裝 `@azure/identity`：

**npm**:

```bash
npm install @azure/identity
```

**pnpm**:

```bash
pnpm add @azure/identity
```

**Yarn**:

```bash
yarn add @azure/identity
```

**Bun**:

```bash
bun add @azure/identity
```

## 建構函式參數

**container** (`string`): Azure Blob Storage 容器名稱

**connectionString** (`string`): 完整的 Azure Storage 連線字串。優先於其他驗證選項。

**accountName** (`string`): Azure Storage 帳戶名稱。除非使用 connectionString 或 endpoint，否則為必填。

**accountKey** (`string`): Azure Storage 帳戶金鑰。

**sasToken** (`string`): 共用存取簽章 Token。需要 accountName 或 endpoint。

**useDefaultCredential** (`boolean`): 使用 @azure/identity 的 DefaultAzureCredential。 (Default: `false`)

**endpoint** (`string`): 自訂 Blob 服務端點 URL。用於搭配 Azurite 進行本機開發。

**prefix** (`string`): 所有鍵可使用的選用前綴（作用如同子目錄）。

**id** (`string`): 此檔案系統執行個體的唯一識別碼。 (Default: `Auto-generated`)

**displayName** (`string`): 在 UI 中顯示的易讀名稱。

**icon** (`FilesystemIcon`): UI 使用的圖示識別碼。

**description** (`string`): 在 UI 中顯示的檔案系統簡短說明。

**readOnly** (`boolean`): 設為 true 時，會封鎖所有寫入操作。 (Default: `false`)

## 屬性

**id** (`string`): 檔案系統執行個體識別碼。

**name** (`string`): Provider 名稱（'AzureBlobFilesystem'）。

**provider** (`string`): Provider 識別碼（'azure-blob'）。

**readOnly** (`boolean | undefined`): 檔案系統是否處於唯讀模式。

## 方法

AzureBlobFilesystem 實作 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-TW/reference/workspace/filesystem)，並提供所有標準檔案系統方法：

- `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()`

初始化檔案系統。驗證容器存取權與認證。

```typescript
await filesystem.init()
```

### `getInfo()`

傳回此檔案系統執行個體的中繼資料。

```typescript
const info = filesystem.getInfo()
// { id: '...', name: 'AzureBlobFilesystem', provider: 'azure-blob', status: 'ready' }
```

### `getContainer()`

傳回底層 Azure Blob Storage `ContainerClient`。

```typescript
const container = await filesystem.getContainer()
```

### `getMountConfig()`

傳回支援 Azure Blob 檔案系統掛載之 Sandbox Provider 的掛載設定。

```typescript
const config = filesystem.getMountConfig()
// { type: 'azure-blob', container: 'my-container', ... }
```

> **備註:** Azure Blob Sandbox 掛載取決於 Sandbox 是否支援 `azure-blob` 掛載設定。當 Sandbox Provider 不支援 Azure Blob 掛載時，請使用 `filesystem` 直接執行 Workspace 檔案操作。

## 相關內容

- [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-TW/reference/workspace/filesystem)
- [S3Filesystem 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/s3-filesystem)
- [GCSFilesystem 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/gcs-filesystem)
- [Workspace 概觀](https://mastra.zisheng.pro/zh-TW/docs/workspace/overview)