# 下载工作区原始文件

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

将工作区文件按原始字节下载，支持可选的全量限制或前缀读取。

```text
GET https://api.moi.matrixorigin.cn/v5/workspaces/{id}/files/{file_id}/download
```

## 调用前准备

`BASE_URL` 使用产品 API 前缀 `https://api.moi.matrixorigin.cn/v5`；专有部署填写对应的产品 API 地址。

准备目标工作区个人访问令牌；WORKSPACE_ID须与路径工作区一致，FILE_ID来自实际文件结果。BASE_URL包含同环境产品前缀，示例文件/ID仅为占位值。

## 请求参数

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl --fail-with-body -sS -X GET "$BASE_URL/workspaces/$WORKSPACE_ID/files/$FILE_ID/download" \
  -H "X-API-Key: $MOI_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -o "$OUTPUT_FILE"
```

指定MAX_BYTES为正整数字节数，分别选择完整文件限制或前缀读取。

```bash
curl --fail-with-body -sS "$BASE_URL/workspaces/$WORKSPACE_ID/files/$FILE_ID/download" \
  -H "X-API-Key: $MOI_KEY" -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "X-MOI-Max-Download-Bytes: $MAX_BYTES" \
  -o "$OUTPUT_FILE"
```

```bash
curl --fail-with-body -sS "$BASE_URL/workspaces/$WORKSPACE_ID/files/$FILE_ID/download" \
  -H "X-API-Key: $MOI_KEY" -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "X-MOI-Download-Prefix-Bytes: $MAX_BYTES" \
  -o "$OUTPUT_FILE"
```

:::::
:::::{tab-item} 参数说明

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `X-MOI-Max-Download-Bytes` | integer | 否 | 正整数请求头；文件超过上限时在读取前拒绝。 |
| `X-MOI-Download-Prefix-Bytes` | integer | 否 | 正整数请求头；返回至多该长度前缀。 |

两个请求头不能同时提供。Content-Length为本次字节数，前缀读取不代表完整文件。zip使用application/zip，其他文件使用application/octet-stream；附件文件名按原始名称编码。

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```text
sample
```

:::::
:::::{tab-item} 字段说明

响应为字节流；消费并关闭流，检查读取/退出状态后使用文件。响应开始后失败可中断连接。

:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": 2,
  "message": "示例错误信息"
}
```

:::::
:::::{tab-item} 字段说明

无效字节限制或两个限制冲突为400/2，并返回相应details.reason。错误使用数值code/message。 大小超限为413/14，details含reason=DOWNLOAD_LIMIT_EXCEEDED、file_size、limit。外部源不存在/拒绝/不可用分别404/3、403/5、503/15，reason为SOURCE_OBJECT_NOT_FOUND、SOURCE_OBJECT_ACCESS_DENIED、SOURCE_OBJECT_UNAVAILABLE，并含domain/file_id。

:::::
::::::
:::::::
