本章节提供 Mobile Use Agent（MUA）OpenAPI 的通用数据结构。各接口的请求方式、请求参数及返回参数，请查阅对应的 OpenAPI 文档。

前提条件

获取账号的 Access Key ID 和 Secret Access Key （AK/SK），用于 API 请求鉴权。详细步骤，参考 API 访问密钥使用指南。

请求结构

调用 MUA OpenAPI 是通过向指定服务地址发送请求，并需满足签名信息和具体接口的业务信息来完成的。OpenAPI 的请求需要包含服务地址、请求方式、请求参数等信息。接口调用成功后，对返回结果进行解析。

服务地址

open.volcengineapi.com

通信协议

MUA OpenAPI 通信均采用 HTTPS 协议，确保数据传输的安全性和完整性，为您提供一个安全可靠的通信环境。

字符编码

请求及返回结果使用 UTF-8 的字符集进行编码。

请求方式

根据各个接口的具体需求，选择 GET 或 POST 方式发起请求。

请求参数

在发起请求时，请包含以下两类参数：

公共请求参数：所有接口调用时必须包含的参数。公共请求参数首字母均为大写，以此区分接口特有的请求参数。有关火山引擎 OpenAPI 公共参数的详细说明，请参考公共参数。

示例

以查询代理运行配置列表 ListAgentRunConfig 接口为例，一条未编码的 URL 请求示例如下：

说明如下：

参数/结构	说明
Host	请求的通信协议和服务接入地址，为 open.volcengineapi.com。
Action	指定要调用的接口名称。例如，查询代理运行配置列表接口名称为 ListAgentRunConfig。
Version	接口的版本号。MUA OpenAPI 版本号统一为 2023-08-01。
公共请求参数	系统规定的公共参数，主要包括以下参数： AccessKey：访问密钥 ID，用于标识请求方身份，参考 API 访问密钥使用指南获取。 SecretKey：私有访问密钥，用于对请求进行签名，不直接传入请求 Header，参考 API 访问密钥使用指南获取。 ServiceName：OpenAPI 服务名称。MUA OpenAPI 的服务名称固定为 ipaas。 Region：OpenAPI 服务所在区域。MUA OpenAPI 的服务区域固定为 cn-north-1，详情请参见公共参数。
请求体	调用 OpenAPI 需要的业务参数。

通用数据结构

本节介绍 MUA OpenAPI 中的通用数据结构。OutputSchema 用于约束任务输出格式；CallbackInfo 用于配置任务完成后的回调地址及重试策略。

OutputSchema

参数名称	类型	是否必须	描述
Type	String	是	返回数据结构的类型，目前仅支持取值 dict。
Fields	[]FieldSchema	否	定义具体返回结构。详情参见下表 FieldSchema。

FieldSchema

参数名称	类型	是否必须	描述
Name	String	是	字段名称。
Type	String	是	字段类型。
Description	String	否	字段描述。
Required	Boolean	是	字段是否为必填项。 true ：该字段为必填项。 false：该字段为可选项。
Fields	[]FieldSchema	否	子字段列表，用于定义嵌套的返回结构。

使用示例

OutputSchema 示例代码如下：

CallbackInfo

参数名称	类型	是否必须	描述
CallbackUrl	String	否	回调 URL 地址，支持 HTTP/HTTPS，代理任务执行期间产生的回调会发送到该地址。回调包括：任务状态更新回调任务执行失败回调任务中断回调
CallbackRetryLimit	Int	否	回调重试次数，例如取值为 3 表示最多回调 3 次。取值范围：1~5。默认值：3。说明超出取值范围的参数值系统会按默认值处理。
CallbackErrorCode	List[String]	否	自定义错误码，用于服务判断错误情况并决定是否重试。如 CallbackErrorCode 取值为 ["2xx"]，表示服务接收到回调返回在 200~299 间错误码时，会进行重试。重试次数由 CallbackRetryLimit 参数定义。默认值为 ["3xx", "4xx", "5xx"]。可填内容： 2xx：表示错误码 200~299。 200：表示错误码 200。 200~250：表示错误码 200~250。
CallbackTimeout	Int	否	回调超时时间，单位：秒。取值范围：1~300。默认值：5。说明超出取值范围的参数值系统会按默认值处理。
CallbackHeaders	Dict[String]String	否	自定义回调请求头，默认为 {}，示例值：{"a": "b"}。