> 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/chinese-simplified/api-wen-dang-shang-xia-wen-xin-xi/wan-jia-biao-qian.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` ：用户的唯一标识符。作为端点中的路径参数传递。
* **请求正文**
* **标签** ：用户的新标签列表
**示例**
```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": ["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",
"标签": ["label1", "label2", "label3", "label4"],
"新增标签": ["label3", "label4"]
}
}
```
* **4XX 响应**
| 状态码 | 错误消息 |
|---|
| 400 | {"message": "无效的标签，标签必须是仅包含字母数字、连字符 (-) 或下划线 (_) 的字符串。"} |
| 422 | {"message" :"一个用户最多可以有 5 个标签。"} |
* `DELETE` /users/{user\_id}/v1/labels/{label}
* 删除给定标签（如果已附加到该用户）
* **参数**
* **路径参数**
* `user_id`：用户的唯一标识符
* `标签`：标签名称
* **示例调用**
```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 响应**