# 文件上传与下载
[ExecuteRuntimeUploadFiles](https://support.huaweicloud.com/api-agentarts/ExecuteRuntimeUploadFiles.html)接口，允许将本地文件上传到会话沙箱的文件系统中。上传后，Agent代码可以通过文件路径直接读取。
#### 文件上传接口说明
表1接口说明 
| 项目     | 说明                                     |
|:---|:---|
| 请求方法    | POST                                    |
| 请求路径    | /runtimes/{runtime_name}/upload-files |
| 关键查询参数 | path（必填），表示目标文件路径或目录路径。                   |
   
表2Query参数说明 
| 请求头         | 是否必填 | 说明                                                                                                                                                                                                                                                                                                                        |
|:---|:---|:---|
| path       | 是     | 目标路径。支持两种写法： - 指定完整文件路径（如/workspace/data.csv），适用于单文件上传。  - 指定目录路径（如/workspace/，以/结尾），文件会自动保存到该目录下。不能使用 /（根目录），不能使用 ..（相对路径回退）。   |
| file_mode   | 否     | 设置文件权限（Linux八进制权限，如0644）。默认由镜像的umask决定。                                                                                                                                                                                                                                                                                |
| user_id   | 否  | 设置文件所属用户（Linux UID）。默认为当前启动镜像的用户UID。                                                                                                                                                                                                                                                                                  |
| group_id | 否     | 设置文件所属用户组（Linux GID）。默认为当前启动镜像的用户组GID。                                                                                                                                                                                                                                                                                  |
| endpoint  | 否   | 访问方式名称，用于指定运行时版本。默认Latest。                                                                                                                                                                                                                                                                                             |
   
- 仅传文件名时（如path=data.csv），文件会自动保存到用户主目录 \~/ 下。
- 单文件不超过100MB。
- 多文件总计不超过 500MB（仅multipart表单模式）。
表3请求头参数 
| 请求头                         | 是否必填   | 说明                                                                                                |
|:---|:---|:---|
| Content-Type                  | 是     | 固定为 application/json。                                                                          |
| Authorization               | 是       | 身份认证凭据。API Key 方式填写 Bearer {api_key}；IAM 方式由签名 SDK 自动生成；OAuth 2.0 方式填写 Bearer {jwt_token}。       |
| X-Hw-Agentarts-Session-Id | 是        | 会话 ID，用于标识一次会话。您可以自行生成一个字符串（如 UUID），同一个 Session ID 的多次调用在 Agent 侧可关联上下文。由英文、数字、-、_ 组成，不超过 64 个字符。 |
| X-Sdk-Content-Sha256          | IAM认证时必填 | 如果智能体运行时的入站认证类型为IAM认证时，需要指定该Header头为UNSIGNED-PAYLOAD。                                             |
| X-Hw-Agentgateway-User-Id   | 否          | 用户标识，用于区分不同终端用户。由英文、数字、-、_ 组成，不超过 128 个字符。                                                        |
   
#### 三种文件上传方式
AgentArts支持三种上传方式，适用于不同场景：
表4文件上传方式 
| 上传方式     | Content-Type            | path参数含义                         | 适用场景                          |
|:---|:---|:---|:---|
| 单文件流式上传  | application/octet-stream | 目标文件的完整路径（如 /workspace/data.csv）。 | 上传单个文件。                       |
| tar包上传 | application/x-tar       | 目标目录路径（如 /workspace/）。           | 一次上传多个文件，打包为 tar 格式，服务端自动解压。 |
| 表单上传     | multipart/form-data      | 目标目录路径（如 /workspace/）。         | 一次上传多个文件，使用标准表单格式。           |
   
表单上传和tar上传时，path参数应指定为目录路径（以/结尾），文件会保存到该目录下。
#### 上传文件调用示例
**以下示例使用API Key鉴权方式进行演示。**
- **示例一：单文件上传（最常用）**
  ```
  curl -X POST \
    "https://{域名}/runtimes/{runtime_name}/upload-files?path=/workspace/data.csv" \
    -H "Authorization: Bearer {api_key}" \
    -H "X-Hw-Agentarts-Session-Id: {session_id}" \
    -H "Content-Type: application/octet-stream" \
    --data-binary @./local_data.csv
  ```
  
- **示例二：多文件表单上传**
  ```
  curl -X POST \
    "https://{域名}/runtimes/{runtime_name}/upload-files?path=/workspace/" \
    -H "Authorization: Bearer {api_key}" \
    -H "X-Hw-Agentarts-Session-Id: {session_id}" \
    -F "file1=@./data.csv" \
    -F "file2=@./config.json"
  ```
  
- **示例三：tar包批量上传**
  ```
  # 1. 先在本地打包
  tar -czf bundle.tar.gz ./data/*
  # 2. 上传 tar 包（服务端自动解压到 /workspace/）
  curl -X POST \
    "https://{域名}/runtimes/{runtime_name}/upload-files?path=/workspace/" \
    -H "Authorization: Bearer {api_key}" \
    -H "X-Hw-Agentarts-Session-Id: {session_id}" \
    -H "Content-Type: application/x-tar" \
    --data-binary @./bundle.tar.gz
  ```
  
#### 下载文件接口说明
[ExecuteRuntimeDownloadFiles](https://support.huaweicloud.com/api-agentarts/ExecuteRuntimeDownloadFiles.html)接口，将会话沙箱中的文件下载到本地。典型用法：下载 Agent 生成的分析报告、表格、代码文件等结果。
表5接口说明 
| 项目     | 说明                                          |
|:---|:---|
| 请求方法 | GET                                         |
| 请求路径  | /runtimes/{runtime_name}/download-files    |
| 关键查询参数 | path（必填），表示源文件路径；recursive（可选），表示是否按归档包下载。 |
   
表6Query参数说明 
| 请求头      | 是否必填 | 说明                                               |
|:---|:---|:---|
| path    | 是   | 沙箱内需要下载的文件路径（URL编码格式）。支持绝对路径和相对路径。                |
| recursive | 否      | 默认false（单文件下载）。设为true时按tar归档包下载，适用于下载整个目录下的所有文件。 |
| endpoint   | 否    | 访问方式名称，用于指定运行时版本。默认Latest。                         |
   
表7请求头参数 
| 请求头                          | 是否必填      | 说明                                                                                                |
|:---|:---|:---|
| Content-Type                 | 是         | 固定为 application/json。                                                                            |
| Authorization              | 是         | 身份认证凭据。API Key 方式填写 Bearer {api_key}；IAM 方式由签名 SDK 自动生成；OAuth 2.0 方式填写 Bearer {jwt_token}。        |
| X-Hw-Agentarts-Session-Id | 是          | 会话 ID，用于标识一次会话。您可以自行生成一个字符串（如 UUID），同一个 Session ID 的多次调用在 Agent 侧可关联上下文。由英文、数字、-、_ 组成，不超过 64 个字符。 |
| X-Sdk-Content-Sha256      | IAM认证时必填 | 如果智能体运行时的入站认证类型为IAM认证时，需要指定该Header头为UNSIGNED-PAYLOAD。                                            |
| X-Hw-Agentgateway-User-Id  | 否        | 用户标识，用于区分不同终端用户。由英文、数字、-、_ 组成，不超过 128 个字符。                                                         |
   
#### 文件下载调用示例
**以下示例使用API Key鉴权方式进行演示。**
- **示例一：下载单个文件**
  ```
  curl -X GET \
    "https://{域名}/runtimes/{runtime_name}/download-files?path=/workspace/report.pdf" \
    -H "Authorization: Bearer {api_key}" \
    -H "X-Hw-Agentarts-Session-Id: {session_id}" \
    -o report.pdf
  ```
  
- **示例二：下载整个目录**
  ```
  curl -X GET \
    "https://{域名}/runtimes/{runtime_name}/download-files?path=/workspace/output/&recursive=true" \
    -H "Authorization: Bearer {api_key}" \
    -H "X-Hw-Agentarts-Session-Id: {session_id}" \
    -o output.tar
  ```