私有匹配 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'

回應範例¶

成功處理後沒有特殊的回應內容。