2365 lines
59 KiB
Markdown
2365 lines
59 KiB
Markdown
---
|
||
title: accounts API 方法
|
||
description: 关于账户和账户资料的方法。
|
||
menu:
|
||
docs:
|
||
weight: 20
|
||
name: accounts
|
||
parent: methods
|
||
identifier: methods-accounts
|
||
aliases: [
|
||
"/methods/accounts",
|
||
"/api/methods/accounts"
|
||
]
|
||
---
|
||
|
||
<style>
|
||
#TableOfContents ul ul ul {display: none}
|
||
</style>
|
||
|
||
## 注册账户 {#create}
|
||
|
||
```http
|
||
POST /api/v1/accounts HTTP/1.1
|
||
```
|
||
|
||
创建账户记录。返回发起请求的应用的账户访问令牌。应用应保存此令牌以供将来使用，并应等待用户通过点击其电子邮件收件箱中的链接来确认其账户。
|
||
|
||
OAuth 应用和创建的用户账户之间的关系将被存储。
|
||
|
||
**返回:** [Token]({{< relref "entities/token" >}})\
|
||
**OAuth:** 应用令牌 + `write:accounts`\
|
||
**版本历史:**\
|
||
2.7.0 - 添加\
|
||
3.0.0 - 添加 `reason` 参数\
|
||
3.4.0 - 向失败响应添加 `details`\
|
||
4.4.0 - 添加 `date_of_birth` 参数
|
||
|
||
#### 请求
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: {{<required>}} 提供此标头与 `Bearer <app_token>`，以获得对此 API 方法的访问授权。
|
||
|
||
##### 表单数据参数
|
||
|
||
username
|
||
: {{<required>}} 字符串。账户所需的用户名。
|
||
|
||
email
|
||
: {{<required>}} 字符串。用于登录的电子邮件地址。
|
||
|
||
password
|
||
: {{<required>}} 字符串。用于登录的密码。
|
||
|
||
agreement
|
||
: {{<required>}} 布尔值。用户是否同意本站规则、条款和政策。应向用户展示这些内容，以便他们在将此参数设置为 TRUE 之前表示同意。
|
||
|
||
locale
|
||
: {{<required>}} 字符串。将发送的确认电子邮件的语言。
|
||
|
||
reason
|
||
: 字符串。若注册需要手动批准，则版主将审查此文本。
|
||
|
||
date_of_birth
|
||
: 字符串 ([Date](/api/datetime-format#date))，若实例有最低年龄要求，则为必填。
|
||
|
||
#### 响应
|
||
|
||
##### 200: OK
|
||
|
||
```json
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
```json
|
||
{
|
||
"error": "The access token is invalid"
|
||
}
|
||
```
|
||
|
||
##### 422: Unprocessable entity
|
||
|
||
`details` 参数包含所有检测到的错误。其结构是一个哈希，键是错误的参数，值是找到的所有错误的数组。
|
||
|
||
错误响应示例：
|
||
|
||
```json
|
||
{
|
||
"error": "Validation failed: Password can't be blank, Username must contain only letters, numbers and underscores, Agreement must be accepted",
|
||
"details": {
|
||
"password": [
|
||
{
|
||
"error": "ERR_BLANK",
|
||
"description": "can't be blank"
|
||
}
|
||
],
|
||
"username": [
|
||
{
|
||
"error": "ERR_INVALID",
|
||
"description": "must contain only letters, numbers and underscores"
|
||
}
|
||
],
|
||
"agreement": [
|
||
{
|
||
"error": "ERR_ACCEPTED",
|
||
"description": "must be accepted"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
你可能会遇到以下错误：
|
||
|
||
ERR_BLOCKED
|
||
: 当电子邮件提供商不被允许时出现
|
||
|
||
ERR_UNREACHABLE
|
||
: 当电子邮件地址无法通过 DNS（MX、A、AAAA）解析到任何 IP 时出现
|
||
|
||
ERR_TAKEN
|
||
: 当用户名或电子邮件已被占用时出现
|
||
|
||
ERR_RESERVED
|
||
: 当用户名被保留时出现，例如注册使用的用户名为“webmaster”或“admin”
|
||
|
||
ERR_ACCEPTED
|
||
: 当未接受协议时出现
|
||
|
||
ERR_BLANK
|
||
: 当未填写必填项时出现
|
||
|
||
ERR_INVALID
|
||
: 当某一项格式错误时，例如错误的字符或无效的电子邮件地址出现
|
||
|
||
ERR_TOO_LONG
|
||
: 当某一项超过字符数限制时出现
|
||
|
||
ERR_TOO_SHORT
|
||
: 当某一项低于字符数要求时出现
|
||
|
||
ERR_INCLUSION
|
||
: 当某一项的值不是允许的值之一时出现，例如填写了不受支持的语言
|
||
|
||
##### 429: Rate limited
|
||
|
||
```json
|
||
{
|
||
"error": "请求过多"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 验证账户凭据 {#verify_credentials}
|
||
|
||
```http
|
||
GET /api/v1/accounts/verify_credentials HTTP/1.1
|
||
```
|
||
|
||
测试以确保用户令牌有效。
|
||
|
||
**返回:** [CredentialAccount]({{< relref "entities/Account#CredentialAccount">}})\
|
||
**OAuth:** 用户令牌 + `profile` 或 `read:accounts`\
|
||
**版本历史:**\
|
||
0.0.0 - 添加
|
||
4.3.0 - 添加 `profile` 段
|
||
|
||
#### 请求
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: {{<required>}} 提供此标头与 `Bearer <user_token>`，以获得对此 API 方法的访问授权。
|
||
|
||
#### 响应
|
||
|
||
##### 200: OK
|
||
|
||
请注意额外的 `source` 属性，该属性在你自己的账户之外不可见。另请注意，纯文本用于 `source` 中，而 HTML 用于其相应的属性，例如 `note` 和 `fields`。
|
||
|
||
```json
|
||
{
|
||
"id": "14715",
|
||
"username": "trwnh",
|
||
"acct": "trwnh",
|
||
"display_name": "infinite love ⴳ",
|
||
"locked": false,
|
||
"bot": false,
|
||
"created_at": "2016-11-24T10:02:12.085Z",
|
||
"note": "<p>i have approximate knowledge of many things. perpetual student. (nb/ace/they)</p><p>xmpp/email: a@trwnh.com<br /><a href=\"https://trwnh.com\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">trwnh.com</span><span class=\"invisible\"></span></a><br />help me live: <a href=\"https://liberapay.com/at\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">liberapay.com/at</span><span class=\"invisible\"></span></a> or <a href=\"https://paypal.me/trwnh\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">paypal.me/trwnh</span><span class=\"invisible\"></span></a></p><p>- my triggers are moths and glitter<br />- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise<br />- dm me if i did something wrong, so i can improve<br />- purest person on fedi, do not lewd in my presence<br />- #1 ami cole fan account</p><p>:fatyoshi:</p>",
|
||
"url": "https://mastodon.social/@trwnh",
|
||
"avatar": "https://files.mastodon.social/accounts/avatars/000/014/715/original/34aa222f4ae2e0a9.png",
|
||
"avatar_static": "https://files.mastodon.social/accounts/avatars/000/014/715/original/34aa222f4ae2e0a9.png",
|
||
"header": "https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg",
|
||
"header_static": "https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg",
|
||
"followers_count": 821,
|
||
"following_count": 178,
|
||
"statuses_count": 33120,
|
||
"last_status_at": "2019-11-24T15:49:42.251Z",
|
||
"source": {
|
||
"privacy": "public",
|
||
"sensitive": false,
|
||
"language": "",
|
||
"note": "i have approximate knowledge of many things. perpetual student. (nb/ace/they)\r\n\r\nxmpp/email: a@trwnh.com\r\nhttps://trwnh.com\r\nhelp me live: https://liberapay.com/at or https://paypal.me/trwnh\r\n\r\n- my triggers are moths and glitter\r\n- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise\r\n- dm me if i did something wrong, so i can improve\r\n- purest person on fedi, do not lewd in my presence\r\n- #1 ami cole fan account\r\n\r\n:fatyoshi:",
|
||
"fields": [
|
||
{
|
||
"name": "Website",
|
||
"value": "https://trwnh.com",
|
||
"verified_at": "2019-08-29T04:14:55.571+00:00"
|
||
},
|
||
{
|
||
"name": "Sponsor",
|
||
"value": "https://liberapay.com/at",
|
||
"verified_at": "2019-11-15T10:06:15.557+00:00"
|
||
},
|
||
{
|
||
"name": "Fan of:",
|
||
"value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo's Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)",
|
||
"verified_at": null
|
||
},
|
||
{
|
||
"name": "Main topics:",
|
||
"value": "systemic analysis, design patterns, anticapitalism, info/tech freedom, theory and philosophy, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people!",
|
||
"verified_at": null
|
||
}
|
||
],
|
||
"follow_requests_count": 0
|
||
},
|
||
"emojis": [
|
||
{
|
||
"shortcode": "fatyoshi",
|
||
"url": "https://files.mastodon.social/custom_emojis/images/000/023/920/original/e57ecb623faa0dc9.png",
|
||
"static_url": "https://files.mastodon.social/custom_emojis/images/000/023/920/static/e57ecb623faa0dc9.png",
|
||
"visible_in_picker": true
|
||
}
|
||
],
|
||
"fields": [
|
||
{
|
||
"name": "Website",
|
||
"value": "<a href=\"https://trwnh.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">trwnh.com</span><span class=\"invisible\"></span></a>",
|
||
"verified_at": "2019-08-29T04:14:55.571+00:00"
|
||
},
|
||
{
|
||
"name": "Sponsor",
|
||
"value": "<a href=\"https://liberapay.com/at\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">liberapay.com/at</span><span class=\"invisible\"></span></a>",
|
||
"verified_at": "2019-11-15T10:06:15.557+00:00"
|
||
},
|
||
{
|
||
"name": "Fan of:",
|
||
"value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo's Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)",
|
||
"verified_at": null
|
||
},
|
||
{
|
||
"name": "Main topics:",
|
||
"value": "systemic analysis, design patterns, anticapitalism, info/tech freedom, theory and philosophy, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people!",
|
||
"verified_at": null
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
若令牌无效或不正确，凭据验证将失败。
|
||
|
||
```json
|
||
{
|
||
"error": "The access token is invalid"
|
||
}
|
||
```
|
||
|
||
##### 403: Forbidden
|
||
|
||
你的用户账户当前已禁用，缺少已验证的电子邮件地址或正在等待批准。
|
||
|
||
```json
|
||
{
|
||
"error": "Your login is currently disabled"
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"error": "Your login is missing a confirmed e-mail address"
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"error": "Your login is currently pending approval"
|
||
}
|
||
```
|
||
|
||
##### 422: Unprocessable entity
|
||
|
||
令牌没有授权用户
|
||
|
||
```json
|
||
{
|
||
"error": "This method requires an authenticated user"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 更新账户凭据 {#update_credentials}
|
||
|
||
```http
|
||
PATCH /api/v1/accounts/update_credentials HTTP/1.1
|
||
```
|
||
|
||
更新用户的显示和偏好设置。
|
||
|
||
**返回:** 用户自己的 [Account]({{< relref "entities/Account">}})，带有 [`source`]({{< relref "entities/Account#source">}}) 属性\
|
||
**OAuth:** 用户令牌 + `write:accounts`\
|
||
**版本历史:**\
|
||
1.1.1 - 添加\
|
||
2.3.0 - 添加 `locked` 参数\
|
||
2.4.0 - 添加 `source[privacy,sensitive]` 参数\
|
||
2.4.2 - 添加 `source[language]` 参数\
|
||
2.7.0 - 添加 `discoverable` 参数\
|
||
4.1.0 - 添加 `hide_collections` 参数\
|
||
4.2.0 - 添加 `indexable` 参数\
|
||
4.4.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 3) - 添加 `attribution_domains` 参数
|
||
|
||
#### 请求
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: {{<required>}} 提供此标头与 `Bearer <user_token>`，以获得对此 API 方法的访问授权。
|
||
|
||
##### 表单数据参数
|
||
|
||
display_name
|
||
: 字符串。用于 profile 的昵称。
|
||
|
||
note
|
||
: 字符串。账户简介。
|
||
|
||
avatar
|
||
: 使用“multipart/form-data”编码的头像图片
|
||
|
||
header
|
||
: 使用“multipart/form-data”编码的横幅图片
|
||
|
||
locked
|
||
: 布尔值。是否需要手动批准关注请求。
|
||
|
||
bot
|
||
: 布尔值。账户是否具有机器人标志。
|
||
|
||
discoverable
|
||
: 布尔值。账户是否应被展示在用户列表中。
|
||
|
||
hide_collections
|
||
: 布尔值。是否隐藏关注者和关注的账户。
|
||
|
||
indexable
|
||
: 布尔值。公开嘟文是否应可供任何人搜索。
|
||
|
||
attribution_domains[]
|
||
: 字符串数组。允许授权该账户的网站域名。
|
||
|
||
fields_attributes
|
||
: 哈希。要设置的个人资料字段。在此哈希中，键是被强制转换为字符串的整数（尽管确切的整数并不重要），值是另一个包含 `name` 和 `value` 的哈希。默认情况下，最多 4 个字段。
|
||
|
||
fields_attributes[:index][name]
|
||
: 字符串。个人资料字段的名称。默认情况下，最多 255 个字符。
|
||
|
||
fields_attributes[:index][value]
|
||
: 字符串。个人资料字段的值。默认情况下，最多 255 个字符。
|
||
|
||
source[privacy]
|
||
: 字符串。默认发嘟可见性设置。可以是“public”、“unlisted”或“private”。
|
||
|
||
source[sensitive]
|
||
: 布尔值。是否默认将嘟文标记为敏感。
|
||
|
||
source[language]
|
||
: 字符串。新嘟文默认语言（ISO 6391）
|
||
|
||
#### 响应
|
||
|
||
##### 200: OK
|
||
|
||
要更新账户字段，你需要参照一下结构构造你的哈希，例如：
|
||
|
||
```json
|
||
{
|
||
"fields_attributes": {
|
||
"0": {
|
||
"name": "Website",
|
||
"value": "https://trwnh.com"
|
||
},
|
||
"1": {
|
||
"name": "Sponsor",
|
||
"value": "https://liberapay.com/at"
|
||
},
|
||
// ...
|
||
}
|
||
}
|
||
```
|
||
|
||
作为查询参数，你的请求可能如下所示：
|
||
|
||
```http
|
||
PATCH https://mastodon.example/api/v1/accounts/update_credentials
|
||
?fields_attributes[0][name]=Website
|
||
&fields_attributes[0][value]=https://trwnh.com
|
||
&fields_attributes[1][name]=Sponsor
|
||
&fields_attributes[1][value]=https://liberapay.com/at
|
||
&...
|
||
```
|
||
|
||
请注意，整数索引实际上并不重要 - 字段将按提供的顺序填充。 例如：
|
||
|
||
```json
|
||
{
|
||
"fields_attributes": {
|
||
"420": {
|
||
"name": "1st",
|
||
"value": "field"
|
||
},
|
||
"69": {
|
||
"name": "2nd",
|
||
"value": "field"
|
||
},
|
||
"1312": {
|
||
"name": "3rd",
|
||
"value": "field"
|
||
},
|
||
"-99999999999999999999999999999999": {
|
||
"name": "4th",
|
||
"value": "field"
|
||
},
|
||
}
|
||
}
|
||
```
|
||
|
||
你应该使用 accounts/verify_credentials，首先从 `source` 参数中获取纯文本表示形式，然后允许用户编辑这些纯文本表示形式，然后再通过此 API 提交它们。实例将生成相应的 HTML。
|
||
|
||
```json
|
||
{
|
||
"id": "14715",
|
||
"username": "trwnh",
|
||
"acct": "trwnh",
|
||
"display_name": "infinite love ⴳ",
|
||
"locked": false,
|
||
"bot": false,
|
||
"created_at": "2016-11-24T10:02:12.085Z",
|
||
"note": "<p>i have approximate knowledge of many things. perpetual student. (nb/ace/they)</p><p>xmpp/email: a@trwnh.com<br /><a href=\"https://trwnh.com\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">trwnh.com</span><span class=\"invisible\"></span></a><br />help me live: <a href=\"https://liberapay.com/at\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">liberapay.com/at</span><span class=\"invisible\"></span></a> or <a href=\"https://paypal.me/trwnh\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">paypal.me/trwnh</span><span class=\"invisible\"></span></a></p><p>- my triggers are moths and glitter<br />- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise<br />- dm me if i did something wrong, so i can improve<br />- purest person on fedi, do not lewd in my presence<br />- #1 ami cole fan account</p><p>:fatyoshi:</p>",
|
||
"url": "https://mastodon.social/@trwnh",
|
||
"avatar": "https://files.mastodon.social/accounts/avatars/000/014/715/original/34aa222f4ae2e0a9.png",
|
||
"avatar_static": "https://files.mastodon.social/accounts/avatars/000/014/715/original/34aa222f4ae2e0a9.png",
|
||
"header": "https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg",
|
||
"header_static": "https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg",
|
||
"followers_count": 834,
|
||
"following_count": 182,
|
||
"statuses_count": 33760,
|
||
"last_status_at": "2019-12-01T00:12:08.731Z",
|
||
"source": {
|
||
"privacy": "public",
|
||
"sensitive": false,
|
||
"language": "",
|
||
"note": "i have approximate knowledge of many things. perpetual student. (nb/ace/they)\r\n\r\nxmpp/email: a@trwnh.com\r\nhttps://trwnh.com\r\nhelp me live: https://liberapay.com/at or https://paypal.me/trwnh\r\n\r\n- my triggers are moths and glitter\r\n- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise\r\n- dm me if i did something wrong, so i can improve\r\n- purest person on fedi, do not lewd in my presence\r\n- #1 ami cole fan account\r\n\r\n:fatyoshi:",
|
||
"fields": [
|
||
{
|
||
"name": "Website",
|
||
"value": "https://trwnh.com",
|
||
"verified_at": "2019-08-29T04:14:55.571+00:00"
|
||
},
|
||
{
|
||
"name": "Sponsor",
|
||
"value": "https://liberapay.com/at",
|
||
"verified_at": "2019-11-15T10:06:15.557+00:00"
|
||
},
|
||
{
|
||
"name": "Fan of:",
|
||
"value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo's Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)",
|
||
"verified_at": null
|
||
},
|
||
{
|
||
"name": "Main topics:",
|
||
"value": "systemic analysis, design patterns, anticapitalism, info/tech freedom, theory and philosophy, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people!",
|
||
"verified_at": null
|
||
}
|
||
],
|
||
"follow_requests_count": 0
|
||
},
|
||
"emojis": [
|
||
{
|
||
"shortcode": "fatyoshi",
|
||
"url": "https://files.mastodon.social/custom_emojis/images/000/023/920/original/e57ecb623faa0dc9.png",
|
||
"static_url": "https://files.mastodon.social/custom_emojis/images/000/023/920/static/e57ecb623faa0dc9.png",
|
||
"visible_in_picker": true
|
||
}
|
||
],
|
||
"fields": [
|
||
{
|
||
"name": "Website",
|
||
"value": "<a href=\"https://trwnh.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">trwnh.com</span><span class=\"invisible\"></span></a>",
|
||
"verified_at": "2019-08-29T04:14:55.571+00:00"
|
||
},
|
||
{
|
||
"name": "Sponsor",
|
||
"value": "<a href=\"https://liberapay.com/at\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">liberapay.com/at</span><span class=\"invisible\"></span></a>",
|
||
"verified_at": "2019-11-15T10:06:15.557+00:00"
|
||
},
|
||
{
|
||
"name": "Fan of:",
|
||
"value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo's Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)",
|
||
"verified_at": null
|
||
},
|
||
{
|
||
"name": "Main topics:",
|
||
"value": "systemic analysis, design patterns, anticapitalism, info/tech freedom, theory and philosophy, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people!",
|
||
"verified_at": null
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
```json
|
||
{
|
||
"error": "访问令牌无效"
|
||
}
|
||
```
|
||
|
||
##### 422: Unprocessable entity
|
||
|
||
令牌没有授权用户
|
||
|
||
```json
|
||
{
|
||
"error": "This method requires an authenticated user"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 获取账户 {#get}
|
||
|
||
```http
|
||
GET /api/v1/accounts/:id HTTP/1.1
|
||
```
|
||
|
||
查看账户信息。
|
||
|
||
**返回:** [Account]({{< relref "entities/Account">}})\
|
||
**OAuth:** 公开\
|
||
**版本历史:**\
|
||
0.0.0 - 添加\
|
||
2.4.0 - 若账户已封禁，则返回 410\
|
||
3.3.0 - 返回一个带有 `suspended: true` 的账户，而不是 410
|
||
|
||
#### 请求
|
||
##### 路径参数
|
||
|
||
:id
|
||
: {{<required>}} 字符串。数据库中账户的 ID。
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: 提供此标头与 `Bearer <user_token>`，以获得对此 API 方法的访问授权。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
将返回账户记录。请注意，本站用户的 `acct` 不包括域名。
|
||
|
||
###### 本站用户
|
||
|
||
```json
|
||
{
|
||
"id": "1",
|
||
"username": "Gargron",
|
||
"acct": "Gargron",
|
||
"display_name": "Eugen",
|
||
"locked": false,
|
||
"bot": false,
|
||
"created_at": "2016-03-16T14:34:26.392Z",
|
||
"note": "<p>Developer of Mastodon and administrator of mastodon.social. I post service announcements, development updates, and personal stuff.</p>",
|
||
"url": "https://mastodon.social/@Gargron",
|
||
"avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg",
|
||
"avatar_static": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg",
|
||
"header": "https://files.mastodon.social/accounts/headers/000/000/001/original/c91b871f294ea63e.png",
|
||
"header_static": "https://files.mastodon.social/accounts/headers/000/000/001/original/c91b871f294ea63e.png",
|
||
"followers_count": 318699,
|
||
"following_count": 453,
|
||
"statuses_count": 61013,
|
||
"last_status_at": "2019-11-30T20:02:08.277Z",
|
||
"emojis": [],
|
||
"fields": [
|
||
{
|
||
"name": "Patreon",
|
||
"value": "<a href=\"https://www.patreon.com/mastodon\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://www.</span><span class=\"\">patreon.com/mastodon</span><span class=\"invisible\"></span></a>",
|
||
"verified_at": null
|
||
},
|
||
{
|
||
"name": "Homepage",
|
||
"value": "<a href=\"https://zeonfederated.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">zeonfederated.com</span><span class=\"invisible\"></span></a>",
|
||
"verified_at": "2019-07-15T18:29:57.191+00:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
###### 外站用户
|
||
|
||
```json
|
||
{
|
||
"id": "23634",
|
||
"username": "noiob",
|
||
"acct": "noiob@awoo.space",
|
||
"display_name": "shork",
|
||
"locked": false,
|
||
"bot": false,
|
||
"created_at": "2017-02-08T02:00:53.274Z",
|
||
"note": "<p>:ms_rainbow_flag: :ms_bisexual_flag: :ms_nonbinary_flag: <a href=\"https://awoo.space/tags/awoo\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>awoo</span></a>.space <a href=\"https://awoo.space/tags/admin\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>admin</span></a> ~ <a href=\"https://awoo.space/tags/bi\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>bi</span></a> ~ <a href=\"https://awoo.space/tags/nonbinary\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>nonbinary</span></a> ~ compsci student ~ likes video <a href=\"https://awoo.space/tags/games\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>games</span></a> and weird/ old electronics and will post obsessively about both ~ avatar by <span class=\"h-card\"><a href=\"https://weirder.earth/@dzuk\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>dzuk</span></a></span></p>",
|
||
"url": "https://awoo.space/@noiob",
|
||
"avatar": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png",
|
||
"avatar_static": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png",
|
||
"header": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png",
|
||
"header_static": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png",
|
||
"followers_count": 553,
|
||
"following_count": 405,
|
||
"statuses_count": 28982,
|
||
"last_status_at": "2019-12-01T00:39:57.264Z",
|
||
"emojis": [
|
||
{
|
||
"shortcode": "ms_rainbow_flag",
|
||
"url": "https://files.mastodon.social/custom_emojis/images/000/028/691/original/6de008d6281f4f59.png",
|
||
"static_url": "https://files.mastodon.social/custom_emojis/images/000/028/691/static/6de008d6281f4f59.png",
|
||
"visible_in_picker": true
|
||
},
|
||
{
|
||
"shortcode": "ms_bisexual_flag",
|
||
"url": "https://files.mastodon.social/custom_emojis/images/000/050/744/original/02f94a5fca7eaf78.png",
|
||
"static_url": "https://files.mastodon.social/custom_emojis/images/000/050/744/static/02f94a5fca7eaf78.png",
|
||
"visible_in_picker": true
|
||
},
|
||
{
|
||
"shortcode": "ms_nonbinary_flag",
|
||
"url": "https://files.mastodon.social/custom_emojis/images/000/105/099/original/8106088bd4782072.png",
|
||
"static_url": "https://files.mastodon.social/custom_emojis/images/000/105/099/static/8106088bd4782072.png",
|
||
"visible_in_picker": true
|
||
}
|
||
],
|
||
"fields": [
|
||
{
|
||
"name": "Pronouns",
|
||
"value": "they/them",
|
||
"verified_at": null
|
||
},
|
||
{
|
||
"name": "Alt",
|
||
"value": "<span class=\"h-card\"><a href=\"https://cybre.space/@noiob\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>noiob</span></a></span>",
|
||
"verified_at": null
|
||
},
|
||
{
|
||
"name": "Bots",
|
||
"value": "<span class=\"h-card\"><a href=\"https://botsin.space/@darksouls\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>darksouls</span></a></span>, <span class=\"h-card\"><a href=\"https://botsin.space/@nierautomata\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>nierautomata</span></a></span>, code for <span class=\"h-card\"><a href=\"https://botsin.space/@awoobot\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>awoobot</span></a></span>",
|
||
"verified_at": null
|
||
},
|
||
{
|
||
"name": "Website",
|
||
"value": "<a href=\"http://shork.xyz\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">http://</span><span class=\"\">shork.xyz</span><span class=\"invisible\"></span></a>",
|
||
"verified_at": "2019-11-23T20:25:47.907+00:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
###### 已封禁用户
|
||
|
||
```json
|
||
{
|
||
"id": "14",
|
||
"username": "stigatle",
|
||
"acct": "stigatle@quitter.no",
|
||
"display_name": "",
|
||
"locked": false,
|
||
"bot": false,
|
||
"discoverable": false,
|
||
"group": false,
|
||
"created_at": "2016-03-18T10:04:51.700Z",
|
||
"note": "",
|
||
"url": "https://quitter.no/stigatle",
|
||
"avatar": "https://mastodon.social/avatars/original/missing.png",
|
||
"avatar_static": "https://mastodon.social/avatars/original/missing.png",
|
||
"header": "https://mastodon.social/headers/original/missing.png",
|
||
"header_static": "https://mastodon.social/headers/original/missing.png",
|
||
"followers_count": 0,
|
||
"following_count": 0,
|
||
"statuses_count": 0,
|
||
"last_status_at": null,
|
||
"suspended": true,
|
||
"emojis": [],
|
||
"fields": []
|
||
}
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
若实例处于白名单模式，且 `Authorization` 标头缺失或无效。
|
||
|
||
```json
|
||
{
|
||
"error": "此 API 需要已认证的用户"
|
||
}
|
||
```
|
||
|
||
##### 404: Not found
|
||
|
||
账户不存在。
|
||
|
||
```json
|
||
{
|
||
"error": "记录未找到"
|
||
}
|
||
```
|
||
|
||
##### 410: Gone
|
||
|
||
账户已被封禁（版本 2.4.0 起至 3.3.0 止）。
|
||
|
||
---
|
||
|
||
## 获取多个账户信息 {#index}
|
||
|
||
```http
|
||
GET /api/v1/accounts HTTP/1.1
|
||
```
|
||
|
||
查看多个账户的信息。
|
||
|
||
**返回：** [Account]({{< relref "entities/Account">}}) 数组
|
||
**OAuth：** 公开
|
||
**版本历史：**
|
||
4.3.0 - 添加
|
||
|
||
#### 请求
|
||
##### 标头
|
||
|
||
##### 查询参数
|
||
|
||
id[]
|
||
: 字符串数组。数据库中账户的 ID。
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: 提供此标头并附带 `Bearer <用户令牌>` 以获得对此 API 方法的访问授权。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
将返回请求的已验证且已被批准账户的 [Account]({{< relref "entities/Account">}}) 记录。若账户不存在或未确认，返回的记录数可能会少于请求的数量。
|
||
|
||
使用 `id[]=1&id[]=2` 的调用示例（当 ID 为 2 的账户不存在时）：
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": "1",
|
||
"username": "Gargron",
|
||
"acct": "Gargron",
|
||
"display_name": "Eugen",
|
||
"locked": false,
|
||
"bot": false,
|
||
"created_at": "2016-03-16T14:34:26.392Z",
|
||
"note": "<p>Developer of Mastodon and administrator of mastodon.social. I post service announcements, development updates, and personal stuff.</p>",
|
||
"url": "https://mastodon.social/@Gargron",
|
||
"avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg",
|
||
"avatar_static": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg",
|
||
"header": "https://files.mastodon.social/accounts/headers/000/000/001/original/c91b871f294ea63e.png",
|
||
"header_static": "https://files.mastodon.social/accounts/headers/000/000/001/original/c91b871f294ea63e.png",
|
||
"followers_count": 318699,
|
||
"following_count": 453,
|
||
"statuses_count": 61013,
|
||
"last_status_at": "2019-11-30T20:02:08.277Z",
|
||
"emojis": [],
|
||
"fields": [
|
||
{
|
||
"name": "Patreon",
|
||
"value": "<a href=\"https://www.patreon.com/mastodon\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://www.</span><span class=\"\">patreon.com/mastodon</span><span class=\"invisible\"></span></a>",
|
||
"verified_at": null
|
||
},
|
||
{
|
||
"name": "Homepage",
|
||
"value": "<a href=\"https://zeonfederated.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">zeonfederated.com</span><span class=\"invisible\"></span></a>",
|
||
"verified_at": "2019-07-15T18:29:57.191+00:00"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
若实例处于白名单模式，且 `Authorization` 标头缺失或无效，则返回此错误。
|
||
|
||
```json
|
||
{
|
||
"error": "This API requires an authenticated user"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 获取账户的嘟文 {#statuses}
|
||
|
||
```http
|
||
GET /api/v1/accounts/:id/statuses HTTP/1.1
|
||
```
|
||
|
||
获取指定账户发布的嘟文。
|
||
|
||
**返回：** [Status]({{< relref "entities/status">}}) 数组
|
||
**OAuth：** 公开访问（仅限公开嘟文），或用户令牌 + `read:statuses`（用于访问用户有权查看的私密嘟文）
|
||
**版本历史：**
|
||
0.0.0 - 添加
|
||
1.4.2 - 添加 `only_media` 和 `exclude_replies`
|
||
1.6.0 - 添加 `pinned`
|
||
2.6.0 - 添加 `min_id`
|
||
2.7.0 - 添加 `exclude_reblogs` 并允许未经身份验证的使用
|
||
2.8.0 - 添加 `tagged` 参数
|
||
3.3.0 - 现在可以同时使用 `min_id` 和 `max_id`
|
||
|
||
#### 请求
|
||
##### 路径参数
|
||
|
||
:id
|
||
: {{<required>}} 字符串。数据库中账户的 ID。
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: 提供此标头并附带 `Bearer <用户令牌>` 以获得对此 API 方法的访问授权。
|
||
|
||
##### 查询参数
|
||
|
||
max_id
|
||
: 字符串。返回的所有结果 ID 都将小于此 ID。事实上设置结果的上限。
|
||
|
||
since_id
|
||
: 字符串。返回的所有结果 ID 都将大于此 ID。事实上是设置结果的下限。
|
||
|
||
min_id
|
||
: 字符串。返回紧邻此 ID 之后的新结果。事实上在此 ID 设置游标并向前分页。
|
||
|
||
limit
|
||
: 整数。返回的最大结果数。默认为 20 条嘟文。最多 40 条嘟文。
|
||
|
||
only_media
|
||
: 布尔值。过滤没有附件的嘟文。
|
||
|
||
exclude_replies
|
||
: 布尔值。过滤回复给其他账户的嘟文。
|
||
|
||
exclude_reblogs
|
||
: 布尔值。过滤转嘟。
|
||
|
||
pinned
|
||
: 布尔值。仅筛选置顶的嘟文。默认为 false，包含所有嘟文。置顶嘟文在返回结果的顺序中没有特殊优先级。
|
||
|
||
tagged
|
||
: 字符串。筛选使用了特定话题标签的嘟文。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": "108880211901672326",
|
||
"created_at": "2022-08-24T22:29:46.493Z",
|
||
"in_reply_to_id": "108880209317577809",
|
||
"in_reply_to_account_id": "103641",
|
||
"sensitive": false,
|
||
// ...
|
||
},
|
||
// ...
|
||
]
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
若实例处于白名单模式，且 `Authorization` 标头缺失或无效，则返回此错误。
|
||
|
||
白名单模式的响应示例：
|
||
|
||
```json
|
||
{
|
||
"error": "This API requires an authenticated user"
|
||
}
|
||
```
|
||
|
||
2.7.0 版本之前的响应示例：
|
||
|
||
```json
|
||
{
|
||
"error": "The access token is invalid"
|
||
}
|
||
```
|
||
|
||
##### 404: Not found
|
||
|
||
账户不存在。
|
||
|
||
```json
|
||
{
|
||
"error": "Record not found"
|
||
}
|
||
```
|
||
|
||
##### 410: Gone
|
||
|
||
账户已被封禁（版本 2.4.0 起至 3.3.0 止）。
|
||
|
||
---
|
||
|
||
## 获取账户的关注者 {#followers}
|
||
|
||
```http
|
||
GET /api/v1/accounts/:id/followers HTTP/1.1
|
||
```
|
||
|
||
获取关注指定账户的用户列表，前提是该账户所有者未隐藏其社交关系网络。
|
||
|
||
**返回：** [Account]({{< relref "entities/Account">}}) 数组
|
||
**OAuth：** 公开访问
|
||
**版本历史：**
|
||
0.0.0 - 添加
|
||
3.3.0 - 现在可以同时使用 `min_id` 和 `max_id`
|
||
4.0.0 - 不再需要应用令牌 + `read:accounts`
|
||
|
||
#### 请求
|
||
##### 路径参数
|
||
|
||
:id
|
||
: {{<required>}} 字符串。数据库中账户的 ID。
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: 提供此标头并附带 `Bearer <用户令牌>` 以获得对此 API 方法的访问授权。
|
||
|
||
##### 查询参数
|
||
|
||
max_id
|
||
: **内部参数。** 使用 HTTP `Link` 标头进行分页。
|
||
|
||
since_id
|
||
: **内部参数。** 使用 HTTP `Link` 标头进行分页。
|
||
|
||
min_id
|
||
: **内部参数。** 使用 HTTP `Link` 标头进行分页。
|
||
|
||
limit
|
||
: 整数。返回的最大结果数。默认为 40 个账户。最多 80 个账户。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
limit=2 的输出示例。
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": "1020382",
|
||
"username": "atul13061987",
|
||
"acct": "atul13061987",
|
||
"display_name": "",
|
||
// ...
|
||
},
|
||
{
|
||
"id": "1020381",
|
||
"username": "linuxliner",
|
||
"acct": "linuxliner",
|
||
"display_name": "",
|
||
// ...
|
||
}
|
||
]
|
||
```
|
||
|
||
由于关注关系 ID 通常不会通过任何 API 响应公开，你需要解析 HTTP `Link` 标头来加载更早或更新的结果。更多信息请参见 [通过 API 响应分页]({{<relref "api/guidelines#pagination">}})。
|
||
|
||
```http
|
||
Link: <https://mastodon.example/api/v1/accounts/14715/followers?limit=2&max_id=7486869>; rel="next", <https://mastodon.example/api/v1/accounts/14715/followers?limit=2&since_id=7489740>; rel="prev"
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
`Authorization` 标头无效或缺失，或者实例处于白名单模式且你的令牌未获得用户授权。
|
||
|
||
白名单模式的响应示例：
|
||
|
||
```json
|
||
{
|
||
"error": "This API requires an authenticated user"
|
||
}
|
||
```
|
||
|
||
标头缺失或令牌无效的响应示例：
|
||
|
||
```json
|
||
{
|
||
"error": "The access token is invalid"
|
||
}
|
||
```
|
||
|
||
##### 404: Not found
|
||
|
||
账户不存在。
|
||
|
||
```json
|
||
{
|
||
"error": "Record not found"
|
||
}
|
||
```
|
||
|
||
##### 410: Gone
|
||
|
||
账户已被封禁（版本 2.4.0 起至 3.3.0 止）。
|
||
|
||
---
|
||
|
||
## 获取账户正在关注的用户 {#following}
|
||
|
||
```http
|
||
GET /api/v1/accounts/:id/following HTTP/1.1
|
||
```
|
||
|
||
获取指定账户正在关注的用户列表，前提是该账户所有者未隐藏其社交关系网络。
|
||
|
||
**返回：** [Account]({{< relref "entities/Account">}}) 数组
|
||
**OAuth：** 公开访问
|
||
**版本历史：**
|
||
0.0.0 - 添加
|
||
3.3.0 - 现在可以同时使用 `min_id` 和 `max_id`
|
||
4.0.0 - 不再需要应用令牌 + `read:accounts`
|
||
|
||
#### 请求
|
||
##### 路径参数
|
||
|
||
:id
|
||
: {{<required>}} 字符串。数据库中账户的 ID。
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: 提供此标头并附带 `Bearer <用户令牌>` 以获得对此 API 方法的访问授权。
|
||
|
||
##### 查询参数
|
||
|
||
max_id
|
||
: **内部参数。** 使用 HTTP `Link` 标头进行分页。
|
||
|
||
since_id
|
||
: **内部参数。** 使用 HTTP `Link` 标头进行分页。
|
||
|
||
min_id
|
||
: **内部参数。** 使用 HTTP `Link` 标头进行分页。
|
||
|
||
limit
|
||
: 整数。返回的最大结果数。默认为 40 个账户。最多 80 个账户。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
limit=2 的输出示例。
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": "963410",
|
||
"username": "gautambhatia",
|
||
"acct": "gautambhatia",
|
||
"display_name": "Gautam Bhatia",
|
||
// ...
|
||
},
|
||
{
|
||
"id": "1007400",
|
||
"username": "seafrog",
|
||
"acct": "seafrog@glitterkitten.co.uk",
|
||
"display_name": "🐓🦃 Heck Partridge 🤠 🦆",
|
||
// ...
|
||
]
|
||
```
|
||
|
||
由于关注关系 ID 通常不会通过任何 API 响应公开，你需要解析 HTTP `Link` 标头来加载更早或更新的结果。更多信息请参见 [通过 API 响应分页]({{<relref "api/guidelines#pagination">}})。
|
||
|
||
```http
|
||
Link: <https://mastodon.example/api/v1/accounts/1/followers?limit=2&max_id=7628164>; rel="next", <https://mastodon.example/api/v1/accounts/1/followers?limit=2&since_id=7628165>; rel="prev"
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
`Authorization` 标头无效或缺失，或者实例处于白名单模式且你的令牌未获得用户授权。
|
||
|
||
白名单模式的响应示例：
|
||
|
||
```json
|
||
{
|
||
"error": "This API requires an authenticated user"
|
||
}
|
||
```
|
||
|
||
标头缺失或令牌无效的响应示例：
|
||
|
||
```json
|
||
{
|
||
"error": "The access token is invalid"
|
||
}
|
||
```
|
||
|
||
##### 404: Not found
|
||
|
||
账户不存在。
|
||
|
||
```json
|
||
{
|
||
"error": "Record not found"
|
||
}
|
||
```
|
||
|
||
##### 410: Gone
|
||
|
||
账户已被封禁（版本 2.4.0 起至 3.3.0 止）。
|
||
|
||
---
|
||
|
||
## 获取账户的精选话题标签 {#featured_tags}
|
||
|
||
```http
|
||
GET /api/v1/accounts/:id/featured_tags HTTP/1.1
|
||
```
|
||
|
||
获取此账户的精选话题标签。
|
||
|
||
**返回：** [FeaturedTag]({{< relref "entities/featuredtag">}}) 数组
|
||
**OAuth：** 公开
|
||
**版本历史：**
|
||
3.3.0 - 添加
|
||
|
||
#### 请求
|
||
##### 路径参数
|
||
|
||
:id
|
||
: {{<required>}} 字符串。数据库中账户的 ID。
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: 提供此标头并附带 `Bearer <用户令牌>` 以获得对此 API 方法的访问授权。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": "627",
|
||
"name": "nowplaying",
|
||
"statuses_count": 36,
|
||
"last_status_at": "2019-11-15T07:14:43.524Z"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
## 获取包含此账户的列表 {#lists}
|
||
|
||
```http
|
||
GET /api/v1/accounts/:id/lists HTTP/1.1
|
||
```
|
||
|
||
获取你已将此账户添加到的用户列表。
|
||
|
||
**返回：** [List]({{< relref "entities/list">}}) 数组
|
||
**OAuth：** 用户令牌 + `read:lists`
|
||
**版本历史：**
|
||
2.1.0 - 添加
|
||
|
||
#### 请求
|
||
##### 路径参数
|
||
|
||
:id
|
||
: {{<required>}} 字符串。数据库中账户的 ID。
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: {{<required>}} 提供此标头并附带 `Bearer <用户令牌>` 以获得对此 API 方法的访问授权。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
若该账户属于任何列表，将返回这些列表的实体。若该账户不属于你的任何列表，则返回空数组。
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": "13694",
|
||
"title": "dev"
|
||
}
|
||
]
|
||
```
|
||
|
||
```json
|
||
[]
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
`Authorization` 标头无效或缺失，或者实例处于白名单模式且你的令牌未获得用户授权。
|
||
|
||
白名单模式的响应示例：
|
||
|
||
```json
|
||
{
|
||
"error": "This API requires an authenticated user"
|
||
}
|
||
```
|
||
|
||
标头缺失或令牌无效的响应示例：
|
||
|
||
```json
|
||
{
|
||
"error": "The access token is invalid"
|
||
}
|
||
```
|
||
|
||
##### 404: Not found
|
||
|
||
账户不存在。
|
||
|
||
```json
|
||
{
|
||
"error": "Record not found"
|
||
}
|
||
```
|
||
|
||
##### 410: Gone
|
||
|
||
账户已被封禁（版本 2.4.0 起至 3.3.0 止）。
|
||
|
||
##### 422: Unprocessable entity
|
||
|
||
令牌没有授权用户。
|
||
|
||
```json
|
||
{
|
||
"error": "This method requires an authenticated user"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 关注账户 {#follow}
|
||
|
||
```http
|
||
POST /api/v1/accounts/:id/follow HTTP/1.1
|
||
```
|
||
|
||
关注指定账户。也可用于更新是否显示转嘟或启用通知。
|
||
|
||
**返回：** [Relationship]({{< relref "entities/relationship">}})
|
||
**OAuth：** 用户令牌 + `write:follows`
|
||
**版本历史：**
|
||
0.0.0 - 添加
|
||
3.3.0 - 添加 `notify`
|
||
3.5.0 - 弃用 `follow` 作用域。现在额外接受 `write`
|
||
4.0.0 - 添加 `languages`
|
||
|
||
#### 请求
|
||
##### 路径参数
|
||
|
||
:id
|
||
: {{<required>}} 字符串。数据库中账户的 ID。
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: {{<required>}} 提供此标头并附带 `Bearer <用户令牌>` 以获得对此 API 方法的访问授权。
|
||
|
||
##### 表单数据参数
|
||
|
||
reblogs
|
||
: 布尔值。是否在主页时间线上接收此账户的转嘟？默认为 true。
|
||
|
||
notify
|
||
: 布尔值。当此账户发布嘟文时是否接收通知？默认为 false。
|
||
|
||
languages[]
|
||
: 字符串数组（ISO 639-1 双字符语言代码）。根据设置的语言过滤接收到的嘟文。若未提供，你将接收此账户所有语言的嘟文。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
成功关注，或账户已被关注。
|
||
|
||
```json
|
||
{
|
||
"id": "3",
|
||
"following": true,
|
||
"showing_reblogs": false,
|
||
"notifying": false,
|
||
"followed_by": false,
|
||
"blocking": false,
|
||
"blocked_by": false,
|
||
"muting": false,
|
||
"muting_notifications": false,
|
||
"requested": false,
|
||
"domain_blocking": false,
|
||
"endorsed": false
|
||
}
|
||
```
|
||
|
||
##### 403: Forbidden
|
||
|
||
试图关注你屏蔽的或屏蔽你的用户。
|
||
|
||
```json
|
||
{
|
||
"error": "This action is not allowed"
|
||
}
|
||
```
|
||
|
||
##### 422: Unprocessable entity
|
||
|
||
令牌没有授权用户。
|
||
|
||
```json
|
||
{
|
||
"error": "This method requires an authenticated user"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 取消关注账户 {#unfollow}
|
||
|
||
```http
|
||
POST /api/v1/accounts/:id/unfollow HTTP/1.1
|
||
```
|
||
|
||
取消关注指定账户。
|
||
|
||
**返回：** [Relationship]({{< relref "entities/relationship">}})
|
||
**OAuth：** 用户令牌 + `write:follows`
|
||
**版本历史：**
|
||
0.0.0 - 添加
|
||
3.5.0 - 弃用 `follow` 作用域。现在额外接受 `write`
|
||
|
||
#### 请求
|
||
##### 路径参数
|
||
|
||
:id
|
||
: {{<required>}} 字符串。数据库中账户的 ID。
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: {{<required>}} 提供此标头并附带 `Bearer <用户令牌>` 以获得对此 API 方法的访问授权。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
成功取消关注，或账户本未被关注。
|
||
|
||
```json
|
||
{
|
||
"id": "3",
|
||
"following": false,
|
||
"showing_reblogs": false,
|
||
"notifying": false,
|
||
"followed_by": false,
|
||
"blocking": false,
|
||
"blocked_by": false,
|
||
"muting": false,
|
||
"muting_notifications": false,
|
||
"requested": false,
|
||
"domain_blocking": false,
|
||
"endorsed": false
|
||
}
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
`Authorization` 标头无效或缺失
|
||
|
||
```json
|
||
{
|
||
"error": "The access token is invalid"
|
||
}
|
||
```
|
||
|
||
##### 422: Unprocessable entity
|
||
|
||
令牌没有已授权的用户
|
||
|
||
```json
|
||
{
|
||
"error": "This method requires an authenticated user"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 屏蔽账户 {#block}
|
||
|
||
```http
|
||
POST /api/v1/accounts/:id/block HTTP/1.1
|
||
```
|
||
|
||
屏蔽指定的账户。客户端应过滤来自此账户的嘟文（例如，由于主页时间线上的转嘟而收到的嘟文）。
|
||
|
||
**返回：** [Relationship]({{< relref "entities/relationship">}})\
|
||
**OAuth：** 用户令牌 + `write:blocks`\
|
||
**版本历史：**\
|
||
0.0.0 - 添加\
|
||
3.5.0 - 弃用了 `follow` 作用域。现在额外接受 `write`
|
||
|
||
#### 请求
|
||
##### 路径参数
|
||
|
||
:id
|
||
: {{<required>}} 字符串。账户在数据库中的 ID。
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: {{<required>}} 提供此标头，格式为 `Bearer <user_token>`，以获取对此 API 方法的访问授权。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
成功屏蔽，或账户已被屏蔽
|
||
|
||
```json
|
||
{
|
||
"id": "3",
|
||
"following": false,
|
||
"showing_reblogs": false,
|
||
"notifying": false,
|
||
"followed_by": false,
|
||
"blocking": true,
|
||
"blocked_by": false,
|
||
"muting": false,
|
||
"muting_notifications": false,
|
||
"requested": false,
|
||
"domain_blocking": false,
|
||
"endorsed": false
|
||
}
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
`Authorization` 标头无效或缺失
|
||
|
||
```json
|
||
{
|
||
"error": "The access token is invalid"
|
||
}
|
||
```
|
||
|
||
##### 422: Unprocessable entity
|
||
|
||
令牌没有已授权的用户
|
||
|
||
```json
|
||
{
|
||
"error": "This method requires an authenticated user"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 解除屏蔽账户 {#unblock}
|
||
|
||
```http
|
||
POST /api/v1/accounts/:id/unblock HTTP/1.1
|
||
```
|
||
|
||
解除对指定账户的屏蔽。
|
||
|
||
**返回：** [Relationship]({{< relref "entities/relationship">}})\
|
||
**OAuth：** 用户令牌 + `write:blocks`\
|
||
**版本历史：**\
|
||
0.0.0 - 添加\
|
||
3.5.0 - 弃用了 `follow` 作用域。现在额外接受 `write`
|
||
|
||
#### 请求
|
||
##### 路径参数
|
||
|
||
:id
|
||
: {{<required>}} 字符串。账户在数据库中的 ID。
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: {{<required>}} 提供此标头，格式为 `Bearer <user_token>`，以获取对此 API 方法的访问授权。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
成功解除屏蔽，或账户本就未被屏蔽
|
||
|
||
```json
|
||
{
|
||
"id": "3",
|
||
"following": false,
|
||
"showing_reblogs": false,
|
||
"notifying": false,
|
||
"followed_by": false,
|
||
"blocking": false,
|
||
"blocked_by": false,
|
||
"muting": false,
|
||
"muting_notifications": false,
|
||
"requested": false,
|
||
"domain_blocking": false,
|
||
"endorsed": false
|
||
}
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
`Authorization` 标头无效或缺失
|
||
|
||
```json
|
||
{
|
||
"error": "The access token is invalid"
|
||
}
|
||
```
|
||
|
||
##### 422: Unprocessable entity
|
||
|
||
令牌没有已授权的用户
|
||
|
||
```json
|
||
{
|
||
"error": "This method requires an authenticated user"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 隐藏账户 {#mute}
|
||
|
||
```http
|
||
POST /api/v1/accounts/:id/mute HTTP/1.1
|
||
```
|
||
|
||
隐藏指定的账户。客户端应过滤来自此账户的嘟文和通知（例如，由于主页时间线上的转嘟而收到的嘟文）。
|
||
|
||
**返回：** [Relationship]({{< relref "entities/relationship">}})\
|
||
**OAuth：** 用户令牌 + `write:mutes`\
|
||
**版本历史：**\
|
||
0.0.0 - 添加\
|
||
3.3.0 - 添加了 `duration`\
|
||
3.5.0 - 弃用了 `follow` 作用域。现在额外接受 `write`
|
||
|
||
#### 请求
|
||
##### 路径参数
|
||
|
||
:id
|
||
: {{<required>}} 字符串。账户在数据库中的 ID。
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: {{<required>}} 提供此标头，格式为 `Bearer <user_token>`，以获取对此 API 方法的访问授权。
|
||
|
||
##### 表单数据参数
|
||
|
||
notifications
|
||
: 布尔值。除了嘟文之外是否也隐藏通知？默认为 true。
|
||
|
||
duration
|
||
: 数字。隐藏应持续多长时间（秒）。默认为 0（无限期）。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
成功隐藏，或账户已被隐藏。请注意，你可以再次调用此 API 方法并设置 `notifications=false` 来更新关系，以便仅隐藏嘟文。
|
||
|
||
```json
|
||
{
|
||
"id": "3",
|
||
"following": false,
|
||
"showing_reblogs": false,
|
||
"notifying": false,
|
||
"followed_by": false,
|
||
"blocking": false,
|
||
"blocked_by": false,
|
||
"muting": true,
|
||
"muting_notifications": true,
|
||
"requested": false,
|
||
"domain_blocking": false,
|
||
"endorsed": false
|
||
}
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
`Authorization` 标头无效或缺失
|
||
|
||
```json
|
||
{
|
||
"error": "访问令牌无效"
|
||
}
|
||
```
|
||
|
||
##### 422: Unprocessable entity
|
||
|
||
令牌没有已授权的用户
|
||
|
||
```json
|
||
{
|
||
"error": "此方法需要已认证的用户"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 解除隐藏账户 {#unmute}
|
||
|
||
```http
|
||
POST /api/v1/accounts/:id/unmute HTTP/1.1
|
||
```
|
||
|
||
解除对指定账户的隐藏。
|
||
|
||
**返回：** [Relationship]({{< relref "entities/relationship">}})\
|
||
**OAuth：** 用户令牌 + `write:mutes`\
|
||
**版本历史：**\
|
||
0.0.0 - 添加\
|
||
3.5.0 - 弃用了 `follow` 作用域。现在额外接受 `write`
|
||
|
||
#### 请求
|
||
##### 路径参数
|
||
|
||
:id
|
||
: {{<required>}} 字符串。账户在数据库中的 ID。
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: {{<required>}} 提供此标头，格式为 `Bearer <user_token>`，以获取对此 API 方法的访问授权。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
成功解除隐藏，或账户本就未被隐藏
|
||
|
||
```json
|
||
{
|
||
"id": "3",
|
||
"following": false,
|
||
"showing_reblogs": false,
|
||
"notifying": false,
|
||
"followed_by": false,
|
||
"blocking": false,
|
||
"blocked_by": false,
|
||
"muting": false,
|
||
"muting_notifications": false,
|
||
"requested": false,
|
||
"domain_blocking": false,
|
||
"endorsed": false
|
||
}
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
`Authorization` 标头无效或缺失
|
||
|
||
```json
|
||
{
|
||
"error": "访问令牌无效"
|
||
}
|
||
```
|
||
|
||
##### 422: Unprocessable entity
|
||
|
||
令牌没有已授权的用户
|
||
|
||
```json
|
||
{
|
||
"error": "此方法需要已认证的用户"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 在你的账户页中推荐账户 {#pin}
|
||
|
||
```http
|
||
POST /api/v1/accounts/:id/pin HTTP/1.1
|
||
```
|
||
|
||
将指定账户添加到用户的推荐账户中。（推荐的账户目前显示在用户自己的账户页上公开显示。）
|
||
|
||
**返回：** [Relationship]({{< relref "entities/relationship">}})\
|
||
**OAuth：** 用户令牌 + `write:accounts`\
|
||
**版本历史：**\
|
||
2.5.0 - 添加\
|
||
4.0.0 - 调用此方法现在是幂等的
|
||
|
||
#### 请求
|
||
##### 路径参数
|
||
|
||
:id
|
||
: {{<required>}} 字符串。账户在数据库中的 ID。
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: {{<required>}} 提供此标头，格式为 `Bearer <user_token>`，以获取对此 API 方法的访问授权。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
成功推荐，或目标账户已被推荐。
|
||
|
||
```json
|
||
{
|
||
"id": "1",
|
||
"following": true,
|
||
"showing_reblogs": true,
|
||
"notifying": false,
|
||
"followed_by": true,
|
||
"blocking": false,
|
||
"blocked_by": false,
|
||
"muting": false,
|
||
"muting_notifications": false,
|
||
"requested": false,
|
||
"domain_blocking": false,
|
||
"endorsed": true
|
||
}
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
`Authorization` 标头无效或缺失
|
||
|
||
```json
|
||
{
|
||
"error": "The access token is invalid"
|
||
}
|
||
```
|
||
|
||
##### 403: 禁止访问
|
||
|
||
令牌缺少必要的范围
|
||
|
||
```json
|
||
{
|
||
"error": "This operation exceeds the authorization scope"
|
||
}
|
||
```
|
||
|
||
##### 422: Unprocessable entity
|
||
|
||
你没有关注此账户
|
||
|
||
```json
|
||
{
|
||
"error": "Validation failed: You must be already following the person you want to endorse"
|
||
}
|
||
```
|
||
|
||
或者，令牌未获得用户授权
|
||
|
||
```json
|
||
{
|
||
"error": "This method requires an authenticated user"
|
||
}
|
||
```
|
||
|
||
或者（4.0 版本之前），该账户可能已被推荐
|
||
|
||
```json
|
||
{
|
||
"error": "Duplicate record"
|
||
}
|
||
```
|
||
|
||
##### 500: 服务器错误
|
||
|
||
有时在账户已被推荐时会返回此错误。
|
||
|
||
---
|
||
|
||
## 在账户页中取消推荐账户 {#unpin}
|
||
|
||
```http
|
||
POST /api/v1/accounts/:id/unpin HTTP/1.1
|
||
```
|
||
|
||
将指定账户从用户的推荐账户中移除。
|
||
|
||
**返回：** [Relationship]({{< relref "entities/relationship">}})\
|
||
**OAuth：** 用户 + `write:accounts`\
|
||
**版本历史：**\
|
||
2.5.0 - 添加
|
||
|
||
#### 请求
|
||
##### 路径参数
|
||
|
||
:id
|
||
: {{<required>}} 字符串。账户在数据库中的 ID。
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: {{<required>}} 提供此标头，格式为 `Bearer <user_token>`，以获取对此 API 方法的访问授权。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
成功取消推荐，或账户本就未被推荐
|
||
|
||
```json
|
||
{
|
||
"id": "1",
|
||
"following": true,
|
||
"showing_reblogs": true,
|
||
"notifying": false,
|
||
"followed_by": true,
|
||
"blocking": false,
|
||
"blocked_by": false,
|
||
"muting": false,
|
||
"muting_notifications": false,
|
||
"requested": false,
|
||
"domain_blocking": false,
|
||
"endorsed": false
|
||
}
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
`Authorization` 标头无效或缺失
|
||
|
||
```json
|
||
{
|
||
"error": "The access token is invalid"
|
||
}
|
||
```
|
||
|
||
##### 422: Unprocessable entity
|
||
|
||
令牌没有已授权的用户
|
||
|
||
```json
|
||
{
|
||
"error": "This method requires an authenticated user"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 对指定账户设置私人备注 {#note}
|
||
|
||
```http
|
||
POST /api/v1/accounts/:id/note HTTP/1.1
|
||
```
|
||
|
||
对指定账户设置私人备注。
|
||
|
||
**返回：** [Relationship]({{< relref "entities/relationship">}})\
|
||
**OAuth：** 用户 + `write:accounts`\
|
||
**版本历史：**\
|
||
3.2.0 - 添加
|
||
|
||
#### 请求
|
||
##### 路径参数
|
||
|
||
:id
|
||
: {{<required>}} 字符串。账户在数据库中的 ID。
|
||
|
||
##### 标头
|
||
|
||
Authorization
|
||
: {{<required>}} 提供此标头，格式为 `Bearer <user_token>`，以获取对此 API 方法的访问授权。
|
||
|
||
##### 表单数据参数
|
||
|
||
comment
|
||
: 字符串。要对该账户设置的备注。提供空字符串或省略此参数以清除当前设置的备注。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
成功更新账户备注
|
||
|
||
```json
|
||
{
|
||
"id": "1",
|
||
"following": true,
|
||
"showing_reblogs": true,
|
||
"notifying": false,
|
||
"followed_by": true,
|
||
"blocking": false,
|
||
"blocked_by": false,
|
||
"muting": false,
|
||
"muting_notifications": false,
|
||
"requested": false,
|
||
"domain_blocking": false,
|
||
"endorsed": false,
|
||
"note": "这是一条备注"
|
||
}
|
||
```
|
||
|
||
成功移除账户备注
|
||
|
||
```json
|
||
{
|
||
"id": "1",
|
||
"following": true,
|
||
"showing_reblogs": true,
|
||
"notifying": false,
|
||
"followed_by": true,
|
||
"blocking": false,
|
||
"blocked_by": false,
|
||
"muting": false,
|
||
"muting_notifications": false,
|
||
"requested": false,
|
||
"domain_blocking": false,
|
||
"endorsed": false,
|
||
"note": ""
|
||
}
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
`Authorization` 标头无效或缺失
|
||
|
||
```json
|
||
{
|
||
"error": "The access token is invalid"
|
||
}
|
||
```
|
||
|
||
##### 422: Unprocessable entity
|
||
|
||
令牌没有已授权的用户
|
||
|
||
```json
|
||
{
|
||
"error": "This method requires an authenticated user"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 检查与其他账户的关系 {#relationships}
|
||
|
||
```http
|
||
GET /api/v1/accounts/relationships HTTP/1.1
|
||
```
|
||
|
||
查明是否关注、屏蔽、隐藏了指定账户等。
|
||
|
||
**返回：** [Relationship]({{< relref "entities/Relationship">}}) 数组\
|
||
**OAuth：** 用户令牌 + `read:follows`\
|
||
**版本历史：**\
|
||
0.0.0 - 添加\
|
||
4.3.0 - 添加了 `with_suspended` 参数
|
||
|
||
#### 请求
|
||
##### 标头
|
||
|
||
Authorization
|
||
: {{<required>}} 提供此标头，格式为 `Bearer <user_token>`，以获取对此 API 方法的访问授权。
|
||
|
||
##### 查询参数
|
||
|
||
id[]
|
||
: 字符串数组。检查与所提供的所有账户 ID 的关系。
|
||
|
||
with_suspended
|
||
: 布尔值。是否应返回已封禁用户的关系，默认为 false。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
使用 `id[]=1&id[]=2` 的示例调用
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": "1",
|
||
"following": true,
|
||
"showing_reblogs": true,
|
||
"notifying": false,
|
||
"followed_by": true,
|
||
"blocking": false,
|
||
"blocked_by": false,
|
||
"muting": false,
|
||
"muting_notifications": false,
|
||
"requested": false,
|
||
"domain_blocking": false,
|
||
"endorsed": false
|
||
},
|
||
{
|
||
"id": "2",
|
||
"following": false,
|
||
"showing_reblogs": false,
|
||
"notifying": false,
|
||
"followed_by": false,
|
||
"blocking": false,
|
||
"blocked_by": false,
|
||
"muting": false,
|
||
"muting_notifications": false,
|
||
"requested": false,
|
||
"domain_blocking": false,
|
||
"endorsed": false
|
||
}
|
||
]
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
`Authorization` 标头无效或缺失
|
||
|
||
```json
|
||
{
|
||
"error": "The access token is invalid"
|
||
}
|
||
```
|
||
|
||
##### 422: Unprocessable entity
|
||
|
||
令牌没有已授权的用户
|
||
|
||
```json
|
||
{
|
||
"error": "This method requires an authenticated user"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 查找熟悉的关注者 {#familiar_followers}
|
||
|
||
```http
|
||
GET /api/v1/accounts/familiar_followers HTTP/1.1
|
||
```
|
||
|
||
获取关注指定账户的所有账户列表，并从中筛选出你关注的账户。
|
||
|
||
**返回：** [FamiliarFollowers]({{< relref "entities/FamiliarFollowers">}}) 数组\
|
||
**OAuth：** 用户令牌 + `read:follows`\
|
||
**版本历史：**\
|
||
3.5.0 - 添加
|
||
|
||
#### 请求
|
||
##### 标头
|
||
|
||
Authorization
|
||
: {{<required>}} 提供此标头，格式为 `Bearer <user_token>`，以获取对此 API 方法的访问授权。
|
||
|
||
##### 查询参数
|
||
|
||
id[]
|
||
: 字符串数组。查找所提供账户 ID 的熟悉关注者。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
使用 `id[]=1&id[]=2` 的示例调用
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id":"1",
|
||
"accounts":[
|
||
{
|
||
"id":"1087990",
|
||
"username":"moss",
|
||
"acct":"moss@goblin.camp",
|
||
// ...
|
||
},
|
||
{
|
||
"id":"1092723",
|
||
"username":"vivianrose",
|
||
"acct":"vivianrose",
|
||
// ...
|
||
},
|
||
// ...
|
||
]
|
||
},
|
||
{
|
||
"id":"2",
|
||
"accounts":[]
|
||
}
|
||
]
|
||
```
|
||
|
||
##### 401: Unauthorized
|
||
|
||
`Authorization` 标头无效或缺失
|
||
|
||
```json
|
||
{
|
||
"error": "The access token is invalid"
|
||
}
|
||
```
|
||
|
||
##### 422: Unprocessable entity
|
||
|
||
令牌没有已授权的用户
|
||
|
||
```json
|
||
{
|
||
"error": "This method requires an authenticated user"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 搜索匹配的账户 {#search}
|
||
|
||
```http
|
||
GET /api/v1/accounts/search HTTP/1.1
|
||
```
|
||
|
||
通过用户名或昵称搜索匹配的账户。
|
||
|
||
**返回：** [A此count]({{< relref "entities/Account">}}) 数组
|
||
**OAuth 认证：** 用户令牌 + `read:accounts` 权限
|
||
**版本历史：**
|
||
0.0.0 - 添加
|
||
2.8.0 - 添加 `limit`、`offset` 和 `following`
|
||
|
||
#### 请求
|
||
##### 请求头
|
||
|
||
Authorization
|
||
: {{<required>}} （必填）提供此请求头，格式为 `Bearer <user_token>`，以获得对该 API 方法的授权访问权限。
|
||
|
||
##### 查询参数
|
||
|
||
q
|
||
: {{<required>}} （必填）字符串。账户的搜索查询。
|
||
|
||
limit
|
||
: 整数。最大结果数。默认为 40 个账户。最多 80 个账户。
|
||
|
||
offset
|
||
: 整数。跳过前 n 个结果。
|
||
|
||
resolve
|
||
: 布尔值。尝试 WebFinger 查询。默认为 false。当 `q` 是精确地址时使用此参数。
|
||
|
||
following
|
||
: 布尔值。将搜索范围限制为你关注的用户。默认为 false。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
匹配用户名或昵称中包含 "trwnh" 的账户
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": "14715",
|
||
"username": "trwnh",
|
||
"acct": "trwnh",
|
||
"display_name": "infinite love ⴳ",
|
||
// ...
|
||
},
|
||
{
|
||
"id": "418714",
|
||
"username": "trwnh",
|
||
"acct": "trwnh@pixelfed.social",
|
||
"display_name": "Abdullah Tarawneh",
|
||
// ...
|
||
},
|
||
{
|
||
"id": "419674",
|
||
"username": "trwnh",
|
||
"acct": "trwnh@write.as",
|
||
"display_name": "trwnh",
|
||
// ...
|
||
},
|
||
// ...
|
||
]
|
||
```
|
||
|
||
##### 503: Service Unavailable
|
||
|
||
当 `resolve=true` 时，若 user@domain 地址中的域名部分当前不是一个有效的网站，则返回该响应
|
||
|
||
```json
|
||
{
|
||
"error": "Remote data could not be fetched"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 通过 Webfinger 地址查询账户 ID {#lookup}
|
||
|
||
```http
|
||
GET /api/v1/accounts/lookup HTTP/1.1
|
||
```
|
||
|
||
快速查询用户名以查看其是否可用，跳过 WebFinger 解析。
|
||
|
||
**返回：** [Account]({{< relref "entities/Account">}})
|
||
**OAuth 认证：** 公开
|
||
**版本历史：**
|
||
3.4.0 - 添加
|
||
|
||
#### 请求
|
||
##### 查询参数
|
||
|
||
acct
|
||
: {{<required>}} （必填）字符串。要查询的用户名或 Webfinger 地址。
|
||
|
||
#### 响应
|
||
##### 200: OK
|
||
|
||
使用 `?acct=trwnh` 的示例调用响应如下:
|
||
|
||
```json
|
||
{
|
||
"id": "14715",
|
||
"username": "trwnh",
|
||
"acct": "trwnh",
|
||
"display_name": "infinite love ⴳ",
|
||
"locked": false,
|
||
// ...
|
||
}
|
||
```
|
||
|
||
使用 `?acct=trwnh@pixelfed.social` 的示例调用响应如下:
|
||
|
||
```json
|
||
{
|
||
"id": "418714",
|
||
"username": "trwnh",
|
||
"acct": "trwnh@pixelfed.social",
|
||
"display_name": "Abdullah Tarawneh",
|
||
"locked": false,
|
||
// ...
|
||
}
|
||
```
|
||
|
||
##### 404: Not found
|
||
|
||
用户名或地址未映射到任何账户
|
||
|
||
```json
|
||
{
|
||
"error": "记录未找到"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 身份证明 {{%deprecated%}} {#identity_proofs}
|
||
|
||
```http
|
||
GET /api/v1/accounts/:id/identity_proofs HTTP/1.1
|
||
```
|
||
|
||
**返回：** [IdentityProof]({{< relref "entities/identityproof">}}) 数组
|
||
**OAuth 认证：** 用户令牌
|
||
**版本历史：**
|
||
2.8.0 - 添加
|
||
3.5.0 - 弃用。现在返回一个空数组。
|
||
|
||
#### 请求
|
||
|
||
##### 路径参数
|
||
|
||
:id
|
||
: {{<required>}} （必填）字符串。数据库中账户的 ID。
|
||
|
||
#### 响应
|
||
##### 200: OK (成功)
|
||
|
||
```json
|
||
[
|
||
{
|
||
"provider": "Keybase",
|
||
"provider_username": "gargron",
|
||
"updated_at": "2019-07-21T20:14:39.596Z",
|
||
"proof_url": "https://keybase.io/gargron/sigchain#5cfc20c7018f2beefb42a68836da59a792e55daa4d118498c9b1898de7e845690f",
|
||
"profile_url": "https://keybase.io/gargron"
|
||
}
|
||
]
|
||
```
|
||
|
||
##### 404: Not Found
|
||
|
||
账户不存在
|
||
|
||
```json
|
||
{
|
||
"error": "Record not found"
|
||
}
|
||
```
|
||
|
||
##### 410: Gone
|
||
|
||
账户已被暂停（自 2.4.0 版本起，至 3.3.0 版本）
|
||
|
||
##### 422: Unprocessable Entity
|
||
|
||
令牌没有对应的授权用户
|
||
|
||
```json
|
||
{
|
||
"error": "This method requires an authenticated user"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 另请参阅
|
||
|
||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts_controller.rb" caption="app/controllers/api/v1/accounts_controller.rb" >}}
|
||
|
||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/credentials_controller.rb" caption="app/controllers/api/v1/accounts/credentials_controller.rb" >}}
|
||
|
||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/familiar_followers_controller.rb" caption="app/controllers/api/v1/accounts/familiar_followers_controller.rb" >}}
|
||
|
||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/featured_tags_controller.rb" caption="app/controllers/api/v1/accounts/featured_tags_controller.rb" >}}
|
||
|
||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/follower_accounts_controller.rb" caption="app/controllers/api/v1/accounts/follower_accounts_controller.rb" >}}
|
||
|
||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/following_accounts_controller.rb" caption="app/controllers/api/v1/accounts/following_accounts_controller.rb" >}}
|
||
|
||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/identity_proofs_controller.rb" caption="app/controllers/api/v1/accounts/identity_proofs_controller.rb" >}}
|
||
|
||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/lists_controller.rb" caption="app/controllers/api/v1/accounts/lists_controller.rb" >}}
|
||
|
||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/lookup_controller.rb" caption="app/controllers/api/v1/accounts/lookup_controller.rb" >}}
|
||
|
||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/notes_controller.rb" caption="app/controllers/api/v1/accounts/notes_controller.rb" >}}
|
||
|
||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/pins_controller.rb" caption="app/controllers/api/v1/accounts/pins_controller.rb" >}}
|
||
|
||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/relationships_controller.rb" caption="app/controllers/api/v1/accounts/relationships_controller.rb" >}}
|
||
|
||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/search_controller.rb" caption="app/controllers/api/v1/accounts/search_controller.rb" >}}
|
||
|
||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/statuses_controller.rb" caption="app/controllers/api/v1/accounts/statuses_controller.rb" >}}
|
||
|
||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/account_statuses_filter.rb" caption="app/models/account_statuses_filter.rb" >}}
|
||
|
||
{{< translation-status-zh-cn raw_title="accounts API methods" raw_link="/methods/accounts/" last_translation_time="2025-04-21" raw_commit="6addd5cf525adec1859f48c52dafcfe1f96e558a">}}
|