私有匹配 API

这是在游戏中应用个人匹配时使用的API。要应用组匹配，请使用组API。

匹配请求¶

这在开始匹配请求时被调用。与 matchId 对应的匹配必须在 Hive 控制台中预先创建。

请求 URL¶

实时 URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players
沙盒 URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players
HTTP 方法	POST
内容类型	application/json

头部参数¶

字段名称	描述	类型	必需
授权	API 调用的身份验证令牌（Bearer）	字符串	是

路径参数¶

字段名称	描述	类型	是否必需
gameIndex	可以在Hive控制台应用中心找到的项目标识符	int	是
matchId	在Hive控制台中创建的每个比赛的标识符	int	是

请求体¶

字段名称	描述	类型	必填
playerId	账户标识符	长整型	是
point	这是用于匹配的分数。输入范围是`0 ~ 999,999,999`。如果未输入，将处理为`0`。	整型	否
extraData	附加账户信息（昵称、等级、国家等）。最多可以输入256个字符。将包含在匹配结果中。	字符串	否

响应¶

字段名称	描述
playerId	账户标识符
matchInfo	请求的信息 `gameIndex`: `gameIndex` 的值 `matchId`: `matchId` 的值
requestingStatus	请求状态信息 `requested`: 匹配请求已成功发出 `notRequested`: 未发出匹配请求，或匹配已完成且没有进行中的匹配
requestingInfo	请求信息 `requestTimeUtc`: 基于 UTC+0 的请求时间 `point`: 请求时输入的`point` `extraData`: 请求时输入的`extraData`
matchingInfo	匹配进度信息 (`status`) `matchingInProgress`: 匹配正在进行中 `timeout`: 匹配未在时间限制内发生 `matched`: 匹配已完成

请求示例¶

curl --location 'https://sandbox-api-match.withhive.com/gameindexes/1/matchmakings/1/request' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' \
--data '{
   "playerId":100,
   "point": 1000
}'

响应示例¶

{
   "playerId": 100,
   "matchInfo": {
       "gameIndex": 1,
       "matchId": 1
   },
   "requestingStatus": "requested",
   "requestingInfo": {
       "requestTimeUtc": "2024-06-05T05:09:28.72",
       "point": 1000
   },
   "matchingInfo": {
       "status": "matchingInProgress"
   }
}

检查匹配状态¶

正在检查请求的匹配状态。

请求 URL¶

实时 URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players
沙盒 URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players
HTTP 方法	GET

头部参数¶

字段名称	描述	类型	必需
授权	API 调用的身份验证令牌（Bearer）	字符串	是

路径参数¶

字段名称	描述	类型	是否必填
gameIndex	可以在 Hive 控制台应用中心检查的项目标识符	int	是
matchId	在 Hive 控制台中创建的每个比赛的标识符	int	是

查询参数¶

字段名称	描述	类型	是否必填
id	用户 ID (`playerId`)	长整型	是

响应¶

字段名称	描述
playerId	账户标识符
matchInfo	请求的信息 `gameIndex`: `gameIndex`的值 `matchId`: `matchId`的值
requestingStatus	请求状态信息 `requested`: 匹配请求成功发出 `notRequested` : 没有发出匹配请求，或者匹配已经完成且没有进行中的匹配
requestingInfo	请求信息 `requestTimeUtc`: 基于UTC+0的请求时间 `point`: 请求时输入的`point` `extraData`: 请求时输入的`extraData`
matchingInfo	匹配进度信息 (`status`) `matchingInProgress`: 匹配正在进行中 `timeout`: 在时间限制内未完成匹配 `matched`: 匹配完成

请求示例¶

curl --location --request GET 'https://sandbox-api-match.withhive.com/gameindexes/1/matchmakings/1/players?id=100' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

响应示例¶

当开发者尚未发出匹配请求时，匹配状态结果如下。

{
   "playerId": 100,
   "matchInfo": {
       "gameIndex": 1,
       "matchId": 1
   },
   "requestingStatus": "notRequested"
}

当发出匹配请求 매칭 요청 且匹配仍在进行中时，它返回结果 requested 和 matchingInProgress。

{
   "playerId": 100,
   "matchInfo": {
       "gameIndex": 1,
       "matchId": 1
   },
   "requestingStatus": "requested",
   "requestingInfo": {
       "requestTimeUtc": "2024-06-05T05:09:28.72",
       "point": 1000
   },
   "matchingInfo": {
       "status": "matchingInProgress"
   }
}

在匹配完成后检查请求状态时，它返回matched或timeout的结果。这是匹配完成后但在接收匹配结果回调之前的状态。

    {
       "playerId": 100,
       "matchInfo": {
           "gameIndex": 1,
           "matchId": 1
       },
       "requestingStatus": "requested",
       "requestingInfo": {
           "requestTimeUtc": "2024-06-05T05:09:28.72",
           "point": 1000
       },
       "matchingInfo": {
           "status": "matched"
       }
   }

当匹配完成后，Hive 服务器将作为回调发送匹配结果到开发者的服务器。在开发者的服务器收到匹配结果回调并返回 HTTP 状态 200 响应给 Hive 服务器后，如果再次检查匹配请求状态，它将变为 notRequested，如下所示，并且 matchingInfo 键将被删除。这是因为当 Hive 服务器收到 HTTP 状态 200 作为回调响应时，它确定开发者请求的匹配已完成，并删除相应的匹配请求事务。

{
   "playerId": 100,
   "matchInfo": {
       "gameIndex": 1,
       "matchId": 1
   },
   "requestingStatus": "notRequested"
}

	匹配请求之前	匹配请求之后	匹配结果生成之后	回调接收之后
requestingStatus	未请求	已请求	已请求	未请求
matchingInfo > Status	不适用	匹配进行中	已匹配或超时	不适用
备注		在匹配进行中的时候	在回调接收之前

取消匹配请求¶

取消匹配请求。如果您取消匹配请求，Hive 服务器中的匹配请求事务将被删除。

如果匹配请求在请求匹配之后完成，并且在对匹配结果回调的响应中发送了 HTTP 状态 200，Hive 服务器将内部视为匹配已完成，并删除相应的匹配请求事务。在这种状态下，即使调用了匹配请求的取消，匹配请求事务也已被删除，因此取消请求将不会被执行，也不会单独返回任何异常。

请求 URL¶

实时 URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}
沙盒 URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}
HTTP 方法	DELETE

头部参数¶

字段名称	描述	类型	是否必需
授权	API 调用的身份验证令牌（Bearer）	字符串	是

路径参数¶

字段名称	描述	类型	必需
gameIndex	可以在 Hive 控制台应用中心检查的项目标识符	int	是
matchId	在 Hive 控制台中创建的每场比赛的标识符	int	是
playerId	用户 ID	long	是

响应¶

在200 OK的情况下，主体数据是空的。

请求示例¶

curl --location --request DELETE 'https://sandbox-api-match.withhive.com/gameindexes/1/matchmakings/1/players/100' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

响应示例¶

成功处理后没有特殊的响应内容。