# 调用智能体运行时--上传文件 - ExecuteRuntimeUploadFiles #### 功能介绍 该接口用于调用已经部署好的高代码智能体运行时，上传文件到智能体内的目标路径。 - 仅传 *path* (单个文件名) 时，文件会自动保存到用户主目录 *\~/* - 支持单文件流式上传和 multipart 多文件表单上传件 - 上传文件时，单文件大小限制为 100MB，多文件总大小限制为 500MB 部署智能体运行时请参见[部署智能体运行时](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_031.html)。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-agentarts/agentarts_07_0003.html)。 #### 授权信息 当前API调用无需身份策略权限。 #### URI POST /runtimes/{runtime_name}/upload-files 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | runtime_name | 是 | String | **参数解释**： 智能体运行时名称。 智能体运行时名称获取方式： 1. 进入AgentArts平台，在左侧导航栏选择"部署运行 \> 智能体运行时 "。 2. 在智能体运行时列表中"智能体运行时名称/ID"处获取智能体运行时名称。 **约束限制**: 不涉及。 **取值范围**： 以小写字母开头，以小写字母或数字结尾，可以包含小写字母、数字和中划线，长度为2-48个字符。 **默认取值**: 不涉及。 | 表2Query参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | path | 是 | String | **参数解释**： 目标文件路径（URL 编码格式）。请求头的Content-Type为application/octet-stream时格式为文件名，表单上传和tar上传为目录 **约束限制**: 不允许使用*/* 根目录，不允许出现*\\x00、\\n、\\r、;、\|、\&、$、\\\\*、!、{、}\`等特殊字符 **取值范围**： 参考linux的文件路径格式，支持绝对路径和相对路径（相对路径不允许使用..）。 **默认取值**: 无 | | user_id | 否 | String | **参数解释**： 设置文件所属用户。 **约束限制**: 无 **取值范围**： 纯数字，参考Linux的用户UID。 **默认取值**: 默认为当前启动镜像的用户UID | | group_id | 否 | String | **参数解释**： 设置文件所属用户组。 **约束限制**: 无 **取值范围**： 纯数字，参考Linux的用户组GID。 **默认取值**: 默认为当前启动镜像的用户组GID | | file_mode | 否 | String | **参数解释**： 设置文件的权限 。 **约束限制**: 无 **取值范围**： 纯数字，参考Linux的八进制文件权限(例如 0644)。 **默认取值**: 默认为当前启动镜像的用户的默认创建文件权限，可以依据镜像内umask命令结果 | | endpoint | 否 | String | **参数解释**： 用于调用智能体运行时使用的访问方式名称，访问指定的智能体运行时版本。 获取访问方式名称请参考如下： 1. 进入AgentArts平台，在左侧导航栏选择"部署运行 \> 智能体运行时 "。 2. 单击已创建的智能体运行时名称，在"基本信息"页签下即可查看访问方式。 如未创建访问方式，则默认使用该运行时的Latest访问方式。 **约束限制**: 不涉及。 **取值范围**： 以字母开头，以字母或数字结尾，可以包含字母、数字和中划线，长度为2-48个字符。 **默认取值**: Latest | #### 请求参数 表3请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Hw-Agentarts-Session-Id | 是 | String | **参数解释**： 会话ID，每个会话的唯一标识符。用户可将会话ID设置为任意字符串，例如"123e4567e89b12d3a456426614174000"，无需在其他地方获取。 **约束限制**: 不涉及。 **取值范围**： 由英文，数字，"-"，"_"组成，不超过64位字符。 **默认取值**: 不涉及。 | | X-Hw-Agentgateway-User-Id | 否 | String | **参数解释**： 本次智能体运行时调用对应的用户唯一ID，用于标识此次调用的用户身份，用户可将会话ID设置为任意字符串，例如"123e4567e89b12d3a456426614174000"，无需在其他地方获取。 **约束限制**: 不涉及。 **取值范围**： 由英文，数字，"-"，"_"组成，不超过128位字符。 **默认取值**: 不涉及。 | | Authorization | 是 | String | **参数解释**： 本次智能体运行时调用对应的身份认证凭据。需要根据实际的智能体运行时的入站身份认证方式获取对应的身份认证凭据。 API Key认证、IAM认证及OAuth 2.0认证具体请参见[认证鉴权](https://support.huaweicloud.com/api-agentarts/agentarts_07_0005.html)。 **约束限制**: 不涉及。 **取值范围**： 不超过4096位字符。 **默认取值**: 不涉及。 | | X-Sdk-Content-Sha256 | 否 | String | **参数解释**： 如果智能体运行时的入站认证类型为IAM认证时，需要指定该Header头为UNSIGNED-PAYLOAD。 **约束限制**: 不涉及。 **取值范围**： 固定为UNSIGNED-PAYLOAD。 **默认取值**: 不涉及。 | #### 响应参数 **状态码：200** 表4响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | code | Integer | **参数解释**: 上传文件成功的状态码，固定为200。 **取值范围**: 不涉及。 | | message | String | **参数解释**： 上传文件成功的描述信息。 **取值范围**： 长度为 1 - 512 个字符。 | **状态码：400** 表5响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | Integer | **参数解释**: 异常错误码。 **取值范围**: 不涉及。 | | error_message | String | **参数解释**： 错误详细信息。 **取值范围**： 长度为 1 - 512 个字符。 | **状态码：401** 表6响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | code | Integer | **参数解释**: 异常错误码。 **取值范围**: 不涉及。 | | message | String | **参数解释**： 错误详细信息。 **取值范围**： 长度为 1 - 512 个字符。 | **状态码：404** 表7响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | code | Integer | **参数解释**: 异常错误码。 **取值范围**: 不涉及。 | | message | String | **参数解释**： 错误详细信息。 **取值范围**： 长度为 1 - 512 个字符。 | **状态码：429** 表8响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | Integer | **参数解释**: 异常错误码。 **取值范围**: 不涉及。 | | error_message | String | **参数解释**： 错误详细信息。 **取值范围**： 长度为 1 - 512 个字符。 | **状态码：500** 表9响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | code | Integer | **参数解释**: 异常错误码。 **取值范围**: 不涉及。 | | message | String | **参数解释**： 错误详细信息。 **取值范围**： 长度为 1 - 512 个字符。 | **状态码：503** 表10响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | Integer | **参数解释**: 异常错误码。 **取值范围**: 不涉及。 | | error_message | String | **参数解释**： 错误详细信息。 **取值范围**： 长度为 1 - 512 个字符。 | #### 请求示例 - 使用application/octet-stream纯文件流式上传文件（必须在 path 中指定上传目录）, gateway_domain为运行时的访问域名，可以在智能体运行时的详情页面中获取 ``` POST https://{gateway_domain}/runtimes/{runtime_name}/upload-files?path=/xxx Content-Type: application/octet-stream Body: 需要上传的二进制文件 ``` - 使用application/x-tar上传tar包文件（必须在 path 中指定上传目录）, gateway_domain为运行时的访问域名，可以在智能体运行时的详情页面中获取 ``` POST https://{gateway_domain}/runtimes/{runtime_name}/upload-files?path=/xxx Content-Type: application/x-tar Body: 需要上传的二进制文件tar包 ``` - 使用multipart/form-data表单上传文件，gateway_domain为运行时的访问域名，可以在智能体运行时的详情页面中获取 ``` POST https://{gateway_domain}/runtimes/{runtime_name}/upload-files?path=/xxx Content-Type: multipart/form-data; boundary= Body: Form类型 File=@"/xxx.txt" ``` #### 响应示例 **状态码：200** 智能体调用成功的响应Body体。 ``` { "code" : 200, "message" : "upload xxx success" } ``` **状态码：400** 目标路径为目录或参数错误 ``` { "error_message" : "[node-proxy] path must be a directory ending with '/'", "error_code" : 400 } ``` **状态码：429** 接口调用并发数限流 ``` { "error_message" : "[node-proxy] sandbox upload file concurrency exceeded limit", "error_code" : 429 } ``` **状态码：503** 执行上传命令失败 ``` { "error_message" : "execute upload command failed", "error_code" : 503 } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 智能体调用成功的响应Body体。 | | 400 | 目标路径为目录或参数错误 | | 401 | 未授权（认证令牌缺失、无效或已过期）。 | | 404 | 运行时资源不存在。 | | 429 | 接口调用并发数限流 | | 500 | 服务器内部错误。 | | 503 | 执行上传命令失败 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-agentarts/ErrorCode.html)。