匹配結果回調 API¶

當匹配完成後，Hive 伺服器會向開發者的伺服器請求回調 API，以傳遞匹配結果並接收回應值。

通過請求回調 API 交付匹配結果的順序如下。

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

請求 URL (開發者伺服器 URL)¶

註冊將透過在 Hive 控制台請求回調 API 來接收匹配結果的開發者伺服器 URL 作為 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 回應或沒有其他回應值：如果持續沒有回應，從系統管理的角度來看，匹配結果將在一定期間內不會被傳遞。