本文介绍了调用云游戏服务端 OpenAPI 的方法,对于具体 OpenAPI 的调用方法,请参考具体的接口说明文档。
调用云游戏服务端 OpenAPI 接口时,是通过向指定服务地址发送请求,并需满足签名信息和具体接口的业务信息来完成的。API 的请求需要包含服务地址、请求方式、请求参数等信息。接口调用成功后,对返回结果进行解析。
以查询游戏列表接口为例,一条未编码的 URL 请求示例如下:
https://open.volcengineapi.com?Action=ListGame &Version=2022-02-10 &<通过header传入的公共请求参数> &<请求体>
说明如下:
参数/结构 | 说明 |
---|---|
https://open.volcengineapi.com | 请求的通信协议和服务接入地址 |
Action | 指定要调用的 API 接口(示例中的 ListGame 为获取游戏列表接口) |
Version | 云游戏 OpenAPI 的接口版本号,可以是以下任一值(不同的接口版本号对应不同的参数格式):
详细信息,请参考接口说明文档 |
通过header传入的公共请求参数 | 系统规定的公共参数,主要包括以下参数:
|
请求体 | 调用 OpenAPI 接口需要的业务参数 |
云游戏 OpenAPI 的服务接入地址如下:
服务地域 | 域名 | 备注 |
---|---|---|
国内 | https://open.volcengineapi.com | 火山引擎 |
云游戏提供的所有接口均通过 HTTPS 进行通信,提供高安全性的通信通道。
根据各个接口的具体需求,选择 GET 或 POST 方式发起请求。
在发起请求时,请求体中可能会包含两类参数:公共请求参数和接口特有的业务参数。
请求及返回结果使用 UTF-8 的字符集进行编码。
公共请求参数是每个接口都需要使用的请求参数,在发送请求时都需要携带这些公共请求参数,否则会导致请求失败。公共请求参数首字母均为大写,以此区分接口特有的请求参数。有关火山引擎 OpenAPI 公共参数的详细说明,参考 公共参数。
对于每一次 HTTPS 协议请求,会根据访问中的签名信息验证访问请求者的身份。具体由用户的火山引擎账号对应的 Access Key ID 和 Secret Access Key (AK/SK)对称加密验证实现。具体的签名机制和方法,参考火山引擎 OpenAPI 签名方法。
云游戏 OpenAPI 提供了调用接口的 Java 示例(GitHub Demo Project)。示例代码中封装了调用云游戏服务端 OpenAPI 接口的鉴权和签名步骤,开发者可参考示例代码调用云游戏服务的其它 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": "ListGame", "Region": "cn-north-1", "RequestId": "202202151700410102252431530610EF8E", "Service": "veGame", "Version": "2022-02-10" }, "Result": { "row": [ { "product_id": "1493071161301xxxxxx", "game_id": "7064461037701xxxxxx", "custom_game_id": "game01", "game_name": "游戏名", "rotation": 0, "icon_url": "//xxx.xxx.xxx.xxx/obj/xxx-xxx-y7oawaxxxx/xxxx", "game_status": 1, "inner_status": 20, "deploy_status": 30, "current_version": 7064461037701xxxxxx, "create_at": 1644897746, "has_deploy_strategy": true } ], "total": 1 } }
调用失败
{ "ResponseMetadata": { "RequestId": "202202151820560102252431470018EB60", "Action": "ListGame", "Version": "2022-02-10", "Service": "veGame", "Region": "cn-north-1", "Error": { "CodeN": 100009, "Code": "InvalidAccessKey", "Message": "The security token[xxx] included in the request is invalid." } } }