6.2. Server API 예제 (/player)

Owned by kate.psy (Unlicensed)
Last updated: 11월 18, 2021
5 min read

/player/get



Description

플레이어 정보를 조회합니다.

Method

POST

Request Headers 

  • 게임 서버에서 호출하는 경우

Name

Type

Mandatory

Description

appId

String

Y

앱 아이디

 

appSecret

String

Y

앱 시크릿

playerId

String

Y

플레이어 아이디

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

예제) Authorization: KakaoAK 11118035a320f23423585acae3ded1111

Content-Type

String

Y

"application/json;charset=UTF-8"

Request Body Parameters

Name

Type

Mandatory

Description

Name

Type

Mandatory

Description

playerId

String

Y

조회 대상 플레이어 아이디

fields

List<String>

Y

조회 대상 필드 목록

os, country, lang, market, customProperty, appStatus, regTime, modTime, idpCode, deviceLogin, kakaoServiceUserId, kakaoAppUserId

Response Status Code

Status Code

Status Code 설명

Status Code 상세 설명

Status Code

Status Code 설명

Status Code 상세 설명

200

정상 응답

정상

400

Bad Request

파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류

401

Unauthenticated

인증 실패

406

Not Acceptable

처리 불가

461

Invalid Message Box

messageBoxId로 요청된 메시지 박스가 존재하지 않음.

500

Internal Server Error

서버 시스템 내부 오류

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

Response Content

Name

Type

Description

Name

Type

Description

player

Player

플레이어 정보

Player

Name

Type

Description

Name

Type

Description

playerId

String

플레이어 아이디

appId

String

앱 아이디

idpCode

String

IDP 코드

regTime

Long

등록 일시

modTime

Long

수정 일시

customProperty

Map<String, String>

커스텀 속성

appStatus

String

앱 별 플레이어의 상태 ( normal, restricted, waitForRemove, removed )

os

String

OS 정보

country

String

국가 코드

lang

String

언어 코드

  • 기본 규칙 : https://ko.wikipedia.org/wiki/ISO_639-1

  • 단, 중국어의 경우 간체(중국본토)와 번체(대만)가 구분이 되기 때문에 별도 언어코드로 식별됨 (zh-hans, zh-hant)

  • 언어 코드 구분을 위해서 추가될 수 있음

market

String

마켓 정보

deviceLogin

Boolean

디바이스 로그인 여부

kakaoServiceUserId

Long

카카오 서비스 유저 아이디

kakaoAppUserId

Long

카카오 앱 유저 아이디

Example Request

POST /service/v3/player/get HTTP/1.1 Host: openapi-zinny3.game.kakao.com Content-Type: application/json;charset=UTF-8 appId: 103815 appSecret: 951b75bf17fe0885ab5106ba2a9f9bc9 playerId: 739921939896 zat: f3jf0293jf093jf0932fj039jf0239f    {     "playerId": "739921939896",      "fields": [         "os",         "country",         "lang",         "market",         "customProperty",         "appStatus",         "regTime",         "modTime",         "idpCode",         "deviceLogin",         "kakaoAppUserId"     ] }

Example Response 

HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8   {     "player": {         "country": "kr",         "os": "android",         "deviceLogin": false,         "appStatus": "normal",         "market": "googlePlay",         "regTime": 1478507636101,         "modTime": 1478517838939,         "appId": "103815",         "lang": "ko",         "customProperty": null,         "playerId": "739921939896",         "idpCode": "google",         "kakaoAppUserId": 1122334455     } }

 

/player/getWithIdpId



Description

IDP ID로 플레이어 정보를 조회합니다.

Method

POST

Request Headers 

  • 게임 서버에서 호출하는 경우

Name

Type

Mandatory

Description

appId

String

Y

앱 아이디

 

appSecret

String

Y

앱 시크릿

playerId

String

Y

플레이어 아이디

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

예제) Authorization: KakaoAK 11118035a320f23423585acae3ded1111

Content-Type

String

Y

"application/json;charset=UTF-8"



Request Body Parameters

Name

Type

Mandatory

Description

Name

Type

Mandatory

Description

idpCode

String

Y

IDP 코드 (kakaocapri, google, facebook, zd3)

idpId

String

Y

IDP ID

fields

List<String>

Y

조회 대상 필드 목록

os, country, lang, market, customProperty, appStatus, regTime, modTime, idpCode, deviceLogin

 

Response Status Code

Status Code

Status Code 설명

Status Code 상세 설명

Status Code

Status Code 설명

Status Code 상세 설명

200

정상 응답

정상

400

Bad Request

파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류

401

Unauthenticated

인증 실패

406

Not Acceptable

처리 불가

461

Invalid Message Box

messageBoxId로 요청된 메시지 박스가 존재하지 않음.

500

Internal Server Error

서버 시스템 내부 오류

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

Response Content

Name

Type

Description

Name

Type

Description

player

Player

플레이어 정보



Player

Name

Type

Description

Name

Type

Description

playerId

String

플레이어 아이디

appId

String

앱 아이디

idpCode

String

IDP 코드

regTime

Long

등록 일시

modTime

Long

수정 일시

customProperty

Map<String, String>

커스텀 속성

appStatus

String

앱 별 플레이어의 상태 ( normal, restricted, waitForRemove, removed )

os

String

OS 정보

country

String

국가 코드

lang

String

언어 코드

market

String

마켓 정보

deviceLogin

Boolean

디바이스 로그인 여부

Example Request

POST /service/v3/player/getWithIdpId HTTP/1.1 Host: openapi-zinny3.game.kakao.com Content-Type: application/json;charset=UTF-8 appId: 103815 appSecret: 951b75bf17fe0885ab5106ba2a9f9bc9 playerId: 739921939896 zat: f3jf0293jf093jf0932fj039jf0239f    {         "idpCode": "google",         "idpId": "100571592064225154475",         "fields": [             "os",             "country",             "lang",             "market",             "customProperty",             "appStatus",             "regTime",             "modTime",             "idpCode",             "deviceLogin"         ] }

Example Response 

 

/player/getListWithIdpId



Description

IDP ID 목록으로 플레이어 정보를 조회합니다.

Method

POST

Request Headers 

  • 게임 서버에서 호출하는 경우

Name

Type

Mandatory

Description

appId

String

Y

앱 아이디

 

appSecret

String

Y

앱 시크릿

playerId

String

Y

플레이어 아이디

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

예제) Authorization: KakaoAK 11118035a320f23423585acae3ded1111

Content-Type

String

Y

"application/json;charset=UTF-8"



Request Body Parameters

Name

Type

Mandatory

Description

Name

Type

Mandatory

Description

idpCode

String

Y

IDP 코드 (kakaocapri, google, facebook, zd3)

idpIds

List<String>

Y

IDP ID 목록

fields

List<String>

Y

조회 대상 필드 목록

os, country, lang, market, customProperty, appStatus, regTime, modTime, idpCode, deviceLogin

 

Response Status Code

Status Code

Status Code 설명

Status Code 상세 설명

Status Code

Status Code 설명

Status Code 상세 설명

200

정상 응답

정상

400

Bad Request

파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류

401

Unauthenticated

인증 실패

406

Not Acceptable

처리 불가

461

Invalid Message Box

messageBoxId로 요청된 메시지 박스가 존재하지 않음.

500

Internal Server Error

서버 시스템 내부 오류

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

Response Content

Name

Type

Description

Name

Type

Description

players

List<Player>

플레이어 정보 목록



Player

Name

Type

Description

Name

Type

Description

playerId

String

플레이어 아이디

appId

String

앱 아이디

idpCode

String

IDP 코드

regTime

Long

등록 일시

modTime

Long

수정 일시

customProperty

Map<String, String>

커스텀 속성

appStatus

String

앱 별 플레이어의 상태 ( normal, restricted, waitForRemove, removed )

os

String

OS 정보

country

String

국가 코드

lang

String

언어 코드

market

String

마켓 정보

deviceLogin

Boolean

디바이스 로그인 여부

Example Request

Example Response 

 

/player/getListWithField



Description

조회 조건으로 searchField와 searchValue를 지정하여 플레이어 정보를 조회합니다.

Method

POST

Request Headers 

  • 게임 서버에서 호출하는 경우

Name

Type

Mandatory

Description

appId

String

Y

앱 아이디

 

appSecret

String

Y

앱 시크릿

playerId

String

Y

플레이어 아이디

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

예제) Authorization: KakaoAK 11118035a320f23423585acae3ded1111

Content-Type

String

Y

"application/json;charset=UTF-8"



Request Body Parameters

Name

Type

Mandatory

Description

Name

Type

Mandatory

Description

searchField

String

Y

조회 조건 field name

searchValue

String

Y

조회 조건 field value

fields

List<String>

Y

조회 대상 필드 목록

os, country, lang, market, customProperty, appStatus, regTime, modTime, idpCode, deviceLogin

counterIds

List<String>

N

조회 대상 카운터 필드 목록

 

Response Status Code

Status Code

Status Code 설명

Status Code 상세 설명

Status Code

Status Code 설명

Status Code 상세 설명

200

정상 응답

정상

400

Bad Request

파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류

401

Unauthenticated

인증 실패

406

Not Acceptable

처리 불가

461

Invalid Message Box

messageBoxId로 요청된 메시지 박스가 존재하지 않음.

500

Internal Server Error

서버 시스템 내부 오류

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

Response Content

Name

Type

Description

Name

Type

Description

players

List<Player>

플레이어 정보 목록



Player

Name

Type

Description

Name

Type

Description

playerId

String

플레이어 아이디

appId

String

앱 아이디

idpCode

String

IDP 코드

regTime

Long

등록 일시

modTime

Long

수정 일시

customProperty

Map<String, String>

커스텀 속성

appStatus

String

앱 별 플레이어의 상태 ( normal, restricted, waitForRemove, removed )

os

String

OS 정보

country

String

국가 코드

lang

String

언어 코드

market

String

마켓 정보

deviceLogin

Boolean

디바이스 로그인 여부

Example Request

Example Response