匹配结果回调 API¶

当匹配完成后，Hive服务器会向开发者的服务器请求回调API，以传递匹配结果并接收响应值。

通过请求回调 API 交付匹配结果的顺序如下。

在 Hive 控制台中选择 匹配集成方法 为 server callback
在 Hive 控制台中注册开发者服务器 URL 以接收回调
匹配完成后，Hive 服务器请求开发者服务器的回调 API 以传递匹配结果
如果开发者服务器成功接收到匹配结果，则返回 HTTP 响应状态码 (HttpStatus 200) 给 Hive 服务器

请求 URL (开发者服务器 URL)¶

注册开发者服务器 URL，该 URL 将通过在 Hive 控制台请求回调 API 来接收匹配结果，作为 API 端点。此 URL 必须是外部可公开访问的地址。

头部参数¶

进行回调 API 请求时的头部值如下。

字段名称	描述	类型	是否必需
X-Match-Signature	用于传输数据的HMAC SHA-256算法加密的签名值	字符串	是

Note

您可以通过 X-Match-Signature 值来确定匹配结果的真实性。

X-Match-Signature 的值可以通过下面的示例代码（Java）获得，代码中使用的 HMAC SHA-256 密钥值可以在 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);
    }
}
```

请求体参数（通过回调 API 交付的匹配结果）¶

回调 API 请求期间传输的匹配结果数据如下。

字段名称	描述	类型
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

回调 API 请求示例 (Hive 服务器 → 开发者服务器)¶

curl --location 'HIVE 콘솔에 등록한 앱 개발사 API 엔드포인트' --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": []
}'

返回值¶

如果开发者的服务器成功接收到通过回调API请求由Hive服务器传递的匹配结果，则应返回HttpStatus 200作为响应。

根据开发者服务器的响应，它在Hive服务器上以以下方式处理。

HttpStatus 200 响应：确定匹配结果已成功完成，并终止相应的回调 API 请求。
响应值不是 HttpStatus 200 或超时：回调 API 将定期请求以传递匹配结果。
没有 HttpStatus 200 响应或没有其他响应值：如果持续没有响应，从系统管理的角度来看，匹配结果将在一定时间内不被传递。