群组匹配 API

这是在游戏中用于匹配群体（如熟人或朋友）的API。

在发起匹配请求之前，两个或更多应用用户必须创建一个group，并由小组代表进行匹配请求。

Note

Group API 仅在 Match Unit / Personnel 的 Match ID 设置为 Team 时可用。

创建组¶

这是一个用于创建组以邀请成员加入同一团队的API。

请求的创建者成为小组领导（房间领导）。
在个人匹配请求期间无法使用。
创建时提供邀请熟人的入场代码。
创建时，可以输入分数信息以对应匹配 ID的规则。

请求 URL¶

实时 URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/group
沙盒 URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/group
HTTP 方法	POST
内容类型	application/json

头部参数¶

字段名称	描述	类型	必需
授权	API 调用的身份验证令牌 (Bearer)	字符串	是

路径参数¶

字段名称	描述	类型	必需
gameIndex	可以在 Hive 控制台应用中心检查的项目标识符	int	是
matchId	在 Hive 控制台中创建的每个比赛的标识符	int	是

请求体¶

字段名称	描述	类型	必需
playerId	账户标识符	长整型	是
point	这是用于匹配的分数。输入范围为`0 ~ 999,999,999`。如果未提供，将视为`0`。	整数	否
extraData	附加账户信息（昵称、等级、国家等）。最多可输入256个字符。它将包含在匹配结果中。	字符串	否

响应¶

字段名称	描述	类型
groupCode	进入组所需的代码	字符串
ownerPlayerId	组所有者（主持人）的账户标识符	长整型
memberInfos	结果消息	对象
matchInfo	组所属的 `gameIndex` 和 `matchId` 信息	对象
requstingStatus	请求状态信息	字符串

请求示例¶

curl --location 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/group' --header 'Content-Type: application/json' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' --data '{"playerId":1}'

响应示例¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfos": [
        {
            "playerId": 1
        }
    ],
    "requestingStatus": "notRequested"
}

加入群组¶

这是应用程序用户希望加入一个小组时使用的API，他们使用从小组领导者（房间领导者）那里收到的代码（groupCode）来参与该小组。

请求 URL¶

实时 URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/groups/code/{code}/member
沙盒 URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/groups/code/{code}/member
HTTP 方法	POST

头部参数¶

字段名称	描述	类型	必需
授权	API 调用的身份验证令牌（Bearer）	字符串	是

路径参数¶

字段名称	描述	类型	必需
gameIndex	可以在 Hive 控制台应用中心检查的项目标识符	int	是
matchId	在 Hive 控制台中创建的每个比赛标识符	int	是
code	在组创建 API 的响应中收到的 `groupCode` 值	string	是

请求体¶

字段名称	描述	类型	必需
playerId	账户标识符	长整型	是
point	这是用于匹配的分数。输入范围为`0 ~ 999,999,999`。如果未输入，将视为`0`。	整型	否
extraData	附加账户信息（昵称、等级、国家等）。最多可以输入256个字符。将包含在匹配结果中。	字符串	否

回复¶

字段名称	描述	类型
groupCode	输入相应组的代码	字符串
ownerPlayerId	组长（主机）账户的标识符	长整型
memberInfos	结果消息	对象
matchInfo	组所属的 `gameIndex` 和 `matchId` 信息	对象
requestingStatus	请求状态信息	字符串

请求示例¶

curl --location 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/groups/code/0343322/member' --header 'Content-Type: application/json' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' --data '{"playerId":2}'

响应示例¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1
        },
        {
            "playerId": 2
        }
    ],
    "requestingStatus": "notRequested"
}

离开群组¶

这是您想要离开当前所在小组时使用的 API。如果小组领导者（房间领导者）离开，剩下的成员之一将成为下一个小组领导者。

如果没有剩余的成员，组将被移除。

请求 URL¶

实时 URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}/group
沙盒 URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}/group
HTTP 方法	DELETE

头部参数¶

字段名称	描述	类型	必需
授权	API 调用的身份验证令牌 (Bearer)	字符串	是

路径参数¶

字段名称	描述	类型	必需
gameIndex	在 Hive 控制台应用中心可用的项目标识符	int	是
matchId	在 Hive 控制台中创建的每个比赛的标识符	int	是
playerId	用户 ID	long	是

回复¶

在200 OK的情况下，主体是空的。

请求示例¶

curl --location --request DELETE 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/players/2/group' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

响应示例¶

正常处理时没有特殊的响应内容。

群体强制驱逐 (踢出)¶

这是一个允许组长（房间领导）强制驱逐特定成员的API。

请求 URL¶

实时 URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}/group/members/{targetPlayerId}
沙盒 URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}/group/members/{targetPlayerId}
HTTP 方法	DELETE

头部参数¶

字段名称	描述	类型	是否必需
授权	API 调用的身份验证令牌 (Bearer)	字符串	是

路径参数¶

字段名称	描述	类型	是否必需
gameIndex	可以在 Hive 控制台应用中心检查的项目标识符	int	是
matchId	在 Hive 控制台中创建的每场比赛的标识符	int	是
playerId	用户 ID	long	是
targetPlayerId	要强制移除的成员 ID	long	是

响应¶

这是群组创建API的结果数据格式。只有被强制移除的成员信息（memberInfos）将被移除。

字段名称	描述	类型
groupCode	输入对应组的代码	字符串
ownerPlayerId	组长（主持人）的标识符	长整型
memberInfos	结果消息	对象
matchInfo	组所属的 `gameIndex` 和 `matchId` 信息	对象
requstingStatus	请求状态信息	字符串

请求示例¶

curl --location --request DELETE 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/players/1/group/members/2' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

响应示例¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1
        }
    ],
    "requestingStatus": "notRequested"
}

群组信息检索（基于群组成员）¶

这是一个在请求时检索应用用户所属组信息的API。它可以用于各种目的，并且需要通过轮询定期检查。

通常用于以下目的。

检查加入该组的应用用户列表
检查匹配请求后的匹配结果

请求 URL¶

实时 URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}/group
沙盒 URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}/group
HTTP 方法	GET

头部参数¶

字段名称	描述	类型	是否必填
授权	API 调用的身份验证令牌（Bearer）	字符串	是

路径参数¶

字段名称	描述	类型	是否必填
gameIndex	可以在 Hive 控制台应用中心找到的项目标识符	int	是
matchId	在 Hive 控制台中创建的每个比赛的标识符	int	是
playerId	用户 ID	long	是

响应¶

字段名称	描述	类型
groupCode	输入相应组的代码	字符串
ownerPlayerId	组长账户的标识符	长整型
memberInfos	结果消息	对象
matchInfo	组的 `gameIndex` 和 `matchId` 信息	对象
requstingStatus	请求状态信息	字符串
requestingInfo	匹配请求信息	对象
matchingInfo	匹配进度信息	对象

请求示例¶

curl --location 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/players/1/group' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

响应示例¶

// 매칭 요청 전
{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1
        }
    ],
    "requestingStatus": "notRequested"
}
// 매칭이 성사된 이후 (2:2 팀전)
{
    "groupCode": "3683207",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1,
            "ready": true
        },
        {
            "playerId": 2,
            "ready": true
        }
    ],
    "matchingInfo": {
        "status": "matched",
        "matchingId": "2:1_2024-12-18T06:55:19.91_1",
        "teamInfos": [
            {
                "teamIndex": 0,
                "playerInfos": [
                    {
                        "playerId": 4,
                        "point": 50,
                        "extraData": "bbb"
                    },
                    {
                        "playerId": 3,
                        "extraData": "aaa"
                    }
                ]
            },
            {
                "teamIndex": 1,
                "playerInfos": [
                    {
                        "playerId": 1,
                        "extraData": "extra1"
                    },
                    {
                        "playerId": 2,
                        "point": 250,
                        "extraData": "aaa"
                    }
                ]
            }
        ]
    },
    "requestingStatus": "requested",
    "requestingInfo": {
        "requestTimeUtc": "2024-12-18T06:55:19.17"
    }
}
// 매칭 시간이 초과된 경우(timeout)
{
    "groupCode": "0400606",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1,
            "ready": true
        },
        {
            "playerId": 2,
            "ready": true
        }
    ],
    "matchingInfo": {
        "status": "timeout"
    },
    "requestingStatus": "requested",
    "requestingInfo": {
        "requestTimeUtc": "2024-12-20T06:37:47.99"
    }
}

通过代码获取组信息¶

这是一个使用组长（房间领导）提供的代码（groupCode）检查组是否存在的API。

请求 URL¶

实时 URL	https://api-match.withhive.com/gameindexes/{gameIndex}/groups
沙盒 URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/groups
HTTP 方法	GET

头部参数¶

字段名称	描述	类型	是否必需
授权	API 调用的身份验证令牌 (Bearer)	字符串	是

路径参数¶

字段名称	描述	类型	必需
gameIndex	可以在 Hive 控制台应用中心检查的项目标识符	int	Y

查询参数¶

字段名称	描述	类型	是否必填
code	组代码 (`groupCode`)	字符串	是

响应¶

字段名称	描述	类型
groupCode	进入组所需的代码	字符串
ownerPlayerId	组所有者（主持人）的标识符	长整型
matchInfo	关于组所属的 `gameIndex` 和 `matchId` 的信息	对象

请求示例¶

curl --location 'http://sandbox-api-match.withhive.com/gameindexes/2/groups?code=0343322' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

响应示例¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1
}

会员信息更新¶

这是当属于某个组的成员想要更改其信息时使用的API。可以更改的信息如下。

准备状态 (ready) - 组长（房间领导）是一个未使用的项目。\n
分数 (point)\n
附加信息 (extraData)

请求 URL¶

实时 URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}/group/memberinfo
沙盒 URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}/group/memberinfo
HTTP 方法	PATCH
内容类型	application/json

头部参数¶

字段名称	描述	类型	必需
授权	API 调用的身份验证令牌 (Bearer)	字符串	是

路径参数¶

字段名称	描述	类型	是否必填
gameIndex	可以在Hive控制台应用中心检查的项目标识符	int	是
matchId	在Hive控制台中创建的每个比赛标识符	int	是
playerId	用户ID	long	是

请求体¶

字段名称	描述	类型	必需
ready	准备状态	布尔值	是
point	这是用于匹配的分数。输入范围是 `0 ~ 999,999,999`。如果未输入，将视为 `0`。	整数	否
extraData	附加账户信息（昵称、等级、国家等）。最多可以输入256个字符。它将包含在匹配结果中。	字符串	否

响应¶

字段名称	描述	类型
groupCode	输入相应组的代码	字符串
ownerPlayerId	组长的账户标识符	长整型
memberInfos	结果消息	对象
matchInfo	组所属的 `gameIndex` 和 `matchId` 信息	对象
requstingStatus	请求状态信息	字符串

请求示例¶

curl --location --request PATCH 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/players/2/group/memberinfo' --header 'Content-Type: application/json' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' --data '{"ready":false,"point":0,"extraData":""}'

响应示例¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1
        }
    ],
    "requestingStatus": "notRequested"
}

匹配请求¶

这是每个组开始匹配所请求的API。

您必须提前在控制台中创建与 matchId 对应的比赛。（与个人匹配请求相同）
请求时必须至少有 2 名成员。
不是组长（房间领导）的成员必须将其“准备状态”（Ready）设置为 true。
如果有正在进行的比赛，必须在发出请求之前组织（删除）它。
只有组代表（房间领导）可以发出请求。

请求 URL¶

实时 URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/group/request
沙盒 URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/group/request
HTTP 方法	POST
内容类型	application/json

头部参数¶

字段名称	描述	类型	是否必需
授权	API调用的身份验证令牌（Bearer）	字符串	是

路径参数¶

字段名称	描述	类型	必需
gameIndex	可以在 Hive 控制台应用中心检查的项目标识符	int	是
matchId	在 Hive 控制台中创建的每个比赛的标识符	int	是

请求体¶

字段名称	描述	类型	必需
playerId	账户标识符	长整型	是

响应¶

字段名称	描述	类型
groupCode	进入相应组的代码	字符串
ownerPlayerId	组长（主持人）的标识符	长整型
memberInfos	结果消息	对象
matchInfo	组所属的`gameIndex`和`matchId`信息	对象
requstingStatus	请求状态信息	字符串
requestingInfo	匹配请求信息	对象
matchingInfo	匹配进度信息	对象

请求示例¶

curl --location 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/group/request' --header 'Content-Type: application/json' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' --data '{"playerId":1}'

响应示例¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1
        },
        {
            "playerId": 2,
            "ready": true
        }
    ],
    "matchingInfo": {
        "status": "matchingInProgress"
    },
    "requestingStatus": "requested",
    "requestingInfo": {
        "requestTimeUtc": "2024-12-05T07:35:35.15"
    }
}

取消匹配请求¶

请求 URL¶

实时 URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/group/request
沙盒 URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/group/request
HTTP 方法	DELETE

头部参数¶

字段名称	描述	类型	必需
授权	API 调用的身份验证令牌（Bearer）	字符串	是

路径参数¶

字段名称	描述	类型	必需
gameIndex	可以在 Hive 控制台应用中心检查的项目标识符	int	是
matchId	在 Hive 控制台中创建的每场比赛标识符	int	是

请求体¶

字段名称	描述	类型	必需
playerId	账户标识符	长整型	是

响应¶

字段名称	描述	类型
groupCode	进入组的代码	字符串
ownerPlayerId	组长的标识符	长整型
memberInfos	结果消息	对象
matchInfo	组所属的 `gameIndex` 和 `matchId` 信息	对象
requstingStatus	请求状态信息	字符串

请求示例¶

curl --location --request DELETE 'https://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/group/request' --header 'Content-Type: application/json' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' --data '{"playerId":3}'

响应示例¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1
        },
        {
            "playerId": 2
        }
    ],
    "requestingStatus": "notRequested"
}

公众回应¶

这是关于与组相关的API响应中常用字段的描述。

memberInfos¶

关于属于该组（包括组长或房间领导）的成员信息的字段如下。

字段名称	描述	类型
playerId	账户标识符	long
ready	准备状态	boolean
point	加入（更新）组时输入的分数	integer
extraData	加入（更新）组时输入的附加信息	string

matchInfo¶

由 gameIndex 和 matchId 信息组成的字段所属的组如下。

字段名称	描述	类型
gameIndex	控制台的 `App Center` 中注册的项目的 `游戏索引` 值	整数
matchId	控制台的 `匹配` 中注册的 `匹配 ID`	整数

请求状态¶

匹配请求状态字段对应的值如下。

notRequested: 未请求匹配
requested: 请求匹配

requestingInfo¶

这是匹配请求信息字段。

字段名称	描述	类型
requestTimeUtc	基于UTC+0的请求时间	字符串

matchingInfo¶

包含匹配进度信息的字段如下。

字段名称	描述	类型
status	匹配进度状态	字符串
matchingId	分配给匹配配对的 Id。当上述 status 为 `matched` 时添加。	字符串
privateInfos	（在个人匹配的情况下）输出匹配的应用用户信息数组。	数组
teamInfos	（在团队匹配的情况下）输出匹配的应用用户信息数组。	数组

matchingInfo → 状态¶

匹配进度信息中状态字段对应的值如下。

matchingInProgress : 匹配正在进行中
timeout : 在时间限制内未找到匹配
matched : 匹配成功

matchingInfo → privateInfos¶

构成个人匹配应用用户信息的字段在匹配进度信息中如下所示。它与matchingInfo → teamInfos → playerInfos采用相同的数据格式。

字段名称	描述	类型
playerId	账户标识符。如果为0，则需要作为机器人处理	long
point	加入（更新）小组时输入的分数	integer
extraData	加入（更新）小组时输入的附加信息	string

matchingInfo → teamInfos¶

构成团队信息的字段在匹配进度信息的组匹配中匹配如下。

字段名称	描述	类型
teamIndex	用于区分团队的值，从0开始	整数
playerInfos	属于该团队的应用用户信息	数组

matchingInfo → teamInfos → playerInfos¶

配置应用程序用户信息的字段与匹配进度中匹配的团队如下。
它与matchingInfo → privateInfos的数据显示格式相同。

字段名称	描述	类型
playerId	账户标识符。如果为0，则需要作为机器人处理	long
point	加入（更新）组时输入的分数	integer
extraData	加入（更新）组时输入的附加信息	string