本文介绍了调用云手机-iPaaS服务端 OpenAPI 的方法，对于具体 OpenAPI 的调用方法，请参考具体的接口说明文档。
调用云手机服务端 OpenAPI 接口时，是通过向指定服务地址发送请求，并需满足签名信息和具体接口的业务信息来完成的。API 的请求需要包含服务地址、请求方式、请求参数等信息。接口调用成功后，对返回结果进行解析。
以获取实例列表接口为例，一条未编码的URL请求示例如下：
https://open.volcengineapi.com?Action=ListInstance &Version=2020-10-25 &<通过header传入的公共请求参数> &<请求体>
说明如下：
| 参数/结构 | 说明 |
|---|---|
| https://open.volcengineapi.com | 请求的通信协议和服务接入地址 |
| Action | 指定要调用的 API 接口（示例中的 ListInstance 为查询实例列表接口） |
| Version | 接口的版本号（云手机-iPaaS OpenAPI 的接口版本号固定为 2020-10-25 或 2023-08-01，具体参考接口说明） |
通过header传入的公共请求参数 | 系统规定的公共参数，主要包括以下参数：
|
| 请求体 | 调用 OpenAPI 接口需要的业务参数 |
云手机 OpenAPI 的服务接入地址如下：
| 服务地域 | 域名 | 备注 |
|---|---|---|
| 国内 | https://open.volcengineapi.com | 火山引擎 |
云手机提供的所有接口均通过 HTTPS 进行通信，提供高安全性的通信通道。
根据各个接口的具体需求，选择 GET 或 POST 方式发起请求。
在发起请求时，请求体中可能会包含两类参数：公共请求参数和接口特有的业务参数。
请求及返回结果使用 UTF-8 的字符集进行编码。
公共请求参数是每个接口都需要使用的请求参数，在发送请求时都需要携带这些公共请求参数，否则会导致请求失败。公共请求参数首字母均为大写，以此区分接口特有的请求参数。
调用云手机服务 OpenAPI 需要的公共请求参数如下：
| 名称 | 位置 | 类型 | 是否必填 | 描述 | 示例值 |
|---|---|---|---|---|---|
| Action | Query | String | 是 | 接口名称，与具体的接口相关，表示要执行的操作 | ListInstance |
| Version | Query | String | 是 | 接口版本 | 固定值：2020-10-25 |
| Region | Header | String | 是 | 服务区域 | 固定值：cn-north-1 |
| Service | Header | String | 是 | 服务名称 | 固定值：iPaaS |
| X-Date | Header | String | 是 | 发送请求的时间戳 | 20201103T104027Z， 使用UTC时间，精确到秒 |
Authorization | Header | String | 是 | 发送的请求中包含的签名 | HMAC-SHA256 Credential={AccessKey}/{ShortDate}/{Region}/{Service}/request, SignedHeaders={SignedHeaders}, Signature={Signature} |
| Content-Type | Header | String | 否 | 资源的 MIME 类型 | application/x-www-form-urlencoded; charset=utf-8 |
有关火山引擎 OpenAPI 公共参数的详细说明，请参考 公共参数。
对于每一次 HTTPS 协议请求，会根据访问中的签名信息验证访问请求者的身份。具体由用户的火山引擎账号对应的 AccessKey ID 和 AccessKey Secret（AK/SK）对称加密验证实现。
具体的签名机制和方法，参考火山引擎 OpenAPI 签名方法。
API 请求可返回以下结果：
字段 | 类型 | 是否一定返回 | 说明 |
|---|---|---|---|
| ResponseMetadata | Object | 是 | 响应元数据；需通过解析该结构体，判断响应结果，参考以下 ResponseMetadata 结构说明 |
| Result | Any | 否 | 响应数据；调用成功时返回 |
ResponseMetadata 结构说明
字段 | 类型 | 是否一定返回 | 说明 |
|---|---|---|---|
| RequestId | String | 是 | 请求 ID |
| Action | String | 是 | OpenAPI 接口名称 |
| Version | String | 是 | OpenAPI 接口版本 |
| Service | String | 是 | OpenAPI 服务名称 |
| Region | String | 是 | 服务所在地域信息 |
| Error | Object | 否 | 错误信息；调用失败时返回，参考以下 Error 结构说明 |
Error 结构说明
字段 | 类型 | 是否一定返回 | 说明 |
|---|---|---|---|
| CodeN | Int64 | 是 | 状态码 |
| Code | String | 是 | 状态消息 |
| Message | String | 是 | 具体的错误描述信息 |
调用成功
{ "ResponseMetadata": { "Action": "ListInstance", "Region": "cn-north-1", "RequestId": "20230801174209515C65A8A83C37019069", "Service": "iPaaS", "Version": "2020-10-25" }, "Result": { "row": [ { "product_id": "1669567870972xxxxxx", "instance_id": "i-1771998361xxxxxx", "instance_name": "i-1771998361xxxxxx", "host_id": "h-1771998361xxxxxx", "sn": "i-1771998361xxxxxx", "region": "cn-north", "isp": 7, "dc": "xxxx-ctcucm-02", "dc_name": "机房02(IPv4)", "status": 256, "status_str": "Running", "configuration": { "configuration_code": "CloudHost_XXXXXX_4c6g_monthly", "configuration_name": "加强型（升级版）", "cpu_core": 4, "memory": 6144 }, "image_id": "img-6559xxxx", "create_at": 1692275509 }, { "product_id": "1669567870972xxxxxx", "instance_id": "i-1771998361xxxxxx", "instance_name": "i-1771998361xxxxxx", "host_id": "h-1771998361xxxxxx", "sn": "i-1771998361xxxxxx", "region": "cn-north", "isp": 7, "dc": "xxxx-ctcucm-02", "dc_name": "机房02(IPv4)", "status": 256, "status_str": "Running", "configuration": { "configuration_code": "CloudHost_XXXXXX_4c6g_monthly", "configuration_name": "加强型（升级版）", "cpu_core": 4, "memory": 6144 }, "image_id": "img-6559xxxx", "create_at": 1692278530 } ], "total": 2 } }
调用失败
{ "ResponseMetadata": { "Action": "ListInstance", "Error": { "Code": "[ListInstance] error: product_id is empty", "CodeN": 200000, "Message": "[ListInstance] error: product_id is empty" }, "Region": "cn-north-1", "RequestId": "02162735832694600000000000000000000ffff0aca5d1d6ae229", "Service": "iPaaS", "Version": "2020-10-25" } }