配对 API

先决条件¶

要使用匹配 API，您需要准备以下项目。

API调用的身份验证令牌（Certification Key）：Hive 控制台应用中心 > 管理项目 > 从游戏列表中选择您的游戏 > 游戏详情 > 基本信息 > 认证密钥
游戏索引（gameIndex）：Hive 控制台应用中心 > 管理项目 > 从游戏列表中选择您的游戏 > 游戏详情 > 基本信息 > 游戏索引
匹配ID（matchId）：您可以在Hive 控制台创建匹配时检查此项。

请求 URL 根¶

服务器	网址
实时	api-match.withhive.com
沙盒	sandbox-api-match.withhive.com

常见响应代码¶

这些是常见的API响应代码。

代码	值	描述
200	成功	参考每个API响应
400	错误请求	请求参数或请求体输入不正确
401	未授权	请求消息中的授权头缺失或无效
403	禁止	API调用的身份验证令牌（认证密钥）无效
404	未找到	API路径不正确
500	内部服务器错误	发生内部服务器错误

请求匹配¶

当每个用户请求匹配时调用此 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`)	long	Y

响应¶

字段名称	描述
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"
}

Request Match 返回 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 服务器会将比赛结果回调发送到您的服务器。如果您的服务器接收到比赛结果回调，返回 HTTPStatus 200 给 Hive 服务器，并且如果您再次检查比赛请求状态，它将变为 notRequested，并且 matchingInfo 键将被删除，如下所示。这是因为 Hive 服务器在收到回调的 HTTPStatus 200 后认为您的比赛请求已完成，并删除比赛请求事务。

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

	匹配请求前	匹配请求后	匹配结果创建后	回调接收后
requestingStatus	未请求	已请求	已请求	未请求
matchingInfo > Status	不适用	匹配进行中	已匹配或超时	不适用
备注		匹配进行中	回调接收前

取消匹配请求¶

取消匹配请求。当您取消匹配请求时，匹配请求交易将从 Hive 服务器中删除。

如果在请求匹配之后比赛已完成，并且您已收到匹配结果回调并以 HTTPStatus 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'

响应示例¶

如果请求正常取消，则没有特定的响应。

匹配结果回调¶

当比赛完成时，Hive 服务器会将比赛结果作为回调发送到您的服务器。如果您的服务器没有任何问题地接收到比赛结果回调，则您的服务器应以 HttpStatus 200 响应。通过在 Hive 控制台中注册所需的服务器 URL，比赛结果将作为回调发送到此地址。该地址必须是一个公开可访问的 URL。API 信息如下。

回调接收 URL (Hive 服务器 → 你的服务器)¶

当您的服务器 API 端点在 Hive 控制台中注册时，Hive 服务器在匹配完成后将回调结果发送到此端点。

头部参数¶

字段名称	描述	类型	必需
X-Match-Signature	使用 HMAC SHA-256 算法加密主体内容的签名值	字符串	是

通过回调传递的值¶

字段名称	描述	类型
gameIndex	已完成比赛的 gameIndex 值	int
matchId	已完成比赛的 matchId 值	int
matchingInfos	匹配的应用用户信息数组。`playerId` 字段值为 `0` 的用户被视为机器人。 matchingId: 比赛 id privateInfos: 在单人游戏中匹配的用户信息数组（与 timeoutPlayerInfos 相同的格式） teamInfos: 在团队游戏中匹配的用户信息数组（teamIndex: 队伍编号，playerInfos: 队员信息数组，与 timeoutPlayerInfos 相同的格式）	json
timeoutPlayerInfos	未匹配并超时的应用用户信息数组 extraData: 请求比赛时输入的 extraData point: 请求比赛时输入的点数 playerId: 请求比赛时输入的 playerId	json

回调示例 (Hive 服务器 → 你的服务器)¶

curl --location 'The API endpoint of your server registered in the Hive Console.' --header 'Content-Type: application/json' --header 'X-Match-Signature: nj2YlgGTlLXcAhrl6ijSgfD71gTWokBiM8WPn72xxg8=' --data '{
   "gameIndex": 1,
   "matchId": 1,
   "matchingInfos": [
       {
           "matchingId": "1:1_2024-06-05T05:43:28.91_1",
           "privateInfos": [
               {
                   "playerId": 100,
                   "point": 1000
               },
               {
                   "playerId": 101,
                   "point": 1000
               }
           ]
       }
   ],
   "timeoutPlayerInfos": []
}'

您可以使用头参数 X-Match-Signature 的值来验证回调结果的真实性，用于算法计算的密钥可以在 Hive 控制台中找到。下面是获取签名的 Java 代码示例。

import java.nio.charset.StandardCharsets;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public class MatchSignature {  
   private static final String HMAC_SHA_256 = "HmacSHA256";
   private static final String UTF_8 = "UTF-8";
   public String getSignature(String secret, String httpRequestBody) throws Exception {
       SecretKeySpec key = new SecretKeySpec(secret.getBytes(), HMAC_SHA_256);
       Mac mac = Mac.getInstance(HMAC_SHA_256);
       mac.init(key);
       byte[] source = httpRequestBody.getBytes(UTF_8);

       return new String(Base64.getEncoder().encode(mac.doFinal(source)), StandardCharsets.UTF_8);
   }
}

如果从 Hive 服务器发送的回调成功接收，您应该返回 HTTP 状态 200 作为响应。

响应状态为 HttpStatus 200：认为匹配已成功完成，因此匹配请求将被取消。
响应值不是 HttpStatus 200 或超时：匹配结果回调将定期重新发送。

如果 Hive 服务器无法持续接收 HTTP 状态 200 响应，则匹配结果回调将在一定时间内因系统管理目的而不被传递。