匹配 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	帳號識別碼	long	是
point	比賽中使用的分數。輸入範圍為`0 ~ 999,999,999`。如果未輸入，將使用`0`。	integer	否
extraData	額外的帳號資訊（暱稱、等級、國家等）。最多可以輸入256個字元。它包含在比賽結果中。	string	否

回應¶

字段名称	描述
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)	字串	Y

路徑參數¶

欄位名稱	描述	類型	必填
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: 請求比賽時輸入的 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 回應，則匹配結果回調將因系統管理目的而在一定時間內不會發送。