--- title: admin/accounts API 方法 description: 使用帐户执行管理操作。 menu: docs: name: accounts parent: methods-admin identifier: methods-admin-accounts aliases: [ "/methods/admin/accounts", "/api/methods/admin/accounts", ] --- ## 查看帐户 (v1) {#v1} ```http GET /api/v1/admin/accounts HTTP/1.1 ``` 查看所有帐户,可以选择匹配某些筛选条件,一次最多 100 个。可以使用响应中的 HTTP Link 标头进行分页。有关更多信息,请参见[通过 API 响应进行分页]({{}})。 **返回:** [Admin::Account]({{}}) 数组\ **OAuth:** 用户令牌 + `admin:read:accounts`\ **权限:** 管理用户\ **版本历史:**\ 2.9.1 - 添加\ 3.3.0 - 添加 `sensitized`\ 4.0.0 - 支持自定义用户组和权限 #### 请求 ##### 标头 Authorization : {{}} 提供带有 `Bearer ` 的标头,以获得对此 API 方法的访问授权。 ##### 查询参数 local : 布尔值. 筛选本站帐户? remote : 布尔值. 筛选外站帐户? active : 布尔值. 筛选当前活跃的帐户? pending : 布尔值. 筛选当前待批准的帐户? disabled : 布尔值. 筛选当前已禁用的帐户? silenced : 布尔值. 筛选当前已隐藏的帐户? suspended : 布尔值. 筛选当前已封禁的帐户? sensitized : 布尔值. 筛选强制标记为敏感的帐户? username : 字符串. 搜索给定的用户名。 display_name : 字符串. 搜索给定的昵称。 by_domain : 字符串. 按给定的域名筛选。 email : 字符串. 查找具有此电子邮件的用户。 ip : 字符串. 查找具有此 IP 地址的用户。 staff : 布尔值. 筛选职员帐户? max_id : 字符串. 返回的所有结果都将小于此 ID。事实上设置结果的上限。 since_id : 字符串. 返回的所有结果都将大于此 ID。事实上设置结果的下限。 min_id : 字符串. 返回与此 ID 相邻且更新的结果。事实上在此 ID 处设置游标并向前分页。 limit : Integer. 要返回的最大结果数。默认为 100 个帐户。最多 200 个帐户。 #### 响应 ##### 200: OK ```json [ { "id": "108267707882207829", "username": "trwnh", "domain": null, "created_at": "2022-05-08T18:21:56.870Z", "email": "trwnh@mastodon.local", "ip": { "user_id": 2, "ip": "192.168.42.1", "used_at": "2022-05-08T18:21:56.944Z" }, "role": "user", "confirmed": false, "suspended": false, "silenced": false, "disabled": false, "approved": true, "locale": "en", "invite_request": null, "ips": [ { "ip": "192.168.42.1", "used_at": "2022-05-08T18:21:56.944Z" } ], "account": { "id": "108267707882207829", "username": "trwnh", "acct": "trwnh", // ... } }, { "id": "108267695853695427", "username": "admin", "domain": null, "created_at": "2022-05-08T18:18:53.221Z", "email": "admin@mastodon.local", "ip": { "user_id": 1, "ip": "192.168.42.1", "used_at": "2022-09-08T16:10:38.621Z" }, "role": "admin", "confirmed": true, "suspended": false, "silenced": false, "disabled": false, "approved": true, "locale": null, "invite_request": null, "ips": [ { "ip": "192.168.42.1", "used_at": "2022-09-08T16:10:38.621Z" } ], "account": { "id": "108267695853695427", "username": "admin", "acct": "admin", // ... } } ] ``` ##### 403: Forbidden 授权用户缺少权限,或者 Authorization 标头无效或丢失 ```json { "error": "This action is not allowed" } ``` --- ## 查看帐户 (v2) {#v2} ```http GET /api/v2/admin/accounts HTTP/1.1 ``` 查看所有帐户,可以选择匹配某些筛选条件,一次最多 100 个。可以使用响应中的 HTTP Link 标头进行分页。有关更多信息,请参见[通过 API 响应进行分页]({{}})。 **返回:** [Admin::Account]({{}}) 数组\ **OAuth:** 用户令牌 + `admin:read:accounts`\ **权限:** 管理用户\ **版本历史:**\ 3.5.0 - 添加\ 4.0.0 - 添加 `role_ids`。支持自定义用户组和权限 #### 请求 ##### 标头 Authorization : {{}} 提供带有 `Bearer ` 的标头,以获得对此 API 方法的访问授权。 ##### 查询参数 origin : 字符串. 筛选 `local` 或 `remote` 帐户。 status : 字符串. 筛选 `active`、`pending`、`disabled`、`silenced` 或 `suspended` 帐户。 permissions : 字符串. 筛选具有 `staff` 权限的帐户(可以管理举报的用户)。 role_ids[] : Array of String. 筛选具有这些用户组的用户。 invited_by : 字符串. 查找由此 ID 的帐户邀请的用户。 username : 字符串. 搜索给定的用户名。 display_name : 字符串. 搜索给定的昵称。 by_domain : 字符串. 按给定的域名筛选。 email : 字符串. 查找具有此电子邮件的用户。 ip : 字符串. 查找具有此 IP 地址的用户。 max_id : 字符串. 返回的所有结果都将小于此 ID。事实上设置结果的上限。 since_id : 字符串. 返回的所有结果都将大于此 ID。事实上设置结果的下限。 min_id : 字符串. 返回与此 ID 相邻且更新的结果。事实上在此 ID 处设置游标并向前分页。 limit : Integer. 要返回的最大结果数。默认为 100 个帐户。最多 200 个帐户。 #### 响应 ##### 200: OK ```json [ { "id": "108267695853695427", "username": "admin", "domain": null, "created_at": "2022-05-08T18:18:53.221Z", "email": "admin@mastodon.local", "ip": { "user_id": 1, "ip": "192.168.42.1", "used_at": "2022-09-08T16:10:38.621Z" }, "role": { "id": 3, "name": "Owner", "color": "#3584e4", "position": 1000, "permissions": 1, "highlighted": true, "created_at": "2022-09-08T22:48:07.983Z", "updated_at": "2022-09-09T10:45:13.226Z" }, "confirmed": true, "suspended": false, "silenced": false, "disabled": false, "approved": true, "locale": null, "invite_request": null, "ips": [ { "ip": "192.168.42.1", "used_at": "2022-09-08T16:10:38.621Z" } ], "account": { "id": "108267695853695427", "username": "admin", "acct": "admin", // ... } } ] ``` ##### 403: Forbidden 授权用户缺少权限,或者 Authorization 标头无效或丢失 ```json { "error": "This action is not allowed" } ``` --- ## 查看特定帐户 {#get-one} ```http GET /api/v1/admin/accounts/:id HTTP/1.1 ``` 查看有关给定帐户的管理级别的的信息。 **返回:** [Admin::Account]({{}})\ **OAuth:** 用户令牌 + `admin:read:accounts`\ **权限:** 管理用户\ **版本历史:**\ 2.9.1 - 添加\ 4.0.0 - 支持自定义用户组和权限 #### 请求 ##### 路径参数 :id : {{}} 字符串. 数据库中帐户的 ID。 ##### 标头 Authorization : {{}} 提供带有 `Bearer ` 的标头,以获得对此 API 方法的访问授权。 #### 响应 ##### 200: OK ```json { "id": "108267695853695427", "username": "admin", "domain": null, "created_at": "2022-05-08T18:18:53.221Z", "email": "admin@mastodon.local", "ip": { "user_id": 1, "ip": "192.168.42.1", "used_at": "2022-09-08T16:10:38.621Z" }, "role": { "id": 3, "name": "Owner", "color": "", "position": 1000, "permissions": 1, "highlighted": true, "created_at": "2022-09-08T22:48:07.983Z", "updated_at": "2022-09-08T22:48:07.983Z" }, "confirmed": true, "suspended": false, "silenced": false, "disabled": false, "approved": true, "locale": null, "invite_request": null, "ips": [ { "ip": "192.168.42.1", "used_at": "2022-09-08T16:10:38.621Z" } ], "account": { "id": "108267695853695427", "username": "admin", "acct": "admin", // ... } } ``` ##### 403: Forbidden 授权用户缺少权限,或者 Authorization 标头无效或丢失 ```json { "error": "This action is not allowed" } ``` ##### 404: Not found 帐户不存在 ```json { "error": "Record not found" } ``` --- ## 批准待批准的帐户 {#approve} ```http POST /api/v1/admin/accounts/:id/approve HTTP/1.1 ``` 若给定的本站帐户当前正在等待批准,则批准该帐户。 **返回:** [Admin::Account]({{}})\ **OAuth:** 用户令牌 + `admin:write:accounts`\ **权限:** 管理用户\ **版本历史:**\ 2.9.1 - 添加\ 4.0.0 - 支持自定义用户组和权限 #### 请求 ##### 路径参数 :id : {{}} 字符串. 数据库中帐户的 ID。 ##### 标头 Authorization : {{}} 提供带有 `Bearer ` 的标头,以获得对此 API 方法的访问授权。 #### 响应 ##### 200: OK 该帐户现已批准 ```json { "id": "108965430868193066", "username": "goody", "domain": null, "created_at": "2022-09-08T23:42:04.731Z", // ... "approved": true, // ... } ``` ##### 403: Forbidden 授权用户缺少权限,或者 Authorization 标头无效或丢失,或者帐户当前未决。 ```json { "error": "This action is not allowed" } ``` ##### 404: Not found 帐户不存在 ```json { "error": "Record not found" } ``` --- ## 拒绝待批准的帐户 {#reject} ```http POST /api/v1/admin/accounts/:id/reject HTTP/1.1 ``` 若给定的本站帐户当前正在等待批准,则拒绝该帐户。 **返回:** [Admin::Account]({{}})\ **OAuth:** 用户令牌 + `admin:write:accounts`\ **权限:** 管理用户\ **版本历史:**\ 2.9.1 - 添加\ 4.0.0 - 支持自定义用户组和权限 #### 请求 ##### 路径参数 :id : {{}} 字符串. 数据库中帐户的 ID。 ##### 标头 Authorization : {{}} 提供带有 `Bearer ` 的标头,以获得对此 API 方法的访问授权。 #### 响应 ##### 200: OK ```json { "id": "108965436418975594", "username": "badguy", "domain": null, "created_at": "2022-09-08T23:43:29.427Z", "email": "badguy@mastodon.local", "ip": null, "role": { "id": -99, "name": "", "color": "", "position": -1, "permissions": 65536, "highlighted": false, "created_at": "2022-09-08T22:48:07.977Z", "updated_at": "2022-09-08T22:48:07.977Z" }, "confirmed": true, "suspended": false, "silenced": false, "disabled": false, "approved": false, "locale": "en", "invite_request": "i am going to commit crimes", "ips": [], "account": { "id": "108965436418975594", "username": "badguy", "acct": "badguy", "display_name": "", "locked": false, "bot": false, "discoverable": null, "group": false, "created_at": "2022-09-08T00:00:00.000Z", "note": "", "url": "http://mastodon.local/@badguy", "avatar": "http://mastodon.local/avatars/original/missing.png", "avatar_static": "http://mastodon.local/avatars/original/missing.png", "header": "http://mastodon.local/headers/original/missing.png", "header_static": "http://mastodon.local/headers/original/missing.png", "followers_count": 0, "following_count": 0, "statuses_count": 0, "last_status_at": null, "emojis": [], "fields": [] } } ``` ##### 403: Forbidden 授权用户缺少权限,或者 Authorization 标头无效或丢失,或者帐户当前未决。 ```json { "error": "This action is not allowed" } ``` ##### 404: Not found 帐户不存在 ```json { "error": "Record not found" } ``` --- ## 删除帐户 {#delete} ```http DELETE /api/v1/admin/accounts/:id HTTP/1.1 ``` 永久删除已封禁帐户的数据。 **返回:** [Admin::Account]({{}})\ **OAuth:** 用户令牌 + `admin:write:accounts`\ **权限:** 删除用户数据\ **版本历史:**\ 3.3.0 - 添加\ 4.0.0 - 支持自定义用户组和权限 #### 请求 ##### 路径参数 :id : {{}} 字符串. 数据库中帐户的 ID。 ##### 标头 Authorization : {{}} 提供带有 `Bearer ` 的标头,以获得对此 API 方法的访问授权。 #### 响应 ##### 200: OK 已删除帐户的数据。 ```json { "id": "108965430868193066", "username": "goody", "domain": null, "created_at": "2022-09-08T23:42:04.731Z", "email": "goody@mastodon.local", "ip": { "user_id": 3, "ip": "192.168.42.1", "used_at": "2022-09-08T23:42:04.761Z" }, "role": { "id": -99, "name": "", "color": "", "position": -1, "permissions": 65536, "highlighted": false, "created_at": "2022-09-08T22:48:07.977Z", "updated_at": "2022-09-08T22:48:07.977Z" }, "confirmed": true, "suspended": true, "silenced": false, "disabled": false, "approved": true, "locale": "en", "invite_request": "this is a compelling reason", "ips": [ { "ip": "192.168.42.1", "used_at": "2022-09-08T23:42:04.761Z" } ], "account": { "id": "108965430868193066", "username": "goody", "acct": "goody", "display_name": "", "locked": false, "bot": false, "discoverable": false, "group": false, "created_at": "2022-09-08T00:00:00.000Z", "note": "", "url": "http://mastodon.local/@goody", "avatar": "http://mastodon.local/avatars/original/missing.png", "avatar_static": "http://mastodon.local/avatars/original/missing.png", "header": "http://mastodon.local/headers/original/missing.png", "header_static": "http://mastodon.local/headers/original/missing.png", "followers_count": 0, "following_count": 0, "statuses_count": 0, "last_status_at": null, "suspended": true, "emojis": [], "fields": [] } } ``` ##### 403: Forbidden 授权用户缺少权限,或者 Authorization 标头无效或丢失,或者帐户已被删除。 ```json { "error": "This action is not allowed" } ``` --- ## 对帐户执行操作 {#action} ```http POST /api/v1/admin/accounts/:id/action HTTP/1.1 ``` 对帐户执行操作,并将此操作记录在管理历史记录中。还会解决针对此帐户的任何未处理的举报。 **返回:** 空\ **OAuth:** 用户令牌 + `admin:write:accounts`\ **权限:** 管理用户,管理举报\ **版本历史:**\ 2.9.1 - 添加\ 3.3.0 - 添加 `sensitive` 作为可能的 `type`\ 4.0.0 - 支持自定义用户组和权限 #### 请求 ##### 路径参数 :id : {{}} 字符串. 数据库中帐户的 ID。 ##### 标头 Authorization : {{}} 提供带有 `Bearer ` 的标头,以获得对此 API 方法的访问授权。 ##### 表单数据参数 type : {{}} 字符串. 要执行的操作的类型:`none`、`sensitive`、`disable`、`silence` 或 `suspend`。 report_id : 字符串. 导致采取此操作的相关举报的 ID。 warning_preset_id : 字符串. 预设警告的 ID。 text : 字符串. 采取此操作的原因的其他说明。 send_email_notification : 布尔值. 是否应将包含上述信息的电子邮件发送给用户? #### 响应 ##### 200: OK 该操作已成功执行 ```json {} ``` ##### 403: Forbidden 授权用户缺少权限,或者 Authorization 标头无效或丢失 ```json { "error": "This action is not allowed" } ``` ##### 404: Not found 具有给定 ID 的帐户或举报不存在 ```json { "error": "Record not found" } ``` ##### 422: Server error 未提供 `type` 或无法识别 ```json { "error": "Record invalid" } ``` --- ## 启用当前已停用的帐户 {#enable} ```http POST /api/v1/admin/accounts/:id/enable HTTP/1.1 ``` 重新启用当前已停用的本站帐户。 **返回:** [Admin::Account]({{}})\ **OAuth:** 用户令牌 + `admin:write:accounts`\ **权限:** 管理用户\ **版本历史:**\ 2.9.1 - 添加\ 4.0.0 - 支持自定义用户组和权限 #### 请求 ##### 路径参数 :id : {{}} 字符串. 数据库中帐户的 ID。 ##### 标头 Authorization : {{}} 提供带有 `Bearer ` 的标头,以获得对此 API 方法的访问授权。 #### 响应 ##### 200: OK 已启用的帐户。 ```json { "id": "108965430868193066", "username": "goody", "domain": null, "created_at": "2022-09-08T23:42:04.731Z", // ... "disabled": false, // ... } ``` ##### 403: Forbidden 授权用户缺少权限,或者 Authorization 标头无效或丢失 ```json { "error": "This action is not allowed" } ``` ##### 404: Not found 帐户不存在 ```json { "error": "Record not found" } ``` --- ## 取消帐户的隐藏 {#unsilence} ```http POST /api/v1/admin/accounts/:id/unsilence HTTP/1.1 ``` 若帐户当前已隐藏,则取消隐藏。 **返回:** [Admin::Account]({{}})\ **OAuth:** 用户令牌 + `admin:write:accounts`\ **权限:** 管理用户\ **版本历史:**\ 2.9.1 - 添加\ 4.0.0 - 支持自定义用户组和权限 #### 请求 ##### 路径参数 :id : {{}} 字符串. 数据库中帐户的 ID。 ##### 标头 Authorization : {{}} 提供带有 `Bearer ` 的标头,以获得对此 API 方法的访问授权。 #### 响应 ##### 200: OK 已取消帐户的隐藏,或未被隐藏 ```json { "id": "108965430868193066", "username": "goody", "domain": null, "created_at": "2022-09-08T23:42:04.731Z", // ... "silenced": false, // ... } ``` ##### 403: Forbidden 授权用户缺少权限,或者 Authorization 标头无效或丢失 ```json { "error": "This action is not allowed" } ``` ##### 404: Not found 帐户不存在 ```json { "error": "Record not found" } ``` --- ## 取消封禁帐户 {#unsuspend} ```http POST /api/v1/admin/accounts/:id/unsuspend HTTP/1.1 ``` 取消封禁当前已封禁的帐户。 **返回:** [Admin::Account]({{}})\ **OAuth:** 用户令牌 + `admin:write:accounts`\ **权限:** 管理用户\ **版本历史:**\ 2.9.1 - 添加\ 4.0.0 - 支持自定义用户组和权限 #### 请求 ##### 路径参数 :id : {{}} 字符串. 数据库中帐户的 ID。 ##### 标头 Authorization : {{}} 提供带有 `Bearer ` 的标头,以获得对此 API 方法的访问授权。 #### 响应 ##### 200: OK 帐户成功取消封禁 ```json { "id": "108965430868193066", "username": "goody", "domain": null, "created_at": "2022-09-08T23:42:04.731Z", // ... "suspended": false, // ... } ``` ##### 403: Forbidden 授权用户缺少权限,或者 Authorization 标头无效或丢失,或者帐户当前未封禁 ```json { "error": "This action is not allowed" } ``` ##### 404: Not found 帐户不存在 ```json { "error": "Record not found" } ``` --- ## 取消将帐户标记为敏感 {#unsensitive} ```http POST /api/v1/admin/accounts/:id/unsensitive HTTP/1.1 ``` 若账户之前已标记为敏感,则停止将帐户的嘟文标记为敏感。 **返回:** [Admin::Account]({{}})\ **OAuth:** 用户令牌 + `admin:write:accounts`\ **权限:** 管理用户\ **版本历史:**\ 3.3.0 - 添加\ 4.0.0 - 支持自定义用户组和权限 #### 请求 ##### 路径参数 :id : {{}} 字符串. 数据库中帐户的 ID。 ##### 标头 Authorization : {{}} 提供带有 `Bearer ` 的标头,以获得对此 API 方法的访问授权。 #### 响应 ##### 200: OK 该帐户不再标记为敏感,或者未标记为敏感。 ```json { "id": "108965430868193066", "username": "goody", "domain": null, "created_at": "2022-09-08T23:42:04.731Z", // ... "sensitized": false, // ... } ``` ##### 403: Forbidden 授权用户缺少权限,或者 Authorization 标头无效或丢失 ```json { "error": "This action is not allowed" } ``` ##### 404: Not found 帐户不存在 ```json { "error": "Record not found" } ``` --- ## 另请参阅 {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/accounts_controller.rb" caption="app/controllers/api/v1/admin/accounts_controller.rb" >}} {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/account_actions_controller.rb" caption="app/controllers/api/v1/admin/account_actions_controller.rb" >}} {{< translation-status-zh-cn raw_title="accounts API methods" raw_link="/methods/admin/accounts/" last_translation_time="2025-04-21" raw_commit="6addd5cf525adec1859f48c52dafcfe1f96e558a">}}