> For the complete documentation index, see [llms.txt](https://docs.ggwp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ggwp.com/kr/api-6/player-labels.md).
# 플레이어 레이블
## 설명
이 **플레이어 라벨 API** 특정 사용자에게 할당된 라벨을 관리하기 위한 엔드포인트를 제공합니다.\
라벨은 짧은 식별자입니다(예: `"label1"`, `"label2"`)로 사용자를 분류하거나 태그합니다.
#### 주요 사항
* 각 사용자는 **최대 다섯 개의 고유 라벨**.
* 라벨은 대소문자를 구분합니다.
* 라벨은 영숫자, 하이픈(-) 또는 밑줄(\_)만 포함하는 문자열이어야 합니다.
* 라벨은 최대 32자까지 허용됩니다
## API
* `GET` /users/{user\_id}/v1/labels
* 주어진 user\_id에 대한 모든 라벨을 가져옵니다
* **매개변수**
* **경로 매개변수**
* `user_id`: 사용자의 고유 식별자.
* **샘플 호출**
```
curl --request GET 'https://api.ggwp.com/users/test-user/v1/labels' \
--header 'x-api-key: api_key'
```
* **응답 200**
```json
{
"data": {
"user_id": "test-user",
"labels": ["label1", "label2"]
},
"message": "success"
}
```
* `POST` /users/{user\_id}/v1/labels
* 사용자의 기존 라벨을 제공된 집합으로 대체합니다.
* 부분 라벨 집합은 허용되지 않습니다. 즉, 집합에 있는 어떤 라벨이든 유효하지 않거나 총 개수가 다섯을 초과하면 전체 요청이 무효로 처리됩니다
* **매개변수**
* **경로 매개변수**
* `user_id` : 사용자의 고유 식별자입니다. 엔드포인트의 경로 매개변수로 전달됩니다.
* **요청 본문**
* **labels** : 사용자를 위한 새 라벨 목록
**예시**
```bash
{
"labels": ["label1", "label2"]
}
```
* **샘플 호출**
```bash
curl --request POST 'https://api.ggwp.com/users/test-user/v1/labels' \
--header 'x-api-key: api_key'
--header 'Content-Type: application/json' \
--data-raw '{
"labels": ["label1", "label2"]
}'
```
* **응답 201**
```bash
{
"data": {
"user_id": "test-user",
"labels": ["label1", "label2"]
}
}
```
* **4XX 응답**
| 상태 코드 | 오류 메시지 |
|---|
| 400 | {"message": "잘못된 라벨입니다. 라벨은 영숫자, 하이픈(-), 또는 밑줄(_)만 포함하는 문자열이어야 합니다."} |
| 422 | {"message" :"사용자는 최대 5개의 라벨을 가질 수 있습니다."} |
* `PUT` /users/{user\_id}/v1/labels
* 중복을 제거하여 주어진 사용자에 라벨을 추가합니다.
* 부분 업데이트는 허용되지 않습니다. 즉, 집합에 있는 어떤 라벨이든 유효하지 않거나 총 개수가 다섯을 초과하면 전체 요청이 무효로 처리됩니다.
* **매개변수**
* **경로 매개변수**
* `user_id` : 사용자의 고유 식별자.
* **요청 본문**
* **labels :** 라벨 목록
**예시**
{
"labels": ["label3", "label4"]
}
* **샘플 호출**
```bash
curl --request PUT 'https://api.ggwp.com/users/test-user/v1/labels' \
--header 'x-api-key: api_key'
--header 'Content-Type: application/json' \
--data-raw '{
"labels": ["label3", "label4"]
}'
```
* **응답 200**
```json
{
"data": {
"user_id": "test-user",
"labels": ["label1", "label2", "label3", "label4"],
"added_labels": ["label3", "label4"]
}
}
```
* **4XX 응답**
| 상태 코드 | 오류 메시지 |
|---|
| 400 | {"message": "잘못된 라벨입니다. 라벨은 영숫자, 하이픈(-), 또는 밑줄(_)만 포함하는 문자열이어야 합니다."} |
| 422 | {"message" :"사용자는 최대 5개의 라벨을 가질 수 있습니다."} |
* `DELETE` /users/{user\_id}/v1/labels/{label}
* 해당 사용자가 가진 경우 지정된 라벨을 삭제합니다
* **매개변수**
* **경로 매개변수**
* `user_id`: 사용자 고유 식별자
* `label`: 라벨 이름
* **샘플 호출**
```bash
curl --request DELETE 'https://api.ggwp.com/users/test-user/v1/labels/label4' \
--header 'x-api-key: api_key'
```
* **응답 200**
```json
{
"data": {
"user_id": "test-user",
"labels": ["label1", "label2", "label3"] //삭제 후 남은 라벨
}
}
```
* **4XX 응답**
| 상태 코드 | 오류 메시지 |
|---|
| 404 | {"message": "사용자 test-user에 대한 라벨을 찾을 수 없습니다"} |
* `DELETE` /users/{user\_id}/v1/labels
* 사용자에 연결된 모든 라벨을 삭제합니다
* **매개변수**
* **경로 매개변수**
* `user_id`: 사용자 고유 식별자
* **샘플 호출**
```bash
curl --request DELETE 'https://api.ggwp.com/users/test-user/v1/labels' \
--header 'x-api-key: api_key'
```
* **응답 200**
```json
{
"data": {
"user_id": "test-user",
"labels": []
}
}
```
* **일반적인 4XX 응답**
| 상태 코드 | 오류 메시지 |
|---|
| 400 | {"message":"라벨 이름은 32자를 초과할 수 없습니다} |
| 403 | {"message": "유효하지 않거나 누락된 API 키"} |
| 404 | {"message": "사용자를 찾을 수 없습니다"} |
* **일반적인 5XX 응답**
| 상태 코드 | 오류 메시지 |
|---|
| 500 | 내부 서버 오류 |
| 504 | 게이트웨이 타임아웃 |