> 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-zhuang-tai.md).

# 玩家状态

\[ 基础 URL: `api.ggwp.com`]

`POST` /users/v1/update-status

## **描述**

当你使用 GGWP 之外的系统对玩家采取行动时（例如禁言玩家），你可以将该信息分享给我们，以便我们在系统中更新其状态。下面的指南说明了如何使用我们的 RESTful Player Status API 来完成此操作。 

根据游戏的行为准则，玩家的状态可能会在以下状态之间变动 `active`  和  `已禁言`。可能会有各种事件导致游戏的版主更改玩家的状态。

先前未发送过状态信息的玩家被视为 `未知`.

## **参数**

`请求体`：包含以下字段的字典：

* **user\_id**：所发送状态所属玩家的 ID。
* **status**：玩家的当前状态。支持的值： `active`, `已禁言`
  * `active` → 允许该玩家参与相应频道。
  * `已禁言` → 不允许该玩家参与相应频道。
* **channel**：需要应用状态更改的频道。频道支持的值： `聊天`, `语音`, `discord` 和 `游戏`.
* （可选） **expiry\_at：** 以下格式的时间戳 *YYYY-MM-DD HH:MM:SS* ，表示状态何时需要过期并恢复为 `active`。当状态被设置为 `active` 时，在处理数据时不会在任何地方考虑该字段。
* （可选） **updated\_by：** 进行状态更新的系统用户的姓名或电子邮件。
* （可选） **用户名：** 所发送状态所属用户的姓名。
  * 该 `用户名` 字段接受字符串值，长度范围为 1 到 128 个字符。
  * 如果 `用户名` 如果提供该字段，它会为新用户分配用户名；如果用户已存在，则该值会覆盖现有用户名。
* 示例调用

  ```bash
  curl --request POST 'https://api.ggwp.com/users/v1/update-status' \
  --header 'x-api-key: api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "user_id": "<id1>",
    "status": "active",
    "expiry_at": "2022-12-30 07:44:37",
    "channel": "chat",
    "username": "<username>"
  }'
  ```

## **输出**

* 200 - 操作成功

  ```json
  {
      "success": true
  }
  ```
* 400
  * 错误响应。&#x20;
    * `expiry_at`
      * expiry\_at 字段格式错误，请使用 UTC 时区的 YYYY-MM-DD HH:MM:SS。
      * expiry\_at 应该是未来日期。
    * `status`&#x20;
      * 不是 status 的有效选项。
    * `channel`&#x20;
      * 不是 channel 的有效选项。
    * `用户名`&#x20;
      * username 的长度无效。
  * 示例
    * ```json
      {
          "error": "不是 channel 的有效选项。"
      }
      ```
* 403
  * 无效或缺失的 API 密钥
  * 示例
    * ```json
      {
          "error": "无效或缺失的 API 密钥"
      }
      ```
* 500
  * 错误响应。&#x20;
    * 无法更新 Discord 频道中的用户状态。请提供有效的 Discord 用户。
    * 无法更新用户状态
  * 示例
    * ```json
      {
          "error": "无法更新用户状态"
      }
      ```
  *