個人マッチ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呼び出しのための認証トークン（ベアラ）	文字列	はい

パスパラメータ¶

フィールド名	説明	タイプ	必須
gameIndex	Hiveコンソールアプリセンターにあるプロジェクト識別子	int	はい
matchId	Hiveコンソールで作成された各マッチの識別子	int	はい

リクエストボディ¶

フィールド名	説明	タイプ	必須
playerId	アカウント識別子	long	Y
point	マッチングに使用されるスコアです。入力範囲は`0 ~ 999,999,999`です。入力しない場合は`0`として処理されます。	integer	N
extraData	追加のアカウント情報（ニックネーム、レベル、国など）。最大256文字まで入力できます。マッチング結果に含まれます。	string	N

応答¶

フィールド名	説明
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呼び出しのための認証トークン（ベアラー）	文字列	はい

パスパラメータ¶

フィールド名	説明	タイプ	必須
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"
}

マッチングリクエストが行われると매칭 요청し、マッチングがまだ進行中の場合、結果は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サーバーはマッチング結果をコールバックとして送信します開発者のサーバーに。開発者のサーバーがマッチング結果のコールバックを受信し、HiveサーバーにHTTPステータス200を返すと、マッチングリクエストのステータスが再度チェックされると、以下のようにnotRequestedに変更され、matchingInfoキーが削除されます。これは、HiveサーバーがコールバックレスポンスとしてHTTPステータス200を受信すると、開発者によって要求されたマッチングが完了したと判断し、対応するマッチングリクエストトランザクションを削除するためです。

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

	マッチングリクエスト前	マッチングリクエスト後	マッチング結果生成後	コールバック受信後
requestingStatus	notRequested	requested	requested	notRequested
matchingInfo > Status	N/A	matchingInProgress	matched or timeout	N/A
備考		マッチング進行中の時点	コールバック受信前の時点

マッチリクエストをキャンセル¶

マッチングリクエストをキャンセルしています。マッチングリクエストをキャンセルすると、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

ヘッダーパラメータ¶

フィールド名	説明	タイプ	必須
Authorization	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'

応答サンプル¶

成功した処理に対して特別な応答内容はありません。