マッチメイキングAPI

前提条件¶

マッチメイキングAPIを使用するには、以下のアイテムを準備する必要があります。

• API呼び出しのための認証トークン（Certification Key）：Hive コンソール アプリセンター > プロジェクトを管理 > ゲームリストからゲームを選択 > ゲームの詳細 > 基本情報 > 認証キー
• ゲームインデックス（gameIndex）：Hive コンソール アプリセンター > プロジェクトを管理 > ゲームリストからゲームを選択 > ゲームの詳細 > 基本情報 > ゲームインデックス
• マッチID（matchId）：これは、Hive コンソールでマッチを作成する際に確認できます。

リクエストURLルート¶

一般的な応答コード¶

これらは一般的なAPIレスポンスコードです。

リクエストマッチ¶

ユーザーがマッチをリクエストする際にこのAPIを呼び出します。matchIdに対応するマッチはHiveコンソールで事前に作成されている必要があります。

リクエストURL¶

ヘッダーパラメータ¶

パスパラメータ¶

リクエストボディ¶

応答¶

リクエストサンプル¶

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¶

ヘッダー パラメータ¶

パスパラメータ¶

クエリパラメータ¶

応答¶

リクエストサンプル¶

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 サーバーはあなたのサーバーにマッチ結果コールバックを送信します。あなたのサーバーがマッチ結果コールバックを受信し、Hive サーバーにHTTPステータス200を返すと、再度マッチリクエストのステータスを確認すると、notRequestedに変更され、matchingInfoキーは以下のように削除されます。これは、Hive サーバーがコールバックに対する応答としてHTTPステータス200を受け取った時点で、あなたのマッチリクエストが完了したと見なしてマッチリクエストトランザクションを削除するためです。

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

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

マッチリクエストをキャンセルします。マッチリクエストをキャンセルすると、マッチリクエストトランザクションは Hive サーバーから削除されます。

リクエストマッチの後にマッチが完了し、マッチ結果コールバックを受け取り、HTTPステータス200で応答した場合、Hive サーバーはマッチが完了したと見なし、マッチリクエストトランザクションを削除します。この状態では、マッチリクエストをキャンセルするために呼び出しても、マッチリクエストトランザクションはすでに削除されているため、キャンセル操作は実行されず、例外も返されません。

リクエストURL¶

ヘッダーパラメータ¶

パスパラメータ¶

応答¶

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サーバーはマッチが完了したときにこのエンドポイントにコールバック結果を送信します。

ヘッダーパラメータ¶

コールバックで渡された値¶

コールバックの例 (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の応答を継続的に受信できない場合、システム管理の目的で一定期間マッチ結果のコールバックは配信されません。