개인 매치 API

게임 플레이 시, 개인 단위 매칭을 적용할 때 사용하는 API입니다. 그룹 단위 매칭 플레이를 적용하려면 그룹 API를 사용하세요.

매칭 요청¶

매칭 요청을 시작할 때 호출합니다. matchId에 해당하는 매치를 Hive 콘솔에서 미리 생성해야 합니다.

Request URL¶

LIVE URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/request
SANDBOX URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/request
HTTP METHOD	POST
CONTENT-TYPE	application/json

Header parameters¶

필드명	설명	타입	필수 여부
X-Access-Token	앱 서버 인증을 위한 OAuth 2.0 Access Token (OAuth Token 발급하기 참고)	string	Y

Path parameters¶

필드명	설명	타입	필수 여부
gameIndex	Hive 콘솔 앱센터에서 확인 가능한 프로젝트 식별자	int	Y
matchId	Hive 콘솔에서 생성한 각 매치 식별자	int	Y

Request body¶

필드명	설명	타입	필수 여부
playerId	계정 식별자	long	Y
point	매칭에 사용할 점수입니다. 입력 범위는 `0 ~ 999,999,999`입니다. 미입력 시 `0`으로 처리합니다.	integer	N
extraData	계정 부가 정보(닉네임, 레벨, 국가 등)입니다. 최대 256자 입력할 수 있습니다. 매칭 결과에 함께 포함됩니다.	string	N

Response¶

필드명	설명
playerId	계정 식별자
matchInfo	요청 대상 정보 `gameIndex`: `gameIndex` 값 `matchId`: matchId 값
requestingStatus	요청 상태 정보 `requested`: 매칭을 정상적으로 요청함 `notRequested`: 매칭을 요청하지 않았거나, 매칭이 이미 완료되어 현재 진행 중인 매칭이 없음
requestingInfo	요청 정보 `requestTimeUtc`: UTC+0 기준, 요청 시간 `point`: 요청 시 입력한 `point` `extraData`: 요청 시 입력한 `extraData`
matchingInfo	매칭 진행 정보(`status`) `matchingInProgress`: 매칭 진행 중 `timeout`: 제한 시간 내에 매칭이 이뤄지지 않음 `matched`: 매칭 완료

Request sample¶

curl --location 'https://sandbox-api-match.withhive.com/gameindexes/1/matchmakings/1/request' \
--header 'Content-Type: application/json' \
--header 'X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0...' \
--data '{
   "playerId":100,
   "point": 1000
}'

Response sample¶

{
   "playerId": 100,
   "matchInfo": {
       "gameIndex": 1,
       "matchId": 1
   },
   "requestingStatus": "requested",
   "requestingInfo": {
       "requestTimeUtc": "2024-06-05T05:09:28.72",
       "point": 1000
   },
   "matchingInfo": {
       "status": "matchingInProgress"
   }
}

매칭 상태 확인¶

요청한 매칭 상태를 확인합니다.

Request URL¶

LIVE URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players
SANDBOX URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players
HTTP METHOD	GET

Header parameters¶

필드명	설명	타입	필수 여부
X-Access-Token	앱 서버 인증을 위한 OAuth 2.0 Access Token (OAuth Token 발급하기 참고)	string	Y

Path parameters¶

필드명	설명	타입	필수 여부
gameIndex	Hive 콘솔 앱센터에서 확인 가능한 프로젝트 식별자	int	Y
matchId	Hive 콘솔에서 생성한 각 매치 식별자	int	Y

Query parameters¶

필드명	설명	타입	필수 여부
id	사용자 ID(`playerId`)	long	Y

Response¶

필드명	설명
playerId	계정 식별자
matchInfo	요청 대상 정보 `gameIndex`: `gameIndex` 값 `matchId`: `matchId` 값
requestingStatus	요청 상태 정보 `requested`: 매칭을 정상적으로 요청함 `notRequested` : 매칭을 요청하지 않았거나, 매칭이 이미 완료되어 현재 진행 중인 매칭이 없음
requestingInfo	요청 정보 `requestTimeUtc`: UTC+0 기준, 요청 시간 `point`: 요청 시 입력한 `point` `extraData`: 요청 시 입력한 `extraData`
matchingInfo	매칭 진행 정보(`status`) `matchingInProgress`: 매칭 진행 중 `timeout`: 제한 시간 내에 매칭이 이뤄지지 않음 `matched`: 매칭 완료

Request sample¶

curl --location --request GET 'https://sandbox-api-match.withhive.com/gameindexes/1/matchmakings/1/players?id=100' \
--header 'X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0...'

Response sample¶

개발사가 아직 매칭 요청을 하지 않았을 때, 매칭 상태 결과는 아래와 같습니다.

{
   "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	notRequested	requested	requested	notRequested
matchingInfo > Status	N/A	matchingInProgress	matched or timeout	N/A
비고		매칭 진행 중 시점	콜백 수신 전 시점

매칭 요청 취소¶

매칭 요청을 취소합니다. 매칭 요청을 취소하면 Hive 서버 내 매칭 요청 트랜잭션이 삭제됩니다.

매칭 요청 후 매칭이 완료되어 매칭 결과 콜백을 받고 HTTP 상태 코드 200으로 응답한 상태라면, Hive 서버 내부에서 매칭이 완료된 것으로 보고 해당 매칭 요청 트랜잭션을 삭제합니다. 이 상태에서는 매칭 요청 취소를 호출해도 이미 매칭 요청 트랜잭션이 삭제된 상태이므로 요청 취소 작업은 실행되지 않으며 별도로 예외를 반환하지는 않습니다.

Request URL¶

LIVE URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}
SANDBOX URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}
HTTP METHOD	DELETE

Header parameters¶

필드명	설명	타입	필수 여부
X-Access-Token	앱 서버 인증을 위한 OAuth 2.0 Access Token (OAuth Token 발급하기 참고)	string	Y

Path parameters¶

필드명	설명	타입	필수 여부
gameIndex	Hive 콘솔 앱센터에서 확인 가능한 프로젝트 식별자	int	Y
matchId	Hive 콘솔에서 생성한 각 매치 식별자	int	Y
playerId	사용자 ID	long	Y

Response¶

200 OK인 경우, Body 데이터는 비어있습니다.

Request sample¶

curl --location --request DELETE 'https://sandbox-api-match.withhive.com/gameindexes/1/matchmakings/1/players/100' \
--header 'X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0...'

Response sample¶

정상 처리 시 특별한 응답 내용은 없습니다.