预锁定实例资源--云游戏-火山引擎

文档中心

立即注册

导航

预锁定实例资源

最近更新时间：2025.01.20 15:42:49首次发布时间：2024.04.19 13:53:04

本接口支持预锁定实例资源，可以用于业务排队预申请场景。

请求说明

请求方式：POST
请求地址：https://open.volcengineapi.com?Action=PreAllocateResource&Version=2023-03-18

请求参数

下表仅列出了接口特有的请求参数和部分公共参数。完整的公共参数列表，参考公共请求参数。

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`PreAllocateResource`	接口名称。当前 API 的名称为 `PreAllocateResource`。
Version	String	是	`2023-03-18`	接口版本。当前 API 的版本为 `2023-03-18`。

Body

参数	类型	是否必选	示例值	描述
GameId	String	否	`7067374083209xxxxxx`	游戏 ID，可通过调用 ListGame 接口获取返回的游戏 ID。`GameId` 和 `CustomGameId` 二选一，同时指定时 `GameId` 优先。
CustomGameId	String	否	`id1`	用户自定义游戏 ID。`GameId` 和 `CustomGameId` 二选一，同时指定时 `GameId` 优先。
ClientUserId	String	是	`custom_client_user_id`	自定义客户端用户 ID。与通过客户端 `start()` 接口申请游戏服务、调用 GameStop 接口停止游戏服务时指定的自定义客户端用户 ID 相同。命名规则如下：最大长度为64位的非空字符串，支持的字符集范围为: 大写字母 A ~ Z 小写字母 a ~ z 数字 0 ~ 9 下划线 "_", 减号 "-"
DeviceId	String	是	`device_id`	客户端用户设备 ID，通过客户端 SDK 获取设备唯一标识接口获取。
RoundId	String	是	`round_001`	当次游戏的生命周期标识，需要业务保证每次申请服务时透传的唯一性。
ConfigurationCode	String	否	`ARMSoC_General`	通过火山引擎控制台已订购的实例套餐 ID，可选枚举值包括： `ARMSoC_Standard`：基础型 `ARMSoC_General`：通用型 `ARMSoC_Enhanced`：加强型 `ARMSoC_Advanced`：旗舰型说明如指定套餐 ID，需确保指定的套餐为已订购的套餐；如不指定套餐 ID，则使用游戏已配置的实例套餐
ExpireTime	Integer	否		资源锁定时间，单位为秒。缺省情况下系统默认锁定时间为 60 秒。
UserTag	String	否	`user01`	用户标签，由业务方指定。
PodSettings	String	否		预锁定的实例资源是否支持开启多人游戏及游戏控制权转移（需将结构体序列化成 JSON 字符串）
Extra	JSON Map	否	`-`	根据业务需要，自定义附加参数

返回参数

下表仅列出本接口特有的返回参数。更多信息请见返回结构。

参数	类型	示例值	描述
ReservedId	String	`7077141790263991084`	实例资源锁定成功，返回资源预锁定 ID。说明资源预锁定 ID 用于申请火山引擎云游戏的每次服务，建议业务记录此 ID，用于每次服务会话的唯一标识，可用于调试和问题排查。
ConfigurationCode	String	`ARMSoC_General`	预锁定资源的套餐 ID

请求示例

POST https://open.volcengineapi.com?Action=PreAllocateResource&Version=2023-03-18
{
    "GameId": "7067374083209xxxxxx",
    "RoundId": "round_001",
    "ClientUserId": "custom_client_user_id",
    "DeviceId": "device_id",
    "ConfigurationCode": "ARMSoC_General",
    "ExpireAt": 600,
    "UserTag": "user01",
    "Extra": {
        "key1": "value",
        "key2": "value"
    }
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "202306041104200100100232280022D31",
        "Action": "PreAllocateResource",
        "Version": "2023-03-18",
        "Service": "veGame",
        "Region": "cn-north-1"
    },
    "Result": {
        "ReservedId": "7077141790263991084",
        "ConfigurationCode": "ARMSoC_General"
    }
}

错误码

您可访问公共错误码，获取更多错误码信息。