From a939c23559d33effb90f40da065bdb3383a66e41 Mon Sep 17 00:00:00 2001 From: cdn0x12 Date: Sun, 6 Apr 2025 03:29:30 +0800 Subject: [PATCH] Update zh-cn translations --- content/zh-cn/_index.md | 102 +- content/zh-cn/admin/backups.md | 38 +- content/zh-cn/admin/config.md | 1349 ++++++++-- content/zh-cn/admin/elasticsearch.md | 250 ++ content/zh-cn/admin/install.md | 232 +- content/zh-cn/admin/migrating.md | 133 +- content/zh-cn/admin/moderation.md | 314 ++- content/zh-cn/admin/optional.md | 10 +- content/zh-cn/admin/optional/captcha.md | 34 + content/zh-cn/admin/optional/elasticsearch.md | 164 -- .../admin/optional/object-storage-proxy.md | 129 + .../zh-cn/admin/optional/object-storage.md | 320 +++ content/zh-cn/admin/optional/sso.md | 10 +- content/zh-cn/admin/optional/tor.md | 62 +- content/zh-cn/admin/prerequisites.md | 106 +- content/zh-cn/admin/roles.md | 100 + content/zh-cn/admin/scaling.md | 373 ++- content/zh-cn/admin/setup.md | 36 +- content/zh-cn/admin/tootctl.md | 995 +++++-- content/zh-cn/admin/troubleshooting.md | 48 +- .../admin/troubleshooting/index-corruption.md | 111 + content/zh-cn/admin/upgrading.md | 40 +- content/zh-cn/api/datetime-format.md | 64 + content/zh-cn/api/guidelines.md | 162 ++ content/zh-cn/api/oauth-scopes.md | 171 ++ content/zh-cn/api/oauth-tokens.md | 29 + content/zh-cn/api/rate-limits.md | 51 + content/zh-cn/client/authorized.md | 144 + content/zh-cn/client/intro.md | 139 + content/zh-cn/client/libraries.md | 160 ++ content/zh-cn/client/public.md | 116 + content/zh-cn/client/token.md | 89 + content/zh-cn/dev/code.md | 75 + content/zh-cn/dev/disclosure.md | 18 + content/zh-cn/dev/overview.md | 34 + content/zh-cn/dev/routes.md | 208 ++ content/zh-cn/dev/setup.md | 115 + content/zh-cn/entities/Account.md | 460 ++++ content/zh-cn/entities/AccountWarning.md | 71 + content/zh-cn/entities/Admin_Account.md | 215 ++ .../entities/Admin_CanonicalEmailBlock.md | 50 + content/zh-cn/entities/Admin_Cohort.md | 137 + content/zh-cn/entities/Admin_Dimension.md | 308 +++ content/zh-cn/entities/Admin_DomainAllow.md | 58 + content/zh-cn/entities/Admin_DomainBlock.md | 117 + .../zh-cn/entities/Admin_EmailDomainBlock.md | 123 + content/zh-cn/entities/Admin_Ip.md | 50 + content/zh-cn/entities/Admin_IpBlock.md | 85 + content/zh-cn/entities/Admin_Measure.md | 789 ++++++ content/zh-cn/entities/Admin_Report.md | 175 ++ content/zh-cn/entities/Announcement.md | 214 ++ content/zh-cn/entities/Appeal.md | 32 + content/zh-cn/entities/Application.md | 115 + content/zh-cn/entities/Context.md | 72 + content/zh-cn/entities/Conversation.md | 75 + content/zh-cn/entities/CustomEmoji.md | 78 + content/zh-cn/entities/DomainBlock.md | 64 + content/zh-cn/entities/EncryptedMessage.md | 91 + content/zh-cn/entities/Error.md | 122 + content/zh-cn/entities/ExtendedDescription.md | 46 + content/zh-cn/entities/FamiliarFollowers.md | 66 + content/zh-cn/entities/FeaturedTag.md | 70 + content/zh-cn/entities/Filter.md | 112 + content/zh-cn/entities/FilterKeyword.md | 56 + content/zh-cn/entities/FilterResult.md | 68 + content/zh-cn/entities/FilterStatus.md | 48 + content/zh-cn/entities/IdentityProof.md | 72 + content/zh-cn/entities/Instance.md | 594 +++++ content/zh-cn/entities/List.md | 58 + content/zh-cn/entities/Marker.md | 52 + content/zh-cn/entities/MediaAttachment.md | 242 ++ content/zh-cn/entities/Notification.md | 158 ++ content/zh-cn/entities/NotificationPolicy.md | 94 + content/zh-cn/entities/NotificationRequest.md | 106 + content/zh-cn/entities/Poll.md | 139 + content/zh-cn/entities/Preferences.md | 77 + content/zh-cn/entities/PreviewCard.md | 294 ++ content/zh-cn/entities/PreviewCardAuthor.md | 41 + content/zh-cn/entities/PrivacyPolicy.md | 46 + content/zh-cn/entities/Reaction.md | 83 + content/zh-cn/entities/Relationship.md | 149 ++ .../entities/RelationshipSeveranceEvent.md | 67 + content/zh-cn/entities/Report.md | 139 + content/zh-cn/entities/Role.md | 132 + content/zh-cn/entities/Rule.md | 56 + content/zh-cn/entities/ScheduledStatus.md | 219 ++ content/zh-cn/entities/Search.md | 120 + content/zh-cn/entities/Status.md | 397 +++ content/zh-cn/entities/StatusEdit.md | 146 + content/zh-cn/entities/StatusSource.md | 54 + content/zh-cn/entities/Suggestion.md | 71 + content/zh-cn/entities/Tag.md | 199 ++ content/zh-cn/entities/Token.md | 66 + content/zh-cn/entities/Translation.md | 147 + content/zh-cn/entities/V1_Filter.md | 91 + content/zh-cn/entities/V1_Instance.md | 421 +++ .../zh-cn/entities/V1_NotificationPolicy.md | 92 + content/zh-cn/entities/WebPushSubscription.md | 155 ++ content/zh-cn/methods/accounts.md | 2365 +++++++++++++++++ content/zh-cn/methods/admin/_index.md | 12 + content/zh-cn/methods/admin/accounts.md | 1037 ++++++++ .../methods/admin/canonical_email_blocks.md | 315 +++ content/zh-cn/methods/admin/dimensions.md | 260 ++ content/zh-cn/methods/admin/domain_allows.md | 272 ++ content/zh-cn/methods/admin/domain_blocks.md | 406 +++ .../methods/admin/email_domain_blocks.md | 377 +++ content/zh-cn/methods/admin/ip_blocks.md | 352 +++ content/zh-cn/methods/admin/measures.md | 300 +++ content/zh-cn/methods/admin/reports.md | 552 ++++ content/zh-cn/methods/admin/retention.md | 175 ++ content/zh-cn/methods/admin/trends.md | 263 ++ content/zh-cn/methods/announcements.md | 294 ++ content/zh-cn/methods/apps.md | 196 ++ content/zh-cn/methods/blocks.md | 104 + content/zh-cn/methods/bookmarks.md | 110 + content/zh-cn/methods/conversations.md | 247 ++ content/zh-cn/methods/custom_emojis.md | 89 + content/zh-cn/methods/directory.md | 80 + content/zh-cn/methods/domain_blocks.md | 215 ++ content/zh-cn/methods/emails.md | 80 + content/zh-cn/methods/endorsements.md | 138 + content/zh-cn/methods/favourites.md | 143 + content/zh-cn/methods/featured_tags.md | 314 +++ content/zh-cn/methods/filters.md | 1415 ++++++++++ content/zh-cn/methods/follow_requests.md | 230 ++ content/zh-cn/methods/followed_tags.md | 134 + .../zh-cn/methods/grouped_notifications.md | 672 +++++ content/zh-cn/methods/instance.md | 772 ++++++ content/zh-cn/methods/lists.md | 593 +++++ content/zh-cn/methods/markers.md | 151 ++ content/zh-cn/methods/media.md | 522 ++++ content/zh-cn/methods/mutes.md | 102 + content/zh-cn/methods/notifications.md | 997 +++++++ content/zh-cn/methods/notifications_alpha.md | 635 +++++ content/zh-cn/methods/oauth.md | 346 +++ content/zh-cn/methods/oembed.md | 80 + content/zh-cn/methods/polls.md | 233 ++ content/zh-cn/methods/preferences.md | 71 + content/zh-cn/methods/profile.md | 180 ++ content/zh-cn/methods/proofs.md | 79 + content/zh-cn/methods/push.md | 346 +++ content/zh-cn/methods/reports.md | 158 ++ content/zh-cn/methods/scheduled_statuses.md | 298 +++ content/zh-cn/methods/search.md | 236 ++ content/zh-cn/methods/statuses.md | 2006 ++++++++++++++ content/zh-cn/methods/streaming.md | 733 +++++ content/zh-cn/methods/suggestions.md | 201 ++ content/zh-cn/methods/tags.md | 286 ++ content/zh-cn/methods/timelines.md | 508 ++++ content/zh-cn/methods/trends.md | 229 ++ content/zh-cn/spec/activitypub.md | 898 +++++++ content/zh-cn/spec/bearcaps.md | 31 + content/zh-cn/spec/microformats.md | 103 + content/zh-cn/spec/oauth.md | 90 + content/zh-cn/spec/security.md | 170 ++ content/zh-cn/spec/webfinger.md | 111 + content/zh-cn/user/contacts.md | 42 +- content/zh-cn/user/discoverability.md | 32 +- content/zh-cn/user/external.md | 18 +- content/zh-cn/user/moderating.md | 110 +- content/zh-cn/user/moving.md | 40 +- content/zh-cn/user/network.md | 114 +- content/zh-cn/user/posting.md | 141 +- content/zh-cn/user/preferences.md | 76 +- content/zh-cn/user/profile.md | 94 +- content/zh-cn/user/run-your-own.md | 55 +- content/zh-cn/user/signup.md | 50 +- .../shortcodes/translation-status-zh-cn.html | 2 +- 168 files changed, 36955 insertions(+), 1406 deletions(-) create mode 100644 content/zh-cn/admin/elasticsearch.md create mode 100644 content/zh-cn/admin/optional/captcha.md delete mode 100644 content/zh-cn/admin/optional/elasticsearch.md create mode 100644 content/zh-cn/admin/optional/object-storage-proxy.md create mode 100644 content/zh-cn/admin/optional/object-storage.md create mode 100644 content/zh-cn/admin/roles.md create mode 100644 content/zh-cn/admin/troubleshooting/index-corruption.md create mode 100644 content/zh-cn/api/datetime-format.md create mode 100644 content/zh-cn/api/guidelines.md create mode 100644 content/zh-cn/api/oauth-scopes.md create mode 100644 content/zh-cn/api/oauth-tokens.md create mode 100644 content/zh-cn/api/rate-limits.md create mode 100644 content/zh-cn/client/authorized.md create mode 100644 content/zh-cn/client/intro.md create mode 100644 content/zh-cn/client/libraries.md create mode 100644 content/zh-cn/client/public.md create mode 100644 content/zh-cn/client/token.md create mode 100644 content/zh-cn/dev/code.md create mode 100644 content/zh-cn/dev/disclosure.md create mode 100644 content/zh-cn/dev/overview.md create mode 100644 content/zh-cn/dev/routes.md create mode 100644 content/zh-cn/dev/setup.md create mode 100644 content/zh-cn/entities/Account.md create mode 100644 content/zh-cn/entities/AccountWarning.md create mode 100644 content/zh-cn/entities/Admin_Account.md create mode 100644 content/zh-cn/entities/Admin_CanonicalEmailBlock.md create mode 100644 content/zh-cn/entities/Admin_Cohort.md create mode 100644 content/zh-cn/entities/Admin_Dimension.md create mode 100644 content/zh-cn/entities/Admin_DomainAllow.md create mode 100644 content/zh-cn/entities/Admin_DomainBlock.md create mode 100644 content/zh-cn/entities/Admin_EmailDomainBlock.md create mode 100644 content/zh-cn/entities/Admin_Ip.md create mode 100644 content/zh-cn/entities/Admin_IpBlock.md create mode 100644 content/zh-cn/entities/Admin_Measure.md create mode 100644 content/zh-cn/entities/Admin_Report.md create mode 100644 content/zh-cn/entities/Announcement.md create mode 100644 content/zh-cn/entities/Appeal.md create mode 100644 content/zh-cn/entities/Application.md create mode 100644 content/zh-cn/entities/Context.md create mode 100644 content/zh-cn/entities/Conversation.md create mode 100644 content/zh-cn/entities/CustomEmoji.md create mode 100644 content/zh-cn/entities/DomainBlock.md create mode 100644 content/zh-cn/entities/EncryptedMessage.md create mode 100644 content/zh-cn/entities/Error.md create mode 100644 content/zh-cn/entities/ExtendedDescription.md create mode 100644 content/zh-cn/entities/FamiliarFollowers.md create mode 100644 content/zh-cn/entities/FeaturedTag.md create mode 100644 content/zh-cn/entities/Filter.md create mode 100644 content/zh-cn/entities/FilterKeyword.md create mode 100644 content/zh-cn/entities/FilterResult.md create mode 100644 content/zh-cn/entities/FilterStatus.md create mode 100644 content/zh-cn/entities/IdentityProof.md create mode 100644 content/zh-cn/entities/Instance.md create mode 100644 content/zh-cn/entities/List.md create mode 100644 content/zh-cn/entities/Marker.md create mode 100644 content/zh-cn/entities/MediaAttachment.md create mode 100644 content/zh-cn/entities/Notification.md create mode 100644 content/zh-cn/entities/NotificationPolicy.md create mode 100644 content/zh-cn/entities/NotificationRequest.md create mode 100644 content/zh-cn/entities/Poll.md create mode 100644 content/zh-cn/entities/Preferences.md create mode 100644 content/zh-cn/entities/PreviewCard.md create mode 100644 content/zh-cn/entities/PreviewCardAuthor.md create mode 100644 content/zh-cn/entities/PrivacyPolicy.md create mode 100644 content/zh-cn/entities/Reaction.md create mode 100644 content/zh-cn/entities/Relationship.md create mode 100644 content/zh-cn/entities/RelationshipSeveranceEvent.md create mode 100644 content/zh-cn/entities/Report.md create mode 100644 content/zh-cn/entities/Role.md create mode 100644 content/zh-cn/entities/Rule.md create mode 100644 content/zh-cn/entities/ScheduledStatus.md create mode 100644 content/zh-cn/entities/Search.md create mode 100644 content/zh-cn/entities/Status.md create mode 100644 content/zh-cn/entities/StatusEdit.md create mode 100644 content/zh-cn/entities/StatusSource.md create mode 100644 content/zh-cn/entities/Suggestion.md create mode 100644 content/zh-cn/entities/Tag.md create mode 100644 content/zh-cn/entities/Token.md create mode 100644 content/zh-cn/entities/Translation.md create mode 100644 content/zh-cn/entities/V1_Filter.md create mode 100644 content/zh-cn/entities/V1_Instance.md create mode 100644 content/zh-cn/entities/V1_NotificationPolicy.md create mode 100644 content/zh-cn/entities/WebPushSubscription.md create mode 100644 content/zh-cn/methods/accounts.md create mode 100644 content/zh-cn/methods/admin/_index.md create mode 100644 content/zh-cn/methods/admin/accounts.md create mode 100644 content/zh-cn/methods/admin/canonical_email_blocks.md create mode 100644 content/zh-cn/methods/admin/dimensions.md create mode 100644 content/zh-cn/methods/admin/domain_allows.md create mode 100644 content/zh-cn/methods/admin/domain_blocks.md create mode 100644 content/zh-cn/methods/admin/email_domain_blocks.md create mode 100644 content/zh-cn/methods/admin/ip_blocks.md create mode 100644 content/zh-cn/methods/admin/measures.md create mode 100644 content/zh-cn/methods/admin/reports.md create mode 100644 content/zh-cn/methods/admin/retention.md create mode 100644 content/zh-cn/methods/admin/trends.md create mode 100644 content/zh-cn/methods/announcements.md create mode 100644 content/zh-cn/methods/apps.md create mode 100644 content/zh-cn/methods/blocks.md create mode 100644 content/zh-cn/methods/bookmarks.md create mode 100644 content/zh-cn/methods/conversations.md create mode 100644 content/zh-cn/methods/custom_emojis.md create mode 100644 content/zh-cn/methods/directory.md create mode 100644 content/zh-cn/methods/domain_blocks.md create mode 100644 content/zh-cn/methods/emails.md create mode 100644 content/zh-cn/methods/endorsements.md create mode 100644 content/zh-cn/methods/favourites.md create mode 100644 content/zh-cn/methods/featured_tags.md create mode 100644 content/zh-cn/methods/filters.md create mode 100644 content/zh-cn/methods/follow_requests.md create mode 100644 content/zh-cn/methods/followed_tags.md create mode 100644 content/zh-cn/methods/grouped_notifications.md create mode 100644 content/zh-cn/methods/instance.md create mode 100644 content/zh-cn/methods/lists.md create mode 100644 content/zh-cn/methods/markers.md create mode 100644 content/zh-cn/methods/media.md create mode 100644 content/zh-cn/methods/mutes.md create mode 100644 content/zh-cn/methods/notifications.md create mode 100644 content/zh-cn/methods/notifications_alpha.md create mode 100644 content/zh-cn/methods/oauth.md create mode 100644 content/zh-cn/methods/oembed.md create mode 100644 content/zh-cn/methods/polls.md create mode 100644 content/zh-cn/methods/preferences.md create mode 100644 content/zh-cn/methods/profile.md create mode 100644 content/zh-cn/methods/proofs.md create mode 100644 content/zh-cn/methods/push.md create mode 100644 content/zh-cn/methods/reports.md create mode 100644 content/zh-cn/methods/scheduled_statuses.md create mode 100644 content/zh-cn/methods/search.md create mode 100644 content/zh-cn/methods/statuses.md create mode 100644 content/zh-cn/methods/streaming.md create mode 100644 content/zh-cn/methods/suggestions.md create mode 100644 content/zh-cn/methods/tags.md create mode 100644 content/zh-cn/methods/timelines.md create mode 100644 content/zh-cn/methods/trends.md create mode 100644 content/zh-cn/spec/activitypub.md create mode 100644 content/zh-cn/spec/bearcaps.md create mode 100644 content/zh-cn/spec/microformats.md create mode 100644 content/zh-cn/spec/oauth.md create mode 100644 content/zh-cn/spec/security.md create mode 100644 content/zh-cn/spec/webfinger.md diff --git a/content/zh-cn/_index.md b/content/zh-cn/_index.md index 240441b..0cceb92 100644 --- a/content/zh-cn/_index.md +++ b/content/zh-cn/_index.md @@ -1,106 +1,106 @@ --- -title: 什么是Mastodon？ -description: 欢迎来到Mastodon文档！ +title: 什么是 Mastodon？ +description: 欢迎阅读 Mastodon 文档！ menu: docs: weight: -99 --- -## 什么是微博客？ {#microblogging} +## 什么是微博？{#microblogging} -类似于发布博客是将更新发布到网站上，**发布微博客**是将小的更新发布到你的个人信息流。你可以发布文本，也可以附加图片、音频、视频等媒体，或是发起投票。Mastodon可以让你发现并关注新的朋友们。 +博客（blogging）是在网站上发布更新的行为。与之类似，**微博（microblogging）**则是在你的个人主页信息流中发布简短更新的行为。你可以发布纯文本贴文，也可以选择性地附上图片、音频、视频或投票等媒体。Mastodon 让你可以关注旧朋友并发现新朋友。 -## 什么是联邦？ {#federation} +## 什么是联合？{#federation} -**联邦**是去中心化的一种形式。在联邦中，不是所有人共同使用一个中心服务，而是使用多个不限人数的服务器。 +**联合**是去中心化的一种形式。它并非由单一的中央服务机构提供服务供所有人使用，而是存在多个服务，任何人都可以使用其中的任意一个。 -| 中心化等级 | 示例 | +| 中心化程度 | 示例 | | :--- | :--- | -| 中心化 | Twitter, Facebook, Instagram | -| 联邦式 | 电子邮件, XMPP, 电话网络, 邮政服务 | -| 分布式 | BitTorrent, IPFS, Scuttlebutt | +| 中心化 | Twitter、Facebook、Instagram | +| 联合式 | 电子邮件、XMPP、电话网络、实体邮件 | +| 分布式 | BitTorrent、IPFS、Scuttlebutt | -Mastodon站点可以独立运作。和传统网站一样，人们可以在上面注册、发布消息、上传图片、互相聊天。但与传统网站*不同*的是，Mastodon网站之间可以互动，让跨站用户互相交流，就好像只要你知道他们的电子邮件地址，你就可以从你的Gmail帐户发送电子邮件给使用Outlook、Fastmail、Protonmail或任何其他电子邮件供应商的用户。在Mastodon里，**你可以对任何人在任何网站上的地址进行“@”或私信**。 +一个 Mastodon 站点可以像传统网站一样独立运行。人们可以在上面注册、发帖、上传图片以及相互交流。与传统网站*不同*的是，Mastodon 网站之间可以互通，不同站点的用户能够互相交流；就像你可以从 Gmail 账户向 Outlook、Fastmail、Protonmail 或任何其他电子邮件提供商的用户发送邮件一样，只要你知道对方的电子邮件地址，**你就可以使用任何网站上任何用户的地址来提及或私信他们**。 -{{< figure src="assets/network-models.jpg" caption="上图从左到右依次为：集中式、联邦式、分布式" >}} +{{< figure src="assets/network-models.jpg" caption="从左到右：中心化、联合式、分布式" >}} -## ActivityPub是什么？ {#fediverse} +## 什么是 ActivityPub？{#fediverse} -Mastodon使用一种标准化的、开放的协议来实现站点之间的互动，这种协议叫做**ActivityPub**。任何通过ActivityPub实现互联的软件都可以与Mastodon无缝通信，就像Mastodon站点之间的通信一样。 +Mastodon 使用一个标准化的开放协议来实现联合。这个协议叫做 **ActivityPub**。任何同样通过 ActivityPub 实现联合的软件都可以与 Mastodon 无缝通信，就像 Mastodon 网站之间可以互相通信一样。 -**联邦宇宙**（fediverse）是所有可以通过ActivityPub和互联网互相交流的网站的统称。这包括所有Mastodon服务器，但也包括其他的一些实现： +**联邦宇宙**（“Fediverse”）是所有能够通过 ActivityPub 和互联网相互通信的网站的总称。这包括所有的 Mastodon 站点，也包括其它实现此协议的应用： -* Pleroma：一个模块化的微博客引擎 -* Pixelfed：联邦式的图片分享平台，它可以让你分享和阅读媒体嘟文 -* Misskey：包括一个可自定义界面的微博客 -* PeerTube：它可以让你上传视频到频道 -* Plume：它可以用来发布长篇文章 -* 还有更多，包括许多个人网站！ +- Pleroma，一个模块化的微博引擎 +- Pixelfed，联合式的图片分享平台，允许你分享和浏览媒体贴文 +- Misskey，除微博功能外，还提供可定制的仪表盘 +- PeerTube，允许你将视频上传到频道 +- Plume，允许你发布篇幅更长的文章 +- 还有更多，包括独立站点和私人网站！ -**联邦宇宙**没有自己的所谓品牌，所以你可能更常听到“来关注我的Mastodon吧”而不是“来关注我的联邦宇宙吧”。虽说从技术上讲，后者的说法更准确。 +联邦宇宙本身没有统一的品牌标识，所以你可能更常听到“在 Mastodon 上关注我”，而不是“在联邦宇宙关注我”，但严格来说，后者更准确。 -## 实际影响因素 {#implications} +## 实际影响 {#implications} -### 选择合适的服务提供者与用户政策 {#choice} +### 服务提供者和政策的选择 {#choice} -因为Mastodon只是可以用于驱动任何网站的软件，Mastodon的潜在用户拥有选择服务提供者的权利，用户可以从现有Mastodon站点中选择，或者如果用户愿意的话，也可以创建自己的Mastodon站点。Mastodon项目在 [joinmastodon.org](https://joinmastodon.org) 上维护了一个推荐服务提供者列表，该列表可按类别和/或语言进行排序。一些站点可能有额外的管理政策，例如要求对潜在敏感内容打上特定标签，另一些站点可能有更加宽松的管理政策，但是所有在列表中列出的站点均需遵守[《Mastodon服务器公约》](https://joinmastodon.org/covenant)，这意味着他们承诺积极处理并反对仇恨言论、每日进行备份、至少有一个应急管理员、关站前至少提前3个月发布关站通告。 +Mastodon 仅仅是一款可以驱动任何网站的软件，Mastodon 的潜在用户可以选择一个已有的 Mastodon 网站作为服务提供者，或者如果他们愿意，也可以创建自己的 Mastodon 网站。Mastodon 项目在 [joinmastodon.org](https://joinmastodon.org) 维护了一个推荐的服务提供者列表，可按类别和/或语言排序。有些网站的审核政策可能比其它站点更严格，例如要求对潜在的敏感内容使用特定标签；而有些网站的审核政策可能更为宽松，但列表中的网站都同意遵守 [Mastodon 站点公约](https://joinmastodon.org/covenant)，这意味着它们承诺积极审核仇恨言论、每日进行数据备份、至少配备一名紧急管理员，并在关闭服务前至少提前 3 个月通知用户。 -> 维护一个让所有成员都感到安全的社区并不容易。Mastodon提供了很多基础性的框架和工具来完成这件事，并将改变的权力从一个商业实体转移到社区自己手中。 +> 维护让所有成员都感到安全的社区并非易事。Mastodon 为此提供了大量基础框架和工具，并将实现变革的力量从单一的商业实体转移到了社区自身手中。 > -> -- Eugen Rochko, Jul 6 2018, [《将Mastodon关到笼子里去》](https://blog.joinmastodon.org/2018/07/cage-the-mastodon/) +> -- Eugen Rochko，2018年7月6日，[《将 Mastodon 关入笼中》](https://blog.joinmastodon.org/2018/07/cage-the-mastodon/) -> 一个中心化的社交媒体平台有一个等级结构，在这个结构中平台的规则及其实施，以及平台的发展方向都是由CEO决定的[……] 一个去中心化的网络有意放弃了对平台所有权的控制，从本质上来讲是没有平台所有者的。 +> 中心化的社交媒体平台采用层级结构，规则及规则的执行方式，以及平台的开发和方向都由 CEO 决定 [...] 去中心化网络则有意放弃了平台所有者的控制权，因为它根本就没有所有者。 > -> -- Eugen Rochko, Dec 30 2018, [《为什么去中心化很重要？》](https://blog.joinmastodon.org/2018/12/why-does-decentralization-matter/) +> -- Eugen Rochko，2018年12月30日，[《去中心化为何重要？》](https://blog.joinmastodon.org/2018/12/why-does-decentralization-matter/) -### 资金和盈利 {#monetization} +### 资金来源和商业模式 {#monetization} -Mastodon站点是由不同的人或组织完全独立运营的。Mastodon没有在软件中实现任何盈利策略。 +Mastodon 网站由不同的人或组织完全独立运营。Mastodon 软件本身未实现任何商业变现策略。 -有的服务器运营者选择提供付费帐户；有的服务器运营者是公司，这样便可以利用他们现有的基础设施；有的服务器运营者通过Patreon及其类似服务来众筹资金；有的服务器运营者只是自掏腰包，为自己和朋友搭建私人服务器。所以，如果你想支持你帐户所在服务器的运营者，请检查一下它是否提供了捐赠渠道。 +一些服务器运营者选择提供付费账户，一些运营者是能够利用其现有基础设施的公司，一些则依靠用户通过 Patreon 及类似服务进行众筹，还有一些运营者是自负成本，为自己或许还有一些朋友维护个人站点。因此，如果你想支持托管你账户的服务器，请查看其是否提供了捐助途径。 -Mastodon的开发同样是通过[Patreon](https://patreon.com/mastodon)和[OpenCollective](https://opencollective.com/mastodon)众筹的。**不涉及风险投资。** +Mastodon 的开发同样通过 [Patreon](https://patreon.com/mastodon) 和 [OpenCollective](https://opencollective.com/mastodon) 进行众筹。**没有任何风险投资参与。** -> 在我看来，“即时、公开、全球性的信息传递与交流” 实际上应该是*全球性的*。分布于能够自我管理的独立组织与行为者之中。一个公共设施，没有利用交流牟利的动机。 +> 在我看来，“即时、公开、全球性的消息传递和对话”实际上就应该是_全球性_的。它应该分布在能够自我管理的独立组织和参与者之间。它应该是一种公共服务，没有为牟利而利用这些对话的动机。 > -> -- Eugen Rochko, Mar 3 2018, [《推特不是公共设施》](https://blog.joinmastodon.org/2018/03/twitter-is-not-a-public-utility/) +> -- Eugen Rochko，2018年3月3日，[《Twitter 不是公共服务》](https://blog.joinmastodon.org/2018/03/twitter-is-not-a-public-utility/) -### 跨平台互联 {#interoperability} +### 不同软件间的互操作性 {#interoperability} -实际上：你能否想象一下从你的推特帐户关注一个Instagram用户并在不离开你的帐户的情况下评论他们的照片。如果推特和Instagram是使用同样协议的联邦服务，那么这将是可能的。通过一个Mastodon帐户，**你可以与其他相兼容的网站通迅，** _**即使它并没有运行Mastodon**_。这些网站只需要它们的软件支持ActivityPub协议的相同子集，该协议子集允许创建消息和通过消息进行交互。想了解更多与Mastodon交互所需的技术规范，请参阅[ActivityPub](spec/activitypub)、[WebFinger](spec/webfinger)和[Security](spec/security)。想了解更多关于ActivityPub的用处，请参阅[《为什么ActivityPub是未来》](https://blog.joinmastodon.org/2018/06/why-activitypub-is-the-future/)。 +具体来说：想象一下，如果你能在自己的 Twitter 账户上关注某个 Instagram 用户，并直接评论他们的照片，而无需离开 Twitter。如果 Twitter 和 Instagram 是使用相同协议的联合式服务，这就可能实现。拥有 Mastodon 账户后，**你可以与其它任何兼容的站点进行交流，**_**即使它并非运行 Mastodon 软件**_。唯一的要求是该软件支持 ActivityPub 协议中允许创建贴文更新并与之互动的那部分功能的子集。要了解与 Mastodon 互通所需的技术规范详情，请参阅 [ActivityPub](spec/activitypub)、[WebFinger](spec/webfinger) 和 [安全性说明](spec/security)。要进一步了解 ActivityPub 能让我们实现什么，请参阅 [为什么 ActivityPub 是未来](https://blog.joinmastodon.org/2018/06/why-activitypub-is-the-future/)。 -> 所有这些平台都是不同的，它们关注不同的需求。然而，它们的基石都是相同的：一些人订阅接收其他人的帖子。因此，它们都是相互兼容的。 +> 所有这些平台各不相同，专注于不同的需求。然而，它们的基础是相同的：人们订阅他人以接收他们的帖文。因此，这些平台都是相互兼容的。 > -> -- Eugen Rochko, Jun 27 2018, [《为什么ActivityPub是未来》](https://blog.joinmastodon.org/2018/06/why-activitypub-is-the-future/) +> -- Eugen Rochko，2018年6月27日，[《为什么 ActivityPub 是未来》](https://blog.joinmastodon.org/2018/06/why-activitypub-is-the-future/) -### 自由软件 {#libre} +### 自由/开源软件 {#libre} -与专有服务不同，**任何人都拥有运行，检查，审核，复制，修改，分发和重用Mastodon源代码的完全自由，只要他们保证任何衍生作品都具有同等的自由。** 就像Mastodon用户可以选择他们的服务提供者一样，你作为一个个体可以自由地向Mastodon贡献功能，或者发布包含不同功能的修改版本。这些修改后的版本，也被称为软件分支，被要求维持与Mastodon原始项目同等的自由。例如，[glitch-soc](https://glitch-soc.github.io/docs/)是一个添加了许多实验特性的软件发行版。除此而外，还有许多的独立分支存在，这些分支可能仅仅是主题稍微不同，或者包含对代码库的小修改。因为Mastodon是尊重你的自由的自由软件，像这样的个性化不仅是允许的，而且是鼓励的。 +与专有服务不同，**任何人都有运行、研究、检查、复制、修改、分发和重用 Mastodon 源代码的完全自由，前提是他们必须保证任何衍生作品也享有同样的自由。**就像 Mastodon 用户可以选择他们的服务提供商一样，作为个人，你可以自由地为 Mastodon 贡献功能，或发布包含不同功能的 Mastodon 修改版本。这些修改版本，也被称为软件分支，同样需要维持与原始 Mastodon 项目相同的自由。例如，[glitch-soc](https://glitch-soc.github.io/docs/) 是一个添加了各种实验性功能的软件发行版。此外还存在许多个人分支，它们可能在主题样式上略有不同，或者对代码库进行了少量修改。因为 Mastodon 是尊重你自由的自由软件（libre software），像这样的个性化不仅是被允许的，而且是受鼓励的。 -> 最终的力量在于让人们能够创建自己的空间、自己的社区，以自己的想法修改软件，但又不牺牲与来自不同社区的人们相互交流的能力。 +> 最根本的力量在于赋予人们创造自己的空间、自己的社区的能力，让他们能按自己的意愿修改软件，同时又不牺牲不同社区成员之间相互交流的能力。 > -> -- Eugen Rochko, Feb 20 2017, [《建立社区的力量：对马克·扎克伯格的回应》](https://blog.joinmastodon.org/2017/02/the-power-to-build-communities/) +> -- Eugen Rochko，2017年2月20日，[《构建社区的力量：对 Mark Zuckerberg 的回应》](https://blog.joinmastodon.org/2017/02/the-power-to-build-communities/) -> 去中心化是数字世界的生物多样性，是健康生态系统的标志。像联邦宇宙这样的去中心化网络允许不同的用户界面、不同的软件、不同形式的治理方式共存与合作。 +> 去中心化是数字世界的生物多样性，是健康生态系统的标志。像 Fediverse 这样的去中心化网络允许不同的用户界面、不同的软件、不同的治理形式共存与合作。 > -> -- Eugen Rochko, Dec 30 2018, [《为什么去中心化很重要？》](https://blog.joinmastodon.org/2018/12/why-does-decentralization-matter/) +> -- Eugen Rochko，2018年12月30日，[《去中心化为何重要？(Why does decentralization matter?)》](https://blog.joinmastodon.org/2018/12/why-does-decentralization-matter/) -## 开始你的旅程吧！ {#next-steps} +## 选择你的浏览路径 {#next-steps} -学习如何使用Mastodon： +了解如何使用 Mastodon： {{< page-ref page="user/signup" >}} -学习如何安装Mastodon： +了解如何安装 Mastodon： {{< page-ref page="admin/prerequisites" >}} -学习如何为Mastodon编写应用程序： +了解如何为 Mastodon 编写应用： {{< page-ref page="client/intro" >}} -了解Mastodon后端以及如何向Mastodon项目做贡献： +了解 Mastodon 后端以及如何做出贡献： {{< page-ref page="dev/overview" >}} -{{< translation-status-zh-cn raw_title="What is Mastodon?" raw_link="/" last_tranlation_time="2020-05-02" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}} +{{< translation-status-zh-cn raw_title="What is Mastodon?" raw_link="/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/backups.md b/content/zh-cn/admin/backups.md index 4cc5585..6fc6f68 100644 --- a/content/zh-cn/admin/backups.md +++ b/content/zh-cn/admin/backups.md @@ -1,55 +1,55 @@ --- title: 备份你的服务器 -description: 设置日常备份（可选，但并非如此） +description: 设置定期备份（可选，但实际上很必要） menu: docs: weight: 80 parent: admin --- -对于任何真实世界用途来说，你都应该保证日常备份Mastodon服务器。 +对于所有实际使用的场景，你都应确保定期备份你的 Mastodon 服务器。 -## 概览 {#overview} +## 概述 {#overview} -你所需要备份的东西，按重要程度排序： +需要备份的内容按重要程度排序如下： 1. PostgreSQL 数据库 -2. `.env.production` 文件或等效文件中的应用密钥 +2. 来自 `.env.production` 文件或等效文件的应用密钥 3. 用户上传的文件 4. Redis 数据库 -## 故障模式 {#failure} +## 故障类别 {#failure} -人们通常要应对两种类型故障：硬件故障，诸如磁盘上数据损坏；以及人为软件故障，诸如误删特定文件。本文档中，仅考虑前一种类型。 +人们通常会防范两种类型的故障：硬件故障，如磁盘数据损坏；以及人为和软件错误，如错误删除某特定数据。在本文档中，我们仅考虑前一种类型。 -丢失PostgreSQL数据库，那一切都完了。Mastodon将所有重要数据存储于PostgreSQL数据库中。如果数据库消失，那你服务器上所有的帐户、所有的嘟文、所有关注者都将随之消失。 +Mastodon 将所有最重要的数据存储在 PostgreSQL 数据库中。PostgreSQL 数据库的丢失将导致服务器完全故障，包括所有账户、嘟文与关注者信息。 -如果你丢失了应用密钥，对你的用户而言，Mastodon的某些功能将停止工作。你服务器上的用户将被登出，双因子认证（2FA）将不可用，Web Push API订阅将停止工作。 +如果你丢失了应用密钥，Mastodon 的某些功能将停止为用户工作，用户将被登出，双因素认证将不可用，且 Web Push API 订阅将停止工作。 -如果你丢失了用户上传的文件，你将丢失头像、横幅、媒体附件，但Mastodon*仍会*继续工作。 +如果丢失了用户上传的文件，你将丢失头像、资料卡横幅背景图和媒体附件，但 Mastodon 在未来仍能正常工作。 -丢失Redis数据库几乎是无害的：唯一不可逆的数据是Sidekiq队列及之前失败任务的重试计划。主页与列表时间流虽然存储于Redis，但它们可以使用tootctl再生成。 +丢失 Redis 数据库几乎无害：唯一不可恢复的数据是 Sidekiq 队列的内容和先前失败任务的计划重试时间。主页和列表信息流存储在 Redis 中，但可以通过 tootctl 重新生成。 -最好的备份是所谓的异地备份，即与Mastodon自身不在同一台计算机上存储的备份。如果你托管的服务器起火了，硬盘爆炸了，存储于同一硬件备份将不可用。 +最好的备份是被称为异地备份的备份模式，即不存储在与 Mastodon 服务器本身相同的机器上的备份。如果你的服务器着火并且硬盘驱动器爆炸，存储在同一硬盘上的备份将没有太大用处。 ## 备份应用密钥 {#env} -应用密钥是最容易备份的，因为它们是不变的。你只需要将 `.env.production` 存储在安全的地方就可以了。 +应用密钥是最容易备份的，因为它们从不变化。你只需将 `.env.production` 存储在安全的地方即可。 ## 备份 PostgreSQL {#postgresql} -突然断电、硬盘故障、错误迁移数库库schema都会致使数据损坏。由于以上原因，推荐偶尔使用 `pg_dump` 或 `pg_dumpall` 备份数据库。 +PostgreSQL 面临断电、硬盘驱动器故障与错误的架构迁移带来的数据损坏风险。因此，建议偶尔使用 `pg_dump` 或 `pg_dumpall` 进行备份。 -如果要求高可用性，可以使用热流拷贝（hot streaming replication）使第二台PostgreSQL服务器始终具有最新数据，并做好另一台服务器出现故障切换至此的准备。 +对于高可用配置，可以使用热数据流式复制来拥有一个数据始终最新的第二PostgreSQL服务器，以便在另一服务器宕机时随时切换。 ## 备份用户上传的文件 {#media} -如果你使用外部对象存储，诸如Amazon S3、Google Cloud 或 Wasabi，你无需为怎么备份它们而担心。各自的公司将负责处理硬件故障。 +如果你使用外部对象存储提供商，如亚马逊S3、谷歌云或 Wasabi，则无需担心备份这些文件。相应公司负责处理硬件故障。 -如果你使用本地文件存储，复制体积巨大的 `public/system` 目录（默认存储上传文件的地方）。 +如果你使用是本地文件存储，那么你需要自行对 `public/system` 这个大目录进行备份，该目录是上传文件的默认存储位置。 ## 备份 Redis {#redis} -备份Redis是很容易的。Redis会定期将数据写入`/var/lib/redis/dump.rdb`文件，你只需要复制这个文件就可以了。 +备份 Redis 很容易。Redis 定期写入 `/var/lib/redis/dump.rdb`，这是你唯一需要复制的文件。 -{{< translation-status-zh-cn raw_title="Backing up your server" raw_link="/admin/backups/" last_tranlation_time="2020-05-06" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}} +{{< translation-status-zh-cn raw_title="Backing up your server" raw_link="/admin/backups/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/config.md b/content/zh-cn/admin/config.md index 58561bc..c3fef5b 100644 --- a/content/zh-cn/admin/config.md +++ b/content/zh-cn/admin/config.md @@ -1,247 +1,1246 @@ --- -title: 设置你的环境 -description: 为你安装的Mastodon设置环境变量。 +title: 配置你的环境 +description: 为你的 Mastodon 服务器设置环境变量。 menu: docs: weight: 30 parent: admin --- +Mastodon 使用环境变量作为配置方式。 + +为方便起见，它可以从 Mastodon 目录中的 `.env.production` 纯文本文件（该文件也被称为 "dotenv" 文件）中读取这些变量，但它们始终可以被特定进程覆盖。例如，systemd 服务文件可以从 `EnvironmentFile` 或带有 `Environment` 的配置文件内联定义中读取环境变量，因此你可以为特定服务设置不同的配置参数。也可以在通过命令行调用 Mastodon 时指定它们。 + +## 基础配置 {#basic} + +### 联合与显示 {#federation} + +#### `LOCAL_DOMAIN` + +这是你的站点在网络中的唯一标识符。之后无法安全更改，因为更改它将导致外站服务器将你现有的账户与全新的账户混淆。它必须是你服务器实际对应的域名(不包括协议部分，例如只是`example.com`)。 + +#### `WEB_DOMAIN` + +`WEB_DOMAIN` 是一个可选环境变量，允许在一个域名上配置 Mastodon，同时让用户的标识保持在不同的域上，例如将用户地址配置为 `@alice@example.com`，但在 `mastodon.example.com` 上访问 Mastodon。如果你的域名已经用于不同的网站，但你仍然希望将其用作 Mastodon 标识符，因为它看起来更好或更短，这个配置可能会很有用。 + +与 `LOCAL_DOMAIN` 一样，一旦设置，`WEB_DOMAIN` 就无法安全更改，因为这会使知道你以前设置的外站服务器感到困惑，并可能破坏与它们的通信或使其变得不可靠。由于问题在于外站服务器对你的账户的理解，从头重新安装 Mastodon 也无法解决这个问题。因此，在设置 `LOCAL_DOMAIN` 和 `WEB_DOMAIN` 时请格外小心。 + +要在 `mastodon.example.com` 上安装 Mastodon，并使其为 `@alice@example.com` 这样的域名下的账户提供服务，请将 `LOCAL_DOMAIN` 设为 `example.com`，将 `WEB_DOMAIN` 设置为 `mastodon.example.com`。你还需要在托管 `example.com` 的服务器上进行额外配置，以将来自 `https://example.com/.well-known/webfinger` 的请求重定向到 `https://mastodon.example.com/.well-known/webfinger`。例如，使用 nginx 时，配置可能如下所示： + +``` +location /.well-known/webfinger { + add_header Access-Control-Allow-Origin '*'; + return 301 https://mastodon.example.com$request_uri; +} +``` + +{{< hint style="info" >}} +进行服务重定向时必须添加 CORS 标头；否则，Mastodon 网页界面的某些功能将无法工作。例如可以添加如下 CORS 标头：`Access-Control-Allow-Origin: *` +{{}} + +#### `ALTERNATE_DOMAINS` + +如果你有多个指向你的 Mastodon 服务器的域名，此设置将允许 Mastodon 在使用这些其他域名寻址用户时识别自己。域名之间用逗号分隔，例如`foo.com,bar.com` + +#### `ALLOWED_PRIVATE_ADDRESSES` + +私有IP地址/子网列表，以逗号分隔，允许在出站HTTP请求中使用。Mastodon 阻止来自私有IP地址范围(如 `127.0.0.1` 或 `192.168.1.1/16`)的主机的HTTP请求，以防止[服务器端请求伪造](https://en.wikipedia.org/wiki/Server-side_request_forgery)。此设置将从阻止列表中移除指定的IP地址/子网。 + +#### `AUTHORIZED_FETCH` + +也称为"安全模式"。设置为`true`时，会发生以下变化： + +- Mastodon 将停止为公开嘟文生成链接数据签名，这可以防止它们在没有精确控制的情况下被高效地重新分发。由于带有签名的链接数据对象是完全自包含的，它可以在不向来源服务器发出额外请求的情况下传递。 +- Mastodon 将要求对公开嘟文和账户的 ActivityPub 表示的请求进行HTTP签名认证，这些数据通常在没有任何认证的情况下可用。当没有提供认证时，个人资料将只返回基本的技术信息。 +- 在 4.0.0 版本之前：Mastodon 将要求任何 REST/streaming API 访问携带用户上下文(即已通过具有活跃用户的 OAuth 授权界面授权)，而通常情况下一些 API 端点无需任何认证即可使用。 + +因此，通过以上认证机制并避免不将你的服务器纳入循环的重新分发的情况出现，你可以强制谁可以和谁不可以检索你服务器上的公开内容，例如你已阻止域的服务器。 + {{< hint style="warning" >}} -本页面仍在建设中。 -{{< /hint >}} +不幸的是，安全模式并非没有缺点，这就是它不默认启用的原因。联邦宇宙中，并非所有软件都能完全支持它，尤其是启用之后，与 3.0 之前版本的 Mastodon 服务器的某些功能将被破坏；由于链接数据签名被用于使公开对话的上下文更完整，因此即使在与最新版本的服务器联合时，也会失去一些有用的功能；另外，由于该模式下的公开内容上的认证机制意味着无法缓存，它会带来计算成本的增加。 +{{}} -Mastodon使用环境变量作为其的配置。 +{{< hint style="warning" >}} +安全模式不会隐藏公开嘟文和账户的HTML表示。与 ActivityPub 的第一方表示或 REST API 相比，HTML 是一种更具有损失性的格式，但它仍然是抓取内容的潜在途径。 +{{}} -为了方便起见，Mastodon从Mastodon目录中的 `.env.production` 文件读取环境变量，但是始终可以用特定方式覆盖它们。例如：在 systemd service 文件中可以使用 `EnvironmentFile` 从特定文件中读取环境变量或使用 `Environment` 定义环境变量，因此你可以为不同服务指定不同的环境变量。也可以在从命令行调用运行Mastodon时指定环境变量。 +#### `LIMITED_FEDERATION_MODE` -## 基本参数 {#basic} +设置为 `true` 时，Mastodon 将联合范围限制在你手动批准的站点之内，并禁用所有公共页面和某些 REST API。有限联合模式基于安全模式(`AUTHORIZED_FETCH`)。 -### 站点互联 {#federation} +当将现有实例切换到有限联合模式时，应使用以下命令删除允许的域名之外的实例上已存在的任何数据： -* `LOCAL_DOMAIN` -* `WEB_DOMAIN` -* `ALTERNATE_DOMAINS` +``` +tootctl domain purge --limited-federation-mode +``` -#### `AUTHORIZED_FETCH` {#authorized_fetch} +{{< hint style="warning" >}} +此模式仅供私人使用，例如在学术机构或内部公司网络中，因为它实际上创建了一个数据孤岛，这与 Mastodon 的去中心化使命相悖。 +{{}} - 当设置为 `true` 时，Mastodon将停止内联签名活动，并要求远程服务器在拉取公开（public）和不公开（unlisted）的嘟文时进行身份验证。 - - 这可以阻止被屏蔽的域名拉取你的公开嘟文，但代价是可能增加计算量，并与不支持附带签名的拉取请求的软件不兼容（如低于3.0版本的Mastodon）。 - - 请注意：这个模式并不能保证你的公开嘟文（public、unlisted）不被恶意操作者获取，这仅仅是增加了一点难度。 +{{< hint style="info" >}} +在 3.1.5 版本之前，此设置称为`WHITELIST_MODE`。 +{{}} -#### `WHITELIST_MODE` {#whitelist_mode} +#### `DISALLOW_UNAUTHENTICATED_API_ACCESS` - 当设置为 `true` 时，Mastodon将仅与白名单内的服务器互联，同时关闭公开页面和一些客户端API。 - 白名单模式会启用 authorized fetch 模式。 - - 当一个现存实例站点切换至白名单模式，以下命令可以被用来移除非白名单站点的数据： - ``` - tootctl domain purge --whitelist-mode - ``` - - 请注意：虽然Mastodon 3.0 版本便引入了白名单模式 `WHITELIST_MODE`，但在Mastodon 3.0和3.0.1版中并没有正确实现。 +从 Mastodon v4.0.0 开始，Web 应用将负责渲染所有请求，包括未登录状态下的请求。为了使相关应用视图工作， Web 应用会公开发出 API 请求以获取账户和嘟文。如果你想禁止这一点，请将此变量设置为`true`。请注意，禁止未经认证的 API 访问将导致账户和嘟文的永久链接对未登录用户返回错误，使得本地登录或通过ActivityPub获取内容称为查看内容的唯二方式。 + +#### `SINGLE_USER_MODE` + +若配置为`true`，你的 Mastodon 服务器的首页将始终重定向到数据库中的第一个账户，且注册将被禁用。 + +#### `DISABLE_AUTOMATIC_SWITCHING_TO_APPROVED_REGISTRATIONS` + +为了防止被遗弃的 Mastodon 服务器被用于垃圾信息、骚扰和其他恶意活动，如果服务器开放新用户注册，且一周内没有检测到任何可访问审核举报的用户的活动（包括通过 APP 的非审核活动），Mastodon 将自动切换到需要管理员批准新用户注册的模式。发生这种情况时，拥有更改服务器设置权限的用户将收到电子邮件通知。 + + +设置 `DISABLE_AUTOMATIC_SWITCHING_TO_APPROVED_REGISTRATIONS=true` 可禁用此行为。 + +**版本历史：**\ +4.2.8 - 该配置被添加 + +#### `DEFAULT_LOCALE` + +默认情况下，Mastodon 会自动从浏览器标头中检测访问者的语言，并以该语言 (如果支持) 显示 Mastodon 界面。如果你正在运行特定语言或区域的服务器，这种行为可能会误导不会说你的语言的访客在你的服务器注册。因此，你可能希望将此变量设置为特定语言。 + +示例值：`de` + +支持的语言： + +- `ar` +- `ast` +- `bg` +- `bn` +- `br` +- `ca` +- `co` +- `cs` +- `cy` +- `da` +- `de` +- `el` +- `en` +- `eo` +- `es` +- `es-AR` +- `et` +- `eu` +- `fa` +- `fi` +- `fr` +- `ga` +- `gl` +- `he` +- `hi` +- `hr` +- `hu` +- `hy` +- `id` +- `io` +- `is` +- `it` +- `ja` +- `ka` +- `kab` +- `kk` +- `kn` +- `ko` +- `lt` +- `lv` +- `mk` +- `ml` +- `mr` +- `ms` +- `nl` +- `nn` +- `no` +- `oc` +- `pl` +- `pt-BR` +- `pt-PT` +- `ro` +- `ru` +- `sk` +- `sl` +- `sq` +- `sr` +- `sr-Latn` +- `sv` +- `ta` +- `te` +- `th` +- `tr` +- `uk` +- `ur` +- `vi` +- `zh-CN` +- `zh-HK` +- `zh-TW` ### 密钥 {#secrets} -* `SECRET_KEY_BASE` -* `OTP_SECRET` -* `VAPID_PRIVATE_KEY` -* `VAPID_PUBLIC_KEY` +#### `SECRET_KEY_BASE` + +使用 `rake secret` 生成。更改将破坏所有活跃的浏览器会话。 + +#### `OTP_SECRET` + +使用 `rake secret` 生成。更改将破坏双因素认证。 + +#### `VAPID_PRIVATE_KEY` + +使用 `rake mastodon:webpush:generate_vapid_key` 生成。更改将破坏推送通知。 + +#### `VAPID_PUBLIC_KEY` + +使用 `rake mastodon:webpush:generate_vapid_key` 生成。更改将破坏推送通知。 ### 部署 {#deployment} -* `RAILS_ENV` -* `RAILS_SERVE_STATIC_FILES` -* `RAILS_LOG_LEVEL` -* `TRUSTED_PROXY_IP` -* `SOCKET` -* `PORT` -* `NODE_ENV` -* `BIND` +#### `RAILS_ENV` -### 缩放选项 {#scaling} +环境。可以是 `production`、 `development` 或 `test`。如果你出于开发目的在个人计算机上运行 Mastodon，请使用 `development`。这也是默认值。如果你在线运行 Mastodon，请使用 `production`。Mastodon 将根据环境加载不同的配置默认值。 -* `WEB_CONCURRENCY` -* `MAX_THREADS` -* `PREPARED_STATEMENTS` -* `STREAMING_API_BASE_URL` -* `STREAMING_CLUSTER_NUM` +{{< hint style="warning" >}} +该变量不能在 dotenv(`.env`) 文件中定义，因为它在该文件被加载之前就已使用。 +{{}} -## 数据库连接 {#connections} +#### `RAILS_SERVE_STATIC_FILES` + +若配置为 true， Mastodon 将响应对 `public` 目录中文件的请求。当反向代理(例如 nginx)无法访问 `public` 目录本身的文件系统时，这可能是必要的，例如在容器化环境中。这是一种次优配置，因为直接从文件系统提供静态文件总是比通过 Ruby on Rails 进程提供它们要快得多。 + +#### `RAILS_LOG_LEVEL` + +确定 Mastodon 为 Web 和 Sidekiq 进程生成的日志量。默认为 `info`，这会为 Mastodon 服务的每个请求和 Mastodon 处理的每个后台作业生成日志条目。这可能很有用，但如果有大量流量/活动，可能会变得非常嘈杂并给你的机器的 I/O 带来压力。在这种情况下，建议使用 `warn`，它只会输出关于出错的信息，否则保持安静。可能的值是 `debug`、`info`、`warn`、`error`、`fatal` 和 `unknown`。 + +#### `LOG_LEVEL` + +确定 Mastodon 为流进程生成的日志量。默认为 `info`。其它可能的值有 `silly` 和 `info`。 + +#### `TRUSTED_PROXY_IP` + +告诉 Mastodon Web 进程和流进程哪些 IP 充当你的可信反向代理(例如nginx、Cloudflare)。它影响 Mastodon 如何确定每个请求的源 IP，这用于重要的速率限制和安全功能。如果该值设置不正确，那么 Mastodon 可能会使用反向代理的 IP 而不是实际源 IP。 + +默认情况下，环回和私有网络地址范围是可信的。具体来说： + +- `127.0.0.1/8` +- `::1/128` +- `10.0.0.0/8` +- `172.16.0.0/12` +- `192.168.0.0/16` +- `fc00::/7` + +如果你使用单个反向代理，并且它与你的 Mastodon Web 进程和流进程在同一台机器上运行，或位于同一个私有网络中，那么你很可能不需要修改此设置，可以使用默认设置。如果你使用多个反向代理服务器，并且它们都与你的 Mastodon Web 进程和流进程位于同一个私有网络中，那么理论上同样保持默认设置就可以了。但是，如果你使用的反向代理服务器通过公共IP地址到达你的 Mastodon Web 服务端和流服务端(例如，如果你使用 Cloudflare 或类似代理)，那么你需要设置此变量。它应该是所有可能使用的反向代理的IP，以逗号分隔的IP列表或使用[CIDR表示法](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation)表示的 IP 范围。请注意，当设置此变量时，默认范围(上面提到的)将不再被信任，因此如果你同时拥有外部反向代理和来自 localhost 的代理，则必须同时包含两者的IP(或IP范围)。 + +管理员和协管员可以进入设置 > 审核 > 账户选项卡来找到 Mastodon 看到的每个用户的源 IP。你可以使用像[IPInfo](https://ipinfo.io)这样的工具来判断 IP 是由最终用户 ISP 使用还是由托管你的代理的服务器使用。 + +#### `SOCKET` + +除了绑定到 `127.0.0.1` 这样的 IP 地址之外，你还可以使用 Unix 套接字。此变量是特定于进程的，你可以根据需要为每个进程使用不同的值，它适用于 Web(Puma) 进程和流式 API(Node.js) 进程。 + +{{< hint style="warning" >}} +该变量不能在 dotenv(`.env`) 文件中定义，因为它在该文件被加载之前就已使用。 +{{}} + +#### `PORT` + +在不使用 Unix 套接字时，这将指定进程将监听的端口。此变量是特定于进程的，你可以根据需要为每个进程使用不同的值，它适用于 Web(Puma) 进程和流式 API(Node.js) 进程。默认情况下，Web 进程监听`3000`，流式 API 进程监听`4000`。 + +{{< hint style="warning" >}} +该变量不能在 dotenv(`.env`) 文件中定义，因为它在该文件被加载之前就已使用。 +{{}} + +#### `NODE_ENV` + +相当于 `RAILS_ENV`，但用于流式 API(Node.js) 服务端。 + +{{< hint style="warning" >}} +该变量不能在 dotenv(`.env`) 文件中定义，因为它在该文件被加载之前就已使用。 +{{}} + +#### `BIND` + +在不使用 Unix 套接字时，这将指定进程绑定到的 IP。只要它们监听不同的端口，多个进程就可以绑定到同一个IP。默认为 `127.0.0.1`。 + +{{< hint style="warning" >}} +该变量不能在 dotenv(`.env`) 文件中定义，因为它在该文件被加载之前就已使用。 +{{}} + +#### `MASTODON_USE_LIBVIPS` + +默认情况下， Mastodon 使用 ImageMagick 处理嘟文中的图像。作为替代方案，可以使用 [libvips](https://www.libvips.org) 8.13+，它具有更好的性能和更低的资源使用率。 + +从源代码安装 Mastodon 时，默认为 `false`，设置为 `true` 以启用。 + +部署 Mastodon 容器镜像时，这个值被硬编码为 `true`，不应被覆盖。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +### 扩展选项 {#scaling} + +{{< page-ref page="admin/scaling" >}} + +#### `SIDEKIQ_CONCURRENCY` + +在 4.1 版本中添加。特定于 Sidekiq，此变量确定 Sidekiq 派生多少个不同的进程。默认为 `5`。 + +#### `WEB_CONCURRENCY` + +特定于 Puma，此变量确定 Puma 派生多少个不同的进程。默认为 `2`。 + +#### `MAX_THREADS` + +特定于 Puma，此变量确定每个 Puma 进程维护的线程数。默认为 `5`。 + +#### `PERSISTENT_TIMEOUT` + +特定于 Puma，此变量确定 Puma 在关闭连接之前应等待多长时间。默认为 `20`。 + +#### `PREPARED_STATEMENTS` + +默认情况下， Mastodon 使用 PostgreSQL 的预备语句功能，它提供一些性能优势。如果你使用在不同事务间共享连接的连接池，则此功能不可用，因此必须设置为 `false`。当你扩展服务规模时，基于事务的连接池带来的优势将超过预备语句带来的优势。 + +#### `STREAMING_API_BASE_URL` + +流式 API 可以部署到不同的域/子域。这可能会提高流式 API 的性能，因为在默认配置中，长寿命的流式 API 请求通过 nginx 代理，而从不同的域/子域提供流式 API 将允许完全跳过 nginx。 + +示例值：`wss://streaming.example.com` + +#### `STREAMING_CLUSTER_NUM` {{%removed%}} {#streaming_cluster_num} + +{{< hint style="danger" >}} +**已移除：**\ +流服务器进程现在仅使用单个 node.js 进程，要进一步扩展它，你需要按照[扩展指南](/admin/scaling#streaming)中的文档进行操作 +{{< /hint >}} + +特定于流式 API，此变量确定流式 API 派生多少个不同的进程。默认为 CPU 核心数减一。 + +## 后端配置 {#backend} ### PostgreSQL {#postgresql} -* `DB_HOST` -* `DB_USER` -* `DB_NAME` -* `DB_PASS` -* `DB_PORT` -* `DB_SSLMODE` -* `DATABASE_URL` +#### `DB_HOST` + +默认为 `localhost`。 + +#### `DB_USER` + +默认为 `mastodon`。 + +#### `DB_NAME` + +默认为 `mastodon_production`。 + +#### `DB_PASS` + +无默认值。 + +#### `DB_PORT` + +默认为 `5432`。 + +#### `DB_POOL` + +定义进程中池化的数据库连接数。此值应涵盖进程中的每个线程，因此，它默认为 `MAX_THREADS` 的值。 + +#### `DB_SSLMODE` + +PostgreSQL [SSL模式](https://www.postgresql.org/docs/10/libpq-ssl.html)。默认为`prefer`。 + +#### `DATABASE_URL` + +若提供，则优先于 `DB_HOST`、 `DB_USER`、 `DB_NAME`、 `DB_PASS` 和 `DB_PORT`。 + +示例值：`postgresql://user:password@localhost:5432` + +#### `QUERY_LOG_TAGS_ENABLED` + +若配置为 `true`，则 ActiveRecord 将在每个 SQL 语句的末尾插入注释，这可以帮助分析应用程序的性能。 + +注释使用 SqlCommenter 格式，包含以下属性： +- `namespaced_controller`：生成此 SQL 语句的 HTTP 请求的控制器的完整名称 +- `action`：生成此 SQL 语句的 HTTP 请求的操作名称 +- `sidekiq_job_class`：生成此 SQL 语句的 Sidekiq 作业的类名 + +{{< hint style="warning" >}} +启用此选项将禁用预备语句 +{{}} + +默认为 `false`。 + +**版本历史：**\ +4.4.0 - 该配置被添加 + +### PostgreSQL (只读副本) {#postgresql-replica} + +{{< hint style="info" >}} +如果你想使用只读数据库副本，你可以在[此页面](../scaling/#read-replicas)获取更多详细信息 +{{}} + +#### `REPLICA_DB_HOST` + +无默认值。 + +#### `REPLICA_DB_PORT` + +无默认值。 + +#### `REPLICA_DB_NAME` + +无默认值。 + +#### `REPLICA_DB_USER` + +无默认值。 + +#### `REPLICA_DB_PASS` + +无默认值。 + +#### `REPLICA_DATABASE_URL` + +若提供，则优先于 `REPLICA_DB_HOST`、 `REPLICA_DB_PORT`、 `REPLICA_DB_NAME`、 `REPLICA_DB_USER` 和 `REPLICA_DB_PASS`。 + +无默认值。 ### Redis {#redis} -* `REDIS_HOST` -* `REDIS_PORT` -* `REDIS_URL` -* `REDIS_NAMESPACE` -* `CACHE_REDIS_HOST` -* `CACHE_REDIS_PORT` -* `CACHE_REDIS_URL` -* `CACHE_REDIS_NAMESPACE` +Mastodon以三种不同的方式使用Redis： + +* Web 应用本身使用 Redis 存储数据并与流服务器通信。 +* Redis 被用作 Rails 内置缓存功能的缓存后端。 +* Sidekiq，负责处理后台作业的进程，在 Redis 中存储作业数据。 + +你可以将单个 Redis 实例用于所有三种用例。只需使用下面提到的合适的 `REDIS_*` 变量即可。但你也可以通过使用带有 `CACHE_` 和 `SIDEKIQ_` 前缀的变量来使用两个甚至三个不同的 Redis 实例。 + +{{< hint style="info" >}} +建议为易失性缓存使用单独的 Redis 服务器。如果你的单个 Redis 服务器负载超过可承受范围，你可能希望这样做。 +{{}} + +#### `REDIS_HOST` + +默认为 `localhost`。 + +#### `REDIS_PORT` + +默认为 `6379`。 + +#### `REDIS_USER` + +可选。用于连接 Redis 的用户名。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +#### `REDIS_PASSWORD` + +可选。用于连接 Redis 的密码。 + +#### `REDIS_URL` + +若提供，则优先于 `REDIS_HOST`、 `REDIS_PORT`、 `REDIS_USER`、 `REDIS_PASSWORD` 和 Sentinel 设置。 + +示例值： `redis://user:password@localhost:6379` + +如果你需要使用 TLS 连接到 Redis 服务器，你必须使用带有协议头 `rediss://` 的 `REDIS_URL`，并按照下面的描述设置 `REDIS_DRIVER`。 + +#### `REDIS_DRIVER` + +若提供， Redis 连接的驱动将从使用 Mastodon 默认的 hiredis 驱动更改为标准 Ruby 驱动。使用 Ruby 驱动是使用 TLS 连接到 Redis 所必需的。请注意，在某些环境中，使用 Ruby 驱动可能会影响 Redis 性能。 + +默认为 `hiredis`，可接受的值是 `hiredis` 或 `ruby`。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +#### `REDIS_NAMESPACE` + +如果提供，将为所有Redis键添加命名空间前缀。这允许在不同项目或Mastodon服务器之间共享同一个Redis数据库。 + +{{< hint style="warning" >}} +此选项已弃用。 Sidekiq 7 移除了对命名空间的支持，未来版本的 Mastodon 也会这样做。到那时，我们会尝试提供一个明确的迁移路径。如果你正在设置新的实例，强烈不建议使用此选项。 +{{}} + +**版本历史：**\ +4.3.0 - 该配置被弃用 + +#### `REDIS_SENTINELS` + +Redis Sentinel 实例 HOST:PORT 列表。端口号是可选的，如果省略，它将使用 `REDIS_SENTINEL_PORT` 中给出的值或默认值 `26379`。 + +请注意，如果你想使用 Redis Sentinel，你还需要指定 `REDIS_SENTINEL_MASTER`。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +#### `REDIS_SENTINEL_MASTER` + +要连接的 Redis Sentinel 主节点的名称。 + +请注意，如果你想使用 Redis Sentinel，你还需要指定 `REDIS_SENTINELS`。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +#### `REDIS_SENTINEL_PORT` + +`REDIS_SENTINELS` 中给出的 Sentinel 的默认端口。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +#### `REDIS_SENTINEL_USERNAME` + +用于向 Sentinel 进行身份验证的用户名。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +#### `REDIS_SENTINEL_PASSWORD` + +用于向 Sentinel 进行身份验证的密码。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +#### `CACHE_REDIS_HOST` + +默认为 `REDIS_HOST` 的值。 + +#### `CACHE_REDIS_PORT` + +默认为 `REDIS_PORT` 的值。 + +#### `CACHE_REDIS_USER` + +可选。用于连接Redis的用户名。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +#### `CACHE_REDIS_PASSWORD` + +可选。用于连接 Redis 的密码。 + +#### `CACHE_REDIS_URL` + +如果提供，优先于 `CACHE_REDIS_HOST` 和 `CACHE_REDIS_PORT`。默认为 `REDIS_URL` 的值。 + +#### `CACHE_REDIS_NAMESPACE` + +默认为 `REDIS_NAMESPACE` 的值。 + +#### `CACHE_REDIS_SENTINELS` + +逗号分隔的 Redis Sentinel 实例 HOST:PORT 列表。端口号是可选的，如果省略，它将使用默认值 `26379`。 + +请注意，如果你想使用 Redis Sentinel，你还需要指定 `CACHE_REDIS_SENTINEL_MASTER`。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +#### `CACHE_REDIS_SENTINEL_MASTER` + +要连接的 Redis Sentinel 主节点的名称。 + +请注意，如果你想使用 Redis Sentinel，你还需要指定 `CACHE_REDIS_SENTINELS`。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +#### `CACHE_REDIS_SENTINEL_PORT` + +`CACHE_REDIS_SENTINELS` 中给出的 Sentinel 的默认端口。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +#### `CACHE_REDIS_SENTINEL_USERNAME` + +用于向 Sentinel 进行身份验证的用户名。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +#### `CACHE_REDIS_SENTINEL_PASSWORD` + +用于向 Sentinel 进行身份验证的密码。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +#### `SIDEKIQ_REDIS_HOST` + +默认为 `REDIS_HOST` 的值。 + +#### `SIDEKIQ_REDIS_PORT` + +默认为 `REDIS_PORT` 的值。 + +#### `SIDEKIQ_REDIS_USER` + +可选。用于连接 Redis 的用户名。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +#### `SIDEKIQ_REDIS_PASSWORD` + +可选。用于连接 Redis 的密码。 + +#### `SIDEKIQ_REDIS_URL` + +如果提供，优先于 `SIDEKIQ_REDIS_HOST` 和 `SIDEKIQ_REDIS_PORT`。默认为 `REDIS_URL` 的值。 + +#### `SIDEKIQ_REDIS_NAMESPACE` + +默认为 `REDIS_NAMESPACE` 的值。 + +#### `SIDEKIQ_REDIS_SENTINELS` + +逗号分隔的 Redis Sentinel 实例 HOST:PORT 列表。端口号是可选的，如果省略，它将使用默认值 `26379`。 + +请注意，如果你想使用Redis Sentinel，你还需要指定`SIDEKIQ_REDIS_SENTINEL_MASTER`。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +#### `SIDEKIQ_REDIS_SENTINEL_MASTER` + +要连接的 Redis Sentinel 主节点的名称。 + +请注意，如果你想使用 Redis Sentinel，你还需要指定 `SIDEKIQ_REDIS_SENTINELS`。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +#### `SIDEKIQ_REDIS_SENTINEL_PORT` + +`SIDEKIQ_REDIS_SENTINELS` 中给出的 Sentinel 的默认端口。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +#### `SIDEKIQ_REDIS_SENTINEL_USERNAME` + +用于向 Sentinel 进行身份验证的用户名。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +#### `SIDEKIQ_REDIS_SENTINEL_PASSWORD` + +用于向 Sentinel 进行身份验证的密码。 + +**版本历史：**\ +4.3.0 - 该配置被添加 ### Elasticsearch {#elasticsearch} -* `ES_ENABLED` -* `ES_HOST` -* `ES_PORT` -* `ES_PREFIX` +{{< page-ref page="admin/elasticsearch" >}} -### StatsD {#statsd} +#### `ES_ENABLED` -* `STATSD_ADDR` -* `STATSD_NAMESPACE` +若配置为 `true`，Mastodon 将使用 Elasticsearch 执行搜索功能。 -## 限制 {#limits} +#### `ES_PRESET` -* `SINGLE_USER_MODE` -* `EMAIL_DOMAIN_WHITELIST` -* `DEFAULT_LOCALE` -* `MAX_SESSION_ACTIVATIONS` -* `USER_ACTIVE_DAYS` +该变量控制 Elasticsearch 索引配置(分片数量和副本)。 -## 电子邮件 {#email} +可能的值是： -* `SMTP_SERVER` -* `SMTP_PORT` -* `SMTP_LOGIN` -* `SMTP_PASSWORD` -* `SMTP_FROM_ADDRESS` -* `SMTP_DOMAIN` -* `SMTP_DELIVERY_METHOD` -* `SMTP_AUTH_METHOD` -* `SMTP_CA_FILE` -* `SMTP_OPENSSL_VERIFY_MODE` -* `SMTP_ENABLE_STARTTLS_AUTO` -* `SMTP_TLS` +- `single_node_cluster`(默认) +- `small_cluster` +- `large_cluster` -## 文件存储 {#cdn} +有关每个设置的详细信息，请查看[Elasticsearch设置页面](../elasticsearch#choosing-the-correct-preset)。 -* `CDN_HOST` -* `S3_ALIAS_HOST` +#### `ES_HOST` + +Elasticsearch 服务器的主机名。默认为 `localhost`。如果使用 TLS，请在主机名前加上 `https://`。例如：`https://elastic.example.com`。 + +#### `ES_PORT` + +Elasticsearch 服务器的端口。默认为 `9200` + +#### `ES_USER` + +可选，用于向 Elasticsearch 进行身份验证 + +#### `ES_PASS` + +可选，用于向 Elasticsearch 进行身份验证 + +#### `ES_PREFIX` + +如果Elasticsearch服务器在多个项目或不同的Mastodon服务器之间共享，则很有用。默认为`REDIS_NAMESPACE`的值。 + +#### `ES_CA_FILE` + +覆盖要使用的 CA 捆绑文件。在使用自签名证书时很有用。 + +**版本历史：**\ +4.3.0 - 该配置被添加 + +### SMTP 电子邮件发件 {#smtp} + +#### `SMTP_SERVER` + +#### `SMTP_PORT` + +#### `SMTP_LOGIN` + +#### `SMTP_PASSWORD` + +#### `SMTP_FROM_ADDRESS` + +#### `SMTP_DOMAIN` + +#### `SMTP_DELIVERY_METHOD` + +#### `SMTP_AUTH_METHOD` + +#### `SMTP_CA_FILE` + +#### `SMTP_OPENSSL_VERIFY_MODE` + +#### `SMTP_ENABLE_STARTTLS_AUTO` + +#### `SMTP_ENABLE_STARTTLS` + +可选的值有: `auto` (默认)、 `always` 或 `never`。 + +**版本历史：**\ +4.0.0 - 该配置被添加 + +#### `SMTP_TLS` + +#### `SMTP_SSL` + +电子邮件配置基于 Mastodon 所基于的 *Ruby on Rails* 框架的 *action_mailer* 组件。关于 action_mailer 的完整文档可在 [这里](https://guides.rubyonrails.org/action_mailer_basics.html#action-mailer-configuration) 获取。客户端使用 SMTP 或其衍生产品：StartTLS + SMTP 或 SMTPS (使用 TLS 的 SMTP)。 + +### 基础配置 {#basic} + +* `SMTP_SERVER`：指定要使用的服务器。例如 `sub.domain.tld`。 +* `SMTP_PORT`：默认值为 `25` (SMTP 的常用端口)。如果检测到 StartTLS，可能会切换到端口 `587`。 +* `SMTP_DOMAIN`：仅在需要 HELO 域时才需要。默认将设置为 `SMTP_SERVER` 域。 +* `SMTP_FROM_ADDRESS`：指定发件人地址。 +* `SMTP_DELIVERY_METHOD`：默认值为 `smtp` (也可以是 `sendmail`)。 + +### SMTP服务器的身份验证 {#smtpauthentication} + +* `SMTP_LOGIN`：SMTP 用户的登录名。 +* `SMTP_PASSWORD`：SMTP 用户的密码。 +* `SMTP_AUTH_METHOD`：可以是 `plain`(默认；密码以明文传输)、 `login`(密码将被base64编码)或 `cram_md5`。 + +### 安全 SMTP +默认情况下，将尝试与指定的 SMTP 服务器建立 StartTLS 连接。 + +* `SMTP_ENABLE_STARTTLS_AUTO`：默认为 `true`。 +* `SMTP_CA_FILE`：可以指定一个值，但在许多 Linux 发行版(如基于 Debian 的发行版)中，这将是 `/etc/ssl/certs/ca-certificates.crt`。 +* `SMTP_OPENSSL_VERIFY_MODE`：可以是 `none` 或 `peer`。使用 TLS 时，接受带有自签名证书的连接可能很有用。 +* `SMTP_TLS`：`true` 或 `false` (默认 `false`) +* `SMTP_SSL`：`true` 或 `false` (默认 `false`) + +请注意，目前只有 `TLSv1.3` 和 `TLSv1.2` 被认为是安全的SSL/TLS协议。 + +### Prometheus指标 {#prometheus} + +Mastodon 支持使用 Prometheus 格式公开一些指标，该配置是可选的。 + +对于 Ruby 进程，它使用 [`prometheus_exporter` gem](https://github.com/discourse/prometheus_exporter)。请参考其文档了解更多详情。 + +默认情况下，你需要运行 `prometheus_exporter` 服务器(使用 `./bin/prometheus_exporter`)来收集指标并公开它们以供抓取。如果你想更改此行为，请查看 `MASTODON_PROMETHEUS_EXPORTER_LOCAL`。 + +请注意， Prometheus 格式的指标始终对流服务端启用，并且可以在 `http://streaming-server-host:port/metrics` 访问。 + +**版本历史：**\ +4.4.0 - 该配置被添加对Ruby进程的支持 + +#### `MASTODON_PROMETHEUS_EXPORTER_ENABLED` + +若配置为 `true`， Mastodon 的 Ruby 进程(Web & Sidekiq)将启用 Prometheus 检测。 + +#### `MASTODON_PROMETHEUS_EXPORTER_WEB_DETAILED_METRICS` + +若配置为 `true`，检测服务将收集并公开每个 Web 请求的每个控制器/操作指标。请注意，这可能会导致一些资源开销。 + +#### `MASTODON_PROMETHEUS_EXPORTER_SIDEKIQ_DETAILED_METRICS` + +若配置为 `true`，检测服务将收集并公开每个 Sidekiq 作业的每个作业指标。请注意，这可能会导致一些资源开销。 + +#### `MASTODON_PROMETHEUS_EXPORTER_LOCAL` + +若配置为 `true`，将启动一个进程内服务器来公开指标，而不是尝试将它们发送到外部的 `prometheus_exporter` 服务器。在容器化环境中运行 Sidekiq 时，这可能很有用，以避免外部导出器的开销。指标将在 `http://host:port/metrics` 上公开。 + +重要提示：这对于多进程服务器(如 Puma)不起作用，因为每个进程都会尝试监听同一个端口并会失败。 + +#### `PROMETHEUS_EXPORTER_HOST` + +如果未启用进程内服务器，指标将发送到该主机(应该运行 `prometheus_exporter` 服务器)。默认为 `localhost`。 + +#### `PROMETHEUS_EXPORTER_PORT` + +如果未启用进程内服务器，指标将发送到该端口(应该运行 `prometheus_exporter` 服务器)。默认为 `9394`。 + +#### `MASTODON_PROMETHEUS_EXPORTER_HOST` + +如果启用了进程内服务器，进程内导出器将监听该主机。默认为`localhost` + +#### `MASTODON_PROMETHEUS_EXPORTER_PORT` + +如果启用了进程内服务器，进程内导出器将监听该端口。默认为`9394` + +### OpenTelemetry {#otel} + +Mastodon 支持使用 OpenTelemetry 协议导出跟踪数据。该检测使用标准 OTel Ruby SDK，应该支持[标准 OTel 环境配置变量](https://opentelemetry.io/docs/languages/sdk-configuration/general/)， `OTEL_SERVICE_NAME` 除外(参见下面的`OTEL_SERVICE_NAME_PREFIX`)。Mastodon 目前只提供 OLTP 导出器。 + +**版本历史：**\ +4.3.0 - 添加了对Ruby后端的支持 + +#### `OTEL_SERVICE_NAME_PREFIX` + +OTEL 服务名称的前缀。服务名称将是 `$prefix/web` 和 `$prefix/sidekiq`。默认为`mastodon`。 + +#### `OTEL_SERVICE_NAME_SEPARATOR` + +在区分不同服务时在服务名称中使用的字符。默认为 `/` (即 `mastodon/web`)。 + + +#### `OTEL_EXPORTER_OTLP_ENDPOINT` + +发送跟踪的 OLTP 服务器的 URL。如果未设置此变量，则禁用 OpenTelemetry 检测。没有默认值(空值)。 + +## 文件存储 {#files} + +### CDN {#cdn} + +#### `CDN_HOST` + +你可以从单独的域名(如 CDN(内容分发网络))提供静态资产(徽标、表情符号、 CSS、 JS等)，因为这可以减少用户的加载时间。 + +示例值： `https://assets.example.com` + +{{< hint style="info" >}} +提供文件时必须使用 CORS 标头，否则 Mastodon 的 Web UI 的某些功能将无法工作。例如可以提供如下标头: `Access-Control-Allow-Origin: *` +{{}} ### 本地文件存储 {#paperclip} -* `PAPERCLIP_ROOT_PATH` -* `PAPERCLIP_ROOT_URL` +#### `PAPERCLIP_ROOT_PATH` -### Amazon S3 及其兼容存储 {#s3} +#### `PAPERCLIP_ROOT_URL` -* `S3_ENABLED` -* `S3_BUCKET` -* `AWS_ACCESS_KEY_ID` -* `AWS_SECRET_ACCESS_KEY` -* `S3_REGION` -* `S3_PROTOCOL` -* `S3_HOSTNAME` -* `S3_ENDPOINT` -* `S3_SIGNATURE_VERSION` -* `S3_BATCH_DELETE_LIMIT` -* `S3_BATCH_DELETE_RETRY` +### AWS S3和兼容服务 {#s3} + +{{< page-ref page="admin/optional/object-storage" >}} + +存储桶必须支持访问控制列表 (ACLs)。对于 AWS S3，这意味着将"对象所有权"设置设为"已启用 ACL"。对于 Google Cloud Storage，这意味着将"访问控制"设置设为"细粒度"。 + +#### `S3_ENABLED` + +#### `S3_REGION` + +#### `S3_ENDPOINT` + +#### `S3_BUCKET` + +#### `AWS_ACCESS_KEY_ID` + +#### `AWS_SECRET_ACCESS_KEY` + +#### `S3_SIGNATURE_VERSION` + +#### `S3_OVERRIDE_PATH_STYLE` + + +#### `S3_PROTOCOL` + +#### `S3_HOSTNAME` + +#### `S3_ALIAS_HOST` + + +#### `S3_OPEN_TIMEOUT` + +#### `S3_READ_TIMEOUT` + +#### `S3_FORCE_SINGLE_REQUEST` + +#### `S3_ENABLE_CHECKSUM_MODE` + +#### `S3_STORAGE_CLASS` + +#### `S3_MULTIPART_THRESHOLD` + +#### `S3_PERMISSION` + +#### `S3_BATCH_DELETE_LIMIT` + +#### `S3_BATCH_DELETE_RETRY` ### Swift {#swift} -* `SWIFT_ENABLED` -* `SWIFT_USERNAME` -* `SWIFT_TENANT` -* `SWIFT_PASSWORD` -* `SWIFT_PROJECT_ID` -* `SWIFT_AUTH_URL` -* `SWIFT_CONTAINER` -* `SWIFT_OBJECT_URL` -* `SWIFT_REGION` -* `SWIFT_DOMAIN_NAME` -* `SWIFT_CACHE_TTL` +#### `SWIFT_ENABLED` + +#### `SWIFT_USERNAME` + +#### `SWIFT_TENANT` + +#### `SWIFT_PASSWORD` + +#### `SWIFT_PROJECT_ID` + +#### `SWIFT_AUTH_URL` + +#### `SWIFT_CONTAINER` + +#### `SWIFT_OBJECT_URL` + +#### `SWIFT_REGION` + +#### `SWIFT_DOMAIN_NAME` + +#### `SWIFT_CACHE_TTL` + +### HTTP 缓存清除器 + +若配置，当媒体文件从你的源站被删除或变为不可用时，缓存清除器会发送一个请求来使其缓存失效。这将确保任何已从 Mastodon 中移除的内容都会被从你的缓存层/CDN 中清除。 + +{{< hint style="info" >}} +实现此目的的方式非常依赖于你的代理/CDN提供商，并且需要配置。如果你使用 nginx 进行 HTTP 缓存，你应该查看 `proxy_cache_purge` 配置指令。 +{{}} + +#### `CACHE_BUSTER_ENABLED` + +若配置为 `true`，那么 Mastodon 在删除文件时将向媒体 URL 发送缓存清除请求，以便可以从缓存中清除文件。 + +默认为 `false` + +#### `CACHE_BUSTER_HTTP_METHOD` + +默认为 `GET` + +#### `CACHE_BUSTER_SECRET_HEADER` + +包含 `CACHE_BUSTER_SECRET` 中定义的密钥的标头名称。 + +默认为空值，表示不会添加标头 + +#### `CACHE_BUSTER_SECRET` + +上面配置的 `CACHE_BUSTER_SECRET_HEADER` 标头的值。 ## 外部认证 {#external-authentication} -* `OAUTH_REDIRECT_AT_SIGN_IN` +### OmniAuth + +#### `ALLOW_UNSAFE_AUTH_PROVIDER_REATTACH` +允许现有用户使用他们以前未使用过的外部认证提供商登录，前提是他们使用相同的电子邮件地址。如果你想提供用户在不同外部提供商之间迁移的能力，该选项可能很有用，但这会构成潜在的安全风险，如果攻击者设法在你配置的任何提供商上使用要攻击的目标账号的邮件地址创建一个新的身份，就可以劫持该账号。 + +**版本历史：**\ +4.2.6 - 该配置被添加 + +#### `OMNIAUTH_ONLY` + +#### `ONE_CLICK_SSO_LOGIN` +启用`登录或注册`按钮。 +对于全部使用单个外部提供商(CAS、SAML或OIDC)进行认证的实例很有用。 + +启用此功能将阻止匿名会话的缓存。 +另外，当使用OIDC发现时，身份提供商必须在 Mastodon 启动前可用。 ### LDAP {#ldap} -* `LDAP_ENABLED` -* `LDAP_HOST` -* `LDAP_PORT` -* `LDAP_METHOD` -* `LDAP_BASE` -* `LDAP_BIND_DN` -* `LDAP_PASSWORD` -* `LDAP_UID` -* `LDAP_SEARCH_FILTER` +#### `LDAP_ENABLED` + +#### `LDAP_HOST` + +#### `LDAP_PORT` + +#### `LDAP_METHOD` + +#### `LDAP_BASE` + +#### `LDAP_BIND_DN` + +#### `LDAP_PASSWORD` + +#### `LDAP_UID` + +#### `LDAP_SEARCH_FILTER` + +#### `LDAP_MAIL` + +#### `LDAP_UID_CONVERSION_ENABLED` ### PAM {#pam} -* `PAM_ENABLED` -* `PAM_EMAIL_DOMAIN` -* `PAM_DEFAULT_SERVICE` -* `PAM_CONTROLLED_SERVICE` +#### `PAM_ENABLED` + +#### `PAM_EMAIL_DOMAIN` + +#### `PAM_DEFAULT_SERVICE` + +#### `PAM_CONTROLLED_SERVICE` ### CAS {#cas} -* `CAS_ENABLED` -* `CAS_URL` -* `CAS_HOST` -* `CAS_PORT` -* `CAS_SSL` -* `CAS_VALIDATE_URL` -* `CAS_CALLBACK_URL` -* `CAS_LOGOUT_URL` -* `CAS_LOGIN_URL` -* `CAS_UID_FIELD` -* `CAS_CA_PATH` -* `CAS_DISABLE_SSL_VERIFICATION` -* `CAS_UID_KEY` -* `CAS_NAME_KEY` -* `CAS_EMAIL_KEY` -* `CAS_NICKNAME_KEY` -* `CAS_FIRST_NAME_KEY` -* `CAS_LAST_NAME_KEY` -* `CAS_LOCATION_KEY` -* `CAS_IMAGE_KEY` -* `CAS_PHONE_KEY` +#### `CAS_ENABLED` + +#### `CAS_DISPLAY_NAME` + +#### `CAS_URL` + +#### `CAS_HOST` + +#### `CAS_PORT` + +#### `CAS_SSL` + +#### `CAS_VALIDATE_URL` + +#### `CAS_CALLBACK_URL` + +#### `CAS_LOGOUT_URL` + +#### `CAS_LOGIN_URL` + +#### `CAS_UID_FIELD` + +#### `CAS_CA_PATH` + +#### `CAS_DISABLE_SSL_VERIFICATION` + +#### `CAS_UID_KEY` +用于账户的用户名的键。 +创建的账户将是`@uid@domain.tld`。 + +#### `CAS_NAME_KEY` + +#### `CAS_EMAIL_KEY` + +#### `CAS_NICKNAME_KEY` + +#### `CAS_FIRST_NAME_KEY` + +#### `CAS_LAST_NAME_KEY` + +#### `CAS_LOCATION_KEY` + +#### `CAS_IMAGE_KEY` +用作账户头像的图像的键。 +此键中的值必须是图像文件的URL。 +需使用支持的文件格式(JPEG 或 PNG，而非 SVG)很重要。 + +#### `CAS_PHONE_KEY` + +#### `CAS_SECURITY_ASSUME_EMAIL_IS_VERIFIED` ### SAML {#saml} -* `SAML_ENABLED` -* `SAML_ACS_URL` -* `SAML_ISSUER` -* `SAML_IDP_SSO_TARGET_URL` -* `SAML_IDP_CERT` -* `SAML_IDP_CERT_FINGERPRINT` -* `SAML_NAME_IDENTIFIER_FORMAT` -* `SAML_CERT` -* `SAML_PRIVATE_KEY` -* `SAML_SECURITY_WANT_ASSERTION_SIGNED` -* `SAML_SECURITY_WANT_ASSERTION_ENCRYPTED` -* `SAML_SECURITY_ASSUME_EMAIL_IS_VERIFIED` -* `SAML_ATTRIBUTES_STATEMENTS_UID` -* `SAML_ATTRIBUTES_STATEMENTS_EMAIL` -* `SAML_ATTRIBUTES_STATEMENTS_FULL_NAME` -* `SAML_ATTRIBUTES_STATEMENTS_FIRST_NAME` -* `SAML_ATTRIBUTES_STATEMENTS_LAST_NAME` -* `SAML_UID_ATTRIBUTE` -* `SAML_ATTRIBUTES_STATEMENTS_VERIFIED` -* `SAML_ATTRIBUTES_STATEMENTS_VERIFIED_EMAIL` +#### `SAML_ENABLED` + +#### `SAML_ACS_URL` + +#### `SAML_ISSUER` + +#### `SAML_IDP_SSO_TARGET_URL` + +#### `SAML_IDP_CERT` + +#### `SAML_IDP_CERT_FINGERPRINT` + +#### `SAML_NAME_IDENTIFIER_FORMAT` + +#### `SAML_CERT` + +#### `SAML_PRIVATE_KEY` + +#### `SAML_SECURITY_WANT_ASSERTION_SIGNED` + +#### `SAML_SECURITY_WANT_ASSERTION_ENCRYPTED` + +#### `SAML_SECURITY_ASSUME_EMAIL_IS_VERIFIED` + +#### `SAML_ATTRIBUTES_STATEMENTS_UID` + +#### `SAML_ATTRIBUTES_STATEMENTS_EMAIL` + +#### `SAML_ATTRIBUTES_STATEMENTS_FULL_NAME` + +#### `SAML_ATTRIBUTES_STATEMENTS_FIRST_NAME` + +#### `SAML_ATTRIBUTES_STATEMENTS_LAST_NAME` + +#### `SAML_UID_ATTRIBUTE` + +#### `SAML_ATTRIBUTES_STATEMENTS_VERIFIED` + +#### `SAML_ATTRIBUTES_STATEMENTS_VERIFIED_EMAIL` ## 隐藏服务 {#hidden-services} -* `http_proxy` -* `ALLOW_ACCESS_TO_HIDDEN_SERVICE` +### TOR {#tor} -## 其它 {#other} +{{< page-ref page="admin/optional/tor" >}} -* `SKIP_POST_DEPLOYMENT_MIGRATIONS` +#### `http_proxy` -{{< translation-status-zh-cn raw_title="Configuring your environment" raw_link="/admin/config/" last_tranlation_time="2020-05-04" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}} +#### `http_hidden_proxy` + +#### `ALLOW_ACCESS_TO_HIDDEN_SERVICE` + +## 限制 {#limits} + +### 反垃圾信息/滥用 + +#### `HCAPTCHA_SITE_KEY` +#### `HCAPTCHA_SECRET_KEY` + +若配置，注册确认页面将显示验证码，请查看[验证码](https://docs.joinmastodon.org/admin/optional/captcha/) + +### 电子邮件域名 + +#### `EMAIL_DOMAIN_ALLOWLIST` + +若配置，将只允许使用指定域名的邮箱注册，**排除**其他所有域名。域名以竖线`|`分隔，例如：`foo.com|bar.com` + +#### `EMAIL_DOMAIN_DENYLIST` {{%deprecated%}} + +若配置，将不允许使用指定域名的邮箱注册。域名以竖线`|`分隔，例如：`foo.com|bar.com` + +{{< hint style="warning" >}} +此选项已被弃用。你可以通过管理界面或`tootctl`命令行界面动态调整邮箱域名阻止列表。 +{{}} + +### 会话 + +#### `MAX_SESSION_ACTIVATIONS` + +定义每个用户允许的浏览器会话的最大数量，默认为 10。如果创建了一个新的浏览器会话并且超出了限制，则最旧的会话将被删除，导致用户从该会话中注销。 + +### 主页提要 + +#### `USER_ACTIVE_DAYS` + +Mastodon 在 RAM 中存储主页信息流(具体而言，信息流存储于 Redis 数据库中)。这使得它们可以被非常快速地访问和更新，但这也意味着如果它们不被使用，你可能不希望把它们保留在那里，而且你可能不想花费资源将新条目插入到不会被访问的主页信息流中。因此， Mastodon 会定期清除一段时间内未上线的用户的主页信息流，如果他们重新出现，服务端会从数据库数据中重新生成这些主页信息流。默认情况下，如果用户在过去 `7` 天内上线，则被视为活跃用户。 + +主页信息流的重新生成在计算上是昂贵的，如果你的 Sidekiq 不断地执行这项工作，是因为你的用户每3天上线一次，但你的 `USER_ACTIVE_DAYS` 设置为2，那么请考虑调整它。 + +{{< hint style="info" >}} +此设置与用于统计目的的活跃用户数(例如月活跃用户数)判定无关。 +{{}} + +## 其他 {#other} + +### 数据库迁移 {#migrations} + +#### `SKIP_POST_DEPLOYMENT_MIGRATIONS` + +此变量仅在运行 `rake db:migrate` 时有效，它只与 Mastodon 升级过程有关。有两种类型的数据库迁移，一种是在新代码部署和运行之前运行的，另一种是在之后运行的。默认情况下，这两种类型的迁移都会执行。如果你在运行迁移之前关闭了所有 Mastodon 进程，那么就没有区别。该变量对于零停机时间升级是有意义的。在特定 Mastodon 版本的升级说明中，你将看到是否需要使用它。 + +### 数据库加密支持 + +必须设置以下三个环境变量才能启用 Rails 中的 Active Record 加密功能， Mastodon 使用该功能来加密和解密某些数据库属性。 + +- `ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY` +- `ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY` +- `ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT` + +**版本历史：**\ +4.3.0 - 该配置被添加 + +### StatsD(在4.3.0中移除) {#statsd} + +{{< hint style="danger" >}} +StatsD 支持在 Mastodon 4.2.0 中已弃用，并在 4.3.0 中被完全移除。 +{{< /hint >}} + +#### `STATSD_ADDR` + +若配置， Mastodon 将把一些事件和指标记录到由其主机名和端口标识的StatsD实例中。 + +示例值：`localhost:8125` + +#### `STATSD_NAMESPACE` + +若配置，所有 StatsD 键将以此为前缀。当 `RAILS_ENV` 为 `production` 时默认为 `Mastodon.production`，当为 `development` 时默认为 `Mastodon.development`，等等。 + +#### `STATSD_SIDEKIQ` + +若配置为 `true`，Mastodon 将一些 Sidekiq 指标记录到 StatsD 中。默认为 `false`。 + +### 未分类或未排序 + +#### `BUNDLE_GEMFILE` + +#### `DEEPL_API_KEY` + +#### `DEEPL_PLAN` + +#### `ENABLE_SIDEKIQ_UNIQUE_JOBS_UI` + +启用 `sidekiq-unique-jobs` 的 Web 界面。这可以用于查看和清除此 gem 管理的锁，但在实践中很少有用，并且过去存在过关键的安全漏洞。 +如果你只需要清除所有锁，你现在可以使用新添加的 `bundle exec rake sidekiq_unique_jobs:delete_all_locks`。 + +**版本历史：**\ +4.2.6 - 该配置被添加 + +#### `LIBRE_TRANSLATE_ENDPOINT` + +#### `LIBRE_TRANSLATE_API_KEY` + +#### `GITHUB_REPOSITORY` + +默认为 `mastodon/mastodon` + +#### `SOURCE_BASE_URL` + +默认为`https://github.com/$GITHUB_REPOSITORY` + +#### `FFMPEG_BINARY` + +默认为空值(未启用) + +#### `LOCAL_HTTPS` + +#### `PATH` + +#### `MAX_FOLLOWS_THRESHOLD` + +默认为 `7500` + +#### `MAX_FOLLOWS_RATIO` + +默认为 `1.1` + +#### `IP_RETENTION_PERIOD` + +默认为 `31536000`(1年) + +#### `SESSION_RETENTION_PERIOD` + +默认为 `31536000`(1年) + +#### `BACKTRACE` + +设置为 `1` 以允许回溯 Rails 框架代码。 + +#### `DISABLE_SIMPLECOV` + +#### `EMAIL_DOMAIN_LISTS_APPLY_AFTER_CONFIRMATION` + +#### `DISABLE_FOLLOWERS_SYNCHRONIZATION` + +#### `MAX_REQUEST_POOL_SIZE` + +默认为 `512`。 + +#### `GITHUB_API_TOKEN` + +用于从 GitHub 提交历史生成 `AUTHORS.md` 的 rake 任务。 + +{{< translation-status-zh-cn raw_title="Configuring your environment" raw_link="/admin/config/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/elasticsearch.md b/content/zh-cn/admin/elasticsearch.md new file mode 100644 index 0000000..176058a --- /dev/null +++ b/content/zh-cn/admin/elasticsearch.md @@ -0,0 +1,250 @@ +--- +title: 配置全文搜索 +description: 设置 Elasticsearch 以搜索嘟文(包括创建的嘟文、喜欢的嘟文和被提及的嘟文)、可公开索引的嘟文与账号 +aliases: +- /admin/optional/elasticsearch +menu: + docs: + weight: 40 + parent: admin +--- + +当 Elasticsearch 可用时，Mastodon 支持全文搜索。强烈建议配置此功能。 + +Mastodon 的全文搜索允许已登录用户查找以下内容： +- 选择在搜索结果中显示的账号发布的公开嘟文 +- 自己创建的嘟文 +- 提及自己的嘟文 +- 自己喜欢的嘟文 +- 自己收藏的嘟文 +- 账号(显示名称、用户名和简介) + +全文搜索有意不允许在整个数据库中搜索任意字符串。 + +## 安装 Elasticsearch {#install} + +{{< hint style="info" >}} +Mastodon 经过测试与 Elasticsearch 7 版本兼容。它理论上也支持 OpenSearch 以及 Elasticsearch 6 和 8 版本，但这些设置不受官方支持。 +{{< /hint >}} + +Elasticsearch 需要 Java 运行环境。如果你尚未安装 Java，请立即进行安装。假设你以 `root` 用户身份登录： + +```bash +apt install openjdk-17-jre-headless +``` + +将 Elasticsearch 官方仓库添加到 apt： + +```bash +wget -O /usr/share/keyrings/elasticsearch.asc https://artifacts.elastic.co/GPG-KEY-elasticsearch +echo "deb [signed-by=/usr/share/keyrings/elasticsearch.asc] https://artifacts.elastic.co/packages/7.x/apt stable main" > /etc/apt/sources.list.d/elastic-7.x.list +``` + +现在你可以安装 Elasticsearch： + +```bash +apt update +apt install elasticsearch +``` + +{{< hint style="warning" >}} +**安全警告：** 默认情况下， Elasticsearch 应仅绑定到 `localhost`，即无法从外部网络访问。你可以通过查看 `/etc/elasticsearch/elasticsearch.yml` 中的 `network.host` 来检查 Elasticsearch 绑定的地址。请考虑到任何能够访问 Elasticsearch 的人都可以访问和修改其中的任何数据，因为没有认证层。所以确保访问安全非常重要。建议使用防火墙，只开放 22、 80 和 443 端口，如[主安装说明](../../prerequisites/#install-a-firewall-and-only-whitelist-ssh-http-and-https-ports)中所述。如果你有多主机设置，你必须了解如何保护内部流量安全。 +{{< /hint >}} + +启动 Elasticsearch： + +```bash +systemctl daemon-reload +systemctl enable --now elasticsearch +``` + +## 配置 Mastodon {#config} + +编辑 `.env.production` 以添加以下变量： + +```bash +ES_ENABLED=true +ES_HOST=localhost +ES_PORT=9200 +ES_PRESET= # single_node_cluster, small_cluster或large_cluster +# ES_USER= +# ES_PASS= +``` + +_注意_：如果使用 TLS，请在主机名前加上 `https://`。例如：`https://elastic.example.com`。 + +### 选择正确的预设 + +`ES_PRESET` 的值取决于你的 Elasticsearch 规模，它将用于为你的索引设置最适合你设置的分片和副本数量： +- `single_node_cluster` 如果你的 Elasticsearch 集群中只有一个节点。索引将配置为无副本 +- `small_cluster` 如果你的集群少于 6 个节点。索引将配置为单副本 +- `large_cluster` 如果你的集群有 6 个或更多节点。索引将较之 `small_cluster` 配置更多的分片，以便它们可以分布在更多节点上 + +如果你在同一台机器上有多个 Mastodon 服务器，并且计划为所有这些服务器使用相同的 Elasticsearch 实例，请确保它们都在配置中设置了唯一的 `REDIS_NAMESPACE`，以区分索引。如果你需要覆盖 Elasticsearch 索引的前缀，可以直接设置 `ES_PREFIX`。 + +### 安全性 + +默认情况下，Elasticsearch 不处理任何认证，所有请求都以完全管理员权限进行。我们强烈建议你在集群上配置 Elasticsearch 安全功能。 + +要进行配置，请参考[官方文档](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/security-minimal-setup.html)。它将指导你进行以下操作： +- 启用安全功能（`xpack.security.enabled: true`） +- 为内置用户创建密码 + +完成后，你可以创建自定义用户组供 Mastodon 连接。 + +例如（可以参考此段命令并使用你的 Elastic 管理员密码）： + +```sh +curl -X POST -u elastic:admin_password "localhost:9200/_security/role/mastodon_full_access?pretty" -H 'Content-Type: application/json' -d' +{ + "cluster": ["monitor"], + "indices": [{ + "names": ["*"], + "privileges": ["read", "monitor", "write", "manage"] + }] +} +' +``` + +[Elasticsearch用户组创建文档](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/security-api-put-role.html) + +创建用户组后，你可以为Mastodon服务器创建用户，并为其分配用户组。 + +例如（请调整此片段以使用你的Elastic管理员密码，并自定义你新`mastodon`用户的密码）： + +```sh +curl -X POST -u elastic:admin_password "localhost:9200/_security/user/mastodon?pretty" -H 'Content-Type: application/json' -d' +{ + "password" : "l0ng-r4nd0m-p@ssw0rd", + "roles" : ["mastodon_full_access"] +} +' +``` + +[Elasticsearch用户创建文档](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/security-api-put-user.html) + +完成后，你需要配置 Mastodon 使用新创建用户的凭据。 + +然后在 `.env.production` 中，调整你的配置： + +```bash +ES_USER=mastodon +ES_PASS=l0ng-r4nd0m-p@ssw0rd +``` + +设置完成，你的 Elasticsearch 实例应该更安全了！ + +### 填充索引 + +保存新配置后，重启 Mastodon 进程使其生效： + +```bash +systemctl restart mastodon-sidekiq +systemctl reload mastodon-web +``` + +现在是时候创建 Elasticsearch 索引并填充数据了： + +```bash +su - mastodon +cd live +RAILS_ENV=production bin/tootctl search deploy +``` + +{{< hint style="info" >}} +创建 Elasticsearch 索引可能需要 JVM（Java 虚拟机）提供的更多内存。如果 Elasticsearch 在创建索引时崩溃，请尝试分配更多内存。 + +1. 在 `/etc/elasticsearch/jvm.options.d/` 目录下创建并打开一个文件（例如：`nano /etc/elasticsearch/jvm.options.d/ram.options`） +2. 添加以下文本并根据需求编辑分配的内存。根据经验， Elasticsearch 应使用你可用内存的25%-50%。请不要分配超过可用内存的内存量。 +``` +# Xms表示总堆空间的初始大小 +# Xmx表示总堆空间的最大大小 +# 两个值应该相同 +-Xms2048m +-Xmx2048m +``` +3. 保存文件。 +4. 使用 `systemctl restart elasticsearch` 重启 Elasticsearch。 +5. 重试创建 Elasticsearch 索引。如果 Elasticsearch 仍然崩溃，请尝试设置更高的数值。 +{{< /hint >}} + +## 其他语言的搜索优化 +### 中文搜索优化 {#chinese-search-optimization} + +标准分析器是 Elasticsearch 的默认分析器，但对于中文等某些语言来说，它可能不是最佳选择。要增强搜索体验，请考虑安装特定语言的分析器。在 Elasticsearch 中创建索引之前，请确保安装以下扩展： + +- [elasticsearch-analysis-ik](https://github.com/medcl/elasticsearch-analysis-ik) +- [elasticsearch-analysis-stconvert](https://github.com/medcl/elasticsearch-analysis-stconvert) + +然后按如下方式修改 Mastodon 的索引定义： + +```diff +diff --git a/app/chewy/accounts_index.rb b/app/chewy/accounts_index.rb +--- a/app/chewy/accounts_index.rb ++++ b/app/chewy/accounts_index.rb +@@ -4,7 +4,7 @@ class AccountsIndex < Chewy::Index + settings index: { refresh_interval: '5m' }, analysis: { + analyzer: { + content: { +- tokenizer: 'whitespace', ++ tokenizer: 'ik_max_word', + filter: %w(lowercase asciifolding cjk_width), + }, + +diff --git a/app/chewy/statuses_index.rb b/app/chewy/statuses_index.rb +--- a/app/chewy/statuses_index.rb ++++ b/app/chewy/statuses_index.rb +@@ -16,9 +16,17 @@ class StatusesIndex < Chewy::Index + language: 'possessive_english', + }, + }, ++ char_filter: { ++ tsconvert: { ++ type: 'stconvert', ++ keep_both: false, ++ delimiter: '#', ++ convert_type: 't2s', ++ }, ++ }, + analyzer: { + content: { +- tokenizer: 'uax_url_email', ++ tokenizer: 'ik_max_word', + filter: %w( + english_possessive_stemmer + lowercase +@@ -27,6 +35,7 @@ class StatusesIndex < Chewy::Index + english_stop + english_stemmer + ), ++ char_filter: %w(tsconvert), + }, + }, + } +diff --git a/app/chewy/tags_index.rb b/app/chewy/tags_index.rb +--- a/app/chewy/tags_index.rb ++++ b/app/chewy/tags_index.rb +@@ -2,10 +2,19 @@ + + class TagsIndex < Chewy::Index + settings index: { refresh_interval: '15m' }, analysis: { ++ char_filter: { ++ tsconvert: { ++ type: 'stconvert', ++ keep_both: false, ++ delimiter: '#', ++ convert_type: 't2s', ++ }, ++ }, + analyzer: { + content: { +- tokenizer: 'keyword', ++ tokenizer: 'ik_max_word', + filter: %w(lowercase asciifolding cjk_width), ++ char_filter: %w(tsconvert), + }, + + edge_ngram: { +``` + +{{< translation-status-zh-cn raw_title="Configuring full-text search" raw_link="/admin/elasticsearch/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/install.md b/content/zh-cn/admin/install.md index 6e9f7dc..4caa6b9 100644 --- a/content/zh-cn/admin/install.md +++ b/content/zh-cn/admin/install.md @@ -1,6 +1,6 @@ --- -title: 从源中安装 -description: 创建你自己的Mastodon站点的教学指献。 +title: 从源代码安装 +description: 创建你自己的 Mastodon 站点的教程。 menu: docs: weight: 20 @@ -9,105 +9,84 @@ menu: ## 前提条件 {#pre-requisites} -* 一台你有root访问权限的运行 **Ubuntu 18.04** 的机器 -* 一个用于Mastodon站点的**域名**（或一个子域名），例如：`example.com` -* 一个电子邮件发送服务提供商，或其他**SMTP服务器** +* 一台运行 **Ubuntu 24.04** 或 **Debian 12** 的机器，你需要拥有root访问权限 +* 一个用于 Mastodon 站点的**域名**（或子域名），例如 `example.com` +* 一个电子邮件发送服务或其他 **SMTP 服务器** -你需要使用root用户运行命令。如果你现在不是root用户，请切换至root用户： +在以下示例中，我们将使用 `example.com` 作为域名。请记得在运行任何命令前将其替换为你自己的域名。 -### 软件仓库 {#system-repositories} +你将以 root 身份运行命令。如果你还不是 root 用户，请切换到 root：`sudo -i` -首先确保已经安装curl： +### 系统存储库 {#system-repositories} + +首先确保已安装 curl、 wget、 gnupg、 apt-transport-https、 lsb-release 和 ca-certificates： + +```bash +apt install -y curl wget gnupg apt-transport-https lsb-release ca-certificates +``` #### Node.js {#node-js} ```bash -curl -sL https://deb.nodesource.com/setup_12.x | bash - +curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg +echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list ``` -#### Yarn {#yarn} +#### PostgreSQL {#postgresql} ```bash -curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list +wget -O /usr/share/keyrings/postgresql.asc https://www.postgresql.org/media/keys/ACCC4CF8.asc +echo "deb [signed-by=/usr/share/keyrings/postgresql.asc] http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/postgresql.list ``` -### 软件包 {#system-packages} +### 系统软件包 {#system-packages} ```bash apt update apt install -y \ - imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev file git-core \ - g++ libprotobuf-dev protobuf-compiler pkg-config nodejs gcc autoconf \ + imagemagick ffmpeg libvips-tools libpq-dev libxml2-dev libxslt1-dev file git-core \ + g++ libprotobuf-dev protobuf-compiler pkg-config gcc autoconf \ bison build-essential libssl-dev libyaml-dev libreadline6-dev \ - zlib1g-dev libncurses5-dev libffi-dev libgdbm5 libgdbm-dev \ - nginx redis-server redis-tools postgresql postgresql-contrib \ - certbot python-certbot-nginx yarn libidn11-dev libicu-dev libjemalloc-dev + zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev \ + nginx nodejs redis-server redis-tools postgresql postgresql-contrib \ + certbot python3-certbot-nginx libidn11-dev libicu-dev libjemalloc-dev ``` -### 安装 Ruby {#installing-ruby} +#### Yarn {#yarn} -因为使用 rbenv 可以更容易的获得正确的版本并在新版本发布后进行更新，我们将使用 rbenv 来管理Ruby版本。rbenv 必须安装在单个Linux用户中，因此，我们首先需要使用以下命令创建一个Mastodon用户： +启用`corepack`，以便自动安装正确版本的`yarn`： ```bash -adduser --disabled-login mastodon +corepack enable ``` -切换到mastodon用户： +### 创建 `mastodon` 用户 {#creating-the-mastodon-user} + +执行以下命令，创建用于运行 Mastodon 的用户： ```bash -su - mastodon -``` - -执行以下步骤安装 rbenv 和 rbenv-build： - -```bash -git clone https://github.com/rbenv/rbenv.git ~/.rbenv -cd ~/.rbenv && src/configure && make -C src -echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc -echo 'eval "$(rbenv init -)"' >> ~/.bashrc -exec bash -git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build -``` - -上述操作完成，我们便可以安装正确的 Ruby 版本： - -```bash -RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 2.6.6 -rbenv global 2.6.6 -``` - -我们同样需要安装 bundler： - -```bash -gem install bundler --no-document -``` - -返回root用户： - -```bash -exit +adduser --disabled-password mastodon ``` ## 配置 {#setup} ### 配置 PostgreSQL {#setting-up-postgresql} -#### 性能调优（可选） {#performance-configuration-optional} +#### 性能配置（可选） {#performance-configuration-optional} -为了优化性能，你可以使用 [pgTune](https://pgtune.leopard.in.ua/#/) 生成一个合适的配置文件。编辑 `/etc/postgresql/9.6/main/postgresql.conf` 中的相应数值并使用 `systemctl restart postgresql` 命令重启 PostgreSQL。 +为获得最佳性能，你可以使用 [pgTune](https://pgtune.leopard.in.ua/#/) 生成适当的配置，并在使用 `systemctl restart postgresql` 重启 PostgreSQL 之前编辑 `/etc/postgresql/17/main/postgresql.conf` 中的值。 -#### 创建帐户 {#creating-a-user} +#### 创建用户 {#creating-a-user} -你需创建一个供Mastodon使用的PostgreSQL帐户。创建一个使用“ident”认证方式的帐户是最容易的配置方法，即PostgreSQL帐户不需要独立的密码并由同名Linux用户使用。 +你需要创建一个供 Mastodon 使用的 PostgreSQL 用户。在简单配置中，最简单的方法是使用 "ident" 认证，即 PostgreSQL 用户没有单独的密码，可以由具有相同用户名的 Linux 用户使用。 -打开控制台： +打开命令行： ```bash sudo -u postgres psql ``` -在控制台中执行： +在命令行中执行： ```sql CREATE USER mastodon CREATEDB; @@ -116,9 +95,9 @@ CREATE USER mastodon CREATEDB; 完成！ -### 配置 Mastodon {#setting-up-mastodon} +### 设置 Mastodon {#setting-up-mastodon} -现在该下载Mastodon代码了。切换至mastodon用户： +现在是下载 Mastodon 代码的时候了。切换到 mastodon 用户： ```bash su - mastodon @@ -126,111 +105,140 @@ su - mastodon #### 检出代码 {#checking-out-the-code} -使用git下载最新稳定版Mastodon： +使用 git 下载 Mastodon 的最新稳定版本： ```bash git clone https://github.com/mastodon/mastodon.git live && cd live -git checkout $(git tag -l | grep -v 'rc[0-9]*$' | sort -V | tail -n 1) +git checkout $(git tag -l | grep '^v[0-9.]*$' | sort -V | tail -n 1) ``` -#### 安装依赖 {#installing-the-last-dependencies} +#### 安装 Ruby {#installing-ruby} -现在，安装Ruby和JavaScript依赖： +我们将使用 rbenv 来管理 Ruby 版本，因为它简化了获取正确版本和在新版本可用时进行更新的过程。 +安装 rbenv 和 ruby-build： + +```bash +git clone https://github.com/rbenv/rbenv.git ~/.rbenv +echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc +echo 'eval "$(rbenv init -)"' >> ~/.bashrc +exec bash +git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build +``` + +完成这些后，我们可以安装正确的Ruby版本： + +```bash +RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install +``` + +#### 安装最后的依赖项 {#installing-the-last-dependencies} + +现在安装 Ruby 和 JavaScript 依赖项： ```bash bundle config deployment 'true' bundle config without 'development test' bundle install -j$(getconf _NPROCESSORS_ONLN) -yarn install --pure-lockfile +yarn install ``` {{< hint style="info" >}} -两个`bundle config`命令仅仅第一次安装依赖时需要。如果你之后进行升级或重安装依赖，只需要`bundle install`就够了。 +仅在首次安装依赖项时需要执行两个 `bundle config` 命令。如果你之后要更新或重新安装依赖项，只需执行 `bundle install` 就足够了。 {{< /hint >}} -#### 生成配置文件 {#generating-a-configuration} +#### 生成配置 {#generating-a-configuration} -运行交互式安装向导： +运行交互式设置向导： ```bash -RAILS_ENV=production bundle exec rake mastodon:setup +RAILS_ENV=production bin/rails mastodon:setup ``` -它将： +这将： * 创建一个配置文件 -* 预编译静态文件 -* 创建数据库schema +* 运行资源预编译 +* 创建数据库架构 -配置文件被保存在`.env.production`。如果你愿意的话，你可以查看并编辑这个文件。请参阅[配置文件的文档]({{< relref "config" >}})。 +配置文件保存为 `.env.production`。你可以查看并按照喜好编辑它。请参考[配置文档]({{< relref "config" >}})。 -你已经完成需使用mastodon用户进行的操作，请切换回root用户： +现在你已完成 mastodon 用户的操作，切回 root 用户： ```bash exit ``` -### 配置 nginx {#setting-up-nginx} +### 获取SSL证书 {#acquiring-a-ssl-certificate} -从Mastodon目录复制配置文件模版到nginx： +我们将使用 Let's Encrypt 获取免费的 SSL 证书： + +```bash +certbot certonly --nginx -d example.com +``` + +这将获取证书并将其保存在 `/etc/letsencrypt/live/example.com/` 目录下。 + +### 设置nginx {#setting-up-nginx} + +从 Mastodon 目录复制 nginx 的配置模板： ```bash cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/mastodon +rm /etc/nginx/sites-enabled/default ``` -编辑 `/etc/nginx/sites-available/mastodon` +然后编辑 `/etc/nginx/sites-available/mastodon` 以 -1. 替换 `example.com` 为你自己的域名 -2. 启用 `ssl_certificate` 和 `ssl_certificate_key` 这两行，并把它们替换成如下两行（如果你使用自己的证书的话则可以忽略这一步） +1. 将 `example.com` 替换为你自己的域名 +2. 取消注释 `ssl_certificate` 和 `ssl_certificate_key`（如果你使用自己的证书，请忽略此步骤）： -``` -ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem; -ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key; -``` + ``` + ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;; + ``` -3. 你还可以根据自己的需求做出其它的一些调整。 +3. 进行你可能需要的任何其他调整。 -重载 nginx 以使变更生效： - -### 获取SSL证书 {#acquiring-a-ssl-certificate} - -我们将使用 Let’s Encrypt 获取一个免费的SSL证书： +允许其他用户遍历 mastodon 用户的主目录，以便 nginx 的 `www-data` 用户可以访问资源文件： ```bash -certbot --nginx -d example.com +chmod o+x /home/mastodon ``` -这个命令将获取一个证书，自动更新 `/etc/nginx/sites-available/mastodon` 以使用新证书并重载nginx以使变更生效。 - -现在你应该能够通过浏览器访问你的域名，然后看到一只大象锤击电脑屏幕的错误页面。这是因为我们还没有启动Mastodon进程。 - -### 配置 systemd 服务 {#setting-up-systemd-services} - -从Mastodon目录复制systemd服务模版： +重启 nginx 使更改生效： ```bash +systemctl restart nginx +``` + +此时，你应该能够在浏览器中访问你的域名，看到大象撞击电脑屏幕的错误页面。这是因为我们还没有启动 Mastodon 进程。 + +### 设置 systemd 服务 {#setting-up-systemd-services} + +从 Mastodon 目录复制 systemd 服务模板： + +```sh cp /home/mastodon/live/dist/mastodon-*.service /etc/systemd/system/ ``` -然后修改以下文件，以保证用户名与路径是正确的： +如果你修改了默认设置，请检查用户名和路径是否正确： -* `/etc/systemd/system/mastodon-web.service` -* `/etc/systemd/system/mastodon-sidekiq.service` -* `/etc/systemd/system/mastodon-streaming.service` - -最后，启动新systemd服务并将该服务设为开机自动激活： - -```bash -systemctl daemon-reload -systemctl start mastodon-web mastodon-sidekiq mastodon-streaming -systemctl enable mastodon-* +```sh +$EDITOR /etc/systemd/system/mastodon-*.service ``` -他们将在开机启动时自动开始运行。 +最后，启动并启用新的 systemd 服务： + +```sh +systemctl daemon-reload +systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming +``` + +Mastodon 服务现在将在开机时自动启动。 {{< hint style="success" >}} -**欢呼吧！你现在可以从浏览器中访问你的域名了！** +**太好了！以上就是安装 Mastodon 的全部步骤。现在你可以在浏览器中访问你的站点了！** {{< /hint >}} -{{< translation-status-zh-cn raw_title="Installing from source" raw_link="/admin/install/" last_tranlation_time="2020-05-04" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}} +{{< translation-status-zh-cn raw_title="Installing from source" raw_link="/admin/install/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/migrating.md b/content/zh-cn/admin/migrating.md index c191069..6a10a8e 100644 --- a/content/zh-cn/admin/migrating.md +++ b/content/zh-cn/admin/migrating.md @@ -1,95 +1,154 @@ --- title: 迁移到新机器 -description: 在不损失任何东西的情况下，把你的Mastodon复制安装至新的服务器上。 +description: 将你的 Mastodon 站点无损复制到新服务器。 menu: docs: weight: 90 parent: admin --- -有时，出于各种原因，你需要将你的Mastodon实例从一台服务器迁移至另一台。幸运的是，这个过程并不太困解，虽然这可能导致一段时间的下线。 +出于各种原因，你可能希望将 Mastodon 实例从一台服务器迁移到另一台。幸运的是，这个过程并不太困难，尽管可能会导致一些停机时间。 {{< hint style="info" >}} -本篇指南基于Ubuntu Server编写；根据其他设置的不同，你的过程可能会有变化。 +本指南主要针对 Ubuntu Server 编写；对于其他配置环境，你的实际体验可能有所不同。 {{< /hint >}} ## 基本步骤 {#basic-steps} -1. 依照[产品指南]({{< relref "install" >}})安装新的Mastodon服务器（切记，不要运行 `mastodon:setup`）。 -2. 停止旧服务器上的Mastodon（`systemctl stop 'mastodon-*.service'`）。 -3. 依照如下指示，导出并导入PostgreSQL数据库。 -4. 依照如下指示，复制 `system/` 目录下文件。（注意：如果你使用S3存储，你可以跳过此步）。 +1. 使用[生产环境配置指南]({{< relref "install" >}})设置新的 Mastodon 服务器（但不要运行`mastodon:setup`，只保持PostgreSQL服务运行）。 +2. 停止旧服务器上的 Mastodon 服务（例如`systemctl stop 'mastodon-*.service'`）。 +3. 使用下面的说明导出和加载 PostgreSQL 数据库。 +4. 使用下面的说明复制 `system/` 文件。（注意：如果你使用 S3，可以跳过此步骤。） 5. 复制 `.env.production` 文件。 -6. 运行 `RAILS_ENV=production bundle exec rails assets:precompile` 编译 Mastodon。 -7. 运行 `RAILS_ENV=production ./bin/tootctl feeds build` 重新构建每个用户的主页时间流。 -8. 启动新服务器上的Mastodon。 -9. 更新DNS设置，将其指向新服务器。 -10. 更新或复制你的Nginx设置，如果必要的话可重获取LetsEncrypt证书。 -11. 享受你的新服务器！ +6. 保存 Redis 数据库，停止新旧机器上的 Redis 服务，并将 Redis 数据库从 `/var/lib/redis/` 复制到新服务器。 +7. 运行 `RAILS_ENV=production bundle exec rails assets:precompile` 编译 Mastodon。 +8. 在新服务器上启动 Mastodon 和 Redis。 +9. 运行 `RAILS_ENV=production ./bin/tootctl feeds build` 为每个用户重建主时间线。 +10. 运行 `RAILS_ENV=production ./bin/tootctl search deploy` 重建 Elasticsearch 索引（注意：如果你不使用 Elasticsearch，可以跳过此步骤。） +11. 更新 DNS 设置，指向新服务器。 +12. 更新或复制 Nginx 配置，并根据需要重新运行 LetsEncrypt。 +13. 享受你的新服务器！ ## 详细步骤 {#detailed-steps} -### 什么数据需要被迁移 {#what-data-needs-to-be-migrated} +### 停止 Mastodon 服务 -你必须需要复制如下内容： +```bash +systemctl stop 'mastodon-*.service' +``` -* `~/live/public/system`目录，里面包含了用户上传的图片与视频（如果使用S3，可跳过此步） -* PostgreSQL数据库（使用[pg_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html)） -* `~/live/.env.production`文件，里面包含了服务器配置与密钥 +### 需要迁移哪些数据 {#what-data-needs-to-be-migrated} -不太重要的部分，为了方便起见，你也可以复制如下内容： +总体而言，你需要复制以下内容： -* nginx配置文件（位于`/etc/nginx/sites-available/default`） -* systemd配置文件（`/etc/systemd/system/mastodon-*.service`），里面可能包括一些你服务器的调优与个性化 -* PgBouncer配置文件，位于 `/etc/pgbouncer` （如果你使用PgBouncer的话） +* `~/live/public/system` 目录，该目录包含用户上传的图片和视频（如果使用 S3，则不需要） +* PostgreSQL 数据库（使用 [pg_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html)） +* `~/live/.env.production` 文件，其中包含服务器配置和密钥 +* `/var/lib/redis/` 目录中的 Redis 数据库，其中包含未处理的 Sidekiq 任务。 -### 导出并导入PostgreSQL数据库 {#dump-and-load-postgresql} +以下内容不太重要，但为方便起见，你可能仍然想要复制： -不要运行`mastodon:setup`，而是创建一个名为`template0`的空白PostgreSQL数据库（当导入PostgreSQL导出文件时，这是很有用的，参见[pg_dump文档](https://www.postgresql.org/docs/9.1/static/backup-dump.html#BACKUP-DUMP-RESTORE)）。 +* nginx 配置（位于 `/etc/nginx/sites-available/mastodon`） +* 域名的 SSL 证书（若使用 LetsEncrypt，应位于 `/etc/letsencrypt/live/`） +* systemd 配置文件（`/etc/systemd/system/mastodon-*.service`），其中可能包含你的服务器调整和自定义 +* `/etc/pgbouncer` 下的 PgBouncer 配置（如果你使用它） -在你的旧系统，使用`mastodon`用户运行如下命令： +### 导出与导入 PostgreSQL {#dump-and-load-postgresql} + +我们不运行 `mastodon:setup`，而是使用 `template0` 数据库创建一个空的 PostgreSQL 数据库（这在还原 PostgreSQL 转储文件时很有用，[如 pg_dump 文档所述](https://www.postgresql.org/docs/9.1/static/backup-dump.html#BACKUP-DUMP-RESTORE)）。 + +如果你的 PostgreSQL 用户使用密码，为方便起见，你可能希望在新系统上配置 `mastodon` 用户使用与旧系统相同的密码： + +```bash +sudo -u postgres psql +ALTER USER mastodon WITH PASSWORD 'YOUR_PASSWORD'; +\q +``` + +在旧系统上以 `mastodon` 用户身份运行： ```bash pg_dump -Fc mastodon_production -f backup.dump ``` -使用 `rsync` 或 `scp` 复制 `backup.dump` 文件。然后在新系统，使用`mastodon`帐户创建一个空数据库： +使用 `rsync` 或 `scp` 复制 `backup.dump` 文件。然后在新系统上，以 `mastodon` 用户身份创建一个空数据库： ```bash createdb -T template0 mastodon_production ``` -然后导入它： +然后导入它（将 `-j#` 中的 `#` 替换为系统中的 CPU 数量以提高还原性能）： ```bash -pg_restore -U mastodon -n public --no-owner --role=mastodon \ +pg_restore -Fc -j# -U mastodon -n public --no-owner --role=mastodon \ -d mastodon_production backup.dump ``` -（注意：如果新服务器上的帐户名不是`mastodon`，你应当修改上面命令中 `-U` **和** `--role` 参数。两台服务器的用户名不同也可以。） +（请注意，如果新服务器上的用户名不是 `mastodon`，你应该更改上面的 `-U` 和 `--role` 值。两个服务器之间可以使用不同的用户名。） ### 复制文件 {#copy-files} -本操作可能花费一些时间，若你希望避免不必要重复制，建议使用`rsync`。在你的旧机器上，使用`mastodon`用户，运行： +这可能需要一些时间，为避免不必要的重复复制，建议使用 `rsync`。在旧机器上，以 `mastodon` 用户身份运行： ```bash rsync -avz ~/live/public/system/ mastodon@example.com:~/live/public/system/ ``` -如果旧服务器上任何文件有改动，你需要重运行此命令。 +如果旧服务器上的任何文件发生更改，你需要重新运行此命令。 -你同样需要复制`.env.production`文件，该文件内含密钥。 +你还应该复制 `.env.production` 文件，其中包含密钥。 -可选的，你可以复制nginx、systemd、pgbouncer配置文件，或者从头开始重写它们。 +在新机器上，确保 Redis 未运行，否则它可能会覆盖你尝试还原的转储文件。以 `root` 用户身份运行： + +```bash +systemctl stop redis-server.service +``` + +现在复制你的 Redis 数据库（根据需要调整 Redis 数据库的位置）。在旧机器上，以 `root` 用户身份运行： + +```bash +redis-cli SAVE +systemctl stop redis-server.service +rsync -avz /var/lib/redis/ root@example.com:/var/lib/redis +``` + +作为可选操作，你可以复制 nginx、systemd 和 PgBouncer 配置文件，或者从头重写它们。 ### 迁移期间 {#during-migration} -你可以编辑旧机器上的`~/live/public/500.html`页面，如果你希望展示一个优雅的错误信息，让现有用户知晓正在进行迁移。 +你可以编辑旧机器上的 `~/live/public/500.html` 页面，以显示一条友好的错误消息，让现有用户知道迁移正在进行中。 -你也应该提前一天将DNS TTL设置为较小数值（30-60分钟）。这样当你把DNS指向新IP后，新纪录可以很快扩散开来。 +你可能还想在提前一天将 DNS TTL 设置为较小的值（30-60分钟），这样一旦你将其指向新 IP 地址，DNS 就可以快速传播。 ### 迁移后 {#after-migrating} -你可以使用[whatsmydns.net](https://whatsmydns.net/)来查看DNS扩散的过程。为了跳过这个过程，你可以修改你自己的`/etc/hosts`文件，将其指向你的新服务器，这样你可以尽早开始使用新服务器。 +以mastodon用户身份运行以下命令： -{{< translation-status-zh-cn raw_title="Migrating to a new machine" raw_link="/admin/migrating/" last_tranlation_time="2020-05-06" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}} +```bash +RAILS_ENV=production bundle exec rails assets:precompile +``` + +现在以 root 用户身份运行以下命令： + +```bash +systemctl daemon-reload +systemctl start redis-server +systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming +systemctl restart nginx +``` + +一旦服务器重新上线，你可以为用户重建主页时间线（这可能需要很长时间，取决于用户数量。） + +```bash +RAILS_ENV=production ./bin/tootctl feeds build +``` + +如果你使用 Elasticsearch，请运行以下命令重建索引（这可能需要很长时间，取决于你拥有的状态数量。） + +```bash +RAILS_ENV=production ./bin/tootctl search deploy +``` + +你可以查看 [whatsmydns.net](https://whatsmydns.net/) 以了解 DNS 传播的进度。要加速这个过程，你可以编辑自己的 `/etc/hosts` 文件，指向新服务器，这样你就可以提前开始使用它。 + +{{< translation-status-zh-cn raw_title="Migrating to a new machine" raw_link="/admin/migrating/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/moderation.md b/content/zh-cn/admin/moderation.md index 7c5e001..3f3ea8b 100644 --- a/content/zh-cn/admin/moderation.md +++ b/content/zh-cn/admin/moderation.md @@ -1,76 +1,320 @@ --- -title: 运营操作 -description: 处理不想要的用户与域名 +title: 审核操作 +description: 针对不受欢迎的用户或域名可以采取的操作。 menu: docs: weight: 110 parent: admin --- -## 帐户管理 {#individual-moderation} +## 针对个人用户的审核 {#individual-moderation} -Mastodon运营操作始终作用于本地，即从特定服务器查看的内容。一台服务器管理员（admin）或运营员（moderator）不能影响另一台服务器上的用户，他们只能影响另一台服务器用户的本地服务器副本。 +Mastodon 中的审核始终在本站应用，即从特定实例的角度来看。一个实例的管理员或协管员不能影响另一个实例上的用户，他们只能影响该用户在自己实例上的本地副本。 -### 禁止登录（disable login） {#disable-login} +从 v3.5.0 开始，所有默认的用户审核决定都会通过电子邮件通知受影响的用户。用户可以访问申诉页面，在决定做出后的 20 天内提交一次申诉。协管员可以批准或拒绝申诉。 -Mastodon可以被禁止登录。这样可以禁止用户对帐户进行任何操作，但是其帐户的内容仍保持不变。这个限制是可撤销的，任何时候都可以重新激活该用户。本限制仅适用于你服务器的本地用户。 +### 标记为敏感内容 {#sensitive-user} -### 隐藏（silence） {#silence-user} +当一个账户被标记为敏感时，该用户发布的所有媒体内容将自动被[标记为敏感内容](https://docs.joinmastodon.org/user/posting/#cw)。 -在Mastodon，隐藏（silence）是沙箱（sandbox）的同义词。一个被隐藏的帐户不会出现在未关注该帐户的用户面前。该帐户所有内容仍存在，这些内容可以通过搜索查找到，该帐户可以被提及、被关注，但是这些内容是不可见的。 +### 冻结 {#freeze-user} -此外，隐藏操作不会影响联邦宇宙。一个本地隐藏了的帐户*不会*自动在其他服务器隐藏。 +Mastodon 账户可以被冻结。这会阻止用户使用该账户做任何事情，但所有内容仍然完好无损地保留。这种限制是可逆的；账户可以随时解冻。这种限制仅适用于你实例上的本站用户。 -本限制是可撤销的，任何时间都可以去除该帐户的隐藏。 +当用户的账户被冻结时，他们会被重定向到**账户设置**页面，并显示以下信息： -### 封禁（suspension） {#suspend-user} +> 你不能再登录你的账户，或以任何其他方式使用它，但你的个人资料和其他数据保持完整。 -在Mastodon，封禁（suspension）是删除（deletion）的同义词。该帐户不会出现在搜索之中，其用户资料页将消失，该帐户的所有嘟文，上传，关注者以及所有其它数据都将被移除。本限制是**不可逆的**。当一个帐户被解除屏蔽，用户可以重新控制帐户，但旧数据已经一去不复返了。 +当用户的账户解冻后，正常功能会恢复。 -## 实例管理 {#server-wide-moderation} +### 限制 {#limit-user} -由于使用帐户管理单独处理来自行为异常服务器的大量用户是让人精疲力竭的事，所以可以预清空来自特定服务器的所有用户，即所谓的**域名屏蔽（domain block）**。该操作有多个不同严厉程度。 +之前被称为"隐藏"。被限制的账户将对该实例上的所有其他用户隐藏，除非用户已经关注了被限制的账户。所有内容仍然存在，并且仍然可以通过搜索、提及和关注找到，但内容在公开场合不可见。 -### 拒绝接收媒体文件（reject media） {#reject-media} +目前，限制不影响联合功能。在本站被限制的账户在其他实例*不会*被自动限制。账户限制是可逆的。 -当这个选项被激活，来自该服务器的文件将不会传递至本地。其包括头像、横幅、emoji及媒体附件。 +### 封禁 {#suspend-user} -### 隐藏（silence） {#silence-server} +Mastodon 中的封禁操作意味着账户实际上被删除。该账户不再出现在搜索中，账户页面消失，所有嘟文、上传的内容、关注者和所有其他数据在公开场合被移除。但是，自封禁起 30 天内，所有数据在管理后台仍然保留。这是为了给用户提供与实例管理员合作解决潜在问题并恢复账户的机会。 -对来自该服务器的所有帐户应用隐藏（silence）操作。 +如果账户在 30 天期限内被恢复，所有数据将再次可被公开访问，不会产生不良影响。 30 天期限过后，用户的**所有**数据将从被实例中清除。管理员还可以选择在 30 天内的任何时候立即删除用户的账户数据。 -### 屏蔽（suspend） {#suspend-server} +无论数据在 30 天期限后被删除，还是被管理员提前强制删除，对应账户仍然可以被解除封禁。但是，该账户将不再与之关联的任何数据（状态、个人资料信息、头像或标题图像）。 -对来自该服务器的所有帐户应用封禁（suspension）操作。本地将不储存除用户名外的任何数据。 +对于外站账户，封禁将使其取消关注任何本站账户。即使外站账户在 30 天时间窗口内被解除封禁，这些关系也不会恢复。 -## 反广告措施 {#spam-fighting-measures} +## 对整个站点进行审核 {#server-wide-moderation} -Mastodon有以下基本措施以阻止广告内容： +由于单个审核来自行为不端的站点的大量用户可能会很疲惫，因此可以使用**实例屏蔽**的功能对来自特定服务器的所有用户进行预先审核，这有几个不同的严重级别。 -* 注册时需确认电子邮件地址 -* 基于IP的注册频率限制 +### 拒绝媒体 {#reject-media} -然而，专业广告发送者（spammer）将绕过这些措施。你可以应用的措施是**电子邮件域名屏蔽**。在注册期间，Mastodon将解析所给电子邮箱地址的A纪录或MX纪录，即电子邮件服务器的IP地址，并对照动态存储的黑名单中检查该IP地址。 +启用此选项后，本站不会处理来自该实例的任何文件。这包括头像、背景横幅、表情与媒体附件。 -### 屏蔽电子邮件域名 {#blocking-by-email-server} +### 限制 {#limit-server} -广告发送者（spammer）时常使用不同的电子邮件域名，以让他们看起来是使用许多不同的电子邮件服务器注册，而这些电子邮件域名很难被分别列入黑名单。但是，有时这些域名被解析到了同IP地址电子邮件服务器。如果你发现同一时间有大数广告发送者（spammer）注册，你可以使用在线DNS查询工具或 Linux `dig` 组件来检查，例如：`dig example.com` 将查询该域名的所有DNS A纪录。如果你注意到所有域名指向同一IP，你可以把它添加至电子邮件域名屏蔽列表中。 +相当于[限制](#limit-user)来自该实例的所有过去和未来的账户。之前称为"隐藏"。 -### 封禁IP {#blocking-by-ip} +### 封禁 {#suspend-server} -Mastodon自身不支持基于IP地址的访问者屏蔽，这不是一个万无一失的策略。IP有时会被不同的人共享，并时常会易手。但可以使用 Linux 防火墙来基于IP地址屏蔽访问者。下面的例子需要使用 `iptables` 和 `ipset`： +相当于[封禁](#suspend-user)来自该实例的所有过去和未来的账户。除用户名外，不会在本地存储来自该实例的任何内容。 + +封禁一个实例将删除本站账户与被封禁实例上账户之间的所有现存关注关系。如果外站实例稍后被解除封禁，这些关系不会恢复。 + +## 反垃圾信息措施 {#spam-fighting-measures} + +Mastodon 中有一些基本措施来防止垃圾信息： + +* 注册需要确认电子邮件地址 +* 按 IP 地址限制注册速率 + +然而，专业的垃圾信息发送者会绕过这些措施。你可以采用的另一种措施是**电子邮件域名黑名单**。在注册过程中，Mastodon 会解析给定电子邮件地址的 A 或 MX 记录，即电子邮件服务器的 IP 地址，并检查该 IP 地址是否在动态存储的黑名单中。 + +### 按邮箱服务器屏蔽 {#blocking-by-e-mail-server} + +垃圾信息发送者经常使用不同的电子邮件域名，使其看起来像是使用了许多不同的邮箱服务器，很难将这些域名全部添加到黑名单。但在某些情况下，所有这些域名都解析到单个邮箱服务器 IP。如果你看到大量垃圾信息发送者同时注册，你可以检查这一点，使用在线 DNS 查找工具或 Linux 的 `dig` 实用工具，例如 `dig example.com` 将返回该域的所有 DNS A 记录。如果你注意到所有域名的 IP 都相同，你可以将其添加到电子邮件域名黑名单中。 + +### 按 IP 屏蔽 {#blocking-by-ip} + +在 Mastodon 本身中无法按 IP 地址屏蔽访问者，而且这不是一种万无一失的策略。 IP 有时由很多不同的人共享，且有时会更换。然而，可以在 Linux 中使用防火墙按 IP 地址屏蔽访问者。以下是使用 `iptables` 和 `ipset` 的示例： ```bash -# Install ipset +# 安装 ipset sudo apt install ipset -# Create blacklist named "spambots" +# 创建名为 "spambots" 的黑名单 sudo ipset create spambots nethash -# Add 1.2.3.4 to the blacklist +# 将 1.2.3.4 添加到黑名单 sudo ipset add spambots 1.2.3.4 -# Add firewall rule based on the blacklist +# 基于黑名单添加防火墙规则 sudo iptables -I INPUT 1 -m set --match-set spambots src -j DROP ``` -但是注意，不要把你自己封禁了。 +小心不要将自己锁在机器之外。 -{{< translation-status-zh-cn raw_title="Moderation actions" raw_link="/admin/moderation/" last_tranlation_time="2020-05-08" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}} +### 用于审核级别事件的网络钩子 {#report-events-webhook} + +你可以创建网络钩子，通过实时通知应用程序系统事件来促进审核API的自动化。这也实现了与 Discord、 IRC 和 Slack 等聊天应用的集成，有助于协调审核工作。 + +作为可选操作，你可使用来自 WebSub 规范的 X-Hub-Signature 标头来验证载荷的真实性。 + +当前支持的事件： + +* account.approved +* account.created +* account.updated +* report.created +* report.updated +* status.created +* status.updated + + + +#### 示例载荷： + +```json + +{ + "event":"report.created", + "created_at":"2023-10-26T13:34:00.351Z", + "object":{ + "id":"8437", + "action_taken":false, + "action_taken_at":null, + "category":"violation", + "comment":"", + "forwarded":true, + "created_at":"2023-10-26T13:34:00.348Z", + "updated_at":"2023-10-26T13:34:00.348Z", + "account":{ + "id":"123456789", + "username":"bobisaburger", + "domain":null, + "created_at":"2023-07-13T04:39:22.493Z", + "email":"bobisaburger@emailservice.com", + "ip":"12.34.56.78", + "confirmed":true, + "suspended":false, + "silenced":false, + "sensitized":false, + "disabled":false, + "approved":true, + "locale":"en", + "invite_request":"I would love to be a member of your instance!", + "ips":[ + { + "ip":"12.34.56.78", + "used_at":"2023-07-13T04:45:31.835Z" + }, + { + "ip":"98.76.54.32", + "used_at":"2023-07-13T04:39:22.722Z" + } + ], + "account":{ + "id":"123456789", + "username":"bobisaburger", + "acct":"bobisaburger", + "display_name":"bobisaburger", + "locked":false, + "bot":false, + "discoverable":null, + "group":false, + "created_at":"2023-07-13T00:00:00.000Z", + "note":"", + "url":"https://mastodonwebsite/@bobisaburger", + "uri":"https://mastodonwebsite/users/bobisaburger", + "avatar":"https://locationofavatar.com/image.jpg", + "avatar_static":"https://locationofavatar.com/image.jpg", + "header":"locationofheader.com/image.jpg", + "header_static":"locationofheader.com/image.jpg", + "followers_count":100, + "following_count":200, + "statuses_count":9, + "last_status_at":"2023-08-05", + "noindex":true, + "emojis":[ + + ], + "roles":[ + + ], + "fields":[ + + ] + }, + "role":{ + "id":"-99", + "name":"", + "permissions":"65536", + "color":"", + "highlighted":false + } + }, + "target_account":{ + "id":"123454321", + "username":"cheeseperson", + "domain":"someothermastodonsite.com", + "created_at":"2023-08-20T00:00:00.000Z", + "email":null, + "ip":null, + "confirmed":null, + "suspended":false, + "silenced":false, + "sensitized":false, + "disabled":null, + "approved":null, + "locale":null, + "invite_request":null, + "ips":null, + "account":{ + "id":"123454321", + "username":"cheeseperson", + "acct":"cheeseperson@someothermastodonsite.com", + "display_name":"cheeseperson", + "locked":false, + "bot":false, + "discoverable":false, + "group":false, + "created_at":"2023-08-20T00:00:00.000Z", + "note":"", + "url":"https://someothermastodonsite.com/@cheeseperson", + "uri":"https://someothermastodonsite.com/users/cheeseperson", + "avatar":"https://someothermastadonsite.com/avatars/original/missing.png", + "avatar_static":"https://someothermastadonsite.com/avatars/original/missing.png", + "header":"locationofheader.com/image.jpg", + "header_static":"locationofheader.com/image.jpg", + "followers_count":2, + "following_count":2, + "statuses_count":95, + "last_status_at":"2023-10-26", + "emojis":[ + + ], + "fields":[ + + ] + }, + "role":null + }, + "assigned_account":null, + "action_taken_by_account":null, + "statuses":[ + { + "id":"12345678987654321", + "created_at":"2023-10-26T11:29:13.000Z", + "in_reply_to_id":"1918282746465", + "in_reply_to_account_id":"101010101010", + "sensitive":false, + "spoiler_text":"", + "visibility":"public", + "language":"de", + "uri":"https://someothermastodonsite.com/users/cheeseperson/statuses/111301083360371621", + "url":"https://someothermastodonsite.com/@cheeseperson/111301083360371621", + "replies_count":0, + "reblogs_count":0, + "favourites_count":0, + "edited_at":"2023-10-26T11:30:31.000Z", + "content":"

Here is some content

", + "reblog":null, + "account":{ + "id":"123454321", + "username":"cheeseperson", + "acct":"cheeseperson@someothermastodonsite.com", + "display_name":"cheeseperson", + "locked":false, + "bot":false, + "discoverable":false, + "group":false, + "created_at":"2023-08-20T00:00:00.000Z", + "note":"", + "url":"https://someothermastodonsite.com/@cheeseperson", + "uri":"https://someothermastodonsite.com/users/cheeseperson", + "avatar":"https://someothermastadonsite.com/avatars/original/missing.png", + "avatar_static":"https://someothermastadonsite.com/avatars/original/missing.png", + "header":"locationofheader.com/image.jpg", + "header_static":"locationofheader.com/image.jpg", + "followers_count":2, + "following_count":2, + "statuses_count":95, + "last_status_at":"2023-10-26", + "emojis":[ + + ], + "fields":[ + + ] + }, + "media_attachments":[ + + ], + "mentions":[ + { + "id":"101010101010", + "username":"thirdperson", + "url":"https://thirdpersonsinstance.com/@thirdperson", + "acct":"thirdperson@emailwebsite.com" + } + ], + "tags":[ + + ], + "emojis":[ + + ], + "card":null, + "poll":null + } + ], + "rules":[ + { + "id":"2", + "text":"不要做一个招人讨厌的人！" + } + ] + } +} + + +``` + +{{< translation-status-zh-cn raw_title="Moderation actions" raw_link="/admin/moderation/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/optional.md b/content/zh-cn/admin/optional.md index 128efe0..134de0b 100644 --- a/content/zh-cn/admin/optional.md +++ b/content/zh-cn/admin/optional.md @@ -1,5 +1,5 @@ --- -title: 安装可选特色功能 +title: 安装可选功能 menu: docs: weight: 40 @@ -7,4 +7,10 @@ menu: identifier: admin-optional --- -{{< translation-status-zh-cn raw_title="Installing optional features" raw_link="/admin/optional/" last_tranlation_time="2020-05-04" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}} +Mastodon提供了一些可以根据需要使用的可选功能。 + +- [对象存储](./object-storage/) +- [匿名服务](./tor/) +- [单点登录](./sso/) + +{{< translation-status-zh-cn raw_title="Installing optional features" raw_link="/admin/optional/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/optional/captcha.md b/content/zh-cn/admin/optional/captcha.md new file mode 100644 index 0000000..9720fa3 --- /dev/null +++ b/content/zh-cn/admin/optional/captcha.md @@ -0,0 +1,34 @@ +--- +title: 验证码 +description: 缓解自动注册机器人的问题 +menu: + docs: + weight: 30 + parent: admin-optional +--- + +从 4.2 版本开始， Mastodon 支持使用验证码技术来帮助缓解机器人注册新账户的问题。 +启用验证码后，新注册用户将需要在电子邮件验证过程中完成一个质询响应。 + +![](/assets/captcha/user-view.png) + +{{< hint style="danger" >}} +对于某些人来说，使用中心化的验证码服务可能会引起安全和隐私方面的担忧。 +此外，验证码可能会使注册过程的可访问性大大降低，尤其是对于视力障碍人士，如盲人或视力低下的人而言。 +{{}} + +目前， hCaptcha 是 Mastodon 唯一支持的验证码提供商。 +未来可能会添加其他提供商。 + +## hCaptcha + +- 在 [hcaptcha.com](https://www.hcaptcha.com) 创建一个免费的 hCaptcha 账户 +- 完成注册后，使用 hCaptcha 仪表板添加新站点，输入你的 Mastodon 站点域名并获取站点密钥(Site Key) +- 从 hCaptcha 的账户设置菜单中获取你的密钥(Secret Key) +- 将这些值添加到你的 Mastodon 环境配置中，分别添加 `HCAPTCHA_SITE_KEY` 和 `HCAPTCHA_SECRET_KEY` +- 重启服务器上运行的 Mastodon 服务 +- 从 Mastodon 网页界面导航至**管理**>**服务器设置**>**注册**，并勾选标有"要求新用户解决验证码以确认其账户"的选项 + +![](/assets/captcha/admin-view.png) + +{{< translation-status-zh-cn raw_title="Captcha" raw_link="/admin/optional/captcha/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/optional/elasticsearch.md b/content/zh-cn/admin/optional/elasticsearch.md deleted file mode 100644 index 1777440..0000000 --- a/content/zh-cn/admin/optional/elasticsearch.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -title: 全文搜索 -description: 设置Elasticsearch来搜索自己发出的嘟文、自己喜欢的嘟文、自己的书签和自己被提及的嘟文。 -menu: - docs: - weight: 10 - parent: admin-optional ---- - -当有可用Elasticsearch时，Mastodon支持全文搜索。Mastodon的全文搜索允许登录用户从他们自己的嘟文、他们喜欢的嘟文、他们的书签和他们被提及的嘟文中查找相应结果。Mastodon有意禁用了在全数据库搜索任意关键词的功能。 - -## 安装 Elasticsearch {#install} - -Elasticsearch 需要 Java runtime。如果你还没有安装 Java，请立刻安装上它。以下操均假定你已经登录为`root`用户： - -```bash -apt install openjdk-8-jre-headless -``` - -添加Elasticsearch官方软件仓库至apt： - -```bash -wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | apt-key add - -echo "deb https://artifacts.elastic.co/packages/6.x/apt stable main" | tee -a /etc/apt/sources.list.d/elastic-6.x.list -apt update -``` - -现在，你可以安装 Elasticsearch： - -```bash -apt install elasticsearch -``` - -{{< hint style="warning" >}} -**安全警告：** 默认情况下，Elasticsearch仅绑定于localhost，即无法从外部网络访问。你可以通过查看 `/etc/elasticsearch/elasticsearch.yml` 中的 `network.host` 来检查 Elasticsearch 绑定了哪些地址。考虑到由于缺乏认证层，任何能访问 Elasticsearch 的人都可以读取或修改里面的数据。因此，确保访问安全非常重要。如[主要安装说明](../../prerequisites/#install-a-firewall-and-only-whitelist-ssh-http-and-https-ports)中所述，防火墙建议仅暴露了22、80、443端口。如果你是一个多主机配置，你必须知道如何保证内部流量安全。 -{{< /hint >}} -{{< hint style="danger" >}} -**安全警告:** 由于近期Elasticsearch所使用的`log4j`库被披露出[安全漏洞](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-44228)，使用了旧版本`log4j`(`2.0`到`2.14.1`)的ES可能会受到影响。如果使用了这些版本的`log4j`，请参阅 [此 issue](https://github.com/elastic/elasticsearch/issues/81618#issuecomment-991000240) 来暂时缓解此问题。 -{{< /hint >}} - -启动 Elasticsearch： - -```bash -systemctl enable elasticsearch -systemctl start elasticsearch -``` - -## 配置 Mastodon {#config} - -编辑 `.env.production`，添加如下变量： - -```bash -ES_ENABLED=true -ES_HOST=localhost -ES_PORT=9200 -``` - -如果你同一台机器上运行多个Mastodon服务器，你计划让它们使用同一个Elasticsearch，请确保他们都配置了互不重复的 `REDIS_NAMESPACE` 以分别他们的索引。如果你需要覆盖Elasticsearch索引前缀，你可以直接设置 `ES_PREFIX`。 - - -保存新设置之后，使用如下命令创建Elasticsearch索引： - -```bash -RAILS_ENV=production bundle exec rake chewy:upgrade -``` - -重启Mastodon进程以使新配置生效： - -```bash -systemctl restart mastodon-sidekiq -systemctl reload mastodon-web -``` - -现在，新的嘟文将会被写入Elasticsearch索引。最后一步是导入所有旧有数据。这将花费很长一段时间： - -```bash -RAILS_ENV=production bundle exec rake chewy:sync -``` - -{{< hint style="warning" >}} -**兼容性提示：** Ruby 2.6.0 由于已知Bug，无法进行上述操作。其它Ruby版本，例如：2.6.1，并不存在这个问题。 -{{< /hint >}} - -## 其它语言的搜索优化 - -### 中文搜索优化 {#chinese-search-optimize} - -Elasticsearch默认使用标准分析器，这对于中文来说可能并不太适合。为了提高搜索体验，你可以安装特定语言的专用分析器。在创建Elasticsearch索引之前执行： - - -安装 [elasticsearch-analysis-ik](https://github.com/medcl/elasticsearch-analysis-ik)、[elasticsearch-analysis-stconvert](https://github.com/medcl/elasticsearch-analysis-stconvert) 插件至 Elasticsearch。 - -并对源码做出如下修改： - -```diff -diff --git a/app/chewy/accounts_index.rb b/app/chewy/accounts_index.rb ---- a/app/chewy/accounts_index.rb -+++ b/app/chewy/accounts_index.rb -@@ -4,7 +4,7 @@ class AccountsIndex < Chewy::Index - settings index: { refresh_interval: '5m' }, analysis: { - analyzer: { - content: { -- tokenizer: 'whitespace', -+ tokenizer: 'ik_max_word', - filter: %w(lowercase asciifolding cjk_width), - }, - -diff --git a/app/chewy/statuses_index.rb b/app/chewy/statuses_index.rb ---- a/app/chewy/statuses_index.rb -+++ b/app/chewy/statuses_index.rb -@@ -16,9 +16,17 @@ class StatusesIndex < Chewy::Index - language: 'possessive_english', - }, - }, -+ char_filter: { -+ tsconvert: { -+ type: 'stconvert', -+ keep_both: false, -+ delimiter: '#', -+ convert_type: 't2s', -+ }, -+ }, - analyzer: { - content: { -- tokenizer: 'uax_url_email', -+ tokenizer: 'ik_max_word', - filter: %w( - english_possessive_stemmer - lowercase -@@ -27,6 +35,7 @@ class StatusesIndex < Chewy::Index - english_stop - english_stemmer - ), -+ char_filter: %w(tsconvert), - }, - }, - } -diff --git a/app/chewy/tags_index.rb b/app/chewy/tags_index.rb ---- a/app/chewy/tags_index.rb -+++ b/app/chewy/tags_index.rb -@@ -2,10 +2,19 @@ - - class TagsIndex < Chewy::Index - settings index: { refresh_interval: '15m' }, analysis: { -+ char_filter: { -+ tsconvert: { -+ type: 'stconvert', -+ keep_both: false, -+ delimiter: '#', -+ convert_type: 't2s', -+ }, -+ }, - analyzer: { - content: { -- tokenizer: 'keyword', -+ tokenizer: 'ik_max_word', - filter: %w(lowercase asciifolding cjk_width), -+ char_filter: %w(tsconvert), - }, - - edge_ngram: { -``` - -{{< translation-status-zh-cn raw_title="Full-text search" raw_link="/admin/optional/elasticsearch/" last_tranlation_time="2020-05-05" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}} diff --git a/content/zh-cn/admin/optional/object-storage-proxy.md b/content/zh-cn/admin/optional/object-storage-proxy.md new file mode 100644 index 0000000..b6bea5f --- /dev/null +++ b/content/zh-cn/admin/optional/object-storage-proxy.md @@ -0,0 +1,129 @@ +--- +title: 通过 nginx 代理对象存储 +description: 从自己的域名提供 Mastodon 中用户上传的文件 +--- + +当使用 Amazon S3、Wasabi、Google Cloud 或其他对象存储提供商作为 Mastodon 的对象存储时，默认情况下，文件及其 URL 会通过存储提供商本身提供。这有以下缺点： + +- 带宽通常是按量计费且非常昂贵 +- 如果你决定稍后更换提供商，URL 将会失效 + +你可以选择从自己的域名提供文件，并在此过程中加入缓存机制。在 Mastodon 中，访问模式显示新文件经常被多个客户端同时访问，因为它们出现在通过流式 API 提供的新贴文中或通过联邦与州共享；相比之下，旧内容的访问频率较低。因此，仅依靠缓存并不能显著减少代理到实际对象存储的带宽使用。为了解决这个问题，我们可以实现一个缓存锁定机制，确保一次只进行一个代理请求。 + +以下是实现这一目标的nginx配置示例： + +```nginx +server { + listen 443 ssl http2; + listen [::]:443 ssl http2; + server_name files.example.com; + root /var/www/html; + + ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem; + ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key; + + keepalive_timeout 30; + + location = / { + index index.html; + } + + location / { + try_files $uri @s3; + } + + set $s3_backend 'https://YOUR_BUCKET_NAME.YOUR_S3_HOSTNAME'; + + location @s3 { + limit_except GET { + deny all; + } + + resolver 8.8.8.8; + proxy_set_header Host YOUR_BUCKET_NAME.YOUR_S3_HOSTNAME; + proxy_set_header Connection ''; + proxy_set_header Authorization ''; + proxy_hide_header Set-Cookie; + proxy_hide_header 'Access-Control-Allow-Origin'; + proxy_hide_header 'Access-Control-Allow-Methods'; + proxy_hide_header 'Access-Control-Allow-Headers'; + proxy_hide_header x-amz-id-2; + proxy_hide_header x-amz-request-id; + proxy_hide_header x-amz-meta-server-side-encryption; + proxy_hide_header x-amz-server-side-encryption; + proxy_hide_header x-amz-bucket-region; + proxy_hide_header x-amzn-requestid; + proxy_ignore_headers Set-Cookie; + proxy_pass $s3_backend$uri; + proxy_intercept_errors off; + + proxy_cache CACHE; + proxy_cache_valid 200 48h; + proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504; + proxy_cache_lock on; + + expires 1y; + add_header Cache-Control public; + add_header 'Access-Control-Allow-Origin' '*'; + add_header X-Cache-Status $upstream_cache_status; + add_header X-Content-Type-Options nosniff; + add_header Content-Security-Policy "default-src 'none'; form-action 'none'"; + } +} +``` + +{{< hint style="info" >}} +我们使用 `$s3_backend` 作为变量来强制 nginx 对其值执行 DNS 解析，因为对象存储提供商的 IP 地址可能不会始终保持不变。 +{{}} + +上述配置实现了以下效果： + +- 阻止针对对象存储提供商的除 GET 请求之外的请求 +- 阻止任何经过身份验证的请求到达对象存储提供商 +- 阻止对象存储提供商设置cookie +- 移除对象存储提供商返回的不必要的标头信息 +- 缓存有效文件最多 48 小时 +- 如果对象存储不可用，允许使用旧缓存 +- 使用缓存锁防止同时向对象存储发出请求 +- 使返回的所有文件可被浏览器缓存长达一年 +- 添加 Mastodon 网页界面所需的 CORS 头信息 +- 添加一个特殊的头信息，告诉用户请求是否命中缓存 + +确保替换以下内容： + +- `files.example.com` +- `YOUR_BUCKET_NAME` +- `YOUR_S3_HOSTNAME` + +使用你的实际值，将配置保存到 `/etc/nginx/sites-available/files.example.com`，然后通过以下命令启用它： + +```bash +ln -s /etc/nginx/sites-available/files.example.com /etc/nginx/sites-enabled/ +systemctl reload nginx +``` + +你还需要为其获取SSL证书： + +```bash +certbot --nginx -d files.example.com +systemctl reload nginx +``` + +最后，你需要确保 Mastodon 使用你的新代理生成文件 URL。编辑 Mastodon 的 `.env.production` 添加： + +```bash +S3_ALIAS_HOST=files.example.com +``` + +然后重启 Mastodon： + +```bash +systemctl restart mastodon-sidekiq +systemctl reload mastodon-web +``` + +{{< hint style="success" >}} +**现在你可以在浏览器中访问你的 Mastodon 以确认一切正常加载** +{{< /hint >}} + +{{< translation-status-zh-cn raw_title="Proxying object storage through nginx" raw_link="/admin/optional/object-storage-proxy/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/optional/object-storage.md b/content/zh-cn/admin/optional/object-storage.md new file mode 100644 index 0000000..61bac54 --- /dev/null +++ b/content/zh-cn/admin/optional/object-storage.md @@ -0,0 +1,320 @@ +--- +title: 对象存储 +description: 使用外部对象存储来存储 Mastodon 中用户上传的文件 +menu: + docs: + weight: 15 + parent: admin-optional +--- + +用户上传的文件可以存储在主服务器的文件系统中，或者使用外部对象存储服务器。使用外部对象存储对于扩展 Mastodon 实例来说可能是必需的。 + +## 使用文件系统 {#FS} + +最简单的存储用户上传文件的方式是使用服务器的文件系统。这是默认的工作方式，适用于小型服务器。 + +默认情况下， Mastodon 会将文件上传存储在安装目录下的 `public/system` 文件夹中，但可以通过使用 `PAPERCLIP_ROOT_PATH` 环境变量来覆盖此设置。 + +默认情况下，这些文件可以通过 `https://your-domain/system` 访问，可以使用 `PAPERCLIP_ROOT_URL` 和 `CDN_HOST` 来覆盖此访问路径。 + +{{< hint style="info" >}} +虽然使用服务器的文件系统对小型服务器来说完全可用，但使用外部对象存储更具可扩展性。 +{{}} + +{{< hint style="danger" >}} +必须配置 Web 服务器，使其能够提供这些文件，但不允许列出它们（也就是说 `https://your-domain/system/` 不应返回文件列表）。如果你使用与 Mastodon 一起分发的配置文件，情况应该就是这样，但最好再次检查一下。 +{{}} + +## 兼容 S3 的对象存储后端 {#S3} + +Mastodon 可以使用兼容 S3 的对象存储后端。 建议支持 ACL，因为 ACL 允许 Mastodon 快速地让被封禁用户的媒体附件不可用，或略微提高私有数据的安全性。 + +Mastodon 使用 S3 API (`S3_REGION`, `S3_ENDPOINT`, `S3_BUCKET`, +`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `S3_SIGNATURE_VERSION`, +`S3_OVERRIDE_PATH_STYLE`) 进行所有的写入、删除和权限修改操作。这包括媒体上传（来自 Web 界面、 Mastodon API 客户端和 ActivityPub 服务器）、媒体删除（贴文被编辑或删除时）以及阻止对媒体的访问（当帐户被暂停时）。 + +Mastodon 会向 Web 界面、Mastodon API 客户端和 ActivityPub 服务器发送 URL，用于所有“读取”操作。因此，这些操作是匿名的（不需要身份验证或授权），并使用纯 HTTP GET 方法，这意味着它们可以通过反向代理和 CDN 路由并被缓存。 这也意味着这些 URL 可以包含与 S3 存储提供商本身使用的主机/域名完全不同的主机/域名（根据需要）。 请查看下面的详细文档，其中描述了如何构造这些 URL 以及涉及哪些环境变量。 + +要启用 S3 存储，请将 `S3_ENABLED` 环境变量设置为 `true`。 + +### 用于 S3 API 访问的环境变量 + +- `S3_REGION` (默认为 'us-east-1'，如果使用 AWS S3 则必需提供，使用其他存储提供商可能不需要) +- `S3_ENDPOINT` (默认为 'https://s3..amazonaws.com'， 如果不使用 AWS S3 则必需提供) +- `S3_BUCKET=mastodata` (将 `mastodata` 替换为你的存储桶名称) +- `AWS_ACCESS_KEY_ID` 和 `AWS_SECRET_ACCESS_KEY` 需要设置为你的凭据 +- `S3_SIGNATURE_VERSION` (默认为 'v4'，应该与大多数存储提供商兼容) +- `S3_OVERRIDE_PATH_STYLE` (仅当配置了 `S3_ENDPOINT` 时使用， 如果存储提供商要求将 API 操作发送到 '.`（域名样式），请将其设置为 `true`) + +### 用于客户端访问媒体对象的环境变量 + +- `S3_PROTOCOL` (默认为 `https`) +- `S3_HOSTNAME` (默认为 's3-.amazonaws.com'， 如果不使用 AWS S3 且未设置 `S3_ALIAS_HOST`，则为必需) +- `S3_ALIAS_HOST` (如果你不希望 `S3_BUCKET` 包含在媒体 URL 中，可以使用 `S3_ALIAS_HOST` 代替 `S3_HOSTNAME`， 这需要你在存储提供商前面配置一个反向代理或 CDN) + +如上所述，当客户端需要从存储提供商访问媒体对象时，Mastodon 将向客户端发送 URL。 这些 URL 构造如下： + +- 如果未设置 `S3_ALIAS_HOST`，则 URL 将为 ':////\<对象路径\>' + +- 如果设置了 `S3_ALIAS_HOST`，则 URL 将为 ':///\<对象路径\>' + +注意，当设置了 `S3_ALIAS_HOST` 时，存储桶名称 **不** 包含在生成的 URL 中； 这意味着存储桶名称必须包含在 `S3_ALIAS_HOST` 中（称为“域名样式”对象访问），或者 `S3_ALIAS_HOST` 必须指向一个反向代理或 CDN，它可以将存储桶名称包含在用于将请求发送到存储提供商的 URL 中。 这种类型的配置允许你从实例的客户端“隐藏”存储提供商，这意味着你可以更改存储提供商，而无需更改生成的 URL。 + +除隐藏存储提供商之外，这还可以让你在从存储提供商拉取媒体后缓存媒体，从而降低存储提供商的出口带宽成本。 这可以在你自己的反向代理中完成，也可以通过使用 CDN 来完成。 + +{{< page-ref page="admin/optional/object-storage-proxy.md" >}} + +{{< hint style="info" >}} +你必须使用 CORS 标头来提供文件，否则 Mastodon Web UI 的某些功能将无法正常工作。 例如，`Access-Control-Allow-Origin: *` +{{}} + +### 可选环境变量 + +#### `S3_OPEN_TIMEOUT` + +默认值：5 (秒) + +HTTP 处理程序在尝试打开新的 HTTP 会话时应超时的秒数。 + +#### `S3_READ_TIMEOUT` + +默认值：5 (秒) + +HTTP 处理程序在等待 HTTP 响应时应超时的秒数。 + +#### `S3_FORCE_SINGLE_REQUEST` + +默认值：false + +如果你在处理大型文件时遇到问题，请将其设置为 `true`。 + +#### `S3_ENABLE_CHECKSUM_MODE` + +默认值：false + +使在 Mastodon 从存储提供商检索对象时验证对象校验和。 此功能在 AWS S3 中可用，但在其他兼容 S3 的实现中可能不可用。 + +#### `S3_STORAGE_CLASS` + +默认值：none + +当使用 AWS S3 时，此变量可以设置为 [存储类](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-class-intro.html) 的其中一个选项，这些选项会影响所选的用于上传对象的存储（以及它们的访问时间和成本）。 如果未指定存储类，则 AWS S3 将使用 `STANDARD` 类，但选项包括 `REDUCED_REDUNDANCY`、`GLACIER` 等。 + +#### `S3_MULTIPART_THRESHOLD` + +默认值：15 (兆字节) + +此大小及以下的对象将以单个操作上传，但更大的对象将使用多部分分块机制上传，这可以提高传输速度和可靠性。 + +#### `S3_PERMISSION` + +默认值：`public-read` + +定义上传新文件时的 S3 对象 ACL。 使用 [S3 阻止公共访问](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-control-block-public-access.html) 并启用 `BlockPublicAcls` 选项时请谨慎，因为使用 ACL `public-read` 上传对象将失败 (403)。 在这种情况下，需将 `S3_PERMISSION` 设置为 `private`。 + +{{< hint style="danger" >}} +无论 ACL 配置如何，你的 S3 存储桶都必须设置为确保所有对象都是公共可读，但不可写或可列出。 同时，Mastodon 本身应该对存储桶具有写入权限。 此配置通常在所有 S3 提供商中保持一致，常用提供商在本指南后面会重点介绍。 +{{}} + +#### `S3_BATCH_DELETE_LIMIT` + +默认值: `1000` + +官方的 [Amazon S3 API](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) 可以处理在一个批处理作业中删除 1,000 个对象，但一些提供商可能在处理一个请求中的这么多对象时遇到问题，或者提供更低的限制。 + +#### `S3_BATCH_DELETE_RETRY` + +默认值: 3 + +在批处理删除操作期间，S3 提供商可能会在处理删除请求时周期性地失败或超时。 Mastodon 会退避并重试该请求，直到达到最大重试次数。 + +### MinIO + +MinIO 是 S3 对象提供程序的开源实现。 本节不介绍如何安装它，而是介绍如何配置存储桶以在 Mastodon 中使用。 + +你需要为匿名访问设置一个策略，该策略允许对存储桶包含的对象进行只读访问，而不允许列出它们。 + +为此，你需要设置一个自定义策略（将 `mastodata` 替换为你的 S3 存储桶的实际名称）： +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "AWS": [ + "*" + ] + }, + "Action": [ + "s3:GetObject" + ], + "Resource": [ + "arn:aws:s3:::mastodata/*" + ] + } + ] +} +``` + +Mastodon 本身需要能够写入存储桶，因此请使用你的 MinIO 管理员帐户（不建议）或附加以下策略的 Mastodon 专用帐户（建议）（将 `mastodata` 替换为你的 S3 存储桶的实际名称）： +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "s3:*", + "Resource": "arn:aws:s3:::mastodata/*" + } + ] +} +``` + +你可以通过 MinIO 控制台（基于 Web 的用户界面）或命令行客户端 (`mcli` / `mc`) 设置这些策略。 + +#### 使用 MinIO 控制台 + +连接到 MinIO 控制台 Web 界面并创建一个新存储桶（或导航到你现有的存储桶）： +![](/assets/object-storage/minio-bucket.png) + +然后，将“访问策略”配置为允许读取访问 (`s3:GetObject`) 而未写入访问或列出对象的能力的自定义策略（见上文）： +![](/assets/object-storage/minio-access-policy.png) + +{{< hint style="info" >}} +如果 MinIO 控制台不允许你设置“自定义”策略，则可能需要更新 MinIO。 如果你在 *独立* 或 *文件系统* 模式下使用 MinIO，则 [`RELEASE.2022-10-24T18-35-07Z`](https://github.com/minio/minio/releases/tag/RELEASE.2022-10-24T18-35-07Z) 应该是一个安全的更新版本，不需要 [涉及迁移过程](https://min.io/docs/minio/linux/operations/install-deploy-manage/migrate-fs-gateway.html#migrate-from-gateway-or-filesystem-mode)。 +{{< /hint >}} + +新建一个 `mastodon-readwrite` 策略（见上文）： +![](/assets/object-storage/minio-mastodon-readwrite.png) + +最后，使用 `mastodon-readwrite` 策略创建一个新的 `mastodon` 用户： +![](/assets/object-storage/minio-mastodon-user.png) + +#### 使用命令行实用程序 + +使用 [MinIO 客户端](https://min.io/docs/minio/linux/reference/minio-mc.html) 命令行实用程序（可以根据安装位置调用 `mc` 或 `mcli`）也可以实现相同的目的。 + +创建一个新存储桶： +`mc mb myminio/mastodata` + +将上面的匿名访问策略保存为 `anonymous-readonly-policy.json`，并将 Mastodon 用户访问策略保存为 `mastodon-readwrite.json`（确保将 `mastodata` 替换为你新创建的存储桶的名称）。 + +设置存储桶的匿名访问策略： +`mc anonymous set-json anonymous-readonly-policy.json myminio/mastodata` + +添加 `mastodon-readwrite` 策略: +`mc admin policy add myminio mastodon-readwrite mastodon-readwrite.json` + +添加 `mastodon` 用户（替换密码）： +`mc admin user add myminio mastodon SECRET_PASSWORD` + +将 `mastodon-readwrite` 策略应用到 `mastodon` 用户： +`mc admin policy set myminio mastodon-readwrite user=mastodon` + +### Wasabi 对象存储 + +创建一个新存储桶并定义其策略，允许对象进行匿名读取但不可列出： +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "AWS": "*" + }, + "Action": "s3:GetObject", + "Resource": "arn:aws:s3:::mastodata/*" + } + ] +} +``` + +![](/assets/object-storage/wasabi-access-policy.png) + +{{< hint style="info" >}} +如果你使用旧存储桶，请确保你没有通过 Wasabi 的旧版访问控制设置授予“所有人”读取对象的权限，因为该设置允许列出对象并优先于上面定义的 IAM 策略。 + +![](/assets/object-storage/wasabi-access-control.png) +{{< /hint >}} + +然后，创建一个 `mastodon-readwrite` 策略以授予对你的存储桶的读写访问权限： +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "s3:*", + "Resource": "arn:aws:s3:::mastodata/*" + } + ] +} +``` + +![](/assets/object-storage/wasabi-mastodon-readwrite.png) + +最后，创建一个新的 `mastodon` 用户，并且不要忘记启用 `mastodon-readwrite` 策略： +![](/assets/object-storage/wasabi-mastodon-user.png) + +在 Mastodon 端，你需要设置`S3_FORCE_SINGLE_REQUEST=true`来正确处理大型上传。 + +### DigitalOcean Spaces + +在你的 DigitalOcean Spaces 存储桶中，确保“文件列表”对于拥有访问密钥的用户是“受限制的”。 + +![](/assets/object-storage/do-spaces.png) + +### Scaleway + +如果你想使用 Scaleway 对象存储，我们强烈建议你创建一个专用于 Mastodon 实例资产的 Scaleway 项目，并使用自定义 IAM 策略。 + +首先，创建一个新的 Scaleway 项目，在其中创建对象存储桶。 你需要将存储桶的可见性设置为“私有”，以不允许列出对象。 + +![](/assets/object-storage/scaleway-bucket.png) + +现在你的存储桶已创建，你需要创建 API 密钥，以便在你的 Mastodon 实例配置中使用。 + +前往 IAM 设置（在你的组织菜单中，屏幕的右上角），然后创建一个新的 IAM 策略（例如 `mastodon-media-access`） + +![](/assets/object-storage/scaleway-policy.jpg) + +此策略需要有一个规则，允许它在你上面创建的 Scaleway 项目（作用域）中读取、写入和删除对象。 + +![](/assets/object-storage/scaleway-policy-rules.jpg) + +然后前往 IAM 应用程序页面，创建一个新的应用程序（例如 `my-mastodon-instance`），并选择你上面创建的策略。 + +最后，单击你创建的应用程序，然后单击“API 密钥”，并创建一个新的 API 密钥，以便在你的实例配置中使用。 你应该使用“是，设置首选项目”选项，并选择你上面创建的项目作为此密钥的默认项目。 + +![](/assets/object-storage/scaleway-api-key.png) + +复制 Access Key ID 和 Secret，并将它们用于你的 `AWS_ACCESS_KEY_ID` 和 `AWS_SECRET_ACCESS_KEY` 这两个 Mastodon 配置变量。 + +### Exoscale + +在 Exoscale 中，你的存储桶不应有任何读取 ACL（Mastodon 将根据需要在对象本身上设置 ACL）。 + +你需要为 Mastodon 应用程序创建一个 API 密钥，该密钥限于对象存储 (`sos`) 服务，限于你的存储桶，并且操作不受限制。 + +![](/assets/object-storage/exoscale.png) + +在 Mastodon 端，你需要设置`S3_FORCE_SINGLE_REQUEST=true`才能正确处理大型上传。 + +### Cloudflare R2 + +Cloudflare R2 不支持 ACL，因此需要指示 Mastodon 不尝试设置他们。 为此，需要将 `S3_PERMISSION` 环境变量设置为空字符串。 + +{{< hint style="warning" >}} +如果不支持 ACL，被封禁的用户的媒体文件仍然可以访问。 +{{< /hint >}} + +要获取在 Mastodon 中使用的凭据，请选择“管理 R2 API 令牌”并创建一个新的 API 令牌，具有“编辑”权限。 + +{{< hint style="warning" >}} +本节正在建设中。 +{{< /hint >}} + + +{{< translation-status-zh-cn raw_title="Object storage" raw_link="/admin/optional/object-storage/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/optional/sso.md b/content/zh-cn/admin/optional/sso.md index ecb9bdd..73130cb 100644 --- a/content/zh-cn/admin/optional/sso.md +++ b/content/zh-cn/admin/optional/sso.md @@ -1,13 +1,15 @@ --- -title: 单点登录（SSO） +title: 单点登录 menu: docs: - weight: 30 + weight: 40 parent: admin-optional --- {{< hint style="danger" >}} -本页面仍在建设中。 +此页面正在建设中。 + +目前，请参考[这个拉取请求](https://github.com/mastodon/mastodon/pull/16221) {{< /hint >}} -{{< translation-status-zh-cn raw_title="Single Sign On" raw_link="/admin/optional/sso/" last_tranlation_time="2020-05-04" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}} +{{< translation-status-zh-cn raw_title="Single Sign On" raw_link="/admin/optional/sso/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/optional/tor.md b/content/zh-cn/admin/optional/tor.md index a9ec046..4d8b5fd 100644 --- a/content/zh-cn/admin/optional/tor.md +++ b/content/zh-cn/admin/optional/tor.md @@ -1,31 +1,31 @@ --- -title: 匿名服务 -description: 通过Tor的匿名服务来访问Mastodon。 +title: 洋葱服务 +description: 通过 Tor 洋葱服务提供 Mastodon 服务。 menu: docs: weight: 20 parent: admin-optional --- -可以通过Tor的匿名服务来访问Mastodon。这将给你一个只能通过 Tor 网络连接的 \*.onion 地址。 +Mastodon 可以通过 Tor 作为洋葱服务提供服务。这将为你提供一个 `*.onion` 地址，该地址只能在连接到 Tor 网络时使用。 ## 安装 Tor {#install} -首先，Tor的Debian软件仓库需要被添加至apt中。 +首先需要将 Tor 的 Debian 存储库添加到 apt 中。 ```text deb https://deb.torproject.org/torproject.org stretch main deb-src https://deb.torproject.org/torproject.org stretch main ``` -接下来，添加相应gpg密钥。 +接下来添加 gpg 密钥。 ```bash curl https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | gpg --import gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | apt-key add - ``` -最后，安装所需软件包。 +最后安装所需的软件包。 ```bash apt install tor deb.torproject.org-keyring @@ -33,10 +33,10 @@ apt install tor deb.torproject.org-keyring ## 配置 Tor {#configure} -编辑 `/etc/tor/torrc` 并添加如下设置。 +编辑 `/etc/tor/torrc` 文件并添加以下配置。 ```text -HiddenServiceDir /var/lib/tor/hidden_service/ +HiddenServiceDir /var/lib/tor/onion_service/ HiddenServiceVersion 3 HiddenServicePort 80 127.0.0.1:80 ``` @@ -47,34 +47,37 @@ HiddenServicePort 80 127.0.0.1:80 sudo service tor restart ``` -现在，你的Tor域名可以在 `/var/lib/tor/hidden_service/hostname` 找到。 +现在你可以在 `/var/lib/tor/hidden_service/hostname` 中找到你的 Tor 主机名。 -## 移动你的Mastodon配置 {#nginx} +## 移动你的 Mastodon 配置 {#nginx} -我们将需要将你的Mastodon配置告诉Nginx两次。为了不自我重复（[DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself)），我们需要将Mastodon配置移动到一个可被引用的独立文件。 +我们需要在 Nginx 中配置两次 Mastodon。为了保持["DRY"](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself)原则，我们需要将 Mastodon 配置移到自己的文件中，以便之后可以引用。 -在 `/etc/nginx/snippets/mastodon.conf` 创建一个新文件。放入除`listen`、`server_name`、`include`及所有SSL相关选项之外的所有配置参数至新文件中。你的新文件看起来可能像这样。 +创建一个新文件 `/etc/nginx/snippets/mastodon.conf`。复制所有 Mastodon 配置参数，除了 `listen`、`server_name`、`include` 指令以及所有 SSL 选项。包含一个 `Onion-Location` 头，让支持的浏览器知道该服务也可以通过 Tor 访问。你的新文件应该看起来像这样： -```text +```nginx add_header Referrer-Policy "same-origin"; +add_header Onion-Location mastodon.qKnFwnNH2oH4QhQ7CoRf7HYj8wCwpDwsa8ohJmcPG9JodMZvVA6psKq7qKnFwnNH2oH4QhQ7CoRf7HYj8wCwpDwsa8ohJmcPG9JodMZvVA6psKq7.onion$request_uri; keepalive_timeout 70; sendfile on; client_max_body_size 80m; root /home/mastodon/live/public; -… + +# … + error_page 500 501 502 503 504 /500.html; access_log /var/log/nginx/mastodon_access.log; error_log /var/log/nginx/mastodon_error.log warn; ``` -替换你的旧Mastodon配置文件，在新配置文件中添加一个include指令。 +在新的配置文件中，在原来 Mastodon 配置的位置添加 `include` 指令。 -你的Nginx配置文件将看起来像这样。 +你的 Nginx 配置文件现在应该看起来像这样： -```text +```nginx server { listen 80; server_name mastodon.example.com; @@ -97,13 +100,15 @@ server { } ``` -## 通过http提供Tor服务 {#http} +## 通过 HTTP 提供 Tor 服务 {#http} -尽管通过https提供你的Tor版Mastodon可能很诱人，但对大多数人来说这不是一个好主意。请参阅Tor Project上的[这篇](https://blog.torproject.org/facebook-hidden-services-and-https-certs)博文，了解为什么https证书无法增加价值。由于你无法获得onion域名的SSL证书，当你尝试使用你的Mastodon时还会被证书错误所困扰。最近，一位Tor开发者在[这里](https://matt.traudt.xyz/p/o44SnkW2.html)阐述了为什么通过https提供Tor服务对大多数用例都没有好处的原因。 +本节假设你希望同时在 Tor 和公共互联网上公开你的实例。 -解决方法是通过http提供你的Mastodon服务，但仅供Tor使用。这可以通过在Nginx配置文件中添加额外的设置来完成。 +虽然通过 HTTPS 提供 Mastodon 的 Tor 版本看起来很诱人，但这并不总是理想的选择。HTTPS 证书主要对能够使用自己的公司信息生成证书的大公司有用。没有证书颁发机构(CA)能[免费](https://community.torproject.org/onion-services/advanced/https/)提供它们，Tor 项目的[一篇博客文章](https://blog.torproject.org/facebook-hidden-services-and-https-certs)也解释了为什么 HTTPS 证书对安全性并没有真正的好处。但另一方面，Mastodon 使用了大量使用到 HTTPS 的重定向，有经过验证的证书可能会使你的用户更容易在 Tor 上使用你的实例，而无需手动删除 URL 中的 `https://` 前缀。 -```text +在本节中，我们将介绍如何通过 HTTP 提供 Mastodon 实例，但仅限于 Tor。这可以通过在现有 Nginx 配置前添加额外配置来实现。 + +```nginx server { listen 80; server_name mastodon.qKnFwnNH2oH4QhQ7CoRf7HYj8wCwpDwsa8ohJmcPG9JodMZvVA6psKq7qKnFwnNH2oH4QhQ7CoRf7HYj8wCwpDwsa8ohJmcPG9JodMZvVA6psKq7.onion; @@ -132,11 +137,11 @@ server { } ``` -用你位于 `/var/lib/tor/hidden_service/hostname` 文件中的长hash替换上文中提供的。 +用 `/var/lib/tor/hidden_service/hostname` 文件中的 Tor 域名替换这里提供的长哈希值。这也应该反映在 snippets 文件中的 `Onion-Location` 头中。 -请注意，onion域名已经被附加了“mastodon.”前缀。你的Tor地址充当通配符域名。所有的子域名都将被路由，你可以配置你的Nginx来响应你想要的任何子域名。如果你不想在你的tor域名上托管任何其他服务，你可以省略子域名，或者选择一个不同的子域名。 +注意洋葱主机名前面加了 "mastodon."。你的 Tor 地址充当通配符域名。所有子域名都会被路由，你可以配置 Nginx 响应你想要的任何子域名。如果你不希望在 Tor 地址上托管任何其他服务，可以省略子域名，或选择不同的子域名。 -这里，你就可以看出移动你的mastodon配置到不同文件的好处了。如果不移动的话，你的所有配置都必须粘贴至两个地方，任何对你配置的改动你都必须同时修改两个地方。 +现在你可以看到将 mastodon 配置移动到不同文件的好处。如果不这样做，所有配置都必须复制到两个地方。对配置的任何更改都必须在两个地方进行。 重启你的Web服务器。 @@ -144,10 +149,11 @@ server { service nginx restart ``` -## 陷阱 {#gotchas} +## 注意事项 {#gotchas} -你需要注意一些事情。某些重定向会将你的用户跳转至https。他们必须手动把URL替换成http才能继续。 +你需要注意几点事项： -许多的资源，诸如图片，将仍然从常规非Tor域名加载。问题的严重性很大程度上取决于用户的谨慎程度。 +- 如前所述，Mastodon前端的某些URL会强制用户使用HTTPS URL。他们必须手动将URL替换为HTTP才能继续。 +- 各种资源，如图像，仍将通过你常规的明网域名提供。这可能会成为问题，具体取决于你的用户希望、尝试或需要多高的隐私程度。 -{{< translation-status-zh-cn raw_title="Hidden services" raw_link="/admin/optional/tor/" last_tranlation_time="2020-05-04" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}} +{{< translation-status-zh-cn raw_title="Onion services" raw_link="/admin/optional/tor/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/prerequisites.md b/content/zh-cn/admin/prerequisites.md index f53952f..7843cdb 100644 --- a/content/zh-cn/admin/prerequisites.md +++ b/content/zh-cn/admin/prerequisites.md @@ -1,20 +1,24 @@ --- -title: 准备你的机器 +title: 准备你的服务器 menu: docs: weight: 10 parent: admin --- -如果你正在设置一台全新的机器，推荐你首要完成安全设置。以下内容假定你运行 **Ubuntu 18.04**： +如果你正在设置一台全新的服务器，建议你首先进行安全设置。假设你运行的是**Ubuntu 22.04**： -## 禁止密码登录SSH（仅允许密钥登录） +## 禁用基于密码的 SSH 登录(仅限密钥) -首先，请确保你实际上是通过密钥而不是通过密码登录到服务器的，否则这将使你无法登录。许多托管服务提供商支持上传公钥，并自动为新机器设置基于密钥的root登录。 +首先，你需要确保自己现在已经是在使用密钥而非密码登录服务器，否则，这将使你无法登录。许多托管提供商支持上传公钥，并自动为新机器设置基于密钥的 root 登录。 -编辑 `/etc/ssh/sshd_config` 并找到 `PasswordAuthentication`。确保它已被去除注释并被设为 `no`。如果你做了任何改动，请重启 sshd。 +编辑 `/etc/ssh/sshd_config` 并找到 `PasswordAuthentication`。确保它已取消注释并设置为 `no`。做出更改后，请重启sshd： -## 更新系统 +```bash +systemctl restart ssh.service +``` + +## 更新系统包 ```bash apt update && apt upgrade -y @@ -22,7 +26,13 @@ apt update && apt upgrade -y ## 安装 fail2ban 以阻止重复登录尝试 -编辑 `/etc/fail2ban/jail.local` 并添加以下内容： +首先，安装fail2ban： + +```bash +apt install fail2ban +``` + +编辑 `/etc/fail2ban/jail.local` 并在其中填入以下内容： ```text [DEFAULT] @@ -32,66 +42,110 @@ sendername = Fail2Ban [sshd] enabled = true port = 22 - -[sshd-ddos] -enabled = true -port = 22 +mode = aggressive ``` -最后重启fail2ban： +最后，重启 fail2ban： ```bash systemctl restart fail2ban ``` -## 安装防火墙并只暴露SSH、HTTP、HTTPS端口 +## 安装防火墙并只允许 SSH、 HTTP 和 HTTPS 端口 -首先，安装 iptables-persistent。在安装期间，它将询问你是否保留现有规则。 +首先，安装 iptables-persistent。在安装过程中，它会询问你是否要保留当前规则——选择拒绝。 ```bash apt install -y iptables-persistent ``` -编辑 `/etc/iptables/rules.v4` 并添加如下内容： +编辑 `/etc/iptables/rules.v4` 并在其中填入以下内容： ```text *filter -# Allow all loopback (lo0) traffic and drop all traffic to 127/8 that doesn't use lo0 +# 允许所有回环(lo0)流量，拒绝所有不通过 lo0 接口访问 127/8 地址段的流量 -A INPUT -i lo -j ACCEPT -A INPUT ! -i lo -d 127.0.0.0/8 -j REJECT -# Accept all established inbound connections +# 接受所有已建立的入站连接 -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT -# Allow all outbound traffic - you can modify this to only allow certain traffic +# 允许所有出站流量 - 你可以修改此规则以实现只允许特定流量 -A OUTPUT -j ACCEPT -# Allow HTTP and HTTPS connections from anywhere (the normal ports for websites and SSL). +# 允许来自任何地方的 HTTP 和与HTTPS 连接(网站和 SSL 服务的标准端口) -A INPUT -p tcp --dport 80 -j ACCEPT -A INPUT -p tcp --dport 443 -j ACCEPT -# Allow SSH connections -# The -dport number should be the same port number you set in sshd_config +# (可选)允许来自任何位置的 HTTP/3 连接 +-A INPUT -p udp --dport 443 -j ACCEPT + +# 允许 SSH 连接 +# 这里的端口号应该与你在 sshd_config 中设置的端口号一致 -A INPUT -p tcp -m state --state NEW --dport 22 -j ACCEPT -# Allow ping +# 允许 ping 请求 -A INPUT -p icmp -m icmp --icmp-type 8 -j ACCEPT -# Log iptables denied calls +# 允许目标不可达消息，这里类型 4(需要分片)的消息对于 PMTUD (路径 MTU 发现)功能至关重要 +-A INPUT -p icmp -m icmp --icmp-type 3 -j ACCEPT + +# 记录被 iptables 拒绝的请求 -A INPUT -m limit --limit 5/min -j LOG --log-prefix "iptables denied: " --log-level 7 -# Reject all other inbound - default deny unless explicitly allowed policy +# 拒绝所有其他入站请求 - 默认拒绝策略，除非明确允许 -A INPUT -j REJECT -A FORWARD -j REJECT COMMIT ``` -iptables-persistent 将在机器启动时自动加载配置。但是由于我们现在不会立刻重启，我们需要第一次手动加载它： +通过使用 iptables-persistent 进行配置，该配置将在启动时加载。但由于我们现在不重启，所以需要手动加载一次： ```bash iptables-restore < /etc/iptables/rules.v4 ``` -{{< translation-status-zh-cn raw_title="Preparing your machine" raw_link="/admin/prerequisites/" last_tranlation_time="2020-05-04" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}} +如果你的服务器也可以通过 IPv6 访问，编辑`/etc/iptables/rules.v6`并添加以下内容： +```text +*filter + +# 允许所有本地回环(lo0)流量，并拒绝所有不通过 lo0 接口访问 127/8 地址段的流量 +-A INPUT -i lo -j ACCEPT +-A INPUT ! -i lo -d ::1/128 -j REJECT + +# 接受所有已建立的入站连接 +-A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT + +# 允许所有出站流量 - 你可以修改此规则以实现只允许特定的流量 +-A OUTPUT -j ACCEPT + +# 允许来自任何位置的 HTTP 和 HTTPS 连接(网站和 SSL 服务的标准端口) +-A INPUT -p tcp --dport 80 -j ACCEPT +-A INPUT -p tcp --dport 443 -j ACCEPT +# (可选) 允许来自任何位置的 HTTP/3 连接 +-A INPUT -p udp --dport 443 -j ACCEPT + +# 允许 SSH 连接 +# 这里的端口号应与 sshd_config 中设置的端口号一致 +-A INPUT -p tcp -m state --state NEW --dport 22 -j ACCEPT + +# 允许 ping +-A INPUT -p icmpv6 -j ACCEPT + +# 记录被 iptables 拒绝的请求 +-A INPUT -m limit --limit 5/min -j LOG --log-prefix "iptables denied: " --log-level 7 + +# 拒绝所有其他入站连接 - 默认拒绝策略，除非明确允许 +-A INPUT -j REJECT +-A FORWARD -j REJECT + +COMMIT +``` +与 IPv4 规则类似，你可以这样手动加载它： +```bash +ip6tables-restore < /etc/iptables/rules.v6 +``` + +{{< translation-status-zh-cn raw_title="Preparing your machine" raw_link="/admin/prerequisites/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/roles.md b/content/zh-cn/admin/roles.md new file mode 100644 index 0000000..a417a99 --- /dev/null +++ b/content/zh-cn/admin/roles.md @@ -0,0 +1,100 @@ +--- +title: 用户组 +description: 通过管理员仪表板管理用户组。 +menu: + docs: + parent: admin +--- + +# 用户组 {#roles} +数据库初始化时，用户组是从[`~/config/roles.yml`](https://github.com/mastodon/mastodon/blob/main/config/roles.yml)中的值派生的。 + +{{< page-ref page="entities/Role" >}} + +生成的[默认用户组](#default-roles)有`所有者`、`管理员`和`协管员`。 + +可以使用*用户组*(`/admin/roles`)页面上的[添加用户组](#add-role)来创建用户组及其属性。 + +![](/assets/admin-roles-ui.png) + +可以使用[编辑用户组](#edit-role)功能更改现有用户组的属性。 + +## 默认用户组 {#default-roles} +### 基础用户组（*默认权限*） {#default-base-role} + +影响所有用户，包括没有分配用户组的用户。 + +此用户组唯一可修改的权限标识是**邀请用户**。启用此权限允许所有用户发送邀请。 + +基础用户组的优先级为`0`，此值不能更改。 + +### 所有者 {#default-owner-role} + +被分配了**管理员**权限标识的用户组，绕过所有权限检查。具有所有者用户组的用户拥有每一个[权限标识](/entities/Role/#permission-flags)。 + +可以更改该用户组的*名称*、*徽章颜色*和*显示徽章*属性。该用户组的权限不能被编辑/撤销。 + +所有者用户组具有最高的[优先级](#role-priority)(`1000`)。所有者可以修改任何其他用户组的属性。创建的用户组不能超越所有者用户组，因为新的和现有用户组的[用户组优先级](#role-priority)必须 <= `999`。 + +### 管理员 {#default-admin-role} + +被分配了所有**审核**和**管理**权限标识的用户组。 + +此用户组的**DevOps**权限标识默认禁用，但可以由**所有者**(或具有更高优先级的自定义用户组)启用。 + +可以更改该用户组的*名称*、*徽章颜色*和*显示徽章*属性。 + +管理员用户组的优先级为`100`。 + +### 协管员 {#default-moderator-role} + +被分配了某些**审核**权限标识的用户组。这些权限标识包括... +- **查看仪表板** +- **查看审计日志** +- **管理用户** +- **管理举报** +- **管理分类** + +可以更改该用户组的*名称*、*徽章颜色*和*显示徽章*属性。 + +协管员用户组的优先级为`10`。 + +## 添加用户组 {#add-role} + +`admin/roles/new`页面允许创建自定义用户组。 + +![](/assets/admin-roles-new-ui.png) + +### 输入字段 {#add-role-input-fields} + +{{< page-relref ref="entities/Role#name" caption="名称">}} + +可以存在重复的用户组名称。它们在数据库中通过`id`区分，该`id`不能从网页界面设置。 + +{{< page-relref ref="entities/Role#color" caption="徽章颜色">}} + +### 优先级 {#role-priority} + +- 默认为`0` + - 不能 > `999` + - 可以是任何负整数值 +- 两个用户组可以具有相同的优先级值 + +> "在特定情况下，由更高优先级的用户组决定冲突解决方式。某些操作只能对优先级较低的用户组执行。" + +{{< page-relref ref="entities/Role#highlighted" caption="在账户页面显示用户组徽章">}} + +{{< page-relref ref="entities/Role#permissions" caption="权限">}} + + +## 编辑用户组 {#edit-role} + +![](/assets/admin-roles-edit-ui.png) + +可以使用用户组列表中的*编辑*来编辑现有用户组及其属性。[输入字段](#add-role-input-fields)可以更改和保存，就像创建新用户组时一样。也可以使用此表单删除用户组。 + +![](/assets/admin-roles-edit-role-ui.png) + +具有**管理用户组**权限的已登录用户始终能够看到每个用户组，但不能修改超过或等于其分配用户组[优先级](#role-priority)的用户组。 + +{{< translation-status-zh-cn raw_title="Roles" raw_link="/admin/roles/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/scaling.md b/content/zh-cn/admin/scaling.md index fe39a8e..58b9366 100644 --- a/content/zh-cn/admin/scaling.md +++ b/content/zh-cn/admin/scaling.md @@ -1,218 +1,283 @@ --- -title: 伸缩你的服务器 -descriptions: 为服务更多用户而优化。 +title: 扩大你的站点规模 +descriptions: 为服务更多用户可以进行的优化。 menu: docs: weight: 100 parent: admin --- -## 并发管理 {#concurrency} +## 管理并发度 {#concurrency} -Mastodon有三种进程： +Mastodon 有三种类型的进程： -* Web (Puma) -* Streaming API -* 后台进程 (Sidekiq) +- Web (Puma) +- 流式 API +- 后台处理 (Sidekiq) ### Web (Puma) {#web} -web进程处理绝大多数应用的短HTTP请求。以下环境变量可以控制它： +Web 进程处理应用大部分的短周期 HTTP 请求。可通过以下环境变量控制并发度： -* `WEB_CONCURRENCY` 控制worker进程数 -* `MAX_THREADS` 控制每进程的线程数 +- `WEB_CONCURRENCY` 控制工作进程的数量 +- `MAX_THREADS` 控制每个进程的线程数量 -线程共享其父进程的内存。不同的线程被分配了专有内存，虽然他们通过copy-on-write共享了一些内存。数量较多的线程会先消耗掉你的CPU，数量较多的进程会先消耗掉你的内存。 +线程共享其父进程的内存。不同的进程分配自己的内存，但通过写时复制共享一些内存。增加线程数量会优先耗尽你的 CPU，而增加进程数量会先耗尽你的 RAM。 -这些数值会影响到可以同时处理多少HTTP请求。 +上述变量的值可以影响同时能处理多少 HTTP 请求。 -在吞吐量方面，多进程比多线程要好。 +就吞吐量指标而言，增加进程数量比增加线程数量效果更好。 -### Streaming API {#streaming} +### 流式 API {#streaming} -streaming API处理长HTTP连接与WebSockets连接，通过这些连接用户可以接受到实时更新。以下环境变量可以控制它： +流式 API 处理长周期 HTTP 和 WebSocket 连接，客户端通过这些连接接收实时更新。可通过以下环境变量控制并发度： -* `STREAMING_CLUSTER_NUM` 控制worker进程数 -* `STREAMING_API_BASE_URL` 控制streaming API的base URL +- `STREAMING_API_BASE_URL` 控制流式 API 的根 URL +- `PORT` 控制流式 API 服务器将监听的端口，默认为4000。`BIND`和`SOCKET`环境变量也可以使用。 +- 此外，流式 API 还使用共享的[数据库](/admin/config#postgresql)和 [Redis](/admin/config#redis) 环境变量。 -一个进程可以处理相当数量的连接。 如果您愿意，streaming API可以托管在其他子域上，例如：避免nginx代理连接开销。 +通过设置 `STREAMING_API_BASE_URL`，流式 API 可以使用不同的子域。这允许你为流式 API 和 Web API 请求使用不同的负载均衡器。然而，这也要求应用程序从[实例端点](/methods/instance/#v2)正确请求流式 API URL，而不是假设它与 Web API 托管在同一域名上。 -### 后台进程 (Sidekiq) {#sidekiq} +流式 API 服务端的一个进程可以处理相当多的连接和吞吐量，但如果你发现单个进程无法处理你实例的负载，你可以通过改变每个进程的 `PORT` 号来运行多个进程，然后使用nginx将流量负载均衡到每个实例。例如，一个有大约 50000 个用户且月活跃用户为 10000 - 20000 个用户的社区，通常会有大约 800-1200 个并发流式 API 连接。 -Mastodon许多任务都分配给后台进程，以确保HTTP请求快速响应，并防止HTTP请求中止影响到这些任务的执行。Sidekiq是单个进程，具有可配置的线程数。 +流式 API 服务端还在 `/metrics` 上暴露了一个 [Prometheus](https://prometheus.io/) 端点，提供许多指标帮助你了解 Mastodon 流式 API 服务器的当前负载，一些关键指标包括： -#### 线程数 {#sidekiq-threads} +- `mastodon_streaming_connected_clients`：这是已连接客户端的数量，按客户端类型标记（websocket 或 eventsource） +- `mastodon_streaming_connected_channels`：这是当前订阅的"频道"数量（注意由于我们内部"系统"频道的工作方式，这个数字比连接的客户端要高得多） +- `mastodon_streaming_messages_sent_total`：这是自上次重启以来发送给客户端的消息总数。 +- `mastodon_streaming_redis_messages_received_total`：这是从 Redis pubsub 接收的消息数量，用于补充[直接监控Redis](https://sysdig.com/blog/redis-prometheus/)。 -虽然web进程数与web线程数影响Mastodon实例响应终端用户，分配给后台进程的线程数影响嘟文从作者分发至其他人的速度，电子邮件花多长时间发完等等。 +{{< hint style="info" >}} +运行的流式 API 服务端进程越多， PostgreSQL 上消耗的数据库连接就越多，所以你可能需要使用 PgBouncer，如下文所述。 +{{< /hint >}} -Sidekiq的线程数并不受环境变量控制，但是可通过命令行参数控制，例如： +下面是一个 nginx 配置示例，用于将流量路由到三个不同的进程，分别运行在 `PORT` 4000、 4001 和 4002 上： + +```text +upstream streaming { + least_conn; + server 127.0.0.1:4000 fail_timeout=0; + server 127.0.0.1:4001 fail_timeout=0; + server 127.0.0.1:4002 fail_timeout=0; +} +``` + +如果你使用分布式 systemd 文件，那么可以使用以下命令启动多个流式 API 服务端： + +```bash +$ sudo systemctl start mastodon-streaming@4000.service +$ sudo systemctl start mastodon-streaming@4001.service +$ sudo systemctl start mastodon-streaming@4002.service +``` + +默认情况下， `sudo systemctl start mastodon-streaming` 只在端口4000上启动一个进程，相当于运行 `sudo systemctl start mastodon-streaming@4000.service`。 + +{{< hint style="warning" >}} +Mastodon 的早期版本有一个 `STREAMING_CLUSTER_NUM` 环境变量，该变量使流式 API 服务端使用集群，它启动多个工作进程并使用 Node.js 进行负载均衡。 + +上述配置与其他配置的交互方式使容量规划变得困难，在涉及到数据库连接和 CPU 资源时尤为如此。默认情况下，流式 API 服务端会消耗所有可用 CPU 上的资源，这可能会与服务器上运行的其他软件产生冲突。另一个常见问题是配置错误的 `STREAMING_CLUSTER_NUM` 导致因为每个集群工作进程打开连接池而耗尽数据库连接，因此 `STREAMING_CLUSTER_NUM` 为 `5` 且 `DB_POOL` 为 `10` 可能会消耗50个数据库连接。 + +现在，单个流式 API 服务端进程最多只会使用 `DB_POOL` 个PostgreSQL连接，并且通过运行更多的流式 API 服务端实例来处理扩展。 +{{< /hint >}} + +### 后台处理 (Sidekiq) {#sidekiq} + +Mastodon 中的许多任务都被委托给后台处理，以确保对 HTTP 请求的快速响应，并防止 HTTP 请求中止影响这些任务的执行。Sidekiq 是一个单一进程，具有可配置的线程数。 + +#### 线程数量 {#sidekiq-threads} + +虽然 Web 进程中的线程数影响 Mastodon 实例对最终用户的响应速度，但分配给后台处理的线程数影响嘟文从作者传递给其他人的速度、邮件发送速度等。 + +线程数不是通过环境变量调整的，而是通过调用 Sidekiq 时的命令行参数调整，如下例所示： ```bash bundle exec sidekiq -c 15 ``` -将启一个15线程的sidekiq进程。请注意每个线程都需要能够连接数据库，这意味着数据库连接池应足够大以满足所有进程。数据库连接池的大小由`DB_POOL`环境变量控制，该变量必须至少与进程数同样大。 +这将以 15 个线程启动 Sidekiq 进程。需要注意的是，每个线程都需要一个数据库连接，所以这需要一个大的数据库池。这个池的大小由 `DB_POOL` 环境变量管理，它应该设置为至少等于线程数的值。 #### 队列 {#sidekiq-queues} -Sidekiq根据任务的重要性使用不同队列，这里的重要性是指如果队列不工作，其对本地用户体验的冲击有多大。按重要性降序排列： +Sidekiq 使用不同的队列来处理不同重要性的任务，其中重要性是指如果队列不工作，对服务器本地用户体验的影响程度。队列按重要性降序列出如下： -| 队列 | 重要性 | -| :--- | :--- | -| `default` | 影响本地用户的所有任务 | -| `push` | 推送消息至其它服务器 | -| `mailers` | 分发电子邮件 | -| `pull` | 从其它服务器拉取信息 | -| `scheduler` | 完成计划任务，例如更新当下流行标签及清理日志 | +`default` +: 影响本地用户的所有任务。 -默认队列及其优先级存储于`config/sidekiq.yml`，但可通过调用Sidekiq命令行覆盖，例如： +`push` +: 将负载传递到其他服务器。 + +`ingress` +: 传入的外站活动。优先级低于默认队列，以便在服务器负载过重时本站用户仍能看到他们的嘟文。 + +`mailers` +: 负责邮件的传递。 + +`pull` +: 较低优先级的任务，如处理导入、备份、解析嘟文串、删除用户、转发回复。 + +`scheduler` +: 处理定时任务，如刷新热门话题标签和清理日志。 + +默认队列及其优先级存储在 [config/sidekiq.yml](https://github.com/mastodon/mastodon/blob/main/config/sidekiq.yml) 中，但可以通过 Sidekiq 的命令行调用进行覆盖，例如： ```bash bundle exec sidekiq -q default ``` -仅运行`default`队列。 +此命令将只运行 `default` 队列。 -Sidekiq处理队列的方式是，它首先检查第一个队列中的任务，如果没有，则检查下一个队列。这意味着，如果第一个队列已满，其他队列将延后。 +Sidekiq 通过首先检查第一个队列中的任务来处理队列，如果没有找到，它会检查后续队列。因此，如果第一个队列过满，其他队列中的任务可能会遭遇延迟。 -作为一种解决方案，可以启动为不同队列启动不同的Sidekiq进程以确保真正的并列执行，例如：使用不同Sidekiq参数创建多个systemd服务。 +为队列创建不同的 Sidekiq 进程，可以实现真正的并行执行，例如为具有不同参数的 Sidekiq 创建多个 systemd 服务。 -**请确保仅有一个`scheduler`队列！！** +{{< hint style="warning" >}} +你可以根据需要运行任意多的 Sidekiq 进程和线程，以有效处理运行中的作业，但是 `scheduler` 队列永远不应该在多个 Sidekiq 进程中同时运行。 +{{< /hint >}} +## 使用PgBouncer进行事务池化 {#pgbouncer} -## 使用pgBouncer事务池 {#pgbouncer} +### 为什么你可能需要PgBouncer {#pgbouncer-why} -### 你为什么要用PgBouncer {#pgbouncer-why} +如果你开始耗尽可用的 PostgreSQL 连接（默认为100个），那么 PgBouncer 可能是一个好的解决方案。本文档描述了一些常见的问题，以及 Mastodon 的良好配置默认值。 -如果开始耗尽可用的Postgres连接（默认为100），那PgBouncer可能是一个好方案。本文档将介绍Mastodon的一些常见陷阱及好的默认配置。 - -请注意，你可以在管理界面的“PgHero”查看当前使用了多少Postgres连接。通常Mastodon使用Puma、Sidekiq、streaming API三者线程数总和的连接数。 +在 Mastodon 中具有 `DevOps` 权限的用户可以通过管理视图中的 PgHero 链接监控当前 PostgreSQL 连接的使用情况。通常，打开的连接数等于 Puma、Sidekiq 和流媒体 API 中的线程总数。 ### 安装PgBouncer {#pgbouncer-install} -在Debian和Ubuntu： +在 Debian 和 Ubuntu 上： ```bash sudo apt install pgbouncer ``` -### 配置PgBouncer {#pgbouncer-config} +### 配置 PgBouncer {#pgbouncer-config} #### 设置密码 {#pgbouncer-password} -首先，如果你的Postgres中`mastodon`帐户没有设置密码的话，你需要设置一个密码。 -First off, if your `mastodon` user in PostgreSQL is set up without a password, you will need to set a password. +首先，如果你的 PostgreSQL 中的 `mastodon` 用户没有设置密码，你需要设置一个密码。 -下面是如何重置密码： +以下是重置密码的方法： ```bash psql -p 5432 -U mastodon mastodon_production -w ``` -之后（很显然，使用一个与单词“password”不同的密码）： +然后（显然，此处应该使用不同于 "password" 的密码）： ```sql ALTER USER mastodon WITH PASSWORD 'password'; ``` -然后输入 `\q` 退出。 +然后使用 `\q` 退出。 -#### 配置userlist.txt {#pgbouncer-userlist} +#### 配置 userlist.txt {#pgbouncer-userlist} 编辑 `/etc/pgbouncer/userlist.txt` -只要稍后你在 pgbouncer.ini 中指定一个用户名/密码，userlist.txt文件中的值*不必*与真实PostgreSQL用户相同。你可以随意设定用户名和密码，但是为方便起来，你可以重用“真实”的凭证。添加`mastodon`帐户至`userlist.txt`： +只要你在稍后的 `pgbouncer.ini` 中指定了用户/密码， `userlist.txt` 中的值就不必与真实的 PostgreSQL 用户组对应。你可以任意定义用户和密码，但为了简单起见，你可以重用"真实"的凭证。将 `mastodon` 用户添加到 `userlist.txt`： ```text "mastodon" "md5d75bb2be2d7086c6148944261a00f605" ``` -这里，我们使用md5格式，这里的md5密码就是字符串`密码 + 用户名`的md5值附加上`md5`。例如：为了获得用户名为`mastodon`密码为`password`的散列值，你可以这样做： +这里我们使用 md5 方案，其中 md5 密码只是 `password + username` 的 md5sum，前面加上字符串 `md5`。例如，为用户 `mastodon` 和密码 `password` 生成哈希： ```bash -# ubuntu, debian, etc. +# ubuntu, debian等 echo -n "passwordmastodon" | md5sum -# macOS, openBSD, etc. +# macOS, openBSD等 md5 -s "passwordmastodon" ``` -然后将`md5`添加至开头。 +然后只需在开头添加 `md5`。 -你也可以创建一个`pgbouncer`管理帐户，以登入查看PgBouncer管理数据库。下面是一个`userlist.txt`文件的例子： +你还需要创建一个 `pgbouncer` 管理员用户来登录 PgBouncer 管理数据库。这里是一个示例 `userlist.txt`： ```text "mastodon" "md5d75bb2be2d7086c6148944261a00f605" "pgbouncer" "md5a45753afaca0db833a6f7c7b2864b9d9" ``` -以上两个帐户密码者是`password`。 +上述两个示例中的密码都为 `password`。 #### 配置 pgbouncer.ini {#pgbouncer-ini} 编辑 `/etc/pgbouncer/pgbouncer.ini` -在`[databases]`行下，列出你想连接的Postgres数据库。这里PgBouncer将使用同样的用户名/密码和数据库名称连接下层Postgres数据库： +在 `[databases]` 部分添加一行，列出你想连接的 PostgreSQL 数据库。这里我们只让 PgBouncer 使用相同的用户名/密码和数据库名来连接底层的 PostgreSQL 数据库： -```text +```ini [databases] mastodon_production = host=127.0.0.1 port=5432 dbname=mastodon_production user=mastodon password=password ``` -`listen_addr` 和 `listen_port` 告诉 PgBouncer 从哪个地址/端口接收连接。默认值即可： +`listen_addr` 和 `listen_port` 将告知 PgBouncer 接受哪个地址/端口的连接。默认值的效果已经较为理想： -```text +```ini listen_addr = 127.0.0.1 listen_port = 6432 ``` -将`auth_type`设为`md5`（假定你在`userlist.txt`使用md5格式）： +将 `auth_type` 设为 `md5`（假设你在 `userlist.txt` 中使用了 md5 格式）： -确保`pgbouncer`帐户为管理员： +```ini +auth_type = md5 +``` -**接下来的部分极其重要！** 默认连接池模式是基于连接（session-based），但是Mastodon需要基于事务（transaction-based）。换而言之，当一个事务创建一个Postgres连接随之创建，当事务完成该连接也随之结束。因此，你需要把`pool_mode`从`session`改为`transaction`： +确保 `pgbouncer` 用户是管理员： -接下来，`max_client_conn`定义PgBouncer自身接受多少连接，`default_pool_size`限制后台开启多少Postgres连接。（在PgHero，显示的连接数将与`default_pool_size`数目一致，因为它不知道PgBouncer。） +```ini +admin_users = pgbouncer +``` -使用默认值启动即可，你可以随后调大他们： +Mastodon 需要不同于默认的基于会话的池化模式。具体而言，它需要基于事务的池化模式。这意味着 PostgreSQL 连接在事务开始时建立，在事务完成时终止。因此，必须将 `pool_mode` 设置从 `session` 更改为 `transaction`： -```text +```ini +pool_mode = transaction +``` + +接下来， `max_client_conn` 定义 PgBouncer 本身将接受多少个连接，而 `default_pool_size` 限制了底层会开启多少个 PostgreSQL 连接。（在 PgHero 中举报的连接数将对应于 `default_pool_size`，因为它不知道 PgBouncer 的存在）。 + +默认值可以开始，之后你可以随时增加它们： + +```ini max_client_conn = 100 default_pool_size = 20 ``` -完成更改后，不要忘记重载（reload）或重启（restart）pgbouncer： +修改完成后，不要忘记重新加载或重新启动 PgBouncer： ```bash sudo systemctl reload pgbouncer ``` -#### 调试，确保一切正常 {#pgbouncer-debug} +#### 调试并确认一切正常 {#pgbouncer-debug} -你应该能像连接Postgres一样连接PgBouncer： +你应该能够像连接 PostgreSQL 那样连接到 PgBouncer： ```bash psql -p 6432 -U mastodon mastodon_production ``` -然后，使用你的密码登录。 +然后使用你的密码登录。 -你也可以检查PgBouncer日专，就像这样： +你还可以这样检查 PgBouncer 日志： ```bash tail -f /var/log/postgresql/pgbouncer.log ``` -#### 配置 Mastodon 以连接 PgBouncer {#pgbouncer-mastodon} +#### 配置 Mastodon 与 PgBouncer 通信 {#pgbouncer-mastodon} -首先，确保`.env.production`文件这样设置： +在你的 `.env.production` 文件中，首先确保配置了： ```bash PREPARED_STATEMENTS=false ``` -因为我们使用基于事务（transaction-based）的连接池，我们不能使用参数化查询（prepared statement）。 +由于我们使用基于事务的池化，我们不能使用预处理语句。 -接下来，配置Mastodon使用6432端口（PgBouncer）而不是5432端口（PostgreSQL）就可以了： +接下来，配置 Mastodon 使用端口 6432（PgBouncer）而不是 5432（PostgreSQL），之后你应该就可以开始运行了： ```bash DB_HOST=localhost @@ -223,18 +288,18 @@ DB_PORT=6432 ``` {{< hint style="warning" >}} -你不能使用pgBouncer来执行 `db:migrate` 操作。但是这个问题很容易解决。如果你的postgres和pgBouncer位于同一台主机，只需要在执行任务时与 `RAILS_ENV=production` 一同定义 `DB_PORT=5432` 就可以了，例如：`RAILS_ENV=production DB_PORT=5432 bundle exec rails db:migrate`（如果主机不同，你也可以指定`DB_HOST`等等） +PgBouncer 不能用于执行 `db:migrate` 任务，但这很容易解决。如果你的 PostgreSQL 和 PgBouncer 在同一主机上，可以简单地在调用任务时定义 `DB_PORT=5432` 和 `RAILS_ENV=production`，例如： `RAILS_ENV=production DB_PORT=5432 bundle exec rails db:migrate` （如果不同，你也可以指定 `DB_HOST` 等） {{< /hint >}} #### 管理 PgBouncer {#pgbouncer-admin} -最简单的重启方法： +最简单的重启方法是： ```bash sudo systemctl restart pgbouncer ``` -但如果你设定了PgBouncer管理员帐户，你也可以用管理员帐户连接： +但如果你已经设置了 PgBouncer 管理员用户，你也可以以管理员身份连接： ```bash psql -p 6432 -U pgbouncer pgbouncer @@ -246,22 +311,131 @@ psql -p 6432 -U pgbouncer pgbouncer RELOAD; ``` -使用 `\q` 以退出。 +然后使用 `\q` 退出。 -## 单独的Redis缓存 {#redis} +## 针对缓存分离Redis {#redis} -Redis被广泛使用于应用，但是某些用途比其他用途更重要。主页时间轴、列表时间轴、Sidekiq队列还有streaming API都是由Redis支持的，这些是你不希望丢失的重要数据（尽管丢失了也能存活，不像PostgreSQL数据库的丢失——永远不要丢失PostgreSQL数据库！）。然而，Redis也被用于易失性缓存。如果你正处于扩展阶段，担心你的Redis能否处理所有事情，你可以使用一个不同的Redis数据库来做缓存。在环境变量中，你可以指定 `CACHE_REDIS_URL` 或分离形式，就像 `CACHE_REDIS_HOST`、 `CACHE_REDIS_PORT`等等。未指定部分将会回落至没有前缀的相同设定值。 +Redis 在整个应用中被广泛使用，但有些用途比其他用途更重要。主页订阅、列表订阅、 Sidekiq 队列以及流式 API 都由 Redis 支持，这些是你不想丢失的重要数据（虽然与比不可丢失的 PostgreSQL 数据库不同，丢失这些数据也可以恢复）。 -至于Redis数据库配置，基本上你可以去除后台保存至磁盘，因为重启致使数据丢失也没关系，你可以以此节省一些磁盘I/O。你还可以添加最大内存限制和 key eviction policy，对于这部分，请参阅这个指南：[Using Redis as an LRU cache](https://redis.io/topics/lru-cache)。 +Redis 也用于易失性缓存。如果你正在扩展站点规模，并担忧 Redis 处理负载的能力，你可以专门为缓存分配一个单独的 Redis 数据库。要做到这一点，请在环境中设置 `CACHE_REDIS_URL`，或者定义单独的组件如 `CACHE_REDIS_HOST`、 `CACHE_REDIS_PORT` 等。 -## 只读副本（Read-replicas） {#read-replicas} +未指定的组件将默认为没有 `CACHE_` 前缀的值。 -为了减轻你的Postgresql服务器负担，你可以使用热流复制（hot streaming replication）（只读副本（read replica））。有关示例，请参见[该指南](https://cloud.google.com/community/tutorials/setting-up-postgres-hot-standby)。你可以给以下Mastodon用途使用副本（replica）： +在配置用于缓存的 Redis 数据库时，可以禁用后台保存到磁盘的功能，因为在重启时数据丢失不是很关键，这可以节省一些磁盘 I/O。此外，考虑设置最大内存限制和实现键驱逐策略。有关这些配置的更多详细信息，请查看此指南：[使用 Redis 作为 LRU 缓存](https://redis.io/topics/lru-cache) -* streaming API 服务器无需写入，因此你可以将其直接使用副本（replica）。但由于 streaming API 服务器不经常查询数据库，这样的优化影响很小。 -* 使用 Makara 驱动 web 与 sidekiq 进程，这样可以实现从主（primary）数据库写，从副本（replica）读。让我们开始吧。 +## 针对 Sidekiq 分离 Redis {#redis-sidekiq} -编辑 `config/database.yml` 文件，将 `production` 替换为如下内容： +Redis 在 Sidekiq 中用于跟踪其锁和队列。尽管总体上性能提升不是很大，但一些实例可能会受益于为 Sidekiq 单独设置 Redis 实例。 + +在环境文件中，你可以指定 `SIDEKIQ_REDIS_URL` 或单独的部分如 `SIDEKIQ_REDIS_HOST`、 `SIDEKIQ_REDIS_PORT` 等。未指定的部分回退到不带 `SIDEKIQ_` 前缀的相同值。 + +创建一个单独的 Redis 实例用于 Sidekiq 相对简单： + +首先复制默认的 redis systemd 服务： + +```bash +cp /etc/systemd/system/redis.service /etc/systemd/system/redis-sidekiq.service +``` + +在 `redis-sidekiq.service` 文件中，更改以下值： + +```bash +ExecStart=/usr/bin/redis-server /etc/redis/redis-sidekiq.conf --supervised systemd --daemonize no +PIDFile=/run/redis/redis-server-sidekiq.pid +ReadWritePaths=-/var/lib/redis-sidekiq +Alias=redis-sidekiq.service +``` + +为新的 Sidekiq Redis 实例复制 Redis 配置文件： + +```bash +cp /etc/redis/redis.conf /etc/redis/redis-sidekiq.conf +``` + +在复制后的 `redis-sidekiq.conf` 文件中，更改以下值： + +```bash +port 6479 +pidfile /var/run/redis/redis-server-sidekiq.pid +logfile /var/log/redis/redis-server-sidekiq.log +dir /var/lib/redis-sidekiq +``` + +在启动新的 Redis 实例之前，创建一个数据目录： + +```bash +mkdir /var/lib/redis-sidekiq +chown redis /var/lib/redis-sidekiq +``` + +启动新的 Redis 实例： + +```bash +systemctl enable --now redis-sidekiq +``` + +更新你的环境变量，并添加以下行： + +```bash +SIDEKIQ_REDIS_URL=redis://127.0.0.1:6479/ +``` + +重启 Mastodon 以使用新的 Redis 实例。确保同时重启 web 和 Sidekiq（否则其中一个仍将从错误的实例工作）： + +```bash +systemctl restart mastodon-web.service +systemctl restart redis-sidekiq.service +``` + + +## 用于高可用场景的 Redis Sentinel {#redis-sentinel} + +如前所述， Redis 是 Mastodon 实例运行的关键部分。默认情况下，你的部署将使用单个 Redis 实例，或者如果你设置了缓存，则使用多个实例。但是，如果该实例宕机，也可能导致整个 Mastodon 实例宕机。为了缓解这个问题，可以使用 Redis Sentinel 来跟踪你的 Redis 实例，并在一个实例宕机时自动将客户端引导到新的主实例。你可以指定 `REDIS_SENTINELS`，这是 Mastodon 可以与之交互的 Sentinel 实例的 IP:Port 组合的以逗号分隔的列表，以确定当前的主 Redis 节点。你还需要在 `REDIS_SENTINEL_MASTER` 中指定你想要连接的主节点的名称。默认情况下， Sentinel 将在当前主节点无法访问一分钟后将其设置为宕机并选择新的主节点，但这可以根据你的设置进行配置。 + +所有与 sentinel 相关的变量也可以设置 `CACHE_`和`SIDEKIQ_` 前缀，以便使用多个redis实例。 + +了解更多关于 Redis sentinel 的信息：https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/ + +## 读副本 {#read-replicas} + +为了减轻 PostgreSQL 服务器的负载，你可能希望设置热数据流式复制（读副本）。[参见此指南获取示例](https://cloud.google.com/community/tutorials/setting-up-postgres-hot-standby)。 + +### Mastodon >= 4.2 + +从 4.2 版本开始，Mastodon 内置了对副本的支持。你可以为每个服务（包括 Sidekiq）使用相同的配置，当情况允许时，某些查询将使用 Rails 内置的副本支持被定向到读副本。如果你的副本落后超过几秒钟，应用将停止向它发送查询，直到它赶上进度。 + +要配置读副本，请使用以下环境变量： + +``` +REPLICA_DB_HOST +REPLICA_DB_PORT +REPLICA_DB_NAME +REPLICA_DB_USER +REPLICA_DB_PASS +REPLICA_PREPARED_STATEMENTS +REPLICA_DB_TASKS +``` + +或者，如果你想使用同一个变量配置上述所有配置，也可以使用 `REPLICA_DATABASE_URL`。 + +`REPLICA_DB_TASKS=false` 将使应用连接到副本数据库，但不执行任何数据库管理任务，如模型管理、迁移、种子管理等。默认情况下，它被设为 true。 + +作为可选选项，可用 `REPLICA_PREPARED_STATEMENTS` 覆盖 `PREPARED_STATEMENTS` 的值。如果未设置 `PREPARED_STATEMENTS`，默认为 true。 + +应用上述配置后，你应该开始看到对副本服务器的请求了！ + +### Mastodon <= 4.1 + +对于 4.2 之前的 Mastodon 版本，你可以通过以下方式在 Mastodon 中使用副本： + +- 流式 API 服务端完全不发出写操作，所以你可以直接将其连接到副本（它无论如何也不经常查询数据库，所以这样做的影响很小）。 +- 在 web 和 Sidekiq 进程中使用 Makara 驱动程序，使写操作发送到主数据库，而读操作发送到副本。让我们来讨论这个。 + +{{< hint style="warning" >}} +Sidekiq 进程当前不支持读副本，对 Sidekiq 进程使用读副本将导致作业失败和数据丢失。 +{{< /hint >}} + +你将需要为web进程使用单独的 `config/database.yml` 文件，并编辑它以替换 `production` 部分，如下所示： ```yaml production: @@ -279,10 +453,27 @@ production: url: postgresql://db_user:db_password@db_host:db_port/db_name ``` -确保URL指向PostgreSQL服务器所在位置。你可以添加多个副本（replica）。你可以本地安装一个pgBouncer，该pgBouncer可被配置为根据数据库名称连接两个不同服务器，例如：“mastodon”连接主服务器，“mastodon_replica”连接副本服务器，这样上面文件中的两个URL可以使用同样用户名、密码、主机、端口，不同数据库名称。可能的设置有很多！有关Makara的更多信息，请参阅[其文档](https://github.com/taskrabbit/makara#databaseyml)。 +确保 URL 指向 PostgreSQL 服务器的正确位置。你可以添加多个副本。你可以在本地安装一个 PgBouncer，并配置其基于数据库名称连接到两个不同的服务器，例如， "mastodon" 连接到主服务器， "mastodon_replica" 连接到副本，因此在上面的文件中，两个URL都会指向具有相同用户、密码、主机和端口但数据库名称不同的本地 PgBouncer。这样设置的可能性很多。有关 Makara 的更多信息，[请查看其文档](https://github.com/taskrabbit/makara#databaseyml)。 {{< hint style="warning" >}} -Sidekiq无法可靠的使用只读副本（read-replicas），因为即使是最微小的复制延迟也会导致查询不到相关纪录所致的任务失败。 +确保 sidekiq 进程运行使用标准的 `config/database.yml`，以避免作业失败和数据丢失！ {{< /hint >}} -{{< translation-status-zh-cn raw_title="Scaling up your server" raw_link="/admin/scaling/" last_tranlation_time="2020-05-06" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}} +## 使用 Web 负载均衡器 + +像 DigitalOcean、AWS、Hetzner 等云提供商提供虚拟负载均衡解决方案，它们在多个服务器之间分配网络流量，但提供单一的公共 IP 地址。 + +可以扩展你的部署架构，在其中一个虚拟负载均衡器后面设置多个 web/Puma 服务器，以减少单个服务器被用户流量压垮的风险，帮助提供更一致的性能，并在进行维护或升级时减少停机时间。你应该咨询提供商的文档了解如何设置和配置负载均衡器，但要考虑到你需要配置负载均衡器来监控后端 web/Puma 节点的健康状况，否则你可能会向不响应的服务发送流量。 + +以下端点可用于监控此目的： + +- **Web/Puma:** `/health` +- **流媒体API:** `/api/v1/streaming/health` + +这两个端点都应返回HTTP状态码200，以及文本`OK`作为结果。 + +{{< hint style="info" >}} +你也可以将这些端点用于第三方监控/警报工具的健康检查。 +{{< /hint >}} + +{{< translation-status-zh-cn raw_title="Scaling up your server" raw_link="/admin/scaling/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/setup.md b/content/zh-cn/admin/setup.md index c0f1c07..5cc7252 100644 --- a/content/zh-cn/admin/setup.md +++ b/content/zh-cn/admin/setup.md @@ -1,25 +1,29 @@ --- -title: 配置你的新实例 -description: 一些需要在安装完Mastodon做的事情 +title: 设置你的新实例 +description: 安装 Mastodon 后需要做的事情 menu: docs: weight: 50 parent: admin --- -## 创建一个管理员帐户 {#admin} +## 创建管理员账户 {#admin} -### 通过浏览器 {#admin-gui} +### 在浏览器中创建 {#admin-gui} -在通过浏览器完成帐户注册后，你需要使用命令行给你新创建的帐户以管理员特权。假设你帐户的用户名为`alice`： +在浏览器中注册后，你需要使用命令行给你新创建的账户授予管理员权限。假设你的用户名是 `alice`： ```bash RAILS_ENV=production bin/tootctl accounts modify alice --role Owner ``` -### 通过命令行 {#admin-cli} +{{}} +在 Mastodon 4.0 之前，用户组被硬编码为 `user`、`moderator` 或 `admin` 之一。从 4.0 版本开始， Mastodon 有了一个可自定义的用户组系统，默认创建的用户组为 `Moderator`、`Admin` 和 `Owner`。自定义用户组的名称区分大小写。 +{{}} -你可以使用命令行创建一个全新帐户。 +### 从命令行 {#admin-cli} + +你可以使用命令行创建一个新账户。 ```bash RAILS_ENV=production bin/tootctl accounts create \ @@ -29,19 +33,19 @@ RAILS_ENV=production bin/tootctl accounts create \ --role Owner ``` -一个随机密码将会显示在终端上。 +终端将输出随机生成的密码。 ## 填写站点信息 {#info} -登录后，打开**网站设置**页面。虽然从技术上来说无需填写这些信息，但对于操作服务器的人而言，这被认为是至关重要的。 +登录后，转到**站点设置**页面（在**首选项** -> **管理**下）。理论上填写这些信息不是必须的，但对于运营一个面向人类的站点来说，这被认为是至关重要的。 -| 设置 | 含意 | +| 设置 | 含义 | | :--- | :--- | -| 用于联系的公开用户名 | 你的用户名，人们可以知道谁运营着这台服务器 | -| 用于联系的公开电子邮件地址 | 一个可以联系到你的电子邮件地址，可供那些帐户被锁或没有帐户的人使用 | -| 本站简介 | 你为什么启动这个站点？为谁运营？什么使它与众不同？ | -| 本站详细介绍 | 你可以在此放置各种信息，但建议放置**行为准则**。 | +| 联系人用户名 | 你的用户名，让人们知道谁拥有此站点 | +| 业务邮箱 | 一个电子邮件地址，方便被锁定在账户之外的人或没有账户的人联系你 | +| 实例描述 | 你为什么创建这个站点？它适合谁？它有什么不同？ | +| 自定义扩展信息 | 你可以在这里各种信息，但推荐放置**行为准则** | -填写完这些后，请点击“保存更改”。 +填写完这些信息后，点击"保存更改"。 -{{< translation-status-zh-cn raw_title="Setting up your new instance" raw_link="/admin/setup/" last_tranlation_time="2020-05-04" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}} +{{< translation-status-zh-cn raw_title="Setting up your new instance" raw_link="/admin/setup/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/tootctl.md b/content/zh-cn/admin/tootctl.md index 776f135..3c66308 100644 --- a/content/zh-cn/admin/tootctl.md +++ b/content/zh-cn/admin/tootctl.md @@ -1,461 +1,950 @@ --- -title: 使用管理命令行 -description: 可以从命令行运行tootctl命令 +title: 使用管理 CLI +description: 可以从 CLI 运行的 tootctl 命令。 menu: docs: weight: 60 parent: admin --- ---- -Mastodon的命令行界面是一个位于Mastodon根目录内`bin`目录中的名为`tootctl`的可执行文件。你必须通过`RAILS_ENV`环境变量指定你执行时打算使用的环境。除非你是在本地计算机上进行开发工作，否则你需要使用`RAILS_ENV=production`。如果你确信永不使用其它环境（开发、测试），为了方便起见，你可以把它添加到 `.bashrc` 文件，例如： +Mastodon 的命令行界面是一个名为 `tootctl` 的可执行文件，位于 Mastodon 根目录中的 `bin` 目录内。每次执行它时，你必须通过指定 `RAILS_ENV` 环境变量来指定你打算使用的环境。除非你是在本地机器上工作的开发人员，否则你需要使用 `RAILS_ENV=production`。如果你确信永远不需要其他环境（用于开发、测试或暂存），可以为方便起见将其添加到 `.bashrc` 文件中，例如： ```bash echo "export RAILS_ENV=production" >> ~/.bashrc ``` -如果这样，便无需在每次执行时指定它。否则，通常会这样调用 `tootctl` 命令（假定你的Mastodon代码位于`/home/mastodon/live`）： +如果这样做，你就不需要每次都在行内指定它。如果未配置全局环境变量，且 Mastodon 代码被检出在 `/home/mastodon/live` 中，对 `tootctl` 的调用通常会像这样： ```bash cd /home/mastodon/live RAILS_ENV=production bin/tootctl help ``` -## 基础命令 +## CLI 基础命令 {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/base.rb" caption="lib/mastodon/cli/base.rb" >}} + +--- + + ### `tootctl self-destruct` {#self-destruct} -通过向所有己知实例广播帐户删除通告，将本服务器从联邦宇宙抹除。此命令允许Mastodon服务器“干净退出（clean exit）”，即几乎不在其它服务器留下任何缓存。此命令始终是交互式的，且需要二次确认。 +向其他所有已知实例广播账户删除活动，从联邦中擦除此服务器。这允许运行 Mastodon 的站点从联邦宇宙中"干净退出"，因为它几乎不会在其他实例上留下缓存。该命令始终是交互式的，需要两次确认。 -实际上，不会删除任何本地数据，因为直接清空数据库或删除整个VPS更快。如果你运行此命令后，无论如何都要继续运营实例，状态不匹配可能导致与其它站点互联时出错。 +本地数据实际上并未被删除，因为清空数据库或删除整个 VPS 更快。如果你运行此命令后继续操作实例，则可能会导致状态不匹配，进而导致联合出现故障和问题。 {{< hint style="danger" >}} -**运行此命令之前，请确保你确实知道自己正在做什么。**此操作**不**可逆，并且可能花费很长时间。完成此命令之后，服务器将处于**破碎状态**（BROKEN STATE）。需要一个运行中的Sidekiq进程，所以在队列完全被清空之前不要关闭服务器。 +**在运行此命令之前，请确保你完全了解自己在做什么。** 此操作**不可逆转**，并且可能需要很长时间。站点将在此命令完成后处于**损坏状态**。需要一个正在运行的 Sidekiq 进程，因此在队列完全清空之前不要关闭站点。 {{< /hint >}} -**版本历史：** -* 2.8.0 - 被加入 +`--dry-run` +: 仅打印预期结果，不执行任何操作。 + +**版本历史：**\ +2.8.0 - 该命令被添加 + + +--- -| 选项 | 描述 | -| :--- | :--- | -| `--dry_run` | 仅打印预期结果，而不执行任何操作。 | ### `tootctl --version` {#version} -展示目前运行的Mastodon实例版本。 +显示当前运行的 Mastodon 实例的版本。 -**版本历史：** -* 2.7.0 - 被加入 +**版本历史：**\ +2.7.0 - 该命令被添加 -## 帐户相关命令 {#accounts} + +--- + + +## 账户 CLI {#accounts} {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/accounts.rb" caption="lib/mastodon/cli/accounts.rb" >}} + +--- + + ### `tootctl accounts rotate` {#accounts-rotate} -生成并广播新的RSA密钥，作为安全维护的一部分。 +生成并广播新的 RSA 密钥，作为安全维护的一部分。 -**版本历史：** -* 2.5.0 - 被加入 +`USERNAME` +: 账户的本站用户名。 + +`--all` +: 可以代替 `USERNAME` 提供，为所有本站账户轮换密钥。 + +**版本历史：**\ +2.5.0 - 该命令被添加 + + +--- -| 选项 | 描述 | -| :--- | :--- | -| `USERNAME` | 本地帐户用户名 | -| `--all` | 轮替所有本地帐户密钥，可取代 USERNAME。 | ### `tootctl accounts create` {#accounts-create} -创建一个给定用户名（USERNAME）和给定电子邮件地址（--email）的新帐户。 +使用给定的 `USERNAME` 和提供的 `--email` 创建新用户账户。 -**版本历史：** -* 2.6.0 - 被加入 +`USERNAME` +: 新账户的本站用户名。{{}} + +`--email EMAIL` +: 用户的电子邮件地址。{{}} + +`--confirmed` +: 跳过发送确认电子邮件的流程并立即激活账户。 + +`--role ROLE` +: 通过提供对应[用户组]({{< relref "entities/Role" >}})的 `name` 来定义新账户的自定义用户组。默认用户组包括 `Owner`、`Admin` 和 `Moderator`（区分大小写）。 + +`--reattach` +: 在账户被删除后重新使用旧的 USERNAME。 + +`--force` +: 强制删除任何具有此 `USERNAME` 的现有账户，并重新创建同名的新账户。 + +`--skip-sign-in-token` +: 强制确保用户永远不会被要求提供电子邮件发送的安全代码。 + +**版本历史：**\ +2.6.0 - 该命令被添加\ +4.0.0 - `--role` 不再接受硬编码的 `user`、`moderator` 或 `admin` 用户组。请指定自定义用户组的名称（区分大小写）。 + + +--- -| 选项 | 描述 | -| :--- | :--- | -| `USERNAME` | 新帐户的本地用户名。 必须的。 | -| `--email EMAIL` | 要附加到用户的电子邮件地址。 必须的。 | -| `--confirmed` | 跳过发送确认邮件步骤并立即激活帐户。 | -| `--role ROLE` | 设定新用户的身份为 `user`, `moderator` 或 `admin`。默认为 `user`。 | -| `--reattach` | 重用已被删除帐户的旧用户名。 | -| `--force` | 强制删除使用此用户名（USERNAME）的现有帐户，然后重新的新帐户代替（刚刚删除的）该帐户。 | -| `--skip-sign-in-token` | 强制跳过该用户登录时的邮件验证码（目前这是不可逆操作）。 | ### `tootctl accounts modify` {#accounts-modify} -修改某帐户的身份，电子邮箱地址，激活状态，审核状态及禁用双因素认证（2FA）。 +修改用户账户的用户组、邮箱、活动状态、批准状态或 2FA 要求。 -**版本历史：** -* 2.6.0 - 被加入 +`USERNAME` +: 账户的本站用户名。{{}} + +`--role ROLE` +: 通过提供对应[用户组]({{< relref "entities/Role" >}})的 `name` 来定义现有账户的自定义用户组。默认用户组包括 `Owner`、`Admin` 和 `Moderator`（区分大小写）。 + +`--remove-role` +: 从用户中移除当前用户组。 + +`--email EMAIL` +: 将用户的邮箱地址更新为 `EMAIL`。 + +`--confirm` +: 与 `--email` 一起使用时，跳过确认邮件。 + +`--disable` +: 锁定 `USERNAME` 使其无法访问其账户。 + +`--enable` +: 如果 `USERNAME` 的账户当前被禁用，则解锁该账户。 + +`--approve` +: 若你的实例处于/曾处于批准模式，则批准 `USERNAME` 的账户。 + +`--disable-2fa` +: 移除其它的身份认证因素并允许使用密码登录。 + +`--reset-password` +: 重置给定账户的密码。 + +`--skip-sign-in-token` +: 强制确保用户永远不会被要求提供发送到邮箱中的安全代码。 + +**版本历史：**\ +2.6.0 - 该命令被添加\ +3.1.2 - 添加 `--reset-password`\ +4.0.0 - `--role` 不再接受硬编码的 `user`、`moderator` 或 `admin` 用户组。请指定自定义用户组的名称（区分大小写）。使用 `--remove-role` 移除当前用户组。 + + +--- -| 选项 | 描述 | -| :--- | :--- | -| `USERNAME` | 本地帐户的用户名。 必须的。 | -| `--role ROLE` | 设定该帐户的身份为 `user`, `moderator` 或 `admin`。 | -| `--email EMAIL` | 将该帐户电子邮箱地址改为 EMAIL。 | -| `--confirm` | 跳过邮件确认步骤，当使用 --email 时可用。 | -| `--disable` | 禁止 USERNAME 帐户登录。 | -| `--enable` | 允许 USERNAME 帐户登录，如果该帐户目前被禁止登录。 | -| `--approve` | 审核通过该帐户，如果你的实例为审核制。 | -| `--disable_2fa` | 移除额外认证因素，允许只用密码登录。 | -| `--reset-password` | 重置此用户的密码，将用一个随机生成的字符串作为临时密码。 | -| `--skip-sign-in-token` | 强制跳过该用户登录时的邮件验证码（目前这是不可逆操作）。 | ### `tootctl accounts delete` {#accounts-delete} -删除给定 USERNAME 的用户帐户。 +删除具有给定 USERNAME 的用户账户。 -**版本历史：** -* 2.6.0 - 被加入 +`USERNAME` +: 要删除的账户的本站用户名。{{}} + +**版本历史：**\ +2.6.0 - 该命令被添加 + + +--- -| 选项 | 描述 | -| :--- | :--- | -| `USERNAME` | 本地帐户的用户名。 必须的。 | ### `tootctl accounts backup` {#accounts-backup} -请求给定 USERNAME 帐户的备份。备份将会被 Sidekiq 异步创建，创建完成后用户将接收到一封带有备份链接的电子邮件。 +为具有给定 USERNAME 的用户账户请求备份。备份将在 Sidekiq 中异步创建，完成后，用户将收到一封包含备份链接的电子邮件。 -**版本历史：** -* 2.6.0 - 被加入 +`USERNAME` +: 要备份的账户的本站用户名。{{}} + +**版本历史：**\ +2.6.0 - 该命令被添加 + + +--- -| 选项 | 描述 | -| :--- | :--- | -| `USERNAME` | 本地帐户的用户名。 必须的。 | ### `tootctl accounts cull` {#accounts-cull} -移除不在存在的远程帐户。查询数据库中的所有远程帐户，以确认其是否仍存在于原有服务器，如果不存在，那么该帐户将从数据库中删除。在远程服务器刚刚下线的情况下，最近一周有活动痕迹的帐户将被排除在检测范围之外。 +移除不再存在的外站账户。查询数据库中的每个外站账户，以确定它在原始服务器上是否仍然存在，如果不存在，则从数据库中移除它。在过去一周内有确认活动的账户不包括在检查中，以防服务器只是暂时下线。 -**版本历史：** -* 2.6.0 - 被加入 -* 2.8.0 - 加入 `--dry_run` +`DOMAIN[...]` +: 可选择传递特定域名进行清理 + +`--concurrency N` +: 用于此任务的作业线程数量。默认为 N=5。 + +`--dry-run` +: 仅打印预期结果，不执行任何操作。 + +**版本历史：**\ +2.6.0 - 该命令被添加\ +2.8.0 - 添加 `--dry-run`\ +3.5.0 - 添加传递特定域名的能力 + + +--- -| 选项 | 描述 | -| :--- | :--- | -| `--concurrency N` | 执行该任务的worker数。默认N=5。 | -| `--dry_run` | 仅打印预期结果，而不执行任何操作。 | ### `tootctl accounts refresh` {#accounts-refresh} -重新拉取一个或多个远程帐户的数据与文件。 +重新获取一个或多个账户的外站用户数据和文件。 -**版本历史：** -* 2.6.0 - 被加入 +`USERNAME` +: 外站账户的 username@domain。 + +`--all` +: 可以代替 `USERNAME`，刷新所有外站账户。 + +`--domain DOMAIN` +: 可以代替 `USERNAME`，仅对来自此 `DOMAIN` 的外站账户进行操作。 + +`--concurrency N` +: 用于此任务的作业线程数量。默认为 N=5。 + +`--verbose` +: 在任务处理过程中输出额外信息。 + +`--dry-run` +: 仅打印预期结果，不执行任何操作。 + +**版本历史：**\ +2.6.0 - 该命令被添加 + + +--- + + +### `tootctl accounts merge` {#accounts-merge} + +将两个外站账户合并为一个。这主要用于修复由其他服务器更改其域名导致的重复。默认情况下，这仅在公钥相同时有效，但可以覆盖此设置。 + +`FROM` +: 要移除的外站账户的 username@domain。{{}} + +`TO` +: 要保留的外站账户的 username@domain。{{}} + +`--force` +: 覆盖公钥检查。 + +**版本历史：**\ +3.3.0 - 该命令被添加 + + +--- -| 选项 | 描述 | -| :--- | :--- | -| `USERNAME` | 远程用户名 | -| `--all` | 刷新所有远程帐户，可取代 USERNAME。 | -| `--domain DOMAIN` | 仅操作此域名 DOMAIN 下的远程帐户。可取代 USERNAME。 | -| `--concurrency N` | 执行该任务的worker数。默认N=5。 | -| `--verbose` | 任务进行时，打印额外信息。 | -| `--dry_run` | 仅打印预期结果，而不执行任何操作。 | ### `tootctl accounts follow` {#accounts-follow} -迫使所有本地帐户关注给定本地帐户。 +强制所有本站账户关注具有给定用户名的本站账户。 -**版本历史：** -* 2.7.0 - 被加入 -* 3.0.0 - 使用 USERNAME 取代 ACCT +`USERNAME` +: 本站用户名。{{}} + +`--concurrency N` +: 用于此任务的作业线程数量。默认为 N=5。 + +`--verbose` +: 在任务处理过程中输出额外信息。 + +**版本历史：**\ +2.7.0 - 该命令被添加\ +3.0.0 - 使用 `USERNAME` 代替 `ACCT` + + +--- -| 选项 | 描述 | -| :--- | :--- | -| `USERNAME` | 本地用户名 | -| `--concurrency N` | 执行该任务的worker数。默认N=5。 | -| `--verbose` | 任务进行时，打印额外信息。 | ### `tootctl accounts unfollow` {#accounts-unfollow} -迫使所有本地帐户取消关注给定帐户。 +强制所有本站账户取消关注指定的账户。 -**版本历史：** -* 2.7.0 - 被加入 +`ACCT` +: `username@domain` 地址。{{}} + +`--concurrency N` +: 用于此任务的作业线程数量。默认为 N=5。 + +`--verbose` +: 在任务处理过程中输出额外信息。 + +**版本历史：**\ +2.7.0 - 该命令被添加 + + +--- -| 选项 | 描述 | -| :--- | :--- | -| `ACCT` | `username@domain` 地址 | -| `--concurrency N` | 执行该任务的worker数。默认N=5。 | -| `--verbose` | 任务进行时，打印额外信息。 | ### `tootctl accounts reset-relationships` {#accounts-reset-relationships} -重置某本地帐户所有正在关注和/或关注者。 +重置本站账户的所有关注和/或关注者关系。 -**版本历史：** -* 2.8.0 - 被加入 +`USERNAME` +: 本站用户名。 + +`--follows` +: 强制 `USERNAME` 取消关注所有人，然后重新关注他们。 + +`--followers` +: 移除 `USERNAME` 的所有关注者。 + +**版本历史：**\ +2.8.0 - 该命令被添加 + + +--- -| 选项 | 描述 | -| :--- | :--- | -| `USERNAME` | 本地用户名 | -| `--follows` | 迫使 USERNAME 取消关注所有人后，再重新关注他们。 | -| `--followers` | 移除 USERNAME 的所有关注者。 | ### `tootctl accounts approve` {#accounts-approve} -当实例为审核制时，审核通过新注册者。 +当实例处于批准模式时，批准新的注册申请。 -**版本历史：** -* 2.8.0 - 被加入 +`USERNAME` +: 本站用户名。 -| 选项 | 描述 | -| :--- | :--- | -| `USERNAME` | 审核通过这个用户名的待审核帐户。 | -| `--number N` | 审核通过最近N个注册者。 | -| `--all` | 审核通过所有待审核帐户。 | +`--number N` +: 批准最早的 N 个待处理注册申请。 -## 缓存相关命令 {#cache} +`--all` +: 批准所有待处理的注册申请。 + +**版本历史：**\ +2.8.0 - 该命令被添加 + + +--- + + +### `tootctl accounts prune` {#accounts-prune} + +清理从未与本站用户互动过的外站账户。 + +`--concurrency N` +: 用于此任务的作业线程数量。默认为 N=5。 + +`--dry-run` +: 仅打印预期结果，不执行任何操作。 + +**版本历史：**\ +2.8.0 - 该命令被添加 + + +--- + + +## 缓存 CLI {#cache} {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/cache.rb" caption="lib/mastodon/cli/cache.rb" >}} + +--- + + ### `tootctl cache clear` {#cache-clear} 清除缓存存储。 -**版本历史：** -* 2.8.1 - 被加入 +**版本历史：**\ +2.8.1 - 该命令被添加 + + +--- + ### `tootctl cache recount` {#cache-recount} -通过从头开始进行引用计数，更新指定类型的硬缓存计数。此操作可能会花费很长时间才能完成，这取决于你的数据库大小。帐户将刷新正在关注数、关注者数、嘟文数。嘟文将刷新回复数、转发数及喜爱数。 +从头开始计算引用记录，更新 TYPE 的硬缓存计数器。这与数据库的大小有关，可能需要很长时间才能完成。将刷新账户的关注者、关注和嘟文计数，以及嘟文的回复、转发和收藏计数。 -**版本历史：** -* 3.0.0 - 被加入 +`TYPE` +: `accounts` 或 `statuses`。{{}} -| 选项 | 描述 | -| :--- | :--- | -| TYPE | `accounts` 或 `statuses` | -| `--concurrency N` | 执行该任务的worker数。默认N=5。 | -| `--verbose` | 任务进行时，打印额外信息。 | +`--concurrency N` +: 用于此任务的作业线程数量。默认为 N=5。 -## 域名相关命令 {#domains} +`--verbose` +: 在任务处理过程中输出额外信息。 + +**版本历史：**\ +3.0.0 - 该命令被添加 + + +--- + + +## 实例 CLI {#domains} {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/domains.rb" caption="lib/mastodon/cli/domains.rb" >}} + +--- + + ### `tootctl domains purge` {#domains-purge} -移除给定域名的所有帐号，不留下任何纪录。与封禁（suspension）不同，如果该域名（DOMAIN）仍存在，这意味着如果该域名上的帐户被再次解析，帐户将重新回来。 +从给定 DOMAIN 中移除所有账户，且不留下任何记录。与封禁不同，如果 DOMAIN 在互联网中仍然在线，则意味着如果再次解析，账户可能仍会返回。 -**版本历史：** -* 2.6.0 - 被加入 -* 2.8.0 - 加入 `--whitelist_mode` -* 2.9.0 - 同时移除自定义emoji -* 3.0.0 - 可同时接受多个域名 +`DOMAIN[...]` +: 要清除的域名，以空格分隔。 + +`--by-uri` +: 在 actor URI 中匹配域名，而不是在 Webfinger 地址中匹配。 + +`--limited-federation-mode` +: 可以代替 DOMAIN 提供。不是从单个域名清除，而是从数据库中移除所有不在许可列表中的域名的账户。在启用有限联合模式并定义许可列表后使用此选项。 + +`--concurrency N` +: 用于此任务的作业线程数量。默认为 5。 + +`--verbose` +: 在任务处理过程中输出额外信息。 + +`--dry-run` +: 仅打印预期结果，不执行任何操作。 + +**版本历史：**\ +2.6.0 - 该命令被添加\ +2.8.0 - 添加 `--whitelist-mode`\ +2.9.0 - 同时移除自定义表情\ +3.0.0 - 可以接受多个域名\ +3.2.0 - 将 `--whitelist-mode` 重命名为 `--limited-federation-mode`\ +3.5.0 - 添加 `--by-uri` + + +--- -| 选项 | 描述 | -| :--- | :--- | -| `DOMAIN[...]` | 要移除的域名（Domains），使用空格进行分隔。 | -| `--whitelist_mode` | 可取代 DOMAIN。不是移除单一域名，而是从数据库移除所有来自非白名单站点的帐户。启用白名单模式并完成白名单设定后运行此命令。 | -| `--concurrency N` | 执行该任务的worker数。默认为5。 | -| `--verbose` | 任务进行时，打印额外信息。 | -| `--dry_run` | 仅打印预期结果，而不执行任何操作。 | ### `tootctl domains crawl` {#domains-crawl} -通过使用Mastodon REST API，爬取API暴露的所有节点，收集这些节点的统计数字（只要这些节点支持相关API），来爬取已知联邦宇宙。当没有给定 START 时，此命令将使用服务器数据库中的已知节点作为爬取的种子。返回总实例数、总注册帐户数、最近一周内的总活跃帐户数、最近一周内新加入的总帐户数。 +使用 Mastodon REST API 端点来爬取已知的联邦宇宙，访问该端点获取所有已知的实例，并进一步从这些实例收集统计数据（如果对应实例支持该 API 端点）。当没有给出 START 时，该命令使用服务器自己的已知实例数据库作为初始列表进行爬取。返回总实例数、总注册用户数、过去一周的总活跃用户数以及过去一周加入的总用户数。 -**版本历史：** -* 2.7.0 - 被加入 -* 3.0.0 - 加入 `--exclude_suspended` +`START` +: 可选择从不同的域名开始。 -| 选项 | 描述 | -| :--- | :--- | -| START | 可选的，从一个不同域名开始。 | -| `--concurrency N` | 执行该任务的worker数。默认为50。 | -| `--format FORMAT` | 控制数据的返回方式。`summary`将打印一个总结。`domains`将返回以换行符分隔的所有已发现节点列表。`json`将输出原始数据汇总。默认为`summary`。 | -| `--exclude_suspended` | 输出中不包括已被你封禁的域名，子域名也将包括内。 | +`--exclude-suspended` +: 不要在输出中包含你已屏蔽的实例。这还包括被封禁实例域名的任何子域名。 -## Emoji相关命令 {#emoji} +`--concurrency N` +: 用于此任务的作业线程数量。默认为 N=50。 + +`--format FORMAT` +: 控制结果的返回方式。`summary` 将打印摘要。`domains` 将返回所有发现的对等节点的换行符分隔列表。`json` 将转储聚合的原始数据。默认为 `summary`。 + +**版本历史：**\ +2.7.0 - 该命令被添加\ +3.0.0 - 添加 `--exclude-suspended` + + +--- + + +## 邮件域名屏蔽 CLI {#email-domain-blocks} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/email_domain_blocks.rb" caption="lib/mastodon/cli/email_domain_blocks.rb" >}} + + +--- + + +### `tootctl email-domain-blocks list` {#email-domain-blocks-list} + +列出所有当前被屏蔽的邮件域名。 + +**版本历史：**\ +3.2.0 - 该命令被添加 + + +--- + + +### `tootctl email-domain-blocks add` {#email-domain-blocks-add} + +向邮件域名屏蔽列表添加条目。 + +`DOMAIN[...]` +: 要屏蔽的邮件域名，以空格分隔。{{}} + +`--with-dns-records` +: 如果提供，还将查找 A、AAAA 和 MX 记录并阻止它们。 + +**版本历史：**\ +3.2.0 - 该命令被添加 + + +--- + + +### `tootctl email-domain-blocks remove` {#email-domain-blocks-remove} + +从邮件域名屏蔽列表中移除条目。 + +`DOMAIN[...]` +: 要取消屏蔽的邮件域名，以空格分隔。{{}} + +**版本历史：**\ +3.2.0 - 该命令被添加 + + +--- + + +## 表情 CLI {#emoji} {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/emoji.rb" caption="lib/mastodon/cli/emoji.rb" >}} + +--- + + +### `tootctl emoji export` {#emoji-export} + +将自定义表情导出到 PATH 下的 `export.tar.gz`。 + +`PATH` +: 创建包含图片的 .tar.gz 归档文件的路径。{{}} + +`--overwrite` +: 覆盖 `PATH` 处的任何现有归档文件。 + +`--category CATEGORY` +: 仅导出指定的 `CATEGORY`。如果未提供，将导出所有表情。 + +**版本历史：**\ +3.1.4 - 该命令被添加 + + +--- + + ### `tootctl emoji import` {#emoji-import} -从一个给定路径的 .tar.gz 存档中导入自定义emoji。存档中包含的PNG、GIF文件不能大于50KB，emoji短代码（shortcode）将被设为去除扩展名后的文件名，可以使用选项附加前缀与后缀。 +从给定路径的 .tar.gz 归档文件导入自定义表情。归档文件应包含不大于 50KB 的 PNG 或 GIF 文件，短代码将被设置为不包含扩展名的文件名，可以提供前缀和/或后缀。 -**版本历史：** -* 2.5.0 - 被加入 +`PATH` +: 创建包含图片的 .tar.gz 归档文件的路径。{{}} + +`--prefix PREFIX` +: 在生成的短代码的开头添加 PREFIX。 + +`--suffix SUFFIX` +: 在生成的短代码的末尾添加 SUFFIX。 + +`--overwrite` +: 不跳过现有表情，用短代码一致的已发现表情替换原有表情。 + +`--category CATEGORY` +: 在选择器中将本次处理的表情分组在 CATEGORY 下。 + +`--unlisted` +: 处理的表情不会显示在表情选择器中，只能通过直接使用短代码使用。 + +**版本历史：**\ +2.5.0 - 该命令被添加 + + +--- -| 选项 | 描述 | -| :--- | :--- | -| `PATH` | 含图片的 .tar.gz 存档文件的路径。 | -| `--prefix PREFIX` | 在生成的短代码开头附加前缀 PREFIX。 | -| `--suffix SUFFIX` | 在生成的短代码结尾附加后缀 SUFFIX。 | -| `--overwrite` | 不是跳过已存在的emoji，而是覆盖同名短代码的emoji。 | -| `--unlisted` | 导入的emojis将不在emoji选择器中出现，但仍能通过它们的短代码来使用。 | -| `--category CATEGORY` | 导入的emoji在选择器的将会分组至 CATEGORY。 | ### `tootctl emoji purge` {#emoji-purge} -移除所有自定义emoji。 +移除所有自定义表情。 -**版本历史：** -* 2.8.0 - 被加入 -* 3.1.0 - 加入 `--remote_only` +`--remote-only` +: 如果提供，仅移除外站自定义表情。 -| 选项 | 描述 | -| :--- | :--- | -| `--remote_only` | 如果被提供，将仅移除远程实例。 | +**版本历史：**\ +2.8.0 - 该命令被添加\ +3.1.0 - 该命令被添加 `--remote-only` -## 时间流（Feeds）相关命令 {#feeds} + +--- + + +## 信息流 CLI {#feeds} {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/feeds.rb" caption="lib/mastodon/cli/feeds.rb" >}} + +--- + + ### `tootctl feeds build` {#feeds-build} -为某个或所有用户构建主页（home）和列表（list）时间流。时间流将从数所库中构建，并使用Redis缓存于内存中。Mastodon 自动管理激活用户的主页时间流。 +为一个或所有用户构建主页和列表信息流。信息流将从数据库构建并在 Redis 的内存缓存中存储。Mastodon 自动管理活跃用户的主页信息流。 -**版本历史：** -* 2.6.0 - 被加入 +`USERNAME` +: 要重新生成信息流的本站用户名。 + +`--all` +: 可以代替 `USERNAME` 提供，刷新所有外站账户。 + +`--concurrency N` +: 用于此任务的作业线程数量。默认为 N=5。 + +`--verbose` +: 在任务处理过程中输出额外信息。 + +`--dry-run` +: 仅打印预期结果，不执行任何操作。 + +**版本历史：**\ +2.6.0 - 该命令被添加 + + +--- -| 选项 | 描述 | -| :--- | :--- | -| `USERNAME` | 要被生成时间流的本地用户名。 | -| `--all` | 刷新所有本地用户的时间流，可取代 USERNAME。 | -| `--concurrency N` | 执行该任务的worker数。默认N=5。 | -| `--verbose` | 任务进行时，打印额外信息。 | -| `--dry_run` | 仅打印预期结果，而不执行任何操作。 | ### `tootctl feeds clear` {#feeds-clear} -从Redis中移除所有主页和列表时间流。 +从 Redis 中移除所有主页和列表信息流。 -**版本历史：** -* 2.6.0 - 被加入 +**版本历史：**\ +2.6.0 - 该命令被添加 -## 媒体相关命令 {#media} + +--- + + +## 维护 CLI {#maintenance} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/maintenance.rb" caption="lib/mastodon/cli/maintenance.rb" >}} + + +--- + + +### `tootctl maintenance fix-duplicates` {#maintenance-fix-duplicates} + +修复可能由于更改排序规则导致的数据库索引损坏。删除或合并重复的账户、嘟文、表情等。必须停止 Mastodon 才能运行此任务，该任务将花费很长时间并可能具有破坏性。如果你的数据库索引由于诸如 等问题而损坏，这将非常有用。 + +**版本历史：**\ +3.3.0 - 该命令被添加 + + +--- + + +## 媒体 CLI {#media} {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/media.rb" caption="lib/mastodon/cli/media.rb" >}} + +--- + + ### `tootctl media remove` {#media-remove} -移除本地缓存的其它实例媒体附件。 +移除来自其他服务器的媒体附件、头像或账户页横幅背景的本站缓存副本。默认情况下，只移除媒体附件。 -**版本历史：** -* 2.5.0 - 被加入 -* 2.6.2 - 显示被释放的硬盘空间 +`--days N` +: 指定多旧的媒体附件才能被移除。对于头像和横幅背景，时间间隔针对对用户的最后一次 webfinger 请求和更新时间计算，默认为 7。 + +`--concurrency N` +: 用于此任务的作业线程数量。默认为 N=5。 + +`--prune-profiles` +: 不移除媒体附件，而是移除来自其他服务器的头像和横幅背景的本站缓存副本。不能与 `--remove-headers` 结合使用。 + +`--remove-headers` +: 不移除媒体附件，而是移除来自其他服务器的横幅背景的本站缓存副本。不能与 `--prune-profiles` 结合使用。 + +`--include-follows` +: 覆盖 `--prune-profiles` 和 `--remove-headers` 的默认行为，移除所有外站实例的头像（和横幅背景）的本站缓存副本，无论关注状态如何（默认情况下，只有本站没有被关注或没有关注任何人的账户的头像和横幅背景会被移除）。只能与 `--prune-profiles` 或 `--remove-headers` 一起使用。 + +`--verbose` +: 在任务处理过程中输出额外信息。 + +`--dry-run` +: 仅打印预期结果，不执行任何操作。 + +**版本历史：**\ +2.5.0 - 该命令被添加\ +2.6.2 - 显示释放的磁盘空间\ +4.1.0 - 添加 --prune-profiles、--remove-headers 和 --include-follows。 + + +--- -| 选项 | 描述 | -| :--- | :--- | -| `--days` | 多久之前的媒体附件将会被清理。默认为7天。 | -| `--concurrency N` | 执行该任务的worker数。默认为5。 | -| `--verbose` | 任务进行时，打印额外信息。 | -| `--dry_run` | 仅打印预期结果，而不执行任何操作。 | ### `tootctl media remove-orphans` {#media-remove-orphans} -扫描出不属于任何媒体附件的文件并移除他们。请注意，某些存储提供商会对列出对象所必需的API收取费用。另外，此操作需要遍历每个文件，因此速度很慢。 +扫描不属于现有媒体附件的文件，并移除它们。请注意，某些存储提供商对列出对象所需的 API 请求收费。此外，此操作需要遍历每个文件，因此速度会很慢。 -**版本历史：** -* 3.1.0 - 被加入 +`--start-after` +: 循环将开始的 Paperclip 附件键。如果命令在之前被中断，请使用此选项。 + +`--dry-run` +: 仅打印预期结果，不执行任何操作。 + +`--prefix` +: 仅遍历系统中特定前缀的文件。 + +`--fix-permissions` +: 根据环境变量将 S3 ACL 设置为默认值。 + +**版本历史：**\ +3.1.0 - 该命令被添加\ +3.1.3 - 添加 `--prefix`\ +3.3.0 - 添加 `--fix-permissions` + + +--- -| 选项 | 描述 | -| :--- | :--- | -| `--start_after` | 循环开始的附件key值。如果之前中断过此操作，请使用此选项。 | -| `--dry_run` | 仅打印预期结果，而不执行任何操作。 | ### `tootctl media refresh` {#media-refresh} -从其它服务器重拉取远程媒体附件。你必须使用 --status 、 --account 或 --domain 来指定媒体附件来源。如果附件已经存在于数据库，除非你使用 --force，否则将不会被覆写。 +从其他实例重新获取外站媒体附件。你必须使用 `--status`、`--account`、`--domain` 或 `--days` 指定媒体附件的来源。如果附件已存在于数据库中，除非你使用 `--force`，否则不会被覆盖。 -**版本历史：** -* 3.0.0 - 被加入 -* 3.0.1 - 加入 `--force` 选项，并默认跳过已下载的附件 +`--account ACCT` +: `username@domain` 格式的用户名字符串 + +`--domain DOMAIN` +: FQDN 格式的字符串 + +`--status ID` +: 数据库中嘟文的本站数字 ID。 + +`--days N` +: 限制此任务检查的天数范围。 + +`--concurrency N` +: 用于此任务的作业线程数量。默认为 5。 + +`--verbose` +: 在任务处理过程中输出额外信息。 + +`--dry-run` +: 仅打印预期结果，不执行任何操作。 + +`--force` +: 强制重新下载外站资源并覆盖本站附件。 + +**版本历史：**\ +3.0.0 - 该命令被添加\ +3.0.1 - 添加 `--force` 并默认跳过已下载的附件\ +4.0.0 - 添加 `--days` + + +--- -| 选项 | 描述 | -| :--- | :--- | -| `--account ACCT` | 需要被处理的帐号，格式 `username@domain` | -| `--domain DOMAIN` | FQDN string | -| `--status ID` | 数据库中的嘟文本地数字ID。 | -| `--concurrency N` | 执行该任务的worker数。默认为5。 | -| `--verbose` | 任务进行时，打印额外信息。 | -| `--dry_run` | 仅打印预期结果，而不执行任何操作。 | -| `--force` | 强制重下载远程资源并覆写本地附件。 | ### `tootctl media usage` {#media-usage} -计算被Mastodon消耗的硬盘空间。 +计算 Mastodon 消耗的磁盘空间。 **版本历史：** -* 3.0.1 - 被加入 +3.0.1 - 该命令被添加 + + +--- + ### `tootctl media lookup` {#media-lookup} -提示输入媒体URL，然后查询该媒体显示位置。 +提示输入媒体 URL，然后查找显示该媒体的状态。 -**版本历史：** -* 3.1.0 - 被加入 +**版本历史：**\ +3.1.0 - 该命令被添加 -## 预览卡片（Preview Cards）相关命令 {#preview_cards} + +--- + + +## 预览卡片 CLI {#preview_cards} {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/preview_cards.rb" caption="lib/mastodon/cli/preview_cards.rb" >}} + +--- + + ### `tootctl preview_cards remove` {#preview_cards-remove} -移除本地预览卡片缩略图。 +移除预览卡片的本地缩略图。 -**版本历史：** -* 3.0.0 - 被加入 +`--days N` +: 指定多旧的缩略图才会被移除。默认为 180。（注意：不建议删除最近 14 天内的预览卡片，因为除非链接在最后一次之后的 2 周内重新发布，否则不会重新获取预览卡片。） -| 选项 | 描述 | -| :--- | :--- | -| `--days` | 多久之前的媒体附件将会被清理。默认为180天。（注意：不推荐删除14天内的预览卡片，因为同一链接两周之内再次发布将不会重抓取。） | -| `--concurrency N` | 执行该任务的worker数。默认为5。 | -| `--verbose` | 任务进行时，打印额外信息。 | -| `--dry_run` | 仅打印预期结果，而不执行任何操作。 | -| `--link` | 仅删除链接型（link-type）预览卡片。不处理视频与图片卡片。 | +`--concurrency N` +: 用于此任务的作业线程数量。默认为 N=5。 -## 搜索相关命令 {#search} +`--verbose` +: 在任务处理过程中输出额外信息。 + +`--dry-run` +: 仅打印预期结果，不执行任何操作。 + +`--link` +: 只删除链接类型的预览卡片；保留视频和照片卡片不变。 + +**版本历史：**\ +3.0.0 - 该命令被添加 + + +--- + + +## 搜索 CLI {#search} {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/search.rb" caption="lib/mastodon/cli/search.rb" >}} + +--- + + ### `tootctl search deploy` {#search-deploy} -创建或更新Elasticsearch索引并进行填充。 如果Elasticsearch为空，此命令将创建必要的索引，然后将数据从数据库导入到这些索引中。如果自上次运行以来索引结构已更改，此命令还将升级索引。 +创建或更新 Elasticsearch 索引并填充它。如果 Elasticsearch 为空，此命令将创建必要的索引，然后将数据库中的数据导入到这些索引中。如果自上次运行以来底层架构已更改，此命令也会升级索引。 -**版本历史：** -* 2.8.0 - 被加入 -* 3.0.0 - 加入 `--processes` 选项来并行化 +`--batch-size` +: 默认为 100。较高的批处理大小可以使 Elasticsearch 更快地处理记录，减轻 PostgreSQL 数据库的负载，但在索引期间可能会增加 Elasticsearch 节点的内存压力。 -| 选项 | 描述 | -| :--- | :--- | -| `--processes N` | 并行执行命令。默认N=2。可以设为`auto`来基于可用CPU数获取相应数值。 | +`--only INDEX` +: 指定索引名称 [`instances`、`accounts`、`tags`、`statuses`、`public_statuses`] 以仅创建或更新该索引。 -## 站点设定相关命令 {#settings} +`--concurrency N` +: 在多个线程上并行执行命令。默认为 5。 + +`--import` +: 将数据从数据库导入到索引 + +`--clean` +: 从索引中删除过时的文档 + +`--reset-chewy` +: 重置 Chewy 的内部索引 + +**版本历史:** +2.8.0 - 该命令被添加\ +3.0.0 - 添加 `--processes` 用于并行处理\ +3.3.0 - 更改可选参数\ +3.5.0 - 添加 `--batch-size`\ +3.5.3 - 将 `--batch-size` 默认值从 1000 更改为 100，将 `--concurrency` 从 2 更改为 5，添加 `--import` 和 `--clean`\ +4.2.0 - 为 `--only` 添加 `instances` 和 `public_statuses` 选项，添加 `--reset-chewy` + + +--- + + +## 设置 CLI {#settings} {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/settings.rb" caption="lib/mastodon/cli/settings.rb" >}} + +--- + + ### `tootctl settings registrations open` {#settings-registrations-open} 开放注册。 -**版本历史：** -* 2.6.0 - 被加入 +**版本历史：**\ +2.6.0 - 该命令被添加 + + +--- + ### `tootctl settings registrations close` {#settings-registrations-close} 关闭注册。 -**版本历史：** -* 2.6.0 - 被加入 +**版本历史：**\ +2.6.0 - 该命令被添加 -## 嘟文相关命令 {#statuses} + +--- + + +### `tootctl settings registrations approved` {#settings-registrations-approved} + +将注册设为需要批准。 + +**版本历史：**\ +3.5.2 - 该命令被添加 + +`--require_reason` +: 如果为真，用户注册时必须输入原因。 + + +--- + + +## 嘟文 CLI {#statuses} {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/statuses.rb" caption="lib/mastodon/cli/statuses.rb" >}} + +--- + + ### `tootctl statuses remove` {#statuses-remove} -从数据库中删除未被引用的嘟文，例如来自中继的或来自本地用户不再关注的用户的嘟文，同时没有被回复的或以其他方式与之互动的。 +从数据库中删除未引用的嘟文，例如来自中继的、不被任何本站账户关注、且未被回复或以其他方式互动的嘟文。 -这是一个计算量很大的操作，其会开始之前创建额外的数据库索引，并在结束后删除它们。 +这是一个计算密集的过程，它在开始前创建额外的数据库索引，并在之后删除它们。 -**版本历史：** -* 2.8.0 - 被加入 +`--days N` +: 指定多旧的嘟文才会被删除。默认为 90。 -| 选项 | 描述 | -| :--- | :--- | -| `--days` | 多久之前的嘟文将会被清理。默认为90天。 | +`--skip-media-remove` +: 跳过删除媒体，以防 S3 出错。默认为 false。 -{{< translation-status-zh-cn raw_title="Using the admin CLI" raw_link="/admin/tootctl/" last_tranlation_time="2020-05-05" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}} +**版本历史：**\ +2.8.0 - 该命令被添加\ +3.1.3 - 该命令被添加 `--skip-media-remove`\ +3.5.0 - 现在删除孤立记录并执行额外的清理任务 + + +--- + + +## 升级 CLI {#upgrade} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/upgrade.rb" caption="lib/mastodon/cli/upgrade.rb" >}} + + +--- + + +### `tootctl upgrade storage-schema` {#upgrade-storage-schema} + +升级存储架构，将所有非本站媒体资源存储在顶级缓存目录中。警告：这是可选的，仅适用于 v3.1.4 之前的部署。由于可能移动数 TB 的数据，此命令可能会导致巨大的对象存储成本。 + +`--verbose` +: 在任务处理过程中输出额外信息。 + +`--dry-run` +: 仅打印预期结果，不执行任何操作。 + +**版本历史：**\ +3.1.4 - 该命令被添加 + +{{< translation-status-zh-cn raw_title="Using the admin CLI" raw_link="/admin/tootctl/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/troubleshooting.md b/content/zh-cn/admin/troubleshooting.md index 20f1090..2121cc9 100644 --- a/content/zh-cn/admin/troubleshooting.md +++ b/content/zh-cn/admin/troubleshooting.md @@ -1,29 +1,53 @@ --- -title: 故障分析 +title: 故障排除 menu: docs: weight: 120 parent: admin + identifier: admin-troubleshooting --- -## **我看到一个故障页说一些东西出错了。我怎么找出哪里出错了？** +## **我看到一个错误页面，上面说出了问题。我怎样才能找出是什么问题？** -所有带堆栈追踪（stack traces）的错误信息都将会被写入系统日志。当使用systemd时，可使用 `journalctl -u mastodon-web`（替换以相应的服务名） 来浏览每个服务的日志。当使用Docker时，与之类似：`docker logs mastodon_web_1`（替换以相应的容器名）。 +所有带有堆栈跟踪的错误消息都会写入系统日志。当使用 systemd 时，可以通过`journalctl -u mastodon-web`（请将 `mastodon-web` 替换为实际的正确服务名称）浏览每个 systemd 服务的日志。当使用 Docker 时，可以通过类似的命令 `docker logs mastodon_web_1`（请将 `mastodon_web_1` 替换为实际的正确容器名称）查看日志。 -服务端详细错误信息将*永不会*公开显示，因为它们可能会暴露你的内部设置，并为攻击者提供线索，让他们了解如何更好的入侵或如何更高效的滥用。 +服务器端错误的具体详情_永远不会_向公众显示，因为它们可能会揭示你的内部设置情况，并为攻击者提供如何入侵或更有效地滥用系统的线索。 -来自Mastodon web服务器的每一个响应都带有独一无二的请求ID（request ID），该ID也将反映在日志中。通过检查错误页的请求头，你可以在日志中轻松找到与之对应的堆栈追踪（stack traces）。 +来自 Mastodon 网络服务器的每个响应都带有一个包含唯一请求 ID 的标头，这也将反映在日志中。通过检查错误页面的标头信息，你可以轻松在日志中找到相应的堆栈跟踪。 -## **升级新版本后，有些页面看起来很奇怪，就像它们含有未设置样式的元素一样。为什么？** +## **我在日志中看不到太多内容。如何启用额外的日志/调试信息？** -检查升级后，你是否运行 `RAILS_ENV=production bin/rails assets:precompile` 并重启Mastodon web 进程。因为这看起来像提供了过期的样式与脚本。这也有可能由于内存缺乏导致预编译失败，很不幸webpack会占用大量内存。如果是这个原因，请确保你已经分配了swap空间。另外，也可以在另一台机器上预编译静态文件，然后把它们复制至 `public/packs` 目录。 +默认情况下，你的日志将显示 `info` 级别的日志记录。要查看更多调试消息，你可以修改 `.env.production` 文件以提高相关服务的级别： -## **升级新版本后，一些请求失败了，日志中的错误信息是 missing columns or tables。为什么？** +- **Web/Sidekiq：**将 `RAILS_LOG_LEVEL` 的值设为 `debug`，然后重启你正在尝试排除故障的服务。 +- **Streaming：**将 `LOG_LEVEL` 的值设为 `silly`，然后重启你正在尝试排除故障的服务。 -检查升级后，你是否运行 `RAILS_ENV=production bin/rails db:migrate`。因为这看起来Mastodon代码访问了一个更新或更旧的数据库schema。如果你使用PgBouncer，请确保此命令直接连接PostgreSQL，因为PgBouncer不支持迁移过程中的锁表操作。 +有关这些选项的其他日志级别的更多信息，可以在[配置环境](https://docs.joinmastodon.org/admin/config)页面找到。 -## **我试图运行 `tootctl` 或 `rake`/`rails` 命令，但我得到 uninitialized constants 错误信息。哪里出错了？** +`debug` 或 `silly` 级别可能非常详细，因此在完成故障排除后，你应该注意将日志级别改回较低级别。 -检查你是否在命令前使用 `RAILS_ENV=production` 指定正确的环境。默认情况下，假定使用开发环境，因此代码尝试加载开发相关gem。然而，在生产环境中，我们避免安装这些gem。这就是错误的来源。 +## **升级到较新版本后，某些页面看起来很奇怪，例如出现了没有任何样式的元素。为什么？** -{{< translation-status-zh-cn raw_title="Troubleshooting errors" raw_link="/admin/troubleshooting/" last_tranlation_time="2020-05-08" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}} +请检查你是否在升级后运行了 `RAILS_ENV=production bin/rails assets:precompile`，并重启了 Mastodon 的 web 进程，因为它似乎正在提供过时的样式表和脚本。也可能是由于内存不足导致预编译失败，这是因为遗憾的是 webpack 非常消耗内存。如果是这种情况，请确保你分配了一些交换内存。或者，可以在不同的机器上预编译资源，然后复制 `public/packs` 目录。 + +## **升级到较新版本后，一些请求失败，日志显示关于缺少列或表的错误消息。为什么？** + +检查你是否在升级后运行了 `RAILS_ENV=production bin/rails db:migrate`，因为看起来 Mastodon 的代码正在访问较新或较旧的数据库架构。如果你使用 PgBouncer，请确保此命令直接连接到 PostgreSQL，因为 PgBouncer 不支持迁移中使用的表锁定类型。 + +## **我尝试运行 `tootctl` 或 `rake`/`rails` 命令，但出现关于未初始化常量的错误。怎么回事？** + +检查你是否在命令前指定了正确的环境变量 `RAILS_ENV=production`。默认情况下，环境被假定为开发环境，因此代码尝试加载与开发相关的gems。然而，在生产环境中，我们避免安装这些gems，这就是错误的来源。 + +## **在执行 `RAILS_ENV=production bundle exec rails assets:precompile` 时遇到编译错误，但没有提供更多信息。如何修复？** + +这通常是因为你的服务器在编译资源时内存不足。使用交换文件或增加交换空间以增加内存容量。运行 `RAILS_ENV=production bundle exec rake tmp:cache:clear` 清除缓存，然后执行 `RAILS_ENV=production bundle exec rails assets:precompile` 重新编译。确保在编译错误后清除缓存，否则会显示"一切正常"但资源保持不变。 + +## **我收到这个错误：`Read-only file system @ dir_s_mkdir`。为什么？** + +默认情况下，Mastodon使用[ systemd 的沙箱功能](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Sandboxing)，这种方式不允许在 `/home/mastodon` 以外的位置执行写入。如果 Mastodon 安装在其他位置，你可能需要允许 `mastodon-sidekiq` 和 `mastodon-web` 写入自定义目录： +1. 在文件 `/etc/systemd/system/mastodon-sidekiq.service` 和 `/etc/systemd/system/mastodon-web.service` 中添加参数 `ReadWritePaths`。例如 - `ReadWritePaths=/example/mastodon/live`。 +2. 执行 `systemctl stop mastodon-sidekiq mastodon-web` +3. 执行 `systemctl daemon-reload` +4. 执行 `systemctl start mastodon-sidekiq mastodon-web` + +{{< translation-status-zh-cn raw_title="Troubleshooting errors" raw_link="/admin/troubleshooting/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/troubleshooting/index-corruption.md b/content/zh-cn/admin/troubleshooting/index-corruption.md new file mode 100644 index 0000000..3de81e3 --- /dev/null +++ b/content/zh-cn/admin/troubleshooting/index-corruption.md @@ -0,0 +1,111 @@ +--- +title: 数据库索引损坏 +description: 如何从数据库索引损坏中恢复。 +menu: + docs: + weight: 10 + parent: admin-troubleshooting +--- + +一个比较常见的配置问题可能导致整个数据库的索引损坏。本页尝试解释为什么会发生这种情况以及如何修复它。 + +## 语言数据与排序规则 {#explanation} + +数据库中的文本值，如用户名或状态标识符，使用所谓的排序规则进行比较，这些规则定义了字符的排序方式和大小写转换方式。 +在设置数据库时，Mastodon 会使用数据库服务器的默认语言设置，包括默认排序规则，这通常由操作系统的设置决定。 + +不幸的是，在2018年末，一次 `glibc` 更新改变了许多区域设置的排序规则，这意味着使用受影响的语言设置的数据库现在会以不同方式排序文本值。 +由于数据库索引依赖于它们所索引的值的排序的算法结构，一些索引可能会变得不一致。 + +更多信息：https://wiki.postgresql.org/wiki/Locale_data_changes https://postgresql.verite.pro/blog/2018/08/27/glibc-upgrade.html + +## 我是否受到这个问题的影响？ {#am-i-affected} + +如果你的数据库未使用 `C` 或 `POSIX` 作为其排序规则（你可以通过 `SELECT datcollate FROM pg_database WHERE datname = current_database();` 检查）， +并且你曾经使用过 glibc 2.28 之前的版本，并且在更新到 glibc 2.28 或更新版本后没有立即重新索引你的数据库，那么你的索引可能不一致。 + +{{< hint style="info" >}} +你可能是因为 PgHero 警告"重复索引"而找到此页面的。虽然这类警告有时可能表明部署或更新 Mastodon 时出现问题，**但它们与数据库索引损坏无关，也不表明数据库存在任何功能问题**。 +{{< /hint >}} + +你可以使用 [PostgreSQL 的 `amcheck` 模块](https://www.postgresql.org/docs/10/amcheck.html)检查你的索引是否一致：作为数据库服务器的超级用户，连接到你的 Mastodon 数据库并执行以下命令（这可能需要一段时间）： + +```SQL +CREATE EXTENSION IF NOT EXISTS amcheck; +SELECT bt_index_check(c.oid) +FROM pg_index i +JOIN pg_class c ON i.indexrelid = c.oid +WHERE c.relname IN ('index_account_domain_blocks_on_account_id_and_domain', + 'index_account_proofs_on_account_and_provider_and_username', + 'index_accounts_on_username_and_domain_lower', 'index_accounts_on_uri', + 'index_accounts_on_url', 'index_conversations_on_uri', + 'index_custom_emoji_categories_on_name', + 'index_custom_emojis_on_shortcode_and_domain', + 'index_devices_on_access_token_id', 'index_domain_allows_on_domain', + 'index_domain_blocks_on_domain', 'index_email_domain_blocks_on_domain', + 'index_invites_on_code', 'index_markers_on_user_id_and_timeline', + 'index_media_attachments_on_shortcode', 'index_preview_cards_on_url', + 'index_statuses_on_uri', 'index_tags_on_name_lower', + 'index_tombstones_on_uri', 'index_unavailable_domains_on_domain', + 'index_users_on_email', 'index_webauthn_credentials_on_external_id' +); +``` + +如果出现错误，则你的数据库已损坏，需要修复。如果没有错误，你可能需要执行更复杂的检查以确保。 +与之前的检查不同，这些更复杂的检查在运行时会锁表，从而影响实例的可用性。 + +```SQL +CREATE EXTENSION IF NOT EXISTS amcheck; +SELECT bt_index_parent_check(c.oid) +FROM pg_index i +JOIN pg_class c ON i.indexrelid = c.oid +WHERE c.relname IN ('index_account_domain_blocks_on_account_id_and_domain', + 'index_account_proofs_on_account_and_provider_and_username', + 'index_accounts_on_username_and_domain_lower', 'index_accounts_on_uri', + 'index_accounts_on_url', 'index_conversations_on_uri', + 'index_custom_emoji_categories_on_name', + 'index_custom_emojis_on_shortcode_and_domain', + 'index_devices_on_access_token_id', 'index_domain_allows_on_domain', + 'index_domain_blocks_on_domain', 'index_email_domain_blocks_on_domain', + 'index_invites_on_code', 'index_markers_on_user_id_and_timeline', + 'index_media_attachments_on_shortcode', 'index_preview_cards_on_url', + 'index_statuses_on_uri', 'index_tags_on_name_lower', + 'index_tombstones_on_uri', 'index_unavailable_domains_on_domain', + 'index_users_on_email', 'index_webauthn_credentials_on_external_id' +); +``` + +如果执行成功，没有返回错误，你的数据库应该是一致的，你可以安全地忽略 Mastodon 在运行 `db:migrate` 时发出的警告。 + +## 修复问题 {#fixing} + +如果你受到影响但不采取行动，随着时间推移，你的数据库可能会变得越来越不一致。因此，尽快修复这个问题非常重要。 + +Mastodon 3.2.2 及更高版本附带了一个半交互式脚本，以尽可能良好的方式修复这些损坏。如果你使用的是早期版本，请先更新到 3.2.2。由于这些损坏的存在，可能在运行数据库迁移到 3.2.2 时会失败，但数据库应该会变成一个可以被 Mastodon 3.2.2 附带的维护工具恢复的状态。 + +在尝试修复数据库之前，**停止 Mastodon 并备份你的数据库**。然后，在**Mastodon 仍处于停止状态**的情况下，运行维护脚本： + +``` +RAILS_ENV=production bin/tootctl maintenance fix-duplicates +``` + +该脚本将遍历数据库以自动查找重复项并修复它们。在某些情况下，这些操作是破坏性的。在最具破坏性的情况下，你将被要求选择要保留的记录和要丢弃的记录。在所有情况下，搜索整个数据库中的重复项是一项极其耗时的操作。 + +{{< hint style="warning" >}} +在某些情况下，重复记录可能有无法调和的冲突（例如两个不同的本站用户共享相同的用户名）。在这些情况下，去重操作可能是**部分破坏性的**，你将被询问哪些记录保持不变，哪些记录将被更改。 +因此，此脚本是半交互式的。在所有情况下，搜索整个数据库中的重复项是一项极其耗时的操作。 +{{< /hint >}} + +{{< hint style="danger" >}} +**由于维护脚本将暂时移除索引， Mastodon 必须在整个过程中完全停止，以防止出现其他重复项。** +{{< /hint >}} + +## 避免问题 + +要避免这个问题，请在任何 libc 更新后立即重新索引你的数据库。 +[SQL 命令 `REINDEX`](https://www.postgresql.org/docs/current/sql-reindex.html) +或 +[`reindexdb` 命令行工具](https://www.postgresql.org/docs/current/app-reindexdb.html) +可能对此有用。 + +{{< translation-status-zh-cn raw_title="Database index corruption" raw_link="/admin/troubleshooting/index-corruption/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/admin/upgrading.md b/content/zh-cn/admin/upgrading.md index 8c0bd64..220d245 100644 --- a/content/zh-cn/admin/upgrading.md +++ b/content/zh-cn/admin/upgrading.md @@ -7,70 +7,80 @@ menu: --- {{< hint style="info" >}} -当一个新的Mastodon版本释出后，它将出现在[GitHub releases页面](https://github.com/mastodon/mastodon/releases)。请注意：运行来自`main`分支的未释出代码，虽然可以进行，但不推荐这样做。 +当 Mastodon 发布新版本时，它会出现在[ GitHub 发布页面](https://github.com/mastodon/mastodon/releases) 上。请注意，虽然可以运行 `main` 分支中的未发布代码，但不推荐这样做。 {{< /hint >}} -Mastodon版本与git tags一致。在尝试升级之前，请至[GitHub releases页面](https://github.com/mastodon/mastodon/releases)查找所需版本。该页面包含了一个**更新日专**，其中描述你需要了解的所有差异，以及**特定的升级指令**。 +### 自动更新验证 {#automated_checks} -开始之前，切换至`mastodon`用户： +从 v4.2.0 版本开始，Mastodon 将自动检查可用更新并通知服务器上拥有 `DevOps` 权限的用户。 + +这通过每 30 分钟在后台获取 `https://api.joinmastodon.org/update-check?version=` 来实现。 `current_version` 省略了构建元数据（如果版本字符串中含有`+`，则为第一个 `+` 之后的所有内容）。例如，如果你的版本是 `4.3.0-beta2+my-fork`，Mastodon 将查询 `https://api.joinmastodon.org/update-check?version=4.3.0-beta2`。 + +你可以通过设置 `UPDATE_CHECK_URL` 环境变量来更改 Mastodon 查询的 URL。你也可以通过将此环境变量设置为空字符串来完全禁用此行为，但我们强烈建议不要这样做，除非你通过其他方式关注 Mastodon 更新，因为 Mastodon 偶尔会发布必须及时应用的关键安全更新。 + +### 升级步骤 + +Mastodon 的发布版本对应 git 标签。在尝试升级之前，请在[ GitHub 发布页面](https://github.com/mastodon/mastodon/releases) 上查看所需的发布版本。该页面将包含**变更日志**，描述关于新版本不同之处的所有信息，以及**特定的升级说明**。 + +首先，切换到`mastodon`用户： ```bash su - mastodon ``` -并转至Mastodon根目录： +并转到 Mastodon 根目录： ```bash cd /home/mastodon/live ``` -下载相应版本代码，这里假定版本为`v3.1.2`： +下载发布版本的代码，假设版本为`v3.1.2`： ```bash git fetch --tags git checkout v3.1.2 ``` -现在，执行GitHub版本发布说明中的升级指令。因为不同的版本有不同的指令，所以本页面将不包括任何指令。 +现在执行[ GitHub 上该版本的发行说明](https://github.com/mastodon/mastodon/releases) 中包含的升级说明。由于不同的发布版本需要不同的说明，我们不在此页面上包含任何说明。 {{< hint style="info" >}} -从旧版本升级时，你可以安全的跳过中间版本。你无需单独检出他们。然而，你确实需要追踪每一个版本的升级指令。大多数指令都是重叠的，你只需要确保每条至少执行一次即可。 +从旧版本升级时，你可以安全地跳过中间版本。你不需要单独检出它们。但是，你需要跟随每个版本的说明。大多数说明的步骤是重复的，你只需确保至少执行一次所有内容。 {{< /hint >}} -当你执行完版本发布说明中的指令后，切换回root用户： +在执行完发布说明中的指令后，切回 root 用户： ```bash exit ``` -重启**后台worker**： +重启**后台工作进程**： ```bash systemctl restart mastodon-sidekiq ``` -并重载**web进程**： +并重新加载 **Web 进程**： ```bash systemctl reload mastodon-web ``` {{< hint style="info" >}} -`reload`操作是零下线时间的重启（restart），也被称为“分阶段重启（phased restart）”。因此，Mastodon升级通常不需要为计划下线而提前发布公告。罕见情况下，你可以改用`restart`操作，但你的用户将感到（短暂的）服务中断。 +`reload` 操作是一种零停机重启，也称为"分阶段重启"。因此，Mastodon 升级通常不需要提前通知用户计划停机。在极少数情况下，你可以使用 `restart` 操作代替，但用户会感受到（短暂的）服务中断。 {{< /hint >}} -罕见情况下，**streaming API** 服务也会被更新并需要重启： +**流式 API** 服务器也会更新并需要重启，这将导致所有已连接的客户端断开连接，可能增加服务器负载： ```bash systemctl restart mastodon-streaming ``` {{< hint style="danger" >}} -更新streaming API服务非常罕见，在大多数版本中，*不*需要重启它。重启streaming API将导致服务器负载增加，因为断线的用户会尝试重连或改用REST API轮询。因此请尽量避免重启streaming API服务 +重启流式 API 会增加服务器负载，因为断开连接的客户端会尝试重新连接或改为轮询 REST API，所以尽可能避免这样做。 {{< /hint >}} {{< hint style="success" >}} -**就这样！** 您现在正在运行新版本的Mastodon。 +**以上就是所有步骤！**你现在正在运行新版本的 Mastodon。 {{< /hint >}} -{{< translation-status-zh-cn raw_title="Upgrading to a new release" raw_link="/admin/upgrading/" last_tranlation_time="2020-05-04" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}} +{{< translation-status-zh-cn raw_title="Upgrading to a new release" raw_link="/admin/upgrading/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/api/datetime-format.md b/content/zh-cn/api/datetime-format.md new file mode 100644 index 0000000..3021fa8 --- /dev/null +++ b/content/zh-cn/api/datetime-format.md @@ -0,0 +1,64 @@ +--- +title: Datetime 格式 +description: Datetime 格式 +menu: + docs: + weight: 10 + parent: api +--- + +## Datetime {#datetime} + +“Datetime”指定某个时刻。 + +Datetime 的字符串表示形式使用 [RFC3339 第 5.6 节](https://www.rfc-editor.org/rfc/rfc3339#section-5.6) 中定义的“互联网日期/时间格式”。 + +总的来说，它包含以下必须包含的部分： + +``` +[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[s][TZD] +``` + +其中： + +- `[YYYY]` = 四位数的年份 +- `[MM]` = 两位数的月份（01=一月，以此类推） +- `[DD]` = 两位数的月份中的日期（01 到 31） +- `[hh]` = 小时的两位数字（00 到 23）（不允许 24） +- `[mm]` = 分钟的两位数字（00 到 59） +- `[ss]` = 秒的两位数字（00 到 60） +- `[s]` = 一位或多位数字表示秒的小数部分 +- `[TZD]` = 时区指示符（UTC 为 `Z`，或者 `+[hh]:[mm]` 或 `-[hh]:[mm]` 表示与 UTC 的偏移量） + +例如，`1994-11-05T13:15:30.000Z`（等同于 `1994-11-05T08:15:30-05:00`）。 + +有关完整的 [ABNF 语法](https://www.rfc-editor.org/rfc/rfc2234)，请查看 [RFC3339 第 5.6 节](https://www.rfc-editor.org/rfc/rfc3339#section-5.6)。 + +### 互操作性 + +- 日期和时间部分始终用大写 `T` 分隔（不是小写，也不是空格）。 +- 时区指示符 `Z` 始终为大写，而不是小写。 +- 秒的小数部分（`[s]`）至少用一位数字表示，最多三位数字表示。 +- 精确度较低的字段也可以表示为 Datetime。 例如，服务器可能会将某个 Datetime 值截断至当天午夜。 + +## 日期 {#date} + +“日期”指定活动发生的公历日期，以 UTC 为准。 + +日期的字符串表示形式使用 ISO 8601（日期和时间表示的国际标准，第 5.2.1.1 节）中的完整、扩展的日历日期表示形式。 这也是 [W3C 日期与时间格式](https://www.w3.org/TR/NOTE-datetime)中的“完整日期”格式。 + +包含以下必须包含的组成部分： + +``` +[YYYY]-[MM]-[DD] +``` + +- `[YYYY]` = 四位数的年份 +- `[MM]` = 两位数的月份（01=一月，以此类推） +- `[DD]` = 两位数的月份中的日期（01 到 31） + +### 互操作性 + +- 年、月和日期组件始终用 `-` 分隔。 + +{{< translation-status-zh-cn raw_title="Datetime formats" raw_link="/api/datetime-format/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/api/guidelines.md b/content/zh-cn/api/guidelines.md new file mode 100644 index 0000000..aed44ea --- /dev/null +++ b/content/zh-cn/api/guidelines.md @@ -0,0 +1,162 @@ +--- +title: 指南与最佳实践 +description: 实现 Mastodon 应用时需要注意的事项。 +menu: + docs: + weight: 10 + parent: api +--- + +## 登录 {#login} + +**用户必须能够从应用登录到任何 Mastodon 实例**。 这意味着你必须询问服务器的域名，并使用应用注册 API 动态获取 OAuth2 凭据。 + +{{< page-ref page="client/authorized" >}} + +{{< page-relref ref="methods/oauth" caption="OAuth 方法" >}} + +{{< page-relref ref="api/oauth-scopes" caption="OAuth 作用域" >}} + +## 用户名 {#username} + +**去中心化对于用户而言必须是透明的**。 用户应该能够看到给定的用户来自另一个服务器，例如，可以通过在某处显示他们的 `acct` 实现这一点。 请注意，对于本站用户，`acct` 等于 `username`，对于外站用户，`acct` 等于 `username@domain`。 + +## 处理和排序 ID {#id} + +原始的 Mastodon 实体 ID 以整数形式生成并转换为字符串。 但是，这并不意味着 ID *是* 整数，也不应该将其转换为整数！ 这样做可能会因整数溢出而导致客户端应用崩溃，因此请**始终将 ID 视为字符串。** + +话虽如此，由于 ID 是数字的字符串表示形式，因此仍然可以通过以下步骤轻松地按时间顺序对其进行排序： + +1. 按大小排序。 较新的嘟文将具有更长的 ID。 +2. 按字典顺序排序。 较新的嘟文在按位置比较时，至少会有一个数字更高。 + +## 通过 API 响应进行分页 {#pagination} + +许多 API 方法允许你使用 `limit`、`max_id`、`min_id` 和 `since_id` 等参数进行分页以获取更多信息。 + +limit +: 要返回的最大结果数。 通常存在默认限制和最大限制； 这些限制将根据 API 方法而异。 + +max_id +: 字符串。 返回的所有结果都将小于此 ID。 该参数实际上设置了结果的上限。 + +since_id +: 字符串。 返回的所有结果都将大于此 ID。 该参数实际上设置了结果的下限。 + +min_id +: 字符串。 返回紧邻此 ID 之后的新结果。 该参数实际上在此 ID 处设置了游标，并据此游标向前分页。（自 v2.6.0 起可用。） + +例如，我们可能会使用某些参数获取 `https://mastodon.example/api/v1/accounts/1/statuses`，并且在下列情况下，我们将分别获得以下结果： + +- 设置 `?max_id=1` 将不返回任何嘟文，因为没有 ID 早于 `1` 的嘟文。 +- 设置 `?since_id=1` 将返回最新的嘟文，因为自 `1` 以来已经有很多嘟文。 +- 设置 `?min_id=1` 将返回最旧的嘟文，因为 `min_id` 设置了游标。 + +某些 API 方法作用于未在 API 响应中公开公开的实体 ID，并且仅为后端和数据库所知。（与这种情况有关的通常是引用其他实体的实体，例如引用帐户的 Follow 实体，或引用嘟文的 Favourite 实体等。） + +为了解决这个问题，Mastodon 可能会返回指向“prev”和“next”页面的链接。 这些链接通过响应中的 HTTP `Link` 标头提供。 考虑以下虚构的 API 调用： + +```http +GET https://mastodon.example/api/v1/endpoint HTTP/1.1 +Authorization: Bearer + +Link: ; rel="next", ; rel="prev" +[ + { + // some Entity + }, + // more Entities in an Array +] +``` + +在这种情况下，你可以检索 `Link` 标头并解析它以查找指向较旧或较新页面的链接。 请记住以下规则： + +- 这些链接将全部通过一个 `Link` 标头返回，并用逗号和空格 (`, `) 分隔 +- 每个链接都包含一个 URL 和一个链接关系，用分号和空格 (`; `) 分隔 +- URL 将用尖括号 (`<>`) 括起来，链接关系将用双引号 (`""`) 括起来，并以 `rel=` 为前缀。 +- 链接关系的值将为 `prev` 或 `next`。 + +跟随 `next` 链接应显示较旧的结果。 跟随 `prev` 链接应显示较新的结果。 + +## 弃用 {#deprecations} + +Mastodon 很少删除 API，但这种情况仍然会不时发生。 因此，建议及时了解 Mastodon 的发布版本，并留意已弃用的 API。 + +此外，为了帮助实施者发现已弃用的 API 的使用情况，Mastodon 4.4.0 使用了 [RFC9745](https://datatracker.ietf.org/doc/html/rfc9745) 中定义的 `Deprecation` 标头。 建议库和应用程序开发人员查找此标头并在其开发环境中显示警告，以便可以在这些已弃用的 API 被淘汰之前发现它们。 + +## 格式化 {#formatting} + +无法从外站服务器获取纯文本内容，并且纯文本语法规则在 Mastodon 和其他 fediverse 应用程序之间可能差异很大。 对于某些属性，例如嘟文的内容，**Mastodon 提供经过清理的 HTML**。 有关更多详细信息，请查看 [HTML 清理]({{< relref "spec/activitypub#sanitization" >}})。 你可以预期一下标签出现在内容中： + +* `

` +* `
` +* `` +* `` + +{{< page-relref ref="spec/activitypub#sanitization" caption="ActivityPub > HTML 清理" >}} + +### 提及、话题标签和自定义表情 {#tags} + +提及和话题标签是 `` 标签。 自定义表情符号保留其纯文本简码形式。 为了赋予这些实体语义含义并添加特殊处理，例如在应用内打开提及的账户而不是按网页打开， [Status]({{< relref "entities/Status" >}}) 中包含了对应的元数据，可以将其与特定标签匹配。 + +{{< page-relref ref="entities/Status" caption="嘟文实体" >}} + +{{< page-relref ref="entities/Status#mentions" caption="嘟文#mentions" >}} + +{{< page-relref ref="entities/Status#tags" caption="嘟文#tags" >}} + +{{< page-relref ref="entities/Status#emojis" caption="嘟文#emojis" >}} + +### 链接缩短 {#links} + +Mastodon 中的链接不会使用 URL 缩短器缩短，并且强烈建议不要使用 URL 缩短器。 文本中的 URL 始终计为 23 个字符，旨在以可视化方式缩短。 为此，链接的标记如下所示： + +```html + + + example.com/page + + +``` + +带有 `invisible` 类的 span 可以隐藏。 中间的 span 旨在保持可见。 如果 URL 不是非常长，则它可能没有类； 否则，它将具有 `ellipsis` 类。 标记中未插入省略号 (`…`) 字符； 相反，如果你需要在应用中使用它，则应该自己插入它。 + +## 过滤规则 {#filters} + +### 服务端过滤规则（v2，Mastodon 4.0 及更高版本） {#server-filtered} + +如果过滤规则针对嘟文，则相应的 FilterResult 将包含在 `filtered` 属性中。 客户端应检查此属性是否存在任何匹配项，并使用它们来应用预期的过滤规则操作。 + +但是，客户端实现可能仍然希望在客户端执行自己的规则匹配，因为这将允许追溯应用过滤规则更改，而无需从服务器重新获取嘟文。 这样操作时，应用应注意不要忽略具有 `keyword_matches` 以外的其他属性的 `filtered` 条目，以便处理过滤系统的扩展（例如 `status_matches`）。 + +命中的过滤规则需要根据上下文（`home`、`notifications`、`public`、`thread` 或 `profile`）和到期日期进行过滤。 + +当至少一个被命中且正在生效的过滤规则在 `filter_action` 的值为 `hide` 时，则不应显示该嘟文。 否则，如果至少一个被命中且正在生效的过滤规则在 `filter_action` 的值为 `warn`，则应隐藏该嘟文并显示警告，并且应允许用户在被告知命中了哪些过滤规则后显示该嘟文（通过 `title` 而不是通过实际匹配的关键字来标识）。 + +为了进行扩展，`filter_action` 的未知值应被视为 `warn`。 + +### 客户端过滤（v1，Mastodon 4.0 之前） {#client-filtered} + +客户端必须基于从 API 返回的过滤规则执行自己的文本过滤。 服务器将为 `home` 和 `notifications` 上下文应用 `irreversible` 过滤规则，但**其他任何内容仍由客户端过滤**！ 如果以某种方式未通过 `irreversible` 过滤规则删除嘟文，则客户端仍应对其进行过滤。 + +服务器不会删除过期的过滤规则。 它们应该不再生效，但它们仍然由服务器存储，因为用户可能会更新到期时间以重新启用该过滤规则。 用户最终可以删除这些过滤规则（如果他们希望这样做）。 + +如果 `whole_word` 为 true，则客户端应用应执行以下操作： + +* 为你的应用定义“单词组成字符”。 在官方实现中，JavaScript 中为 `[A-Za-z0-9_]`，Ruby 中为 `[[:word:]]`。 Ruby 使用 POSIX 字符类（字母 | 标记 | 十进制数字 | 连接标点符号）。 +* 如果短语以单词字符开头，且匹配范围之前的上一个字符是一个单词字符，则应将它的匹配范围视为未命中。 +* 如果短语以单词字符结尾，且匹配范围之后的下一个字符是一个单词字符，则应将它的匹配范围视为未命中。 + +请查看 Mastodon 源代码中的 `app/javascript/mastodon/selectors/index.js` 和 `app/lib/feed_manager.rb` 以获取更多详细信息。 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/javascript/mastodon/selectors/index.js" caption="app/javascript/mastodon/selectors/index.js" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/feed_manager.rb" caption="app/lib/feed_manager.rb" >}} + +## 用于裁剪媒体缩略图的焦点 {#focal-points} + +服务器端的预览图像永远不会被裁剪，以便支持各种应用和用户界面。 因此，裁剪必须由应用完成。 为了智能地执行裁剪，可以使用焦点来确保图像的特定部分始终在裁剪后的视口内。 请查看[关于如何定义焦点的指南](https://github.com/jonom/jquery-focuspoint#1-calculate-your-images-focus-point)。 总之，浮点范围为 -1.0 到 1.0，从左到右或从下到上。 (0,0) 是图像的中心。 (0.5, 0.5) 将位于右上象限的中心。 (-0.5, -0.5) 将位于左下象限的中心。 作为参考，Mastodon 前端中的缩略图一般为 16:9。 + +{{< figure src="assets/focal-points.jpg" caption="各种焦点及其坐标的演示" >}} + +{{< translation-status-zh-cn raw_title="Guidelines and best practices" raw_link="/api/guidelines/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/api/oauth-scopes.md b/content/zh-cn/api/oauth-scopes.md new file mode 100644 index 0000000..5407083 --- /dev/null +++ b/content/zh-cn/api/oauth-scopes.md @@ -0,0 +1,171 @@ +--- +title: OAuth 作用域 +description: 定义你对 API 拥有哪些权限 +menu: + docs: + weight: 20 + parent: api +--- + +## OAuth 作用域 + +API 访问被划分为若干 OAuth 作用域，这些作用域基于 [访问令牌]({{< relref "api/oauth-tokens" >}}) 注册和请求的作用域，限制 API 客户端可以执行的操作。Mastodon 中的作用域是分层的。例如，如果你请求了 `read` 作用域，你将自动获得 `read:accounts` 的访问权限。然而，**我们建议你的应用程序尽可能请求最有限的作用域**，也就是说，如果你只需要对列表和当前用户账户详情的读取权限，那么你应该使用 `profile read:lists` 作为你的作用域，而不是 `read`。 + +{{< hint style="info" >}} +如果只是想检索当前已验证用户的详细信息，请使用 `profile` 作用域，该作用域只能访问 [`GET /api/v1/accounts/verify_credentials`]({{< relref "methods/accounts#verify_credentials" >}}) 端点。\ +此作用域是在 Mastodon 4.3 中添加的，因此我们建议在使用此作用域时，遵循下面“发现给定 Mastodon 实例支持的 OAuth 作用域”的指引。 +{{}} + +### 发现给定 Mastodon 实例支持的 OAuth 作用域 + +从 Mastodon 4.3.0 开始，增加了对 [RFC 8414](https://tools.ietf.org/html/rfc8414)'s `GET /.well-known/oauth-authorization-server` 终端的支持，允许你发现 Mastodon 实例支持的作用域（以及其他 OAuth 相关信息，例如终端和授权流程）。 + +我们建议使用此终端，以便为你的 OAuth 应用程序支持多个 Mastodon 版本。 + +如果你向 `GET /.well-known/oauth-authorization-server` 终端发出请求，并且返回 404，那么你可以认为该 Mastodon 实例运行的版本低于 4.3。在这种情况下，你需要查看你的应用程序需要的特定作用域，以及你希望支持的 Mastodon 版本范围内最低的通用作用域。 + +{{< hint style="info" >}} +**示例：** 你想使用 `profile` 作用域，但也想支持没有该作用域且需要 `read:accounts` 的旧 Mastodon 实例。你可以通过向此终端发出请求来发现实例是否支持该作用域。 +{{< /hint >}} + +{{< page-relref ref="methods/oauth#authorization-server-metadata" caption="GET /.well-known/oauth-authorization-server" >}} + +### 可以同时请求多个作用域 + +在创建应用程序期间，你可以使用 `scopes` 参数指定多个以空格分隔的作用域。在授权阶段，你可以使用 `scope` 查询参数执行相同的操作。 + +{{< hint style="danger" >}} +在应用程序创建期间保存的作用域集必须包含你将在授权请求中请求的所有作用域，否则，授权将失败。 +{{< /hint >}} + +{{< hint style="info" >}} +请注意 `scope` 和 `scopes` 的区别。这是因为 `scope` 是一个标准的 OAuth 参数名称，因此它在 OAuth 方法中使用。Mastodon 自己的 REST API 使用更合适的 `scopes` 名称。 +{{< /hint >}} + +如果你没有在授权请求中指定 `scope`，或者在应用程序创建请求中指定 `scopes`，则生成的访问令牌/应用程序将被分配默认作用域。截至 Mastodon 4.3，当前为 `read`，但将来可能会更改。 + +{{< page-relref ref="methods/apps#create" caption="POST /api/v1/apps" >}} + +### 版本历史 {#versions} + +- 0.9.0 - 添加了 read、write、follow 作用域 +- 2.4.0 - 添加了用于推送通知的 push 作用域 +- 2.4.3 - 添加了细粒度作用域 [#7929](https://github.com/mastodon/mastodon/pull/7929) +- 2.6.0 - 弃用了 `read:reports`（未使用的存根） [#8736/adcf23f](https://github.com/mastodon/mastodon/pull/8736/commits/adcf23f1d00c8ff6877ca2ee2af258f326ae4e1f) +- 2.6.0 - 添加了 `write:conversations` [#9009](https://github.com/mastodon/mastodon/pull/9009) +- 2.9.1 - 添加了管理和审核作用域 [#9387](https://github.com/mastodon/mastodon/pull/9387) +- 3.1.0 - 添加了书签作用域 [#7107](https://github.com/mastodon/mastodon/pull/7107) +- 3.5.0 - 弃用了 `follow` 作用域，转而支持细粒度作用域 [#17678](https://github.com/mastodon/mastodon/pull/17678) +- 4.1.0 - 添加了用于阻止和允许的管理员作用域 [#20918](https://github.com/mastodon/mastodon/pull/20918) +- 4.3.0 - 添加了 `profile` 作用域，仅用于获取有关当前已验证用户的信息 [#29087](https://github.com/mastodon/mastodon/pull/29087), [#30357](https://github.com/mastodon/mastodon/pull/30357) + +## 高级作用域列表 + +我们建议你使用下表中右栏显示的[细粒度作用域](#granular-scopes)，而不是使用以下作用域： + +- `read` +- `write` +- `follow` {{%deprecated%}} +- `admin:read` +- `admin:write` + +当只需要有关当前已验证用户的信息时，请使用 `profile` 作用域。 + +### `profile` {#profile} + +仅授予对 [`GET /api/v1/accounts/verify_credentials`]({{< relref "methods/accounts#verify_credentials" >}}) 终端的访问权限。允许你仅检索有关当前已验证用户的信息。 + +### `read` {#read} + +授予读取数据的权限，包括其他用户的数据。请求 `read` 也会授予下表中右栏所示的[细粒度作用域](#granular-scopes)。 + +### `write` {#write} + +授予写入数据的权限。请求 `write` 也会授予下表中右栏所示的[细粒度作用域](#granular-scopes)。 + +### `push` {#push} + +授予对 [Web Push API 订阅]({{< relref "methods/push" >}})的访问权限。在 Mastodon 2.4.0 中添加。 + +### `follow` {#follow} + +{{< hint style="danger" >}} +**已弃用**\ +此作用域已在 3.5.0 及更高版本中弃用。你应该单独请求[细粒度作用域](#granular-scopes)，或者根据需要请求 `read`/`write` 作用域。 +{{< /hint >}} + +授予管理关系的权限。请求 `follow` 也会授予下表中右栏所示的[细粒度作用域](#granular-scopes)。 + +### `admin:read` 和 `admin:write` {#admin} + +用于管理和审核 API。在 Mastodon 2.9.1 中添加。 + +请求 `admin:read` 或 `admin:write` 也会授予下表中右栏所示的[细粒度作用域](#granular-scopes)。 + +{{< hint style="info" >}} +请注意，没有可用的单一 `admin` 作用域。 +{{< /hint >}} + +## 细粒度作用域 {#granular} + +建议你使用细粒度作用域，除非你确实需要通过使用 `scope` 的 `read write follow push` 对所有内容进行完全访问。 + +| 作用域 | 细粒度作用域 | +| :------------------------ | :----------------------------------- | +| `profile` | | +| `push` | | +| `read` | | +| | `read:accounts` | +| | `read:blocks` | +| | `read:bookmarks` | +| | `read:favourites` | +| | `read:filters` | +| | `read:follows` | +| | `read:lists` | +| | `read:mutes` | +| | `read:notifications` | +| | `read:search` | +| | `read:statuses` | +| `write` | | +| | `write:accounts` | +| | `write:blocks` | +| | `write:bookmarks` | +| | `write:conversations` | +| | `write:favourites` | +| | `write:filters` | +| | `write:follows` | +| | `write:lists` | +| | `write:media` | +| | `write:mutes` | +| | `write:notifications` | +| | `write:reports` | +| | `write:statuses` | +| `follow` {{%deprecated%}} | | +| | `read:follows` | +| | `write:follows` | +| | `read:blocks` | +| | `write:blocks` | +| | `read:mutes` | +| | `write:mutes` | +| `admin:read` | | +| | `admin:read:accounts` | +| | `admin:read:reports` | +| | `admin:read:domain_allows` | +| | `admin:read:domain_blocks` | +| | `admin:read:ip_blocks` | +| | `admin:read:email_domain_blocks` | +| | `admin:read:canonical_email_blocks` | +| `admin:write` | | +| | `admin:write:accounts` | +| | `admin:write:reports` | +| | `admin:write:domain_allows` | +| | `admin:write:domain_blocks` | +| | `admin:write:ip_blocks` | +| | `admin:write:email_domain_blocks` | +| | `admin:write:canonical_email_blocks` | + +## 已删除的作用域 {#removed} + +* Mastodon 3.2.0 到 4.3.0 版本确实支持用于端到端加密 API 的 `crypto` 作用域，但是，此功能从未被记录或完全实现，并且已从 4.3.0 版本中删除。使用该作用域注册的任何应用程序在服务器升级到 4.3.0 及更高版本时，都将被删除该作用域。 + +{{< translation-status-zh-cn raw_title="OAuth Scopes" raw_link="/api/oauth-scopes/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/api/oauth-tokens.md b/content/zh-cn/api/oauth-tokens.md new file mode 100644 index 0000000..3c0af26 --- /dev/null +++ b/content/zh-cn/api/oauth-tokens.md @@ -0,0 +1,29 @@ +--- +title: OAuth 令牌 +description: 定义本文档中使用的令牌类型 +menu: + docs: + weight: 15 + parent: api +--- + +## OAuth 令牌 + +Mastodon 支持两种不同的 OAuth 令牌类型：应用令牌和用户令牌。在本文档中，你将在 API 端点的 `OAuth` 字段中看到对这些令牌类型的引用。 + +`OAuth` 字段也引用了“Public”，在这种情况下，访问 API 端点无需提供 OAuth 访问令牌。 + +### 应用令牌 + +要接收应用令牌，你必须执行[客户端凭据授权流程]({{}})，这将为你提供一个令牌，该令牌可用于代表 OAuth 应用程序与 API 交互。目前，只有以下 API 端点接受此令牌类型： + +- [`GET /api/v1/apps/verify_credentials`]({{}}) +- [`POST /api/v1/accounts`]({{}}) + +### 用户令牌 + +要创建用户令牌，你必须执行[授权码授权流程]({{}})，这将为你提供一个与批准访问授权请求的用户关联的访问令牌。 + +许多 Mastodon API 需要用户令牌和特定的作用域才能访问。 + +{{< translation-status-zh-cn raw_title="OAuth Tokens" raw_link="/api/oauth-tokens/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/api/rate-limits.md b/content/zh-cn/api/rate-limits.md new file mode 100644 index 0000000..799d1dd --- /dev/null +++ b/content/zh-cn/api/rate-limits.md @@ -0,0 +1,51 @@ +--- +title: 速率限制 +description: 定义调用 REST API 的频率 +menu: + docs: + weight: 30 + parent: api +--- + +## 响应头 + +速率限制信息将在响应头中返回： + +`X-RateLimit-Limit` +: 在一个时间段内允许的请求数量 + +`X-RateLimit-Remaining` +: 你还可以发起的请求数量 + +`X-RateLimit-Reset` +: 你的速率限制何时重置的时间戳 + +{{< hint style="info" >}} +一个 API 方法可能会受到多个重叠的速率限制。 响应头会返回你最接近超过的那个限制的信息。 +{{}} + +## 限制 + +默认情况下，以下限制是硬编码的： + +### 每个帐户 + +所有端点和方法可以在 5 分钟内被调用 300 次。 + +#### 上传媒体 + +`POST /api/v1/media` 可以在 30 分钟内被调用 30 次。 + +#### 删除状态 + +`DELETE /api/v1/statuses/:id` 或 `POST /api/v1/statuses/:id/unreblog` 可以在 30 分钟内被调用 30 次。 + +### 每个 IP + +所有端点和方法可以在 5 分钟内被调用 300 次。 + +#### 创建帐户 + +`POST /api/v1/accounts` 可以在 30 分钟内被调用 5 次。 + +{{< translation-status-zh-cn raw_title="Rate limits" raw_link="/api/rate-limits/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/client/authorized.md b/content/zh-cn/client/authorized.md new file mode 100644 index 0000000..7963acc --- /dev/null +++ b/content/zh-cn/client/authorized.md @@ -0,0 +1,144 @@ +--- +title: 使用帐户登录 +description: 如何从用户处获取授权，并代表用户执行操作。 +menu: + docs: + weight: 40 + parent: client +--- + +## 作用域说明 {#scopes} + +当我们注册应用及授权用户时，我们需要明确定义生成的令牌将具有哪些权限。这通过使用 [OAuth 作用域]({{< relref "api/oauth-scopes" >}}) 来完成。每个 API 方法都有一个关联的作用域，只有当用于授权的令牌是通过对应的作用域生成的，才能调用该方法。 + +当授权用户时，`scope` 查询参数必须是我们创建应用时指定的作用域的子集。在我们的示例中，我们在创建应用时指定了 `read write push` 作为我们的作用域，但更好的做法是仅请求你的应用实际需要的 [细粒度作用域]({{< relref "api/oauth-scopes#granular-scopes" >}})。 + +有关作用域的完整列表，请查看 [OAuth 作用域]({{< relref "api/oauth-scopes" >}})。每个 API 方法的文档也将指定 OAuth [令牌类型]({{< relref "api/oauth-tokens" >}}) 和调用该方法所需的作用域。如果一个端点指定了 `read:statuses` 并且你具有 `read` 权限，那么你将能够调用该端点，因为作用域是分层的。 + +{{< page-relref ref="api/oauth-scopes" caption="OAuth 作用域" >}} + +## **授权码流程示例** {#flow} + +与之前的身份验证流程类似，但这次，我们还需要从用户处获取授权。 + +### 客户端 ID 与密钥 {#client} + +在开始操作之前，如果你尚未注册客户端应用，请查看上一页的 [创建我们的应用]({{< relref "client/token#creating-our-application" >}}) 或直接转到 [POST /api/v1/apps]({{< relref "methods/apps#create" >}}) 以获取该方法的完整文档。我们将需要应用的 `client_id` 和 `client_secret`。 + +### 获得用户授权 {#login} + +要获取用户授权，请在浏览器中请求 [GET /oauth/authorize]({{< relref "methods/oauth#authorize" >}}) 并使用以下查询参数： + +```bash +https://mastodon.example/oauth/authorize +?client_id=CLIENT_ID +&scope=read+write+push +&redirect_uri=urn:ietf:wg:oauth:2.0:oob +&response_type=code +``` + +请注意以下几点： + +* `client_id` 是在注册应用时获得的对应 `client_id`。 +* `scope` 必须为我们的应用已注册的作用域的子集。最好只请求你所需要的作用域。 有关更多信息，请查看 [OAuth 作用域]({{< relref "api/oauth-scopes" >}})。 +* `redirect_uri` 是我们的应用注册的 URI 之一。 + +在本示例中，我们仍然使用“非常规”方式，这意味着我们将不得不手动复制和粘贴结果代码，但如果你使用你控制的 URI 注册了你的应用，那么代码将通过你的重定向 URI 的请求处理程序作为参数 `code` 的值返回。有关这方面的更多信息，请查看 API 方法文档的响应部分。 + +{{< hint style="warning" >}} +你应该将 `code` 查询参数视为密码，确保它不会记录在请求日志中。 +{{< /hint >}} + +### 获取令牌 {#token} + +获取授权 `code` 后，让我们获取一个访问令牌，该令牌将用于对授权用户的请求进行身份验证。为此，像以前一样使用 [POST /oauth/token]({{< relref "methods/oauth#token" >}})，但传递我们刚刚获得的授权码： + +```bash +curl -X POST \ + -F 'grant_type=authorization_code' \ + -F 'client_id=your_client_id_here' \ + -F 'client_secret=your_client_secret_here' \ + -F 'redirect_uri=urn:ietf:wg:oauth:2.0:oob' \ + -F 'code=user_authzcode_here' \ + https://mastodon.example/oauth/token +``` + +请注意以下几点： + +- 我们正在请求一个 `grant_type` 为 `authorization_code` 的令牌。 +- `client_id` 和 `client_secret` 在你注册应用时已在响应体中提供。 +- `redirect_uri` 必须是在注册应用时定义的 URI 之一。 +- `code` 只能使用一次。如果你需要获取新令牌，你将需要用户通过重复上述 [授权用户]({{< relref "client/authorized#authorize-the-user" >}}) 步骤再次授权。 + +此方法的响应是一个 [令牌]({{< relref "entities/token" >}}) 实体。我们将需要 `access_token` 值。获得访问令牌后，将其保存在本地缓存中。 + +生成的访问令牌的 `scope` 将为在 [授权请求]({{< relref "client/authorized#login" >}}) 期间批准的作用域。 + +{{< hint style="warning" >}} +你应该将 `access_token` 视为密码。我们建议你在存储在缓存中时加密此值，以防止意外的凭据泄露。 +{{< /hint >}} + +要在请求中使用它，请将 HTTP 标头 `Authorization: Bearer ` 添加到任何需要 OAuth 的 API 调用（即，不是公开可访问的）。 + +让我们通过调用 [GET /api/v1/accounts/verify_credentials]({{< relref "methods/accounts#verify_credentials" >}}) 来验证我们获得的凭据是否有效： + +```bash +curl \ + -H 'Authorization: Bearer ' \ + https://mastodon.example/api/v1/accounts/verify_credentials +``` + +如果我们正确地获得了令牌并设置了请求格式，我们应该看到我们的详细信息按 [帐户]({{< relref "entities/account" >}}) 实体的格式返回给我们，其中包含 `source` 参数。 + +## 以授权用户身份执行操作 {#actions} + +有了授权用户的 OAuth 令牌后，我们现在可以以该用户的身份执行令牌作用域内的任何操作。 + +### 发布和删除嘟文 {#statuses} + +- 有关如何创建嘟文的信息，请查看 [POST /api/v1/statuses]({{< relref "methods/statuses#create" >}})。 + - 有关创建媒体附件的信息，请查看 [/api/v1/media]({{< relref "methods/media" >}})。 + - 有关管理计划嘟文的信息，请查看 [/api/v1/scheduled_statuses]({{< relref "methods/scheduled_statuses" >}})。 + +### 与时间线交互 {#timelines} + +- 有关访问时间线的信息，请查看 [/api/v1/timelines]({{< relref "methods/timelines" >}})。 +- 有关保存和加载时间线中的位置的信息，请查看 [/api/v1/markers]({{< relref "methods/markers" >}})。 +- 有关对嘟文执行操作的信息，请查看 [/api/v1/statuses]({{< relref "methods/statuses" >}})。 + - 有关查看和参与投票的信息，请查看 [/api/v1/polls]({{< relref "methods/polls" >}})。 +- 有关获取列表 ID 以与 [GET /api/v1/timelines/list/:list_id]({{< relref "methods/timelines#list" >}}) 一起使用的信息，请查看 [/api/v1/lists]({{< relref "methods/lists" >}})。 +- 有关获取私下提及的信息，请查看 [/api/v1/conversations]({{< relref "methods/conversations" >}})。 +- 有关喜欢列表的信息，请查看 [/api/v1/favourites]({{< relref "methods/favourites" >}})。 +- 有关列出书签的信息，请查看 [/api/v1/bookmarks]({{< relref "methods/bookmarks" >}})。 + +### 与其他用户交互 {#accounts} + +- 有关对其他用户执行操作的信息，请查看 [/api/v1/accounts]({{< relref "methods/accounts" >}})。 +- 有关处理关注请求的信息，请查看 [/api/v1/follow_requests]({{< relref "methods/follow_requests" >}})。 +- 有关隐藏列表的信息，请查看 [/api/v1/mutes]({{< relref "methods/mutes" >}})。 +- 有关屏蔽列表的信息，请查看 [/api/v1/blocks]({{< relref "methods/blocks" >}})。 + +### 接收通知 {#notifications} + +- 有关管理用户通知的信息，请查看 [/api/v1/notifications]({{< relref "methods/notifications" >}})。 +- 有关订阅推送通知的信息，请查看 [/api/v1/push]({{< relref "methods/push" >}})。 + +### 发现功能 {#discovery} + +- 有关查询资源的信息，请查看 [/api/v2/search]({{< relref "methods/search#v2" >}})。 +- 有关推荐关注的账户的信息，请查看 [/api/v1/suggestions]({{< relref "methods/suggestions" >}})。 + +### 用户安全功能 {#safety} + +- 有关管理过滤关键词的信息，请查看 [/api/v1/filters]({{< relref "methods/filters" >}})。 +- 有关管理被屏蔽的实例的信息，请查看 [/api/v1/domain_blocks]({{< relref "methods/domain_blocks" >}})。 +- 有关创建举报的信息，请查看 [/api/v1/reports]({{< relref "methods/reports" >}})。 +- 有关审核操作的信息，请查看 [/api/v1/admin]({{< relref "methods/admin" >}})。 + +### 管理帐户信息 {#manage} + +- 有关管理用户账户页中的特色帐户的信息，请查看 [/api/v1/endorsements]({{< relref "methods/endorsements" >}})。 +- 有关管理用户账户页中的特色话题标签的信息，请查看 [/api/v1/featured_tags]({{< relref "methods/featured_tags" >}})。 +- 有关读取用户设置的信息，请查看 [/api/v1/preferences]({{< relref "methods/preferences" >}})。 + +{{< translation-status-zh-cn raw_title="Logging in with an account" raw_link="/client/authorized/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/client/intro.md b/content/zh-cn/client/intro.md new file mode 100644 index 0000000..f0a7489 --- /dev/null +++ b/content/zh-cn/client/intro.md @@ -0,0 +1,139 @@ +--- +title: API 入门指南 +description: '有关 REST API、HTTP 请求与响应，以及请求参数的入门知识。' +menu: + docs: + weight: 10 + parent: client +--- + +## REST 简介 {#rest} + +Mastodon 通过 REST API 提供对其数据的访问通道。REST 代表具象状态传输规范（REpresentational State Transfer），但就我们的目的而言，只需将其视为根据请求发送和接收有关各种资源的信息即可。Mastodon REST API 使用 HTTP 进行请求，使用 JSON 作为其有效载荷。 + +## 了解 HTTP 请求和响应 {#http} + +REST API 端点可以用某些 HTTP 方法调用，并且可以对同一端点使用多种方法。Mastodon API 通常会使用以下 HTTP 方法： + +* **GET**：读取或查看资源。 +* **POST**：向服务器发送信息。 +* **PUT** \| **PATCH**：更新资源。 +* **DELETE**：删除资源。 + +你喜欢的编程语言可能具有用来发出 HTTP 请求的实用程序或库。在本节中，示例将使用 cURL 实用程序，它是一个命令行实用程序，默认包含在许多操作系统中（命令名称 `curl`）。 + +使用 cURL 时，默认的 HTTP 方法是 GET，但你可以使用 `--request` 或 `-X` 标志指定要发出的请求类型；例如，`curl -X POST` 将发送 POST 请求而不是 GET 请求。你可能还想使用 `-i` 标志来包含可能作为响应的一部分返回的其他 HTTP 标头（如果这与用例相关）。 + +## 提供参数 {#parameters} + +HTTP 请求可以包含各种不同的参数，但最值得注意的是，Mastodon API 可以接收查询字符串、表单数据和 JSON。 + +{{< hint style="info" >}} +API 同等程度地理解通过 POST 请求体提交的查询字符串、表单数据和 JSON。期望将查询字符串用于 GET 请求，将表单数据或 JSON 用于所有其他请求。 +{{< /hint >}} + +### 查询字符串 {#query-strings} + +可以在请求 URL 的末尾附加查询字符串。可以通过先键入 ?，然后以 parameter=value 的格式附加它们。可以通过用 & 分隔来附加多个查询字符串。例如： + +```bash +curl https://mastodon.example/endpoint?q=test&n=0 +``` + +### 表单数据 {#form-data} + +你可以单独发送数据，而不是使用查询字符串（使用查询字符串会更改 URL）。使用 cURL 时，可以通过使用 `--data` 或 `-d` 标志传递数据来完成这一点。可以像查询字符串一样一并发送数据，也可以使用多个数据标志作为键值对单独发送数据。你也可以使用 `--form` 或 `-F` 标志作为键值对，这也允许发送多部分数据，例如文件。请求示例： + +```bash +# 将原始数据作为查询字符串发送 +curl -X POST \ + -d 'q=test&n=0' \ + https://mastodon.example/endpoint +# 单独发送原始数据 +curl -X POST \ + -d 'q=test' \ + -d 'n=0' \ + https://mastodon.example/endpoint +# 显式表单编码；允许使用多部分数据 +curl -X POST \ + -F 'q=test' \ + -F 'n=0' \ + -F 'file=@filename.jpg' \ + https://mastodon.example/endpoint +``` + +### JSON {#json} + +ECMA-404 中定义的 *JavaScript 对象表示法*。你可以查看 [JSON](https://www.json.org/) 的快速单页概述。 + +发送 JSON 与发送表单数据类似，但需要添加一个额外的标头来指定数据采用 JSON 格式。要使用 cURL 发送 JSON 请求，请使用标头将内容类型指定为 JSON，然后将 JSON 数据作为表单数据发送： + +```bash +curl -X POST \ + -H 'Content-Type: application/json' \ + -d '{"parameter": "value"}' \ + https://mastodon.example/endpoint +``` + +## 数据类型 {#types} + +### 多个值（数组） {#array} + +必须使用括号符号对数组参数进行编码。例如，`array[]=foo&array[]=bar` 将转换为以下内容： + +```ruby +array = [ + 'foo', + 'bar', +] +``` + +使用 JSON 时，数组的格式如下： + +```json +{ + "array": ["foo", "bar"] +} +``` + +### 嵌套参数（哈希） {#hash} + +有些参数需要嵌套。为此，还必须使用括号表示法。例如，`source[privacy]=public&source[language]=en` 将转换为： + +```ruby +source = { + privacy: 'public', + language: 'en', +} +``` + +使用 JSON 时，哈希的格式如下： + +```json +{ + "source": { + "privacy": "public", + "language": "en" + } +} +``` + +### 真与假（布尔值） {#boolean} + +对于值 `0`、`f`、`F`、`false`、`FALSE`、`off`、`OFF`，布尔值将被认为是 false；对于空字符串，则认为未提供；对于所有其他值，则认为是 true。使用 JSON 数据时，请改用字面量 `true`、`false` 和 `null`。 + +### 文件 {#file} + +文件上传必须使用 `multipart/form-data` 进行编码。 + +这也可能与数组结合使用。 + +## 如何使用 API 响应数据 {#responses} + +Mastodon REST API 将返回 JSON 作为响应文本。它还会返回 HTTP 标头，这些标头可能有助于处理响应，以及 HTTP 状态代码，该代码应让你知道服务器如何处理请求。可能会出现以下 HTTP 状态代码： + +- 200 = OK。请求已成功处理。 +- 4xx = 客户端错误。你的请求不正确。最常见的是，你可能会看到 401 Unauthorized（未授权）、404 Not Found（未找到）、410 Gone（已删除）或 422 Unprocessed（无法处理）。 +- 5xx = 服务器错误。处理请求时出现问题。最常见的是，你可能会看到 503 Unavailable（服务不可用）。 + +{{< translation-status-zh-cn raw_title="Getting started with the API" raw_link="/client/intro/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/client/libraries.md b/content/zh-cn/client/libraries.md new file mode 100644 index 0000000..00b76de --- /dev/null +++ b/content/zh-cn/client/libraries.md @@ -0,0 +1,160 @@ +--- +title: 库与实现 +description: 用于各种编程语言的 Mastodon API 的代码、库和 SDK。 +menu: + docs: + weight: 60 + parent: client +--- + +感谢我们出色的开发者社区，他们通过各种 API 实现为项目提供了支持。如果你为 Mastodon API 构建了库或 SDK，请[告诉我们](https://github.com/mastodon/mastodon/discussions)，它可能会在未来更新文档时被包含在下面。 + +请注意检查库的最后更新时间，以及它是否包含你可能想要使用的 API 功能。 + +## Arduino / ESP32 / IoT {#arduino-iot} + +* [lyuba](https://github.com/ringtailsoftware/lyuba) +## C# (.NET Standard) {#c-net-standard} + +* [MastodonAPI](https://github.com/golf1052/MastodonAPI) +* [Mastodot](https://github.com/yamachu/Mastodot) +* [Mastonet](https://github.com/glacasa/Mastonet) +* [TootNet](https://github.com/cucmberium/TootNet) +* [mastodon-api-cs](https://github.com/pawotter/mastodon-api-cs) +* [Mastodon.Net](https://github.com/Tlaster/Mastodon.Net) + +## C++ {#c} + +* [mastodonpp](https://schlomp.space/tastytea/mastodonpp) + +## Common Lisp {#common-lisp} + +* [mastodon-cl](https://github.com/compufox/mastodon-cl) +* [tooter](https://github.com/Shinmera/tooter) + +## Crystal {#crystal} + +* [mastodon-api-crystal](https://github.com/renatolond/mastodon-api-crystal) + +## Dart {#dart} + +* [mastodon_dart](https://pub.dev/packages/mastodon_dart) +* [mastodon-api](https://github.com/mastodon-dart/mastodon-api) +* [mastodon-oauth](https://github.com/mastodon-dart/mastodon-oauth2) +* [mastodon](https://github.com/mykdavies/Mastodon) +* [dartodon](https://github.com/darkcl/dartodon) +* [mastodon_entities](https://github.com/MahanRahmati/mastodon-entities) + +## Elixir {#elixir} + +* [hunter](https://github.com/milmazz/hunter) + +## Erlang {#erlang} + +* [masterldon](https://github.com/igb/masterldon) + +## Go {#go} + +* [go-mastodon](https://github.com/mattn/go-mastodon) +* [madon](https://github.com/McKael/madon) +* [go-mastodon-api](https://github.com/aaronland/go-mastodon-api) + +## Haskell {#haskell} + +* [hastodon](https://github.com/syucream/hastodon) + +## Java {#java} + +* [BigBone](https://github.com/andregasser/bigbone) +* [Mastodon4J](https://github.com/Mastodon4J/Mastodon4J) +* [mastodon-jfx](https://github.com/wakingrufus/mastodon-jfx) + +## JavaScript {#javascript} + +* [megalodon](https://github.com/h3poteto/megalodon) +* [masto.js](https://github.com/neet/masto.js) +* [libodonjs](https://github.com/Zatnosk/libodonjs) + +## JavaScript (Browser) {#javascript-browser} + +* [mastodon.js](https://github.com/Kirschn/mastodon.js) + +## JavaScript (Node.js) {#javascript-node-js} + +* [mastodon-api](https://github.com/vanita5/mastodon-api) + +## Kotlin {#kotlin} + +* [BigBone](https://github.com/andregasser/bigbone) +* [mastodonk](https://github.com/outadoc/mastodonk) + +## Nim {#nim} + +* [Mastonim](https://github.com/matrix07012/Mastonim) + +## Objective-C {#objective-c} + +* [Cocotodon](https://github.com/shibafu528/Cocotodon) + +## Perl {#perl} + +* [Mastodon::Client](https://metacpan.org/pod/Mastodon::Client) + +## PHP {#php} + +* [mastodon-api-client](https://github.com/vazaha-nl/mastodon-api-client) +* [Phediverse Mastodon REST Client](https://github.com/phediverse/mastodon-rest) +* [TootoPHP](https://framagit.org/MaxKoder/TootoPHP) +* [oauth2-mastodon](https://github.com/lrf141/oauth2-mastodon) +* [MastodonBotPHP](https://github.com/Eleirbag89/MastodonBotPHP) +* [mastodon-api-php-oauth](https://github.com/yks118/Mastodon-api-php-oauth) +* [mastodon-api-php](https://github.com/colorfield/mastodon-api-php) +* [Mastodon API for Laravel](https://github.com/kawax/laravel-mastodon-api) +* [Mastodon for Drupal](https://www.drupal.org/project/mastodon) +* [Mastodon for Socialite](https://github.com/kawax/socialite-mastodon) + +## PowerShell {#powershell} + +* [Mastodon](https://github.com/JB405/Mastodon) + +## Python {#python} + +* [Mastodon.py](https://github.com/halcy/Mastodon.py) +* [mastopy](https://gitlab.com/spla/mastopy) + +## R {#r} + +* [mastodon](https://github.com/ThomasChln/mastodon) +* [rtoot](https://github.com/schochastics/rtoot) + +## Ruby {#ruby} + +* [mastodon-api](https://github.com/mastodon/mastodon-api) + +## Rust {#rust} + +* [megalodon-rs](https://github.com/h3poteto/megalodon-rs) +* [mastodon-async](https://github.com/dscottboggs/mastodon-async) + +## Scala {#scala} + +* [scaladon](https://github.com/schwitzerm/scaladon) + +## Scheme {#scheme} + +### Guile {#guile} + +* [Guile-Mastodon](https://codeberg.org/WammKD/Guile-Mastodon) + +## Swift {#swift} + +* [Mastodon.swift](https://github.com/Swiftodon/Mastodon.swift) +* [MastodonKit](https://github.com/MastodonKit/MastodonKit) +* [tootsdk](https://github.com/tootsdk/tootsdk) +* [MastodonAPI](https://github.com/li-bei/MastodonAPI) + +## TypeScript {#typescript} + +* [tsl-mastodon](https://github.com/typescriptlibs/tsl-mastodon-api) + +{{< translation-status-zh-cn raw_title="Libraries and implementations" raw_link="/client/libraries/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/client/public.md b/content/zh-cn/client/public.md new file mode 100644 index 0000000..84f8b9f --- /dev/null +++ b/content/zh-cn/client/public.md @@ -0,0 +1,116 @@ +--- +title: 使用公开数据 +description: 熟悉端点与实体。 +menu: + docs: + weight: 20 + parent: client +--- + +现在，你已经知道如何使用 cURL 或你喜欢的编程语言的 HTTP 实用程序或库来构造 HTTP 请求，那么现在是时候了解端点和响应了。 + +## 关于端点 {#endpoints} + +所有 HTTP 请求都是针对目标 URL 发出的。当你请求网站的数据时，你需要使用特定的 URL。根据 URL 的不同，你的请求将被 HTTP 服务器解释，并向你返回适当的响应。 + +本文的示例将使用虚构的 Mastodon 网站 mastodon.example，该网站托管在 `https://mastodon.example`。此网站的根目录为 `/`，特定的子目录和路径被称为端点。Mastodon 的 API 端点位于 `/api` 命名空间下，目前大多数方法都将其端点放置于 `/api/v1` 下。请求将按其 HTTP 方法和端点列出；例如，GET /api/v1/endpoint 应解释为对你域名上的该端点发出的 GET 请求，或者换句话说，`https://mastodon.example/api/v1/endpoint`。 + +## 获取公开时间线 {#timelines} + +让我们来了解 Mastodon 公开数据最基础的用例之一——公共时间线。 + +我们可以尝试请求 [GET /api/v1/timelines/public]({{< relref "methods/timelines" >}})，如下所示： + +```bash +curl https://mastodon.example/api/v1/timelines/public +``` + +哇，响应中有很多文本！公共时间线默认返回 20 条嘟文。 + +{{< hint style="danger" >}} +一些 Mastodon 实例可能会通过管理设置禁用对其时间线的公开访问。如果你的实例进行了这样的配置，那么你将收到错误响应。 +{{}} + +我们可以使用 `limit` 参数来请求更少的内容。让我们尝试请求相同的端点，但这次限制为 2： + +```bash +curl https://mastodon.example/api/v1/timelines/public?limit=2 +``` + +这次我们的响应应该更容易管理。我们可以使用我们选择的实用程序解析或美化这个 JSON，我们应该看到响应类似这样： + +```json +[ + { + "id": "103206804533200177", + "created_at": "2019-11-26T23:27:31.000Z", + // ... + "visibility": "public", + // ... + }, + { + "id": "103206804086086361", + "created_at": "2019-11-26T23:27:32.000Z", + // ... + "visibility": "public", + // ... + } +] +``` + +对于话题标签，我们可以通过调用 [GET /api/v1/timelines/tag/:hashtag]({{< relref "methods/timelines#tag" >}}) 来执行类似的操作——这里，冒号表示端点的这一部分是路径参数。对于 :hashtag，这意味着我们使用标签的名称（我们再次将返回的结果数限制为 2）： + +```bash +curl https://mastodon.example/api/v1/timelines/tag/cats?limit=2 +``` + +我们应该再次看到，在 [Status]({{< relref "entities/status" >}}) 实体的 JSON 数组中返回了 2 条嘟文。我们可以按数组，然后按对象解析 JSON。如果我们使用的是 Python，我们的代码可能如下所示： + +```python +import requests +import json + +response = requests.get("https://mastodon.example/api/v1/timelines/tag/cats?limit=2") +statuses = json.loads(response.text) # this converts the json to a python list of dictionary +assert statuses[0]["visibility"] == "public" # we are reading a public timeline +print(statuses[0]["content"]) # this prints the status text +``` + +{{< hint style="info" >}} +解析 JSON 并在你的程序中使用它超出了本教程的范围，因为它会因你选择的编程语言和你的程序设计方案而异。你可以查找有关如何在你选择的编程语言中与 JSON 一起使用的其他教程。 +{{}} + +{{< hint style="info" >}} +[MastoVue](https://mastovue.glitch.me) 是一个应用示例，可让你浏览公开时间线。 +{{}} + +## 获取公开帐户和嘟文 {#posts} + +现在，我们熟悉了如何发出请求以及如何处理响应，你可以尝试更多公开数据。以下方法可能会引起你的兴趣： + +* 一旦获取了帐户的 id，你就可以使用 [GET /api/v1/accounts/:id]({{< relref "methods/accounts" >}}) 来查看 [Account]({{< relref "entities/account" >}}) 实体。 + * 要查看该帐户发布的公开嘟文，你可以使用 [GET /api/v1/accounts/:id/statuses]({{< relref "methods/statuses" >}}) 并解析生成的 [Status]({{< relref "entities/status" >}}) 实体数组。 +* 一旦获取了嘟文的 id，你就可以使用 [GET /api/v1/statuses/:id]({{< relref "methods/statuses#get-one" >}}) 来查看 Status 实体。 + * 你还可以使用 [GET /api/v1/statuses/:id/reblogged_by]({{< relref "methods/statuses#boosted_by" >}}) 查看谁转发了该嘟文， + * 或 [GET /api/v1/statuses/:id/favourited_by]({{< relref "methods/statuses#favourited_by" >}}) 查看谁喜欢了该嘟文。 + * 请求 [GET /api/v1/statuses/:id/context]({{< relref "methods/statuses#context" >}}) 将向你显示该嘟文在对话串中的上级嘟文和下级嘟文。 + * 如果该嘟文附加了一个投票，你可以使用 [GET /api/v1/polls/:id]({{< relref "methods/polls" >}}) 单独查看该投票。 + +帐户和嘟文的 ID 是 Mastodon 网站数据库本地的，并且每个 Mastodon 网站都会有所不同。 + +## 获取公开实例数据 {#instance} + +你可以使用匿名请求做的最后一件事是查看有关 Mastodon 实例的信息。 + +* 使用 [GET /api/v1/instance]({{< relref "methods/instance#fetch-instance" >}}) 查看常规信息， + * 使用 [GET /api/v1/instance/peers]({{< relref "methods/instance#peers" >}}) 查看其联合列表，或 + * 使用 [GET /api/v1/instance/activity]({{< relref "methods/instance#activity" >}}) 查看其每周活动，或 + * 使用 [GET /api/v1/custom_emojis]({{< relref "methods/custom_emojis" >}}) 列出所有可用的自定义表情。 +* 有关所有可用配置文件的目录，参见 [GET /api/v1/directory]({{< relref "methods/directory" >}})。 +* 有关当前热门话题，参见 [GET /api/v1/trends]({{< relref "methods/trends" >}})。 + +{{< hint style="info" >}} +有关仅使用实例数据可以做什么的实际示例，请查看 [emojos.in](https://emojos.in/)，它允许你预览给定实例中的所有自定义表情符号。 +{{}} + +{{< translation-status-zh-cn raw_title="Playing with public data" raw_link="/client/public/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/client/token.md b/content/zh-cn/client/token.md new file mode 100644 index 0000000..7d53234 --- /dev/null +++ b/content/zh-cn/client/token.md @@ -0,0 +1,89 @@ +--- +title: 获取客户端应用访问权限 +description: 熟悉身份验证和授权的基础知识。 +menu: + docs: + weight: 30 + parent: client +--- + +## 身份验证和授权 {#auth} + +到目前为止，我们一直在处理公开可用的信息，但并非所有信息都是公开的。某些信息在查看之前需要获得许可，以便审计谁在请求该信息（并可能撤销或拒绝访问）。 + +这就是 [OAuth]({{< relref "spec/oauth" >}}) 发挥作用的地方。OAuth 是一种生成访问令牌的机制，该令牌可用于 _验证_ 请求来自特定客户端，并确保请求的操作已获得服务器访问控制策略的 _授权_。 + +## 创建应用 {#app} + +我们需要做的第一件事是注册一个应用，以便稍后能够生成访问令牌。可以像这样创建应用： + +```bash +curl -X POST \ + -F 'client_name=Test Application' \ + -F 'redirect_uris=urn:ietf:wg:oauth:2.0:oob' \ + -F 'scopes=read write push' \ + -F 'website=https://myapp.example' \ + https://mastodon.example/api/v1/apps +``` + +在上面的示例中，我们指定了客户端名称和网站，如果适用，它们将显示在状态中。但更重要的是，请注意以下两个参数： + +- `redirect_uris` 被设置为“非常规”令牌生成，这意味着任何生成的令牌都必须手动复制和粘贴。该参数之所以称为 `redirect_uris`，是因为可以定义多个重定向 URI，但是在生成令牌时，我们需要提供一个包含在此列表中的 URI。 +- `scopes` 允许我们定义稍后可以请求的权限。但是，稍后请求的范围需要是这些已注册范围的子集。有关更多信息，请查看 [OAuth 范围]({{< relref "api/oauth-scopes" >}})。 + +你还可以将 JSON 请求体 POST 到同一端点来创建应用，如[POST /api/v1/apps]({{< relref "methods/apps#create-request-example" >}}) 中所述。 + +{{< hint style="info" >}} +从 Mastodon 4.3.0 开始，你可以通过向 [`/.well-known/oauth-authorization-server`]({{< relref "methods/oauth#authorization-server-metadata" >}}) 端点发出请求来发现服务器支持哪些 `scopes` 以及其他信息。 +{{< /hint >}} + +我们应该看到返回了一个 [CredentialApplication]({{< relref "entities/application#CredentialApplication" >}}) 实体，但目前，我们只关心 `client_id` 和 `client_secret`。 + +`client_id` 和 `client_secret` 值将用于生成访问令牌，因此应将其缓存以供以后使用。有关注册应用程序的更多详细信息，请查看 [POST /api/v1/apps]({{< relref "methods/apps#create" >}})。 + +{{< hint style="warning" >}} +将 `client_id` 和 `client_secret` 属性视为密码。我们建议你在存储在缓存中时对其进行加密，以防止意外的凭据泄露。 +{{< /hint >}} + +## 身份验证代码示例 {#flow} + +现在我们有了一个应用，让我们获取一个访问令牌，该令牌将以刚创建好的应用的身份令服务端验证我们的请求。为此，请使用 [POST /oauth/token]({{< relref "methods/oauth#token" >}}) 如下所示： + +```bash +curl -X POST \ + -F 'client_id=your_client_id_here' \ + -F 'client_secret=your_client_secret_here' \ + -F 'redirect_uri=urn:ietf:wg:oauth:2.0:oob' \ + -F 'grant_type=client_credentials' \ + https://mastodon.example/oauth/token +``` + +请注意以下事项： + +- 注册应用时，`client_id` 和 `client_secret` 已在响应体中提供。 +- `redirect_uri` 必须是在注册应用时定义的 URI 之一。 +- 我们正在请求 `client_credentials` 的 `grant_type`，默认情况下会为我们提供 `read` 范围。 + +此方法的响应是一个 [Token]({{< relref "entities/token" >}}) 实体。我们将需要 `access_token` 值。获得访问令牌后，将其保存在你的本地缓存中。 + +{{< hint style="warning" >}} +将 `access_token` 视为密码。我们建议你在存储在缓存中时加密此值，以防止意外的凭据泄露。 +{{< /hint >}} + +要在请求中使用它，请将 HTTP 标头 `Authorization: Bearer ` 添加到任何需要 OAuth 的 API 调用（即，不可公开访问的 API 调用）。 + +让我们通过调用 [GET /api/v1/apps/verify_credentials]({{< relref "methods/apps#verify_credentials" >}}) 来验证我们获得的凭据是否有效： + +```bash +curl \ + -H 'Authorization: Bearer ' \ + https://mastodon.example/api/v1/apps/verify_credentials +``` + +如果我们已经获得了我们的令牌并正确格式化了我们的请求，我们应该看到我们的详细信息通过 [Application]({{< relref "entities/application" >}}) 实体返回给我们（不包括 `client_secret` 属性）。 + +## 我们可以用身份验证做什么 {#methods} + +通过经过身份验证的客户端应用程序，我们可以查看帐户之间的关系，例如 [GET /api/v1/accounts/:id/following]({{< relref "methods/accounts#following" >}}) 和 [GET /api/v1/accounts/:id/followers]({{< relref "methods/accounts#followers" >}})。此外，某些实例可能要求对本来可以公开访问的方法进行身份验证，因此如果你之前在尝试使用公共方法时遇到任何身份验证错误，这些方法现在应该可以工作了。 + +{{< translation-status-zh-cn raw_title="Obtaining client app access" raw_link="/client/token/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/dev/code.md b/content/zh-cn/dev/code.md new file mode 100644 index 0000000..eb3fee7 --- /dev/null +++ b/content/zh-cn/dev/code.md @@ -0,0 +1,75 @@ +--- +title: 代码结构 +description: 在哪里可以找到代码库的特定部分。 +menu: + docs: + weight: 30 + parent: dev +--- + +### 代码结构 {#structure} + +下面的概述不应被视为完整或权威的，而只是一个粗略的指引，以帮助你在应用程序中确定查找方向。 + +#### Ruby {#ruby} + +`app/controllers` +: 将业务逻辑绑定到模板的代码。 + +`app/helpers` +: 可以从视图中使用的代码，即常见操作。 + +`app/lib` +: 不适合其他类别的代码。 + +`app/models` +: 数据实体及其关联方法的表示。 + +`app/policies` +: 在调用相关方法之前进行的权限检查和其他验证。 + +`app/serializers` +: 从模型生成 JSON 的代码。 + +`app/services` +: 涉及多个模型的复杂逻辑操作。 + +`app/views` +: 用于生成 HTML 或其他输出的模板。 + +`app/workers` +: 在请求-响应周期之外执行的代码。 + +`spec` +: 自动化测试套件。 + +#### JavaScript {#javascript} + +`app/javascript/mastodon` +: 前端 React.js 应用程序的代码。 + +`app/javascript/packs` +: 非 React.js 页面的代码。 + +#### CSS 和其他资源 {#assets} + +`app/javascript/images` +: 图像。 + +`app/javascript/styles` +: 通过 Sass 转换为 CSS 的代码。 + +#### 本地化 {#localizations} + +`config/locales` +: 服务器端 YML 格式的本地化。 + +`app/javascript/mastodon/locales` +: 客户端 JSON 格式的本地化。 + +所有语言设置文件都经过标准化，以确保一致的格式和键顺序，从而最大限度地减少版本控制中的变更范围。 + +- 运行 `bundle exec i18n-tasks normalize` 来规范化服务器端翻译。 +- 运行 `yarn run i18n:extract` 将客户端翻译提取并将其规范化到 `en.json` 中。 + +{{< translation-status-zh-cn raw_title="Code structure" raw_link="/dev/code/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/dev/disclosure.md b/content/zh-cn/dev/disclosure.md new file mode 100644 index 0000000..4119e89 --- /dev/null +++ b/content/zh-cn/dev/disclosure.md @@ -0,0 +1,18 @@ +--- +title: 漏洞赏金与责任披露 +description: 如果你发现了一个严重的漏洞，该怎么办 +menu: + docs: + weight: 9999 + parent: dev +--- + +如果你认为你在 Mastodon 中发现了一个安全漏洞（一个令本不应该发生的事情发生的漏洞），你应该将举报发送至 **security@joinmastodon.org**。我们将很乐意通过我们的 OpenCollective 基金，根据问题的严重程度给予此类举报相应的奖励。 + +请*勿*在 GitHub 或其他公共空间举报此类问题，以便我们有时间发布修复程序，避免 Mastodon 用户面临更高的风险。 + +{{< hint style="info" >}} +“Mastodon 中的漏洞”是指在我们 GitHub 主要源代码存储库中分发的代码中存在的漏洞。特定于某个实例的漏洞（例如，配置错误）应举报给该实例的所有者，而不是我们。 +{{< /hint >}} + +{{< translation-status-zh-cn raw_title="Bug bounties and responsible disclosure" raw_link="/dev/disclosure/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/dev/overview.md b/content/zh-cn/dev/overview.md new file mode 100644 index 0000000..37e3774 --- /dev/null +++ b/content/zh-cn/dev/overview.md @@ -0,0 +1,34 @@ +--- +title: 技术概览 +description: 关于 Mastodon 架构的描述。 +menu: + docs: + weight: 10 + parent: dev +--- + + + +Mastodon 是一个使用 React.js 前端的 Ruby on Rails 应用程序。 它遵循这些框架的标准实践，因此如果你已经熟悉 Rails 或 React.js，在这里你不会发现任何意外。 + +在开发环境中，使用 Mastodon 的最佳方式是在你的系统上安装所有依赖项，而不是使用 Docker 或 Vagrant。 你需要 Ruby、Node.js、PostgreSQL 和 Redis，这是 Rails 应用程序的一组相当标准的依赖项。 + +有关安装这些依赖项的教程可以在文档的“运行 Mastodon”部分中的“从源代码安装”页面上找到。 按照“运行 Mastodon”部分中的安装指南操作后，请查看“设置开发环境”页面，以获取有关如何配置开发环境的更多说明。 + +### 环境 {#environments} + +“环境”是一组用于特定用例的配置值。 环境可能是：开发(development)，你通常打算在其中更改代码；测试(test)，你通常打算在其中运行自动化测试套件；暂存(staging)，旨在向最终用户预览代码；以及生产，旨在面向最终用户。 Mastodon 带有开发、测试和生产的配置。 + +`RAILS_ENV` 的默认值为 `development`，因此你无需设置任何额外的东西即可在开发模式下运行 Mastodon。 事实上，Mastodon 的所有配置都具有适用于开发环境的正确默认值，因此除非你需要自定义某些内容，否则你不需要 `.env` 文件。 以下是开发环境和生产环境之间的一些不同行为： + +- 当你更改 Ruby 代码时，代码会自动重载，这意味着你无需重新启动 Rails 服务端进程即可查看更改 +- 你遇到的所有错误的堆栈跟踪都会在浏览器中显示，而不是隐藏在通用错误页面之后 +- Webpack 会持续运行，并在你更改任何前端文件时重新编译 JS 和 CSS 资源，并且页面会自动重新加载 +- 默认禁用缓存 +- 在 `db:seed` 期间会自动创建一个电子邮件为 `admin@localhost:3000` 且密码为 `mastodonadmin` 的管理员帐户 + +应该注意的是，与 Mastodon 一起分发的 Docker 配置针对生产环境进行了优化，因此极其不适合开发。 另一方面，Vagrant 配置专门用于开发环境，而不是生产用途。 + +{{< translation-status-zh-cn raw_title="Technical overview" raw_link="/dev/overview/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/dev/routes.md b/content/zh-cn/dev/routes.md new file mode 100644 index 0000000..b65eb61 --- /dev/null +++ b/content/zh-cn/dev/routes.md @@ -0,0 +1,208 @@ +--- +title: 路由 +description: HTTP 方法如何映射到控制器与操作。 +menu: + docs: + weight: 40 + parent: dev +--- + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/config/routes.rb" caption="config/routes.rb" >}} + +## 路由说明 {#routes} + +Mastodon 使用 Ruby on Rails，它在 config/routes.rb 中定义其路由配置。本页只解释 Mastodon 如何处理路由的基础知识，你可以查看 [Ruby on Rails 路由指南](https://guides.rubyonrails.org/routing.html) 以获取更详细的信息。 + +### 路由的构建方式 {#router} + +`namespace` 是映射到特定控制器目录的路由的前缀。`resources` 映射到该命名空间目录中的控制器。`scope` 传递到 `module` 的控制器。例如，考虑以下缩写代码： + +{{< code title="config/routes.rb 摘录" >}} +```ruby +namespace :api do + namespace :v1 do + resources :statuses, only [:create, :show, :destroy] do + scope module: :statuses do + resource :favourite, only: :create + resource :unfavourite, to: 'favourites#destroy' + member do + get :context + end + end + end + end +end +``` +{{< /code >}} + +第一个可用的资源是 :statuses，它嵌套在 :api 和 :v1 命名空间下。因此，生成的 HTTP 路由将是 /api/v1/statuses。`only` 定义某些允许的方法，这些方法将在 `app/controllers/api/v1/statuses_controller.rb` 的控制器中定义。 + +在 /api/v1/statuses 中，有一个模块 :statuses 的作用域，其中定义了其他资源。这些资源的控制器位于 `app/controllers/api/v1/statuses/` 中。例如，:favourite 将由 `app/controllers/api/v1/statuses/favourites_controller.rb` 中的 #create 操作处理，而 :unfavourite 将由同一控制器中的 #destroy 操作处理。 + +还为该作用域内的任何 `member` 定义了一个自定义方法，或者换句话说，对于任何要由 `app/controllers/api/v1/statuses_controller.rb` 控制的状态，该方法都映射到 GET /api/v1/statuses/:id/context 并且由该控制器中定义的 :context 操作处理。 + +### 可用方法 {#methods} + +#### :index + +映射到 HTTP GET，用于列出。由控制器中的 #index 操作处理。 + +#### :show + +映射到 HTTP GET，用于显示单个视图。由控制器中的 #show 操作处理。 + +#### :create + +映射到 HTTP POST。由控制器中的 #create 操作处理。 + +#### :update + +映射到 HTTP PUT。由控制器中的 #update 操作处理。 + +#### :destroy + +映射到 HTTP DELETE。由控制器中的 #destroy 操作处理。 + +## .well-known {#well-known} + +### /.well-known/host-meta {#host-meta} + +可扩展资源描述符 (XRD)。 声明 Webfinger 的存在。 + +### /.well-known/nodeinfo {#nodeinfo} + +映射到 `/nodeinfo/2.0` 的 NodeInfo 2.0 端点，用于声明软件名称和版本、协议、使用统计信息以及是否开放注册。 + +### /.well-known/webfinger {#webfinger} + +用于发现 ActivityPub 行为体 ID。有关更多信息，请查看 [对 > WebFinger 的合规性说明]({{< relref "spec/webfinger" >}})。 + +### /.well-known/change-password {#change-password} + +映射到帐户设置页面。 + +### /.well-known/keybase-proof-config {#keybase} + +用于与 Keybase 集成，定义哪些用户名可接受以及可以在哪里检查证明。 + +{{< hint style="warning" >}} +以下部分正在建设中。 +{{< /hint >}} + +## 公开 URI {#public} + +* `/users/username` = 用户 URI +* `/users/username/remote_follow` = 外站关注对话框 +* `/users/username/statuses/id` = 嘟文 URI +* `/@username` = “嘟文”选项卡 +* `/@username/with_replies` = “嘟文与回复”选项卡 +* `/@username/media` = “媒体”选项卡 +* `/@username/tagged/:hashtag` = 用户标记的嘟文 +* `/@username/:status_id` = 嘟文永久链接 +* `/@username/:status_id/embed` = 可嵌入版本 +* `/interact/:status_id` = 外站交互对话框 +* `/explore` = 用户目录 +* `/explore/:hashtag` = 简介中包含此标签的用户 +* `/public` = 公共时间线预览 +* `/about` = 落地页 +* `/about/more` = 详细描述 +* `/terms` = 服务条款 + +## API {#api} + +* /api/oembed +* /api/proofs +* /api/v1 + * [statuses]({{< relref "methods/statuses" >}}) [create, show, destroy] + * reblogged_by [index] + * favourited_by [index] + * reblog [create] + * unreblog [POST reblog#destroy] + * favourite [create] + * unfavourite [POST favourites#destroy] + * bookmark [create] + * unbookmark [POST bookmarks#destroy] + * mute [create] + * unmute [POST mutes#destroy] + * pin [create] + * unpin [POST pins#destroy] + * context [GET] + * [timelines]({{< relref "methods/timelines" >}}) + * home [show] + * public [show] + * tag [show] + * list [show] + * [streaming]({{< relref "methods/streaming" >}}) [index] + * [custom_emojis]({{< relref "methods/custom_emojis" >}}) [index] + * [suggestions]({{< relref "methods/suggestions" >}}) [index, destroy] + * [scheduled_statuses]({{< relref "methods/scheduled_statuses" >}}) [index, show, update, destroy] + * [preferences]({{< relref "methods/preferences" >}}) [index] + * [conversations]({{< relref "methods/conversations" >}}) [index, destroy] + * read [POST] + * [media]({{< relref "methods/media" >}}) [create, update] + * [blocks]({{< relref "methods/blocks" >}}) [index] + * [mutes]({{< relref "methods/mutes" >}}) [index] + * [favourites]({{< relref "methods/favourites" >}}) [index] + * [bookmarks]({{< relref "methods/bookmarks" >}}) [index] + * [reports]({{< relref "methods/reports" >}}) [create] + * [trends]({{< relref "methods/trends" >}}) [index] + * [filters]({{< relref "methods/filters" >}}) [index, create, show, update, destroy] + * [endorsements]({{< relref "methods/endorsements" >}}) [index] + * [markers]({{< relref "methods/markers" >}}) [index, create] + * [apps]({{< relref "methods/apps" >}}) [create] + * verify_credentials [credentials#show] + * [instance]({{< relref "methods/instance" >}}) [show] + * peers [index] + * activity [show] + * [domain_blocks]({{< relref "methods/domain_blocks" >}}) [show, create, destroy] + * [directory]({{< relref "methods/directory" >}}) [show] + * [follow_requests]({{< relref "methods/follow_requests" >}}) [index] + * authorize [POST] + * reject [POST] + * [notifications]({{< relref "methods/notifications" >}}) [index, show] + * clear [POST] + * dismiss [POST] + * [accounts]({{< relref "methods/accounts" >}}) + * verify_credentials [GET credentials#show] + * update_credentials [PATCH credentials#update] + * search [show (search#index)] + * relationships [index] + * [accounts]({{< relref "methods/accounts" >}}) [create, show] + * statuses [index accounts/statuses] + * followers [index accounts/follower_accounts] + * following [index accounts/following_accounts] + * lists [index accounts/lists] + * identity_proofs [index accounts/identity_proofs] + * follow [POST] + * unfollow [POST] + * block [POST] + * unblock [POST] + * mute [POST] + * unmute [POST] + * pin [POST] + * unpin [POST] + * [lists]({{< relref "methods/lists" >}}) [index, create, show, update, destroy] + * accounts [POST accounts/pins#destroy] + * [featured_tags]({{< relref "methods/featured_tags" >}}) [index, create, destroy] + * suggestions [GET suggestions#index] + * [polls]({{< relref "methods/polls" >}}) [create, show] + * votes [create polls/votes] + * [push]({{< relref "methods/push" >}}) + * subscription [create, show, update, destroy] + * [admin]({{< relref "methods/admin" >}}) + * accounts [index, show] + * enable [POST] + * unsilence [POST] + * unsuspend [POST] + * approve [POST] + * reject [POST] + * action [create account_actions] + * reports [index, show] + * assign_to_self [POST] + * unassign [POST] + * reopen [POST] + * resolve [POST] +* /api/v2 + * [search]({{< relref "methods/search" >}}) [GET search#index] + +{{< translation-status-zh-cn raw_title="Routes" raw_link="/dev/routes/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/dev/setup.md b/content/zh-cn/dev/setup.md new file mode 100644 index 0000000..44a5422 --- /dev/null +++ b/content/zh-cn/dev/setup.md @@ -0,0 +1,115 @@ +--- +title: 设置开发环境 +description: 关于如何开始为 Mastodon 进行开发的说明。 +menu: + docs: + weight: 20 + parent: dev +--- + +## Vagrant 使用快速入门 {#vagrant} + +为了方便起见，Mastodon 仓库包含一个 Vagrantfile，用于快速设置开发环境，无需手动配置。要使用此开发环境，请使用二进制可执行文件或通过包管理器安装 [Vagrant](https://vagrantup.com)。 + +安装 Vagrant 后，为方便起见，建议安装一个插件来自动更新你机器的 hosts 文件。这将允许你通过 `http://mastodon.local` 访问开发环境，而无需手动编辑 hosts 文件。为此，请执行以下操作： + +```sh +vagrant plugin install vagrant-hostsupdater +``` + +然后可以启动虚拟机： + +```sh +vagrant up +``` + +启动虚拟机后，你可以启动 Foreman 任务执行器来启动各种 Mastodon 进程： + +```sh +vagrant ssh -c "cd /vagrant && foreman start" +``` + +Mastodon 进程完全启动后，你可以在浏览器中加载 `http://mastodon.local` 以访问 VM 中的 Mastodon 实例。你可以使用用户名 `admin@mastodon.local` 和密码 `mastodonadmin` 以默认管理员用户身份登录。 + +对源代码的任何更改将在保存文件后立即生效。 + +要将 VM 重置为全新状态，你可以销毁它并重新启动它： + +```sh +vagrant destroy +vagrant up +``` + +## 从源代码手动安装 {#manual} + +你可以按照[生产指南中的前提条件说明]({{}})进行配置，但不要创建 `mastodon` 用户。你也不必安装 `nginx`、`certbot` 和 `python-certbot-nginx`，因为开发环境自带 Web 服务器。 如果你使用的是 Windows，在 WSL2 上设置和运行开发环境也已证明是可行的。 + +### 设置 {#setup} + +在项目目录中运行以下命令： + +```sh +bundle install +yarn install +``` + +在开发环境中，Mastodon 将使用 PostgreSQL 作为当前已登录的 Linux 用户，并使用 `ident` 方法。确保你已为当前已登录的用户创建了 PostgreSQL 用户和数据库： + +```sh +sudo -u postgres createuser $YOUR_USERNAME_HERE --createdb +``` + +现在，你可以创建数据库 `mastodon_development` 和 `mastodon_test`，将 schema 加载到其中，并将 `db/seeds/` 中定义的种子数据加载到 `mastodon_development` 中。 + +```sh +rails db:setup +``` + +现在，你可以在浏览器中启动 `http://localhost:3000` 并使用默认管理员用户 (`admin@localhost` / `mastodonadmin`) 登录。 + +{{}} +默认情况下，Mastodon 将在端口 3000 上运行。如果你为其配置了其他端口，则生成的管理员帐户也将使用该端口号。 +{{}} + +### 运行 {#running} + +需要运行多个进程才能实现 Mastodon 的全部功能，尽管可以选择性地省略它们。要仅使用一个命令运行所有进程，你可以安装并使用 Foreman： + +```sh +gem install foreman --no-document +foreman start +``` + +这将启动 `Procfile.dev` 中定义的进程，这将为你提供：一个 Rails 服务端、一个 Webpack 服务端、一个流式 API 服务端和一个 Sidekiq。当然，你也可以根据需要单独运行任何这些进程。 + +## 在开发中使用电子邮件 + +在开发模式下，Mastodon 将使用一个名为 [Letter Opener](https://github.com/ryanb/letter_opener) 的 gem 来“发送”电子邮件，这允许你在浏览器中调试电子邮件，而无需通过 SMTP 服务器实际发送电子邮件。 + +为了使用电子邮件，你需要运行 Sidekiq、Redis 和 PostgreSQL，然后可以通过访问 `http://localhost:3000/letter_opener/` 来查看电子邮件。 + +如果你在 docker 中进行开发，则需要设置 `REMOTE_DEV=true` 环境变量。 + +## 用于测试的有用命令 {#testing} + +`rspec` +: 运行 Ruby 测试套件 + +`yarn run test` +: 运行 JavaScript 测试套件 + +`rubocop` +: 检查 Ruby 代码是否符合我们的代码风格 + +## 更新你的开发实例 {#update} + +`bundle install` +: 更新 Ruby gems 并安装任何新的依赖项 + +`yarn install` +: 更新 Javascript 包并安装任何新的依赖项 + +`RAILS_ENV=development rails db:migrate` +: 为你的开发实例的数据库运行新的数据库迁移 + +{{< translation-status-zh-cn raw_title="Setting up a dev environment" raw_link="/dev/setup/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Account.md b/content/zh-cn/entities/Account.md new file mode 100644 index 0000000..6c5fc1a --- /dev/null +++ b/content/zh-cn/entities/Account.md @@ -0,0 +1,460 @@ +--- +title: Account +description: 表示 Mastodon 的一个账户及其相关的账户。 +menu: + docs: + parent: entities +aliases: [ + "/entities/source/", + "/entities/Source/", + "/entities/field/", + "/entities/Field/", + "/entities/account", + "/entities/Account", + "/entities/credentialaccount", + "/entities/CredentialAccount", + "/entities/mutedaccount", + "/entities/MutedAccount", + "/api/entities/source/", + "/api/entities/Source/", + "/api/entities/field/", + "/api/entities/Field/", + "/api/entities/account", + "/api/entities/Account", + "/api/entities/credentialaccount", + "/api/entities/CredentialAccount", + "/api/entities/mutedaccount", + "/api/entities/MutedAccount", +] +--- + +## 示例 + +```json +{ + "id": "23634", + "username": "noiob", + "acct": "noiob@awoo.space", + "display_name": "ikea shark fan account", + "locked": false, + "bot": false, + "created_at": "2017-02-08T02:00:53.274Z", + "attribution_domains": ["example.com", "example.net"], + "note": "

:ms_rainbow_flag:​ :ms_bisexual_flagweb:​ :ms_nonbinary_flag:​ #awoo#admin#bi#nonbinary#games@dzuk

", + "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": 547, + "following_count": 404, + "statuses_count": 28468, + "last_status_at": "2019-11-17", + "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": "@noiob", + "verified_at": null + }, + { + "name": "Bots", + "value": "@darksouls, @nierautomata, @fedi, code for @awoobot", + "verified_at": null + }, + { + "name": "Website", + "value": "http://shork.xyz}}) 数组\ +**版本历史:**\ +2.4.0 - 添加 + +### `bot` {#bot} + +**描述:** 表示该帐户可能执行自动操作、可能未被监控或标识为机器人。\ +**类型:** 布尔值\ +**版本历史:**\ +2.4.0 - 添加 + +### `group` {#group} + +**描述:** 表示该帐户代表一个组用户组。\ +**类型:** 布尔值\ +**版本历史:**\ +3.1.0 - 添加 + +### `discoverable` {#discoverable} + +**描述:** 帐户是否已选择加入账户目录等发现功能。\ +**类型:** {{}} 布尔值\ +**版本历史:**\ +3.1.0 - 添加 + +### `noindex` {{%optional%}} {#noindex} + +**描述:** 该用户是否已选择不被搜索引擎索引。\ +**类型:** {{}} 布尔值\ +**版本历史:**\ +4.0.0 - 添加 + +### `moved` {{%optional%}} {#moved} + +**描述:** 表示该账户当前处于非活动状态，并且其用户已转移到新帐户。\ +**类型:** {{}} [Account]({{< relref "entities/Account" >}})，如果账户被封禁，则为 null。\ +**版本历史:**\ +2.1.0 - 添加 + +### `suspended` {{%optional%}} {#suspended} + +**描述:** 仅当帐户被封禁时才返回的额外属性。\ +**类型:** 布尔值\ +**版本历史:**\ +3.3.0 - 添加 + +### `limited` {{%optional%}} {#limited} + +**描述:** 一个额外的属性，仅当帐户被隐藏时才会返回。如果为真，则表示应将帐户隐藏并在账户页显示警告。\ +**类型:** 布尔值\ +**版本历史:**\ +3.5.3 - 添加 + +### `created_at` {#created_at} + +**描述:** 帐户的创建时间。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +0.1.0 - 添加\ +3.4.0 - 现在解析为午夜，而不是确切的时间 + +### `last_status_at` {#last_status_at} + +**描述:** 发布最新嘟文的时间。\ +**类型:** {{}} 字符串 ([Date](/api/datetime-format#date))，如果没有嘟文则为 null\ +**版本历史:**\ +3.0.0 - 添加\ +3.1.0 - 现在只返回日期，没有时间 + +### `statuses_count` {#statuses_count} + +**描述:** 此帐户拥有多少条嘟文。\ +**类型:** 整数\ +**版本历史:**\ +0.1.0 - 添加 + +### `followers_count` {#followers_count} + +**描述:** 本实例举报的此账户的关注者数量。\ +**类型:** 整数\ +**版本历史:**\ +0.1.0 - 添加 + +### `following_count` {#following_count} + +**描述:** 本实例举报的此账户的关注数量。\ +**类型:** 整数\ +**版本历史:**\ +0.1.0 - 添加 + +## CredentialAccount 实体属性 {#CredentialAccount} + +```json +{ + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + // ... + "attribution_domains": ["example.com", "example.net"], + "note": "

i have approximate knowledge of many things. perpetual student. (nb/ace/they)

xmpp/email: a@trwnh.com
https://trwnh.com
help me live: https://liberapay.com/trwnh or paypal

- my triggers are moths and glitter
- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise
- dm me if i did something wrong, so i can improve
- purest person on fedi, do not lewd in my presence

", + // ... + "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/trwnh or paypal\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", + "fields": [ + { + "name": "Website", + "value": "https://trwnh.com", + "verified_at": "2019-08-29T04:14:55.571+00:00" + }, + { + "name": "Portfolio", + "value": "https://abdullahtarawneh.com", + "verified_at": "2021-02-11T20:34:13.574+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": "What to expect:", + "value": "talking about various things i find interesting, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people! and to spill my thoughts.", + "verified_at": null + } + ], + "follow_requests_count": 5 + }, + // ... + "fields": [ + { + "name": "Website", + "value": "https://trwnh.com", + "verified_at": "2019-08-29T04:14:55.571+00:00" + }, + { + "name": "Portfolio", + "value": "https://abdullahtarawneh.com", + "verified_at": "2021-02-11T20:34:13.574+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": "What to expect:", + "value": "talking about various things i find interesting, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people! and to spill my thoughts.", + "verified_at": null + } + ], + "role": { + "id": "-99", + "name": "", + "permissions": "65536", + "color": "", + "highlighted": false + } +} +``` + +### `attribution_domains` {#attribution_domains} + +**描述:** 允许对帐户进行标记的网站域。\ +**类型:** 字符串数组\ +**版本历史:**\ +4.4.0 (`mastodon` [API version]({{< relref "entities/Instance#api-versions" >}}) 3) - 添加 + +### `source` {#source} + +**描述:** 一个额外的属性，其中包含要与 API 方法一起使用的源值，这些方法[验证凭据]({{< relref "methods/accounts#verify_credentials" >}})和[更新凭据]({{< relref "methods/accounts#update_credentials" >}})。\ +**类型:** 哈希\ +**版本历史:**\ +2.4.0 - 添加 + +#### `source[note]` {#source-note} + +**描述:** 账户简介，采用纯文本而不是 HTML。\ +**类型:** 字符串\ +**版本历史:**\ +1.5.0 - 添加 + +#### `source[fields]` {#source-fields} + +**描述:** 关于帐户的元数据。\ +**类型:** [Field](#Field) 数组\ +**版本历史:**\ +2.4.0 - 添加 + +#### `source[privacy]` {#source-privacy} + +**描述:** 用于新嘟文的默认嘟文隐私值。\ +**类型:** 字符串（可枚举，oneOf）\ +`public`=公开嘟文\ +`unlisted`=未列出嘟文\ +`private`=仅关注者可见嘟文\ +`direct`=私下提及嘟文\ +**版本历史:**\ +1.5.0 - 添加 + +#### `source[sensitive]` {#source-sensitive} + +**描述:** 默认情况下是否应将新嘟文标记为敏感。\ +**类型:** 布尔值\ +**版本历史:**\ +1.5.0 - 添加 + +#### `source[language]` {#source-language} + +**描述:** 新嘟文的默认发布语言。\ +**类型:** 字符串（ISO 639-1 语言双字母代码）或空字符串\ +**版本历史:**\ +2.4.2 - 添加 + +#### `source[follow_requests_count]` {#follow_requests_count} + +**描述:** 待处理的关注请求数。\ +**类型:** 整数\ +**版本历史:**\ +3.0.0 - 添加 + +### `role` {#role} + +**描述:** 分配给当前授权用户的用户组。\ +**类型:** [Role]({{< relref "entities/Role" >}})\ +**版本历史:**\ +4.0.0 - 添加 + +## MutedAccount 实体属性 {#MutedAccount} + +### `mute_expires_at` {#mute_expires_at} + +**描述:** 定时隐藏到期的时间（如果适用）。\ +**类型:** {{}} 字符串 ([Datetime](/api/datetime-format#datetime))；如果隐藏是无限期的，则为 null\ +**版本历史:**\ +3.3.0 - 添加 + +## Field 实体属性 {#Field} + +### `name` {#name} + +**描述:** 给定字段的键值对的键。\ +**类型:** 字符串\ +**版本历史:**\ +2.4.0 - 添加 + +### `value` {#value} + +**描述:** 与 `name` 键关联的值。\ +**类型:** 字符串 (HTML)\ +**版本历史:**\ +2.4.0 - 添加 + +### `verified_at` {#verified_at} + +**描述:** 实例验证 rel="me" 链接的 URL 值的时间戳。\ +**类型:** {{}} 字符串 ([Datetime](/api/datetime-format#datetime))（如果 `value` 是经过验证的 URL）。否则，为 null。\ +**版本历史:**\ +2.6.0 - 添加 + +## 另请参考 + +{{< page-relref ref="methods/accounts" caption="accounts API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/account_serializer.rb" caption="app/serializers/rest/account_serializer.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/credential_account_serializer.rb" caption="app/serializers/rest/credential_account_serializer.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/muted_account_serializer.rb" caption="app/serializers/rest/muted_account_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Account" raw_link="/entities/Account/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/AccountWarning.md b/content/zh-cn/entities/AccountWarning.md new file mode 100644 index 0000000..829df1a --- /dev/null +++ b/content/zh-cn/entities/AccountWarning.md @@ -0,0 +1,71 @@ +--- +title: AccountWarning +description: 针对特定帐户的管理警告。 +menu: + docs: + parent: entities +aliases: [ + "/entities/AccountWarning", + "/api/entities/AccountWarning", +] +--- + +## 属性 + +### `id` {#id} + +**描述：** 数据库中帐户警告的 ID。\ +**类型：** 字符串（从整数转换而来）\ +**版本历史：**\ +4.3.0 - 添加 + +### `action` {#action} + +**描述：** 对帐户采取的措施。\ +**类型：** 字符串（枚举类型 oneOf）\ +`none` = 未采取任何措施，这只是一个简单的警告\ +`disable` = 目标账户被停用\ +`mark_statuses_as_sensitive` = 来自目标帐户的特定嘟文已被标记为敏感\ +`delete_statuses` = 来自目标帐户的特定嘟文已被删除\ +`sensitive` = 来自目标帐户的所有嘟文都被标记为敏感\ +`silence` = 目标帐户已被限制\ +`suspend` = 目标帐户已被封禁\ +**版本历史：**\ +4.3.0 - 添加 + +### `text` {#text} + +**描述：** 管理员向目标帐户发送的消息。\ +**类型：** 字符串\ +**版本历史：**\ +4.3.0 - 添加 + +### `status_ids` {#status_ids} + +**描述：** 与警告相关的嘟文 ID 列表。当 `action` 为 `mark_statuses_as_sensitive` 或 `delete_statuses` 时，该字段表示受影响的嘟文。\ +**类型：** {{}} 字符串数组（从整数转换而来），或 null\ +**版本历史：**\ +4.3.0 - 添加 + +### `target_account` {#target_account} + +**描述：** 管理操作针对的目标帐户。\ +**类型：** [Account]({{< relref "entities/Account" >}})\ +**版本历史：**\ +4.3.0 - 添加 + +### `appeal` {#appeal} + +**描述：** 目标帐户提交的申诉（如有）。\ +**类型：** {{}} [Appeal]({{< relref "entities/Appeal" >}})，或 null\ +**版本历史：**\ +4.3.0 - 添加 + +### `created_at` {#created_at} + +**描述：** 事件发生的时间。\ +**类型：** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史：**\ +4.3.0 - 添加 + +{{< translation-status-zh-cn raw_title="AccountWarning" raw_link="/entities/AccountWarning/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Admin_Account.md b/content/zh-cn/entities/Admin_Account.md new file mode 100644 index 0000000..56e3f11 --- /dev/null +++ b/content/zh-cn/entities/Admin_Account.md @@ -0,0 +1,215 @@ +--- +title: Admin::Account +description: 给定账户在管理视图下的信息。 +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-account", + "/entities/Admin-Account", + "/entities/admin_account", + "/entities/Admin_Account", + "/api/entities/admin-account", + "/api/entities/Admin-Account", + "/api/entities/admin_account", + "/api/entities/Admin_Account", +] +--- + +## 示例 + +```json +{ + "id": "108965278956942133", + "username": "admin", + "domain": null, + "created_at": "2022-09-08T23:03:26.762Z", + "email": "admin@mastodon.local", + "ip": "192.168.42.1", + "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-15T01:38:58.851Z" + } + ], + "account": { + "id": "108965278956942133", + "username": "admin", + "acct": "admin", + "display_name": "", + "locked": false, + "bot": false, + "discoverable": null, + "group": false, + "created_at": "2022-09-08T00:00:00.000Z", + "note": "", + "url": "http://mastodon.local/@admin", + "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": [] + } +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 数据库中账户的 ID。\ +**类型:** 字符串（从整数转换而来，但不保证一定为数字）\ +**版本历史:**\ +2.9.1 - 添加 + +### `username` {#username} + +**描述:** 账户的用户名。\ +**类型:** 字符串\ +**版本历史:**\ +2.9.1 - 添加 + +### `domain` {#domain} + +**描述:** 外站账户的域名。\ +**类型:** {{}} 字符串，对本站账户为 null\ +**版本历史:**\ +2.9.1 - 添加 + +### `created_at` {#created_at} + +**描述:** 账户首次被发现的时间。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +2.9.1 - 添加 + +### `email` {#email} + +**描述:** 与账户关联的电子邮件地址。\ +**类型:** 字符串\ +**版本历史:**\ +2.9.1 - 添加 + +### `ip` {#ip} + +**描述:** 最后一次登录此账户使用的 IP 地址。\ +**类型:** {{}} 字符串\ +**版本历史:**\ +2.9.1 - 添加\ +3.5.0 - 由于一个错误，返回类型从 String 更改为 [Admin::Ip]({{< relref "entities/Admin_Ip" >}})\ +4.0.0 - 错误已修复，返回类型现在再次为 String + +### `ips` {#ip} + +**描述:** 与此账户关联的所有已知 IP 地址。\ +**类型:** [Admin::Ip]({{< relref "entities/Admin_Ip" >}}) 数组\ +**版本历史:**\ +3.5.0 - 添加 + +### `locale` {#locale} + +**描述:** 账户的语言设置。\ +**类型:** 字符串（ISO 639 Part 1 双字符语言代码）\ +**版本历史:**\ +2.9.1 - 添加 + +### `invite_request` {#invite_request} + +**描述:** 请求邀请时给出的理由（对于需要手动批准注册的实例）\ +**类型:** {{}} 字符串\ +**版本历史:**\ +2.9.1 - 添加 + +### `role` {#role} + +**描述:** 账户的当前用户组。\ +**类型:** [Role]({{}})\ +**版本历史:**\ +2.9.1 - 添加，返回一个 String (可枚举，`user` `moderator` `admin` 其中之一)\ +4.0.0 - 现在使用 Role 实体 + +### `confirmed` {#confirmed} + +**描述:** 账户是否已确认其电子邮件地址。\ +**类型:** 布尔值\ +**版本历史:**\ +2.9.1 - 添加 + +### `approved` {#approved} + +**描述:** 账户当前是否已批准。\ +**类型:** 布尔值\ +**版本历史:**\ +2.9.1 - 添加 + +### `disabled` {#disabled} + +**描述:** 账户当前是否已被禁用。\ +**类型:** 布尔值\ +**版本历史:**\ +2.9.1 - 添加 + +### `silenced` {#silenced} + +**描述:** 账户当前是否已被隐藏。 +**类型:** 布尔值\ +**版本历史:**\ +2.9.1 - 添加 + +### `suspended` {#suspended} + +**描述:** 账户当前是否已被封禁。\ +**类型:** 布尔值\ +**版本历史:**\ +2.9.1 - 添加 + +### `account` {#account} + +**描述:** 关于账户的用户级信息。\ +**类型:** [Account]({{< relref "entities/account" >}})\ +**版本历史:**\ +2.9.1 - 添加 + +### `created_by_application_id` {{%optional%}} {#created_by_application_id} + +**描述:** 创建此帐户的 [Application]({{< relref "entities/application" >}}) 的 ID（如果适用）。\ +**类型:** 字符串（从整数转换而来，但不保证一定为数字）\ +**版本历史:**\ +2.9.1 - 添加 + +### `invited_by_account_id` {{%optional%}} {#invited_by_account_id} + +**描述:** 邀请此用户的 [Account]({{< relref "entities/account" >}}) 的 ID（如果适用）。\ +**类型:** 字符串（从整数转换而来，但不保证一定为数字）\ +**版本历史:**\ +2.9.1 - 添加 + +## 另请参考 + +{{< page-relref ref="methods/admin/accounts" caption="admin/accounts API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/account_serializer.rb" caption="app/serializers/rest/admin/account_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Admin::Account" raw_link="/entities/Admin_Account/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Admin_CanonicalEmailBlock.md b/content/zh-cn/entities/Admin_CanonicalEmailBlock.md new file mode 100644 index 0000000..16f803c --- /dev/null +++ b/content/zh-cn/entities/Admin_CanonicalEmailBlock.md @@ -0,0 +1,50 @@ +--- +title: Admin::CanonicalEmailBlock +description: 表示一个标准电子邮件屏蔽（将被哈希处理）。 +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-canonicalemailblock", + "/entities/Admin-CanonicalEmailBlock", + "/entities/admin_canonicalemailblock", + "/entities/Admin_CanonicalEmailBlock", + "/api/entities/admin-canonicalemailblock", + "/api/entities/Admin-CanonicalEmailBlock", + "/api/entities/admin_canonicalemailblock", + "/api/entities/Admin_CanonicalEmailBlock", +] +--- + +## 示例 + +```json +{ + "id": "2", + "canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c" +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 数据库中电子邮件屏蔽的 ID。\ +**类型:** 字符串 (从整数转换，但不能保证是数字)\ +**版本历史:**\ +4.0.0 - 添加 + +### `canonical_email_hash` {#canonical_email_hash} + +**描述:** 标准电子邮件地址的 SHA256 哈希值。\ +**类型:** 字符串 (SHA256)\ +**版本历史:**\ +4.0.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/admin/canonical_email_blocks" caption="admin/canonical_email_blocks API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/canonical_email_block_serializer.rb" caption="app/serializers/rest/admin/canonical_email_block_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Admin::CanonicalEmailBlock" raw_link="/entities/Admin_CanonicalEmailBlock/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Admin_Cohort.md b/content/zh-cn/entities/Admin_Cohort.md new file mode 100644 index 0000000..64146b3 --- /dev/null +++ b/content/zh-cn/entities/Admin_Cohort.md @@ -0,0 +1,137 @@ +--- +title: Admin::Cohort +description: 表示一组留存指标。 +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-cohort", + "/entities/Admin-Cohort", + "/entities/admin_cohort", + "/entities/Admin_Cohort", + "/api/entities/admin-cohort", + "/api/entities/Admin-Cohort", + "/api/entities/admin_cohort", + "/api/entities/Admin_Cohort", +] +--- + +## 示例 + +以下是 2022 年 9 月的月度留存数据示例，假设有 2 位用户在 2022 年 9 月注册，并在该月至少活跃过一次。 + +```json +{ + "period": "2022-09-01T00:00:00+00:00", + "frequency": "month", + "data": [ + { + "date": "2022-09-01T00:00:00+00:00", + "rate": 1.0, + "value": "2" + } + ] +} +``` + +以下是 2022 年 9 月 8 日至 2022 年 9 月 14 日这一周的每日留存数据示例，假设有 2 位用户在 2022 年 9 月 8 日注册，其中 1 位用户在 2022 年 9 月 9 日后停止活跃。 + +```json +{ + "period": "2022-09-08T00:00:00+00:00", + "frequency": "day", + "data": [ + { + "date": "2022-09-08T00:00:00+00:00", + "rate": 1.0, + "value": "2" + }, + { + "date": "2022-09-09T00:00:00+00:00", + "rate": 1.0, + "value": "2" + }, + { + "date": "2022-09-10T00:00:00+00:00", + "rate": 0.5, + "value": "1" + }, + { + "date": "2022-09-11T00:00:00+00:00", + "rate": 0.5, + "value": "1" + }, + { + "date": "2022-09-12T00:00:00+00:00", + "rate": 0.5, + "value": "1" + }, + { + "date": "2022-09-13T00:00:00+00:00", + "rate": 0.5, + "value": "1" + }, + { + "date": "2022-09-14T00:00:00+00:00", + "rate": 0.5, + "value": "1" + } + ] +} +``` + +## 属性 + +### `period` {#period} + +**描述:** 周期开始的时间戳，午夜。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +3.5.0 - 添加 + +### `frequency` {#frequency} + +**描述:** 返回数据的时间段大小。\ +**类型:** 字符串 (可枚举 oneOf)\ +`day` = 每日\ +`month` = 每月\ +**版本历史:**\ +3.5.0 - 添加 + +### `data` {#data} + +**描述:** 在给定周期内注册的用户的留存数据。\ +**类型:** Array of [CohortData](#CohortData)\ +**版本历史:**\ +3.5.0 - 添加 + +## CohortData entity attributes {#CohortData} + +### `date` {#date} + +**描述:** 时间段开始的时间戳，午夜。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +3.5.0 - 添加 + +### `rate` {#rate} + +**描述:** 在指定 `period` 内注册并在给定 `date` 时间段内活跃的用户的百分比。\ +**类型:** 数值\ +**版本历史:**\ +3.5.0 - 添加 + +### `value` {#value} + +**描述:** 在指定的 `period` 内注册并在给定的 `date` 时间段内活跃的用户人数。\ +**类型:** 整数\ +**版本历史:**\ +3.5.0 - 添加 + +## 另请参考 + +{{< page-relref ref="methods/admin/retention" caption="admin/retention API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/cohort_serializer.rb" caption="app/serializers/rest/admin/cohort_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Admin::Cohort" raw_link="/entities/Admin_Cohort/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Admin_Dimension.md b/content/zh-cn/entities/Admin_Dimension.md new file mode 100644 index 0000000..47b3473 --- /dev/null +++ b/content/zh-cn/entities/Admin_Dimension.md @@ -0,0 +1,308 @@ +--- +title: Admin::Dimension +description: 表示关于实例的定性数据。 +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-dimension", + "/entities/Admin-Dimension", + "/entities/admin_dimension", + "/entities/Admin_Dimension", + "/api/entities/admin-dimension", + "/api/entities/Admin-Dimension", + "/api/entities/admin_dimension", + "/api/entities/Admin_Dimension", +] +--- + +## 属性 + +### `key` {#key} + +**描述:** 请求维度的唯一键。\ +**类型:** 字符串\ +**版本历史:**\ +3.5.0 - 添加 + +### `data` {#data} + +**描述:** 请求维度可用的数据。\ +**类型:** 哈希值的数组\ +**版本历史:**\ +3.5.0 - 添加 + +## Data attributes + +### `key` {#data-key} + +**描述:** 此数据项的唯一键。\ +**类型:** 字符串\ +**版本历史:**\ +3.5.0 - 添加 + +### `human_key` {#data-human_key} + +**描述:** 此数据项的可读键。\ +**类型:** 字符串\ +**版本历史:**\ +3.5.0 - 添加 + +### `value` {#data-value} + +**描述:** 此数据项的值。\ +**类型:** 字符串\ +**版本历史:**\ +3.5.0 - 添加 + +### `unit` {{%optional%}} {#data-unit} + +**描述:** 与此数据项的值相关的单位（如果适用）。\ +**类型:** 字符串\ +**版本历史:**\ +3.5.0 - 添加 + +### `human_value` {{%optional%}} {#data-human_value} + +**描述:** 此数据项的可读格式化值。\ +**类型:** 字符串\ +**版本历史:**\ +3.5.0 - 添加 + +## 示例 + +### `languages` {#languages} + +统计每种语言发布的本站嘟文的数量，然后展示关于每种语言受欢迎程度的维度数据。 + +```json +{ + "key": "languages", + "data": [ + { + "key": "en", + "human_key": "English", + "value": "10" + }, + { + "key": "es", + "human_key": "Spanish", + "value": "1" + }, + // ... + ] +} +``` + +### `sources` {#sources} + +统计由给定客户端发布的本站嘟文的数量，然后展示关于每个客户端受欢迎程度的维度数据。 + +```json +{ + "key": "sources", + "data": [ + { + "key": "web", + "human_key": "Website", + "value": "2" + }, + // ... + ] +} +``` + +### `servers` {#servers} + +统计从给定域发布的嘟文数量，然后展示关于最受欢迎的外站实例的维度数据。 + +```json +{ + "key": "servers", + "data": [ + { + "key": "botsin.space", + "human_key": "botsin.space", + "value": "13738" + }, + { + "key": "mastodon.social", + "human_key": "mastodon.social", + "value": "8928" + }, + // ... + ] + } +``` + +### `space_usage` {#space_usage} + +展示关于实例堆栈中每个软件占用的空间的维度数据。 + +```json +{ + "key": "space_usage", + "data": [ + { + "key": "postgresql", + "human_key": "PostgreSQL", + "value": "14924935", + "unit": "bytes", + "human_value": "14.2 MB" + }, + { + "key": "redis", + "human_key": "Redis", + "value": "1972544", + "unit": "bytes", + "human_value": "1.88 MB" + }, + { + "key": "media", + "human_key": "Media storage", + "value": "0", + "unit": "bytes", + "human_value": "0 Bytes" + } + ] +} +``` + +### `software_versions` {#software_versions} + +展示关于实例堆栈中正在使用的软件版本的维度数据。 + +```json +{ + "key": "software_versions", + "data": [ + { + "key": "mastodon", + "human_key": "Mastodon", + "value": "3.5.3", + "human_value": "3.5.3" + }, + { + "key": "ruby", + "human_key": "Ruby", + "value": "3.0.4p208", + "human_value": "3.0.4p208" + }, + { + "key": "postgresql", + "human_key": "PostgreSQL", + "value": "10.22", + "human_value": "10.22" + }, + { + "key": "redis", + "human_key": "Redis", + "value": "4.0.9", + "human_value": "4.0.9" + } + ] +} +``` + +### `tag_servers` {#tag_servers} + +统计包含给定 `id` 的热门话题标签的嘟文数量，然后展示关于使用该热门话题标签的最受欢迎的实例的维度数据。 + +```json +{ + "key": "tag_servers", + "data": [ + { + "key": "live.hatnix.net", + "human_key": "live.hatnix.net", + "value": "6" + }, + { + "key": "linuxrocks.online", + "human_key": "linuxrocks.online", + "value": "4" + } + ] +} +``` + +### `tag_languages` {#tag_languages} + +统计包含给定 `id` 的热门话题标签的嘟文数量，然后展示关于这些嘟文的最受欢迎的语言的维度数据。 + +```json +{ + "key": "tag_languages", + "data": [ + { + "key": "und", + "human_key": "und", + "value": "8" + }, + { + "key": "en", + "human_key": "English", + "value": "7" + }, + // ... + ] + } +``` + +### `instance_accounts` {#instance_accounts} + +统计给定 `domain` 中每个账户的关注者数量，然后展示关于该外站实例中最受欢迎的账户的维度数据。 + +```json +{ + "key": "instance_accounts", + "data": [ + { + "key": "fribbledom", + "human_key": "fribbledom", + "value": "33" + }, + { + "key": "ShugoWah", + "human_key": "ShugoWah", + "value": "26" + }, + // ... + ] +} +``` + +### `instance_languages` {#instance_languages} + +统计给定 `domain` 中每种语言发布的嘟文数量，然后展示关于该外站实例上每种语言的受欢迎程度的维度数据。 + +```json +{ + "key": "instance_languages", + "data": [ + { + "key": "en", + "human_key": "English", + "value": "5848" + }, + { + "key": "de", + "human_key": "German", + "value": "155" + }, + // ... + ] +} +``` + +## 另请参考 + +{{< page-relref ref="methods/admin/dimensions" caption="admin/dimensions API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/dimension_serializer.rb" caption="app/serializers/rest/admin/dimension_serializer.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/dimension.rb" caption="app/lib/admin/metrics/dimension.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/dimension/" caption="app/lib/admin/metrics/dimension/" >}} + +{{< translation-status-zh-cn raw_title="Admin::Dimension" raw_link="/entities/Admin_Dimension/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Admin_DomainAllow.md b/content/zh-cn/entities/Admin_DomainAllow.md new file mode 100644 index 0000000..5fd58a6 --- /dev/null +++ b/content/zh-cn/entities/Admin_DomainAllow.md @@ -0,0 +1,58 @@ +--- +title: Admin::DomainAllow +description: 表示允许进行联合的域名。 +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-domainallow", + "/entities/Admin-DomainAllow", + "/entities/admin_domainallow", + "/entities/Admin_DomainAllow", + "/api/entities/admin-domainallow", + "/api/entities/Admin-DomainAllow", + "/api/entities/admin_domainallow", + "/api/entities/Admin_DomainAllow", +] +--- + +## 示例 + +```json +{ + "id": "1", + "domain": "mastodon.social", + "created_at": "2022-09-14T21:23:02.755Z" +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 数据库中 DomainAllow 的 ID。\ +**类型:** 字符串（从整数转换而来，但不保证一定是数字）\ +**版本历史:**\ +4.0.0 - 添加 + +### `domain` {#domain} + +**描述:** 允许进行联合的域名。\ +**类型:** 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `created_at` {#created_at} + +**描述:** 域名被允许进行联合的时间。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +## 参见 + +{{< page-relref page="methods/admin/domain_allows" caption="admin/domain_allows API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/domain_allow_serializer.rb" caption="app/serializers/rest/admin/domain_allow_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Admin::DomainAllow" raw_link="/entities/Admin_DomainAllow/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Admin_DomainBlock.md b/content/zh-cn/entities/Admin_DomainBlock.md new file mode 100644 index 0000000..a3cb025 --- /dev/null +++ b/content/zh-cn/entities/Admin_DomainBlock.md @@ -0,0 +1,117 @@ +--- +title: Admin::DomainBlock +description: 表示被限制联合的域名。 +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-domainblock", + "/entities/Admin-DomainBlock", + "/entities/admin_domainblock", + "/entities/Admin_DomainBlock", + "/api/entities/admin-domainblock", + "/api/entities/Admin-DomainBlock", + "/api/entities/admin_domainblock", + "/api/entities/Admin_DomainBlock", +] +--- + +## 示例 + +```json +{ + "id": "1", + "domain": "example.com", + "digest": "a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce1947", + "created_at": "2022-11-16T08:15:34.238Z", + "severity": "noop", + "reject_media": false, + "reject_reports": false, + "private_comment": null, + "public_comment": null, + "obfuscate": false +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 数据库中 DomainBlock 的 ID。\ +**类型:** 字符串 (从整数转换而来，但不保证一定是数字)\ +**版本历史:**\ +4.0.0 - 添加 + +### `domain` {#domain} + +**描述:** 不允许进行联合的域名。\ +**类型:** 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `digest` {#digest} + +**描述:** 不允许进行联合的域名的 sha256 十六进制摘要。\ +**类型:** 字符串\ +**版本历史:**\ +4.3.0 - 添加 + +### `created_at` {#created_at} + +**描述:** 该域名被阻止进行联合的时间。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `severity` {#severity} + +**描述:** 将应用于此域名屏蔽的策略。\ +**类型:** 字符串 (可枚举的 oneOf)\ +`silence` = 默认情况下，来自此域名的帐户发布的嘟文将被隐藏\ +`suspend` = 来自此域名的所有传入数据将被拒绝\ +`noop` = 不执行任何操作。允许拒绝媒体或举报\ +**版本历史:**\ +4.0.0 - 添加 + +### `reject_media` {#reject_media} + +**描述:** 是否拒绝来自此域名的媒体附件\ +**类型:** 布尔值\ +**版本历史:**\ +4.0.0 - 添加 + +### `reject_reports` {#reject_reports} + +**描述:** 是否拒绝来自此域名的举报\ +**类型:** 布尔值\ +**版本历史:**\ +4.0.0 - 添加 + +### `private_comment` {#private_comment} + +**描述:** \ +**类型:** {{}} 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `public_comment` {#public_comment} + +**描述:** \ +**类型:** {{}} 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `obfuscate` {#obfuscate} + +**描述:** 是否在公开展示时混淆该被屏蔽的域名\ +**类型:** 布尔值\ +**版本历史:**\ +4.0.0 - 添加 + +## 参见 + +{{< page-relref page="methods/admin/domain_blocks" caption="admin/domain_blocks API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/domain_block_serializer.rb" caption="app/serializers/rest/admin/domain_block_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Admin::DomainBlock" raw_link="/entities/Admin_DomainBlock/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Admin_EmailDomainBlock.md b/content/zh-cn/entities/Admin_EmailDomainBlock.md new file mode 100644 index 0000000..c6aace5 --- /dev/null +++ b/content/zh-cn/entities/Admin_EmailDomainBlock.md @@ -0,0 +1,123 @@ +--- +title: Admin::EmailDomainBlock +description: 表示一个不能用于注册的电子邮件域名。 +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-emaildomainblock", + "/entities/Admin-EmailDomainBlock", + "/entities/admin_emaildomainblock", + "/entities/Admin_EmailDomainBlock", + "/api/entities/admin-emaildomainblock", + "/api/entities/Admin-EmailDomainBlock", + "/api/entities/admin_emaildomainblock", + "/api/entities/Admin_EmailDomainBlock", +] +--- + +## 示例 + +```json +{ + "id": "1", + "domain": "foo", + "created_at": "2022-11-16T06:09:36.176Z", + "history": [ + { + "day": "1668556800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668470400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668384000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668297600", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668211200", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668124800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668038400", + "accounts": "0", + "uses": "0" + } + ] +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 数据库中 EmailDomainBlock 的 ID。\ +**类型:** 字符串 (从整数转换而来，但不保证一定是数字)\ +**版本历史:**\ +4.0.0 - 添加 + +### `domain` {#domain} + +**描述:** 不允许用于注册的电子邮件域名。\ +**类型:** 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `created_at` {#created_at} + +**描述:** 该电子邮件域名何时被禁止用于注册。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `history` {#history} + +**描述:** 给定日期（通常是过去一周）的使用统计信息。\ +**类型:** 哈希值的数组\ +**版本历史:**\ +4.0.0 - 添加 + +#### `history[][day]` {#history-day} + +**描述:** 给定日期午夜的 UNIX 时间戳。\ +**类型:** 字符串 (UNIX 时间戳)\ +**版本历史:**\ +4.0.0 - 添加 + +#### `history[][accounts]` {#history-accounts} + +**描述:** 当天使用该电子邮件域名尝试注册的帐户数。\ +**类型:** 字符串 (从整数转换而来)\ +**版本历史:**\ +4.0.0 - 添加 + +#### `history[][uses]` {#history-uses} + +**描述:** 当天该电子邮件域名的 IP 注册尝试次数。\ +**类型:** 字符串 (从整数转换而来)\ +**版本历史:**\ +4.0.0 - 添加 + +## 另请参考 + +{{< page-relref page="methods/admin/email_domain_blocks" caption="admin/email_domain_blocks API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/email_domain_block_serializer.rb" caption="app/serializers/rest/admin/email_domain_block_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Admin::EmailDomainBlock" raw_link="/entities/Admin_EmailDomainBlock/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Admin_Ip.md b/content/zh-cn/entities/Admin_Ip.md new file mode 100644 index 0000000..0a56c6f --- /dev/null +++ b/content/zh-cn/entities/Admin_Ip.md @@ -0,0 +1,50 @@ +--- +title: Admin::Ip +description: 表示与用户关联的 IP 地址。 +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-ip", + "/entities/Admin-Ip", + "/entities/admin_ip", + "/entities/Admin_Ip", + "/api/entities/admin-ip", + "/api/entities/Admin-Ip", + "/api/entities/admin_ip", + "/api/entities/Admin_Ip", +] +--- + +## 示例 + +```json +{ + "ip": "192.168.42.1", + "used_at": "2022-09-15T01:38:58.851Z" +} +``` + +## 属性 + +### `ip` {#id} + +**描述:** IP 地址。\ +**类型:** 字符串 (IP 地址)\ +**版本历史:**\ +3.5.0 - 添加 + +### `used_at` {#used_at} + +**描述:** 此 IP 地址最后一次被对应帐户使用时的时间戳。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +3.5.0 - 添加 + +## 参见 + +{{< page-relref ref="entities/Admin_Account#ips" caption="Admin::Account (`ips` attribute)" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/ip_serializer.rb" caption="app/serializers/rest/admin/ip_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Admin::Ip" raw_link="/entities/Admin_Ip/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Admin_IpBlock.md b/content/zh-cn/entities/Admin_IpBlock.md new file mode 100644 index 0000000..6b01b5c --- /dev/null +++ b/content/zh-cn/entities/Admin_IpBlock.md @@ -0,0 +1,85 @@ +--- +title: Admin::IpBlock +description: 表示一个不能用于注册的 IP 地址段。 +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-ipblock", + "/entities/Admin-IpBlock", + "/entities/admin_ipblock", + "/entities/Admin_IpBlock", + "/api/entities/admin-ipblock", + "/api/entities/Admin-IpBlock", + "/api/entities/admin_ipblock", + "/api/entities/Admin_IpBlock", +] +--- + +## 示例 + +```json +{ + "id": "1", + "ip": "8.8.8.8/32", + "severity": "no_access", + "comment": "", + "created_at": "2022-11-16T07:22:00.501Z", + "expires_at": null +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 数据库中 DomainBlock 的 ID。\ +**类型:** 字符串（从整数转换而来，但不保证是一个数字）\ +**版本历史:**\ +4.0.0 - 添加 + +### `ip` {#ip} + +**描述:** 不允许进行联合的 IP 地址段。\ +**类型:** 字符串（IP 地址和前缀）\ +**版本历史:**\ +4.0.0 - 添加 + +### `severity` {#severity} + +**描述:** 与此 IP 段关联的策略。\ +**类型:** 字符串（枚举，oneOf）\ +`sign_up_requires_approval` = 来自此 IP 段的任何注册的账户都需要手动批准。\ +`sign_up_block` = 将拒绝来自此 IP 段的任何注册。\ +`no_access` = 将完全拒绝来自此 IP 段的任何活动。\ +**版本历史:**\ +4.0.0 - 添加 + +### `comment` {#comment} + +**描述:** 此 IP 块的记录原因。\ +**类型:** 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `created_at` {#created_at} + +**描述:** IP 屏蔽的创建时间。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `expires_at` {#expires_at} + +**描述:** IP 屏蔽的过期时间。\ +**类型:** {{}} ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +## 参见 + +{{< page-relref page="methods/admin/ip_blocks" caption="admin/ip_blocks API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/ip_block_serializer.rb" caption="app/serializers/rest/admin/ip_block_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Admin::IpBlock" raw_link="/entities/Admin_IpBlock/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Admin_Measure.md b/content/zh-cn/entities/Admin_Measure.md new file mode 100644 index 0000000..9da3b9e --- /dev/null +++ b/content/zh-cn/entities/Admin_Measure.md @@ -0,0 +1,789 @@ +--- +title: Admin::Measure +description: 表示关于实例的定量数据。 +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-measure", + "/entities/Admin-Measure", + "/entities/admin_measure", + "/entities/Admin_Measure", + "/api/entities/admin-measure", + "/api/entities/Admin-Measure", + "/api/entities/admin_measure", + "/api/entities/Admin_Measure", +] +--- + +## 属性 + +### `key` {#key} + +**描述:** 请求的指标的唯一键。\ +**类型:** 字符串\ +**版本历史:**\ +3.5.0 - 添加 + +### `unit` {#unit} + +**描述:** 与此数据项的值关联的单位（如果适用）。\ +**类型:** {{}} 字符串 或 null\ +**版本历史:**\ +3.5.0 - 添加 + +### `total` {#total} + +**描述:** 与请求的指标关联的数值总计。\ +**类型:** 字符串 (从整数转换)\ +**版本历史:**\ +3.5.0 - 添加 + +### `human_value` {{%optional%}} {#data-human_value} + +**描述:** 此数据项的人类可读格式化值。\ +**类型:** 字符串\ +**版本历史:**\ +3.5.0 - 添加 + +### `previous_total` {{%optional%}} {#previous_total} + +**描述:** 在前一个周期中，与请求的指标关联的数值总计。前一个周期通过从 start_at 和 end_at 得到长度，然后将 start 和 end 日期都向后偏移相同的时间段长度来计算。\ +**类型:** 字符串 (从整数转换)\ +**版本历史:**\ +3.5.0 - 添加 + +### `data` {#data} + +**描述:** 请求的指标的可用数据，按日分成数据桶。\ +**类型:** 哈希值的数组\ +**版本历史:**\ +3.5.0 - 添加 + +#### `data[][date]` {#data-date} + +**描述:** 请求时间段内当天的午夜。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +3.5.0 - 添加 + +#### `data[][value]` {#data-value} + +**描述:** 请求的指标的数值。\ +**类型:** 字符串 (从整数转换)\ +**版本历史:**\ +3.5.0 - 添加 + +## 示例 + +### `active_users` + +时间段从 2022-09-14 开始到 2022-09-22 结束，你实例上的活跃用户总数 + +```json +{ + "key": "active_users", + "unit": null, + "total": "2", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00Z", + "value": "1" + }, + { + "date": "2022-09-18T00:00:00Z", + "value": "1" + }, + { + "date": "2022-09-19T00:00:00Z", + "value": "1" + }, + { + "date": "2022-09-20T00:00:00Z", + "value": "2" + }, + { + "date": "2022-09-21T00:00:00Z", + "value": "1" + } + ] +} +``` + +### `new_users` + +时间段从 2022-09-14 开始到 2022-09-22 结束，加入你实例的用户 + +```json +{ + "key": "new_users", + "unit": null, + "total": "2", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "1" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "1" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] +} +``` + +### `interactions` + +时间段从 2022-09-14 开始到 2022-09-22 结束，本站嘟文上的互动总数（收藏、转发、回复） + +```json +{ + "key": "interactions", + "unit": null, + "total": "0", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-18T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00Z", + "value": "0" + } + ] +} +``` + +### `opened_reports` + +时间段从 2022-09-14 开始到 2022-09-22 结束，提交的举报总数 + +```json +{ + "key": "opened_reports", + "unit": null, + "total": "0", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] + } +``` + +### `resolved_reports` + +时间段从 2022-09-14 开始到 2022-09-22 结束，已解决的举报总数 + +```json +{ + "key": "resolved_reports", + "unit": null, + "total": "0", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] +} +``` + +### `tag_accounts` + +时间段从 2022-09-14 开始到 2022-09-22 结束，至少在一条嘟文中使用过话题标签的帐户总数 + +```json +{ + "key": "tag_accounts", + "unit": null, + "total": "1", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "1" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] +} +``` + +### `tag_uses` + +时间段从 2022-09-14 开始到 2022-09-22 结束，使用过话题标签的嘟文总数 + +```json +{ + "key": "tag_uses", + "unit": null, + "total": "2", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "1" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "1" + } + ] +} +``` + +### `tag_servers` + +时间段从 2022-09-14 开始到 2022-09-22 结束，使用过话题标签的嘟文的外站原始实例总数 + +```json +{ + "key": "tag_servers", + "unit": null, + "total": "0", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] +} +``` + +### `instance_accounts` + +时间段从 2022-09-14 开始到 2022-09-22 结束，来自外站的帐户总数 + +```json +{ + "key": "instance_accounts", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] +} +``` + +### `instance_media_attachments` + +时间段从 2022-09-14 开始到 2022-09-22 结束，来自外站的媒体附件使用的总空间 + +```json +{ + "key": "instance_media_attachments", + "unit": "bytes", + "total": "0", + "human_value": "0 Bytes", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "" + } + ] +} +``` + +### `instance_reports` +时间段从 2022-09-14 开始到 2022-09-22 结束，针对来自外站的帐户提交的举报总数 + +```json +{ + "key": "instance_reports", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] +} +``` + +### `instance_statuses` + +时间段从 2022-09-14 开始到 2022-09-22 结束，来自外站的嘟文总数 + +```json +{ + "key": "instance_statuses", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] +} +``` + +### `instance_follows` + +时间段从 2022-09-14 开始到 2022-09-22 结束，本站用户关注的来自外站的帐户总数 + +```json +{ + "key": "instance_follows", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] +} +``` + +### `instance_followers` + +时间段从 2022-09-14 开始到 2022-09-22 结束，来自外站的帐户关注的本站帐户总数 + +```json +{ + "key": "instance_followers", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] +} +``` + +## 另请参考 + +{{< page-relref ref="methods/admin/dimensions" caption="admin/dimensions API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/measure_serializer.rb" caption="app/serializers/rest/admin/measure_serializer.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/measure.rb" caption="app/lib/admin/metrics/measure.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/measure/" caption="app/lib/admin/metrics/measure/" >}} + +{{< translation-status-zh-cn raw_title="Admin::Measure" raw_link="/entities/Admin_Measure/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Admin_Report.md b/content/zh-cn/entities/Admin_Report.md new file mode 100644 index 0000000..2240b0f --- /dev/null +++ b/content/zh-cn/entities/Admin_Report.md @@ -0,0 +1,175 @@ +--- +title: Admin::Report +description: 关于已提交举报的管理级信息。 +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-report", + "/entities/Admin-Report", + "/entities/admin_report", + "/entities/Admin_Report", + "/api/entities/admin-report", + "/api/entities/Admin-Report", + "/api/entities/admin_report", + "/api/entities/Admin_Report", +] +--- + +## 示例 + +```json +{ + "id": "1", + "action_taken": false, + "action_taken_at": null, + "category": "spam", + "comment": "", + "forwarded": false, + "created_at": "2022-09-09T21:19:23.085Z", + "updated_at": "2022-09-09T21:19:23.085Z", + "account": { + "id": "108965218747268792", + "username": "admin", + "domain": null, + "created_at": "2022-09-08T22:48:07.985Z", + "email": "admin@mastodon.local", + // ... + "account": { + "id": "108965218747268792", + "username": "admin", + "acct": "admin", + // ... + } + }, + "target_account": { + "id": "108965430868193066", + "username": "goody", + "domain": null, + "created_at": "2022-09-08T23:42:04.731Z", + "email": "goody@mastodon.local", + // ... + "account": { + "id": "108965430868193066", + "username": "goody", + "acct": "goody", + // ... + } + }, + "assigned_account": null, + "action_taken_by_account": null, + "statuses": [], + "rules": [] +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 数据库中举报的ID。\ +**类型:** 字符串 (从整数转换而来，但不保证是一个数字)\ +**版本历史:**\ +2.9.1 - 添加 + +### `action_taken` {#action_taken} + +**描述:** 是否针对此举报采取行动并解决此举报。\ +**类型:** 布尔值\ +**版本历史:**\ +2.9.1 - 添加 + +### `action_taken_at` {#action_taken_at} + +**描述:** 如果当前举报已解决，则为采取行动的时间。\ +**类型:** {{}} 字符串 ([Datetime](/api/datetime-format#datetime)) 或 null\ +**版本历史:**\ +2.9.1 - 添加 + +### `category` {#category} + +**描述:** 举报被归类到的类别。\ +**类型:** 字符串 (可枚举的 oneOf)\ +`spam` = 恶意、虚假或重复的内容\ +`violation` = 违反一条或多条特定的 [`规则`](#rules)\ +`other` = 默认（兜底）类别\ +**版本历史:**\ +3.5.0 - 添加 + +### `comment` {#comment} + +**描述:** 可选，举报理由。\ +**类型:** 字符串\ +**版本历史:**\ +2.9.1 - 添加 + +### `forwarded` {#forwarded} + +**描述:** 举报是否被转发到外站实例。\ +**类型:** 布尔值\ +**版本历史:**\ +4.0.0 - 添加 + +### `created_at` {#created_at} + +**描述:** 提交举报的时间。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +2.9.1 - 添加 + +### `updated_at` {#updated_at} + +**描述:** 此举报上一次操作的时间。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +2.9.1 - 添加 + +### `account` {#account} + +**描述:** 提交举报的帐户。\ +**类型:** [Admin::Account]({{< relref "entities/Admin_Account" >}})\ +**版本历史:**\ +2.9.1 - 添加 + +### `target_account` {#target_account} + +**描述:** 被举报的帐户。\ +**类型:** [Admin::Account]({{< relref "entities/Admin_Account" >}})\ +**版本历史:**\ +2.9.1 - 添加 + +### `assigned_account` {#assigned_account} + +**描述:** 分配给此举报的审核员的帐户。\ +**类型:** {{}} [Admin::Account]({{< relref "entities/Admin_Account" >}}) 或 null\ +**版本历史:**\ +2.9.1 - 添加 + +### `action_taken_by_account` {#action_taken_by_account} + +**描述:** 处理举报的审核员的帐户。\ +**类型:** {{}} [Admin::Account]({{< relref "entities/Admin_Account" >}}) 或 null\ +**版本历史:**\ +2.9.1 - 添加 + +### `statuses` {#statuses} + +**描述:** 附加到举报的嘟文，用于提供上下文信息。\ +**类型:** [Status]({{< relref "entities/Status" >}}) 数组\ +**版本历史:**\ +2.9.1 - 添加 + +### `rules` {#rules} + +**描述:** 附加到举报的规则，用于提供上下文信息。\ +**类型:** [Rule]({{< relref "entities/Rule" >}}) 数组\ +**版本历史:**\ +3.5.0 - 添加 + +## 参见 + +{{< page-relref page="methods/admin/reports" caption="admin/reports API 方法">}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/report_serializer.rb" caption="app/serializers/rest/admin/report_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Admin::Report" raw_link="/entities/Admin_Report/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Announcement.md b/content/zh-cn/entities/Announcement.md new file mode 100644 index 0000000..5c52ed0 --- /dev/null +++ b/content/zh-cn/entities/Announcement.md @@ -0,0 +1,214 @@ +--- +title: Announcement +description: 表示管理员设置的公告。 +menu: + docs: + parent: entities +aliases: [ + "/entities/announcement", + "/entities/Announcement", + "/api/entities/announcement", + "/api/entities/Announcement", +] +--- + +## 示例 + +```json +{ + "id": "8", + "content": "

Looks like there was an issue processing audio attachments without embedded art since yesterday due to an experimental new feature. That issue has now been fixed, so you may see older posts with audio from other servers pop up in your feeds now as they are being finally properly processed. Sorry!

", + "starts_at": null, + "ends_at": null, + "all_day": false, + "published_at": "2020-07-03T01:27:38.726Z", + "updated_at": "2020-07-03T01:27:38.752Z", + "read": true, + "mentions": [], + "statuses": [], + "tags": [], + "emojis": [], + "reactions": [ + { + "name": "bongoCat", + "count": 9, + "me": false, + "url": "https://files.mastodon.social/custom_emojis/images/000/067/715/original/fdba57dff7576d53.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/067/715/static/fdba57dff7576d53.png" + }, + { + "name": "thonking", + "count": 1, + "me": false, + "url": "https://files.mastodon.social/custom_emojis/images/000/098/690/original/a8d36edc4a7032e8.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/098/690/static/a8d36edc4a7032e8.png" + }, + { + "name": "AAAAAA", + "count": 1, + "me": false, + "url": "https://files.mastodon.social/custom_emojis/images/000/071/387/original/AAAAAA.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/071/387/static/AAAAAA.png" + }, + { + "name": "🤔", + "count": 1, + "me": true + } + ] +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 数据库中公告的 ID。\ +**类型:** 字符串（从整数转换而来，但不保证一定是数字）\ +**版本历史:**\ +3.1.0 - 添加 + +### `content` {#content} + +**描述:** 公告的文本内容。\ +**类型:** 字符串 (HTML)\ +**版本历史:**\ +3.1.0 - 添加 + +### `starts_at` {#starts_at} + +**描述:** 公告开始的时间。\ +**类型:** {{}} 字符串 ([Datetime](/api/datetime-format#datetime)) 或 null\ +**版本历史:**\ +3.1.0 - 添加 + +### `ends_at` {#ends_at} + +**描述:** 公告结束的时间。\ +**类型:** {{}} 字符串 ([Datetime](/api/datetime-format#datetime)) 或 null\ +**版本历史:**\ +3.1.0 - 添加 + +### `published` {#published} + +**描述:** 公告当前是否处于发布状态。\ +**类型:** 布尔值\ +**版本历史:**\ +3.1.0 - 添加 + +### `all_day` {#all_day} + +**描述:** 公告是否应仅在日期上开始和结束，而不是在特定的时间点开始和结束。如果没有 `starts_at` 或 `ends_at` 时间，则为 false。\ +**类型:** 布尔值\ +**版本历史:**\ +3.1.0 - 添加 + +### `published_at` {#created_at} + +**描述:** 公告发布的时间。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +3.1.0 - 添加 + +### `updated_at` {#updated_at} + +**描述:** 公告上次更新的时间。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +3.1.0 - 添加 + +### `read` {{%optional%}} {#read} + +**描述:** 当前已读该公告的用户。\ +**类型:** 布尔值\ +**版本历史:**\ +3.1.0 - 添加 + +### `mentions` {#mentions} + +**描述:** 公告文本中提及的帐户。\ +**类型:** Array of [Announcement::Account](#Account)\ +**版本历史:**\ +3.1.0 - 添加 + +### `statuses` {#statuses} + +**描述:** 公告文本中链接的嘟文。\ +**类型:** Array of [Announcement::Status](#Status)\ +**版本历史:**\ +3.1.0 - 添加 + +### `tags` {#tags} + +**描述:** 公告文本中链接的话题标签。\ +**类型:** Array of [Status::Tag]({{< relref "entities/Status#Tag" >}})\ +**版本历史:**\ +3.1.0 - 添加 + +### `emojis` {#emojis} + +**描述:** 公告文本中使用的自定义表情。\ +**类型:** Array of [CustomEmoji]({{< relref "entities/CustomEmoji" >}})\ +**版本历史:**\ +3.1.0 - 添加 + +### `reactions` {#reactions} + +**描述:** 附加到公告的表情回应。\ +**类型:** Array of [Reaction]({{< relref "entities/Reaction" >}})\ +**版本历史:**\ +3.1.0 - 添加 + +## Announcement::Account attributes {#Account} + +### `id` {#Account-id} + +**描述:** 被提及用户的帐户 ID。\ +**类型:** 字符串（从整数转换而来，但不保证一定是数字）\ +**版本历史:**\ +3.1.0 - 添加 + +### `username` {#Account-username} + +**描述:** 被提及用户的用户名。\ +**类型:** 字符串\ +**版本历史:**\ +3.1.0 - 添加 + +### `url` {#Account-url} + +**描述:** 被提及用户的账户位置。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +3.1.0 - 添加 + +### `acct` {#Account-acct} + +**描述:** 被提及用户的 webfinger acct: URI。对于本站用户，等同于 `username`；对于外站用户，等同于 `username@domain`。\ +**类型:** 字符串\ +**版本历史:**\ +3.1.0 - 添加 + +## Announcement::Status attributes {#Status} + +### `id` {#Status-id} + +**描述:** 数据库中附加嘟文的 ID。\ +**类型:** 字符串（从整数转换而来，但不保证一定是数字）\ +**版本历史:**\ +3.1.0 - 添加 + +### `url` {#Status-url} + +**描述:** 附加嘟文的 URL。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +3.1.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/announcements" caption="公告 API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/announcement_serializer.rb" caption="app/serializers/rest/announcement_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Announcement" raw_link="/entities/Announcement/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Appeal.md b/content/zh-cn/entities/Appeal.md new file mode 100644 index 0000000..24fab82 --- /dev/null +++ b/content/zh-cn/entities/Appeal.md @@ -0,0 +1,32 @@ +--- +title: Appeal +description: 对管理操作的申诉。 +menu: + docs: + parent: entities +aliases: [ + "/entities/Appeal", + "/api/entities/Appeal", +] +--- + +## 属性 + +### `text` {#text} + +**描述:** 受到管理的账号向管理员发起的申诉文本。\ +**类型:** 字符串\ +**版本历史:**\ +4.3.0 - 添加 + +### `state` {#state} + +**描述:** 申诉的状态。\ +**类型:** 字符串 (枚举类型，取值之一)\ +`approved` = 申诉已被管理者批准\ +`rejected` = 申诉已被管理者驳回\ +`pending` = 申诉已提交，但尚未批准或驳回\ +**版本历史:**\ +4.3.0 - 添加 + +{{< translation-status-zh-cn raw_title="Appeal" raw_link="/entities/Appeal/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Application.md b/content/zh-cn/entities/Application.md new file mode 100644 index 0000000..4dab9d2 --- /dev/null +++ b/content/zh-cn/entities/Application.md @@ -0,0 +1,115 @@ +--- +title: Application +description: 表示一个通过 REST API 访问帐户或发布嘟文的应用。 +menu: + docs: + parent: entities +aliases: [ + "/entities/application", + "/entities/Application", + "/api/entities/application", + "/api/entities/Application", +] +--- + +## 示例 + +```json +{ + "name": "Test Application", + "website": "https://app.example", + "scopes": ["read", "write", "push"], + "redirect_uri": "https://app.example/callback\nhttps://app.example/register", + "redirect_uris": [ + "https://app.example/callback", + "https://app.example/register" + ] +} +``` + +## 属性 + +### `name` {#name} + +**描述:** 你的应用的名称。\ +**类型:** 字符串\ +**版本历史:**\ +0.9.9 - 添加 + +### `website` {{%optional%}} {#website} + +**描述:** 与你的应用关联的网站。\ +**类型:** {{}} 字符串 (URL)\ +**版本历史:**\ +0.9.9 - 添加\ +3.5.1 - this property is now nullable + +### `scopes` {#scopes} + +**描述:** 你的应用的作用域。按空格分隔的已注册的 `scopes` 字符串。\ +**类型:** 字符串数组\ +**版本历史:**\ +4.3.0 - 添加 + +### `redirect_uris` {#redirect_uris} + +**描述:** 你的应用的已注册重定向 URI。\ +**类型:** 字符串数组 (数组中元素的值为 URL 或 `"urn:ietf:wg:oauth:2.0:oob"`)\ +**版本历史:**\ +4.3.0 - 添加 + +### `redirect_uri` {{%deprecated%}} {#redirect_uri} + +**描述:** 你的应用的已注册重定向 URI。\ +当注册了多个重定向 URI 时，可能包含 `\n` 字符。\ +**类型:** 字符串\ +**版本历史:**\ +0.0.0 - 添加\ +4.3.0 - 已弃用，推荐使用 [`redirect_uris`]({{< relref "entities/Application#redirect_uris" >}})，因为当注册了多个重定向 URI 时，此属性的值不是一个格式规范的 URI + +### `vapid_key` {{%deprecated%}} {#vapid_key} + +**描述:** 用于流式推送 API。与 [POST /api/v1/apps]({{< relref "methods/apps#create" >}}) 一同返回。等同于 [WebPushSubscription#server_key]({{< relref "entities/WebPushSubscription#server_key" >}}) 和 [Instance#vapid_public_key]({{< relref "entities/Instance#vapid_public_key" >}})\ +**类型:** 字符串\ +**版本历史:**\ +2.8.0 - 添加\ +4.3.0 - 已弃用，等待移除，请参阅 [api/v2/instance]({{< relref "methods/Instance#v2">}}) 以获取此值 (`configuration.vapid.public_key`) + +## CredentialApplication 属性 {#CredentialApplication} + +所有 [Application](#attributes) 属性以及以下属性： + +### `client_id` {#client_id} + +**描述:** 客户端 ID 密钥，用于获取 OAuth 令牌\ +**类型:** 字符串\ +**版本历史:**\ +0.9.9 - 添加 +4.3.0 - moved to `CredentialApplication` from `Application` + +### `client_secret` {#client_secret} + +**描述:** 客户端密钥，用于获取 OAuth 令牌\ +**类型:** 字符串\ +**版本历史:**\ +0.9.9 - 添加 +4.3.0 - moved to `CredentialApplication` from `Application` + +### `client_secret_expires_at` {#client_secret_expires_at} + +**描述:** 客户端密钥到期时间，目前始终返回 `0`，表示 OAuth 客户端不会过期\ +**类型:** 字符串\ +**版本历史:**\ +4.3.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/apps" caption="应用 API 方法" >}} + +{{< page-relref ref="entities/Status#application" caption="嘟文（`application` 属性）" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/application_serializer.rb" caption="app/serializers/rest/application_serializer.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/credential_application_serializer.rb" caption="app/serializers/rest/credential_application_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Application" raw_link="/entities/Application/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Context.md b/content/zh-cn/entities/Context.md new file mode 100644 index 0000000..d56e3c6 --- /dev/null +++ b/content/zh-cn/entities/Context.md @@ -0,0 +1,72 @@ +--- +title: Context +description: 表示给定嘟文周围的树状结构。用于重建嘟文的嘟文串。 +menu: + docs: + parent: entities +aliases: [ + "/entities/context", + "/entities/Context", + "/api/entities/context", + "/api/entities/Context", +] +--- + +## 示例 + +```json +{ + "ancestors": [ + { + "id": "103188938570975982", + "created_at": "2019-11-23T19:44:00.124Z", + "in_reply_to_id": null, + // ... + }, + { + "id": "103188971072973252", + "created_at": "2019-11-23T19:52:23.398Z", + "in_reply_to_id": "103188938570975982", + // ... + }, + { + "id": "103188982235527758", + "created_at": "2019-11-23T19:55:08.208Z", + "in_reply_to_id": "103188971072973252", + // ... + } + ], + "descendants": [ + { + "id": "103189026958574542", + "created_at": "2019-11-23T20:06:36.011Z", + "in_reply_to_id": "103189005915505698", + // ... + } + ] +} +``` + +## 属性 + +### `ancestors` {#ancestors} + +**描述:** 嘟文串中的上级嘟文。\ +**类型:** [Status]({{< relref "entities/Status" >}})数组\ +**版本历史:**\ +0.6.0 - 添加 + +### `descendants` {#descendants} + +**描述:** 嘟文串中的下级嘟文。\ +**类型:** [Status]({{< relref "entities/Status" >}})数组\ +**版本历史:**\ +0.6.0 - 添加 + +## 另请参阅 + +{{< page-relref ref="methods/statuses#context" caption="GET /api/v1/statuses/:id/context" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/context_serializer.rb" caption="app/serializers/rest/context_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Context" raw_link="/entities/Context/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Conversation.md b/content/zh-cn/entities/Conversation.md new file mode 100644 index 0000000..eb82441 --- /dev/null +++ b/content/zh-cn/entities/Conversation.md @@ -0,0 +1,75 @@ +--- +title: Conversation +description: 表示具有“私下提及”可见性的会话。 +menu: + docs: + parent: entities +aliases: [ + "/entities/conversation", + "/entities/Conversation", + "/api/entities/conversation", + "/api/entities/Conversation", +] +--- + +## 示例 + +```json +{ + "id": "418450", + "unread": true, + "accounts": [ + { + "id": "482403", + "username": "amic", + "acct": "amic@nulled.red", + // ... + } + ], + "last_status": { + "id": "103196583826321184", + "created_at": "2019-11-25T04:08:24.000Z", + "in_reply_to_id": "103196540587943467", + "in_reply_to_account_id": "14715", + // ... + } +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 数据库中会话的 ID。\ +**类型:** 字符串（从整数转换而来，但不保证是一个数字）\ +**版本历史:**\ +2.6.0 - 添加 + +### `unread` {#unread} + +**描述:** 会话当前是否标记为未读？\ +**类型:** 布尔值\ +**版本历史:**\ +2.6.0 - 添加 + +### `accounts` {#accounts} + +**描述:** 会话的参与者。\ +**类型:** [Account]({{< relref "entities/Account" >}}) 数组\ +**版本历史:**\ +2.6.0 - 添加 + +### `last_status` {#last_status} + +**描述:** 会话中的最后一条嘟文。\ +**类型:** {{}} [Status]({{< relref "entities/Status" >}})\ +**版本历史:**\ +2.6.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/conversations" caption="会话 API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/conversation_serializer.rb" caption="app/serializers/rest/conversation_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Conversation" raw_link="/entities/Conversation/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/CustomEmoji.md b/content/zh-cn/entities/CustomEmoji.md new file mode 100644 index 0000000..4216e2d --- /dev/null +++ b/content/zh-cn/entities/CustomEmoji.md @@ -0,0 +1,78 @@ +--- +title: CustomEmoji +description: 表示一个自定义表情。 +menu: + docs: + parent: entities +aliases: [ + "/entities/emoji", + "/entities/Emoji", + "/entities/customemoji", + "/entities/CustomEmoji", + "/api/entities/emoji", + "/api/entities/Emoji", + "/api/entities/customemoji", + "/api/entities/CustomEmoji", +] +--- + +## 示例 + +```json +{ + "shortcode": "blobaww", + "url": "https://files.mastodon.social/custom_emojis/images/000/011/739/original/blobaww.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/011/739/static/blobaww.png", + "visible_in_picker": true, + "category": "Blobs" +} +``` + +## 属性 + +### `shortcode` {#shortcode} + +**描述:** 自定义表情的名称。\ +**类型:** 字符串\ +**版本历史:**\ +2.0.0 - 添加 + +### `url` {#url} + +**描述:** 自定义表情的链接。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +2.0.0 - 添加 + +### `static_url` {#static_url} + +**描述:** 自定义表情的静态副本的链接。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +2.0.0 - 添加 + +### `visible_in_picker` {#visible_in_picker} + +**描述:** 此表情是否在选择器中可见或不公开列出。\ +**类型:** 布尔值\ +**版本历史:**\ +2.0.0 - 添加 + +### `category` {#category} + +**描述:** 用于在选择器中对自定义表情进行排序。\ +**类型:** {{}} 字符串\ +**版本历史:**\ +3.0.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/custom_emojis" caption="GET /api/v1/custom_emojis" >}} + +{{< page-relref ref="entities/Status#emojis" caption="Status (`emojis` attribute)" >}} + +{{< page-relref ref="entities/Announcement#emojis" caption="Announcement (`emojis` attribute)" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/custom_emoji_serializer.rb" caption="app/serializers/rest/custom_emoji_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="CustomEmoji" raw_link="/entities/CustomEmoji/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/DomainBlock.md b/content/zh-cn/entities/DomainBlock.md new file mode 100644 index 0000000..9482867 --- /dev/null +++ b/content/zh-cn/entities/DomainBlock.md @@ -0,0 +1,64 @@ +--- +title: DomainBlock +description: 表示实例屏蔽的域名。 +menu: + docs: + parent: entities +aliases: [ + "/entities/domainblock", + "/entities/DomainBlock", + "/api/entities/domainblock", + "/api/entities/DomainBlock", +] +--- + +## 示例 + +```json +{ + "domain":"daji******.com", + "digest":"3752f63a7079d60c2de5dceb8bd7608e86a15544eb78a494a482041c3684b37f", + "severity":"suspend", + "comment":"Inappropriate content" +} +``` + +## 属性 + +### `domain` {#domain} + +**描述:** 被屏蔽的域名。 这可能会被混淆或由部分删节。\ +**类型:** 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `digest` {#digest} + +**描述:** 域字符串的 SHA256 哈希摘要。\ +**类型:** 字符串 (SHA256)\ +**版本历史:**\ +4.0.0 - 添加 + +### `severity` {#severity} + +**描述:** 域名屏蔽的级别。\ +**类型:** 字符串 (Enumerable, oneOf)\ +`silence` = 来自此域的用户将从时间线、话题标签和通知中隐藏（除非你关注了该用户）。\ +`suspend` = 来自此域名的传入消息将被拒绝并完全丢弃。\ +**版本历史:**\ +4.0.0 - 添加 + +### `comment` {{%optional%}} {#comment} + +**描述:** 域名屏蔽的可选原因。\ +**类型:** 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +## 另请参阅 + +{{< page-relref ref="methods/instance#domain_blocks" caption="GET /api/v1/instance/domain_blocks" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/domain_block_serializer.rb" caption="app/serializers/rest/domain_block_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="DomainBlock" raw_link="/entities/DomainBlock/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/EncryptedMessage.md b/content/zh-cn/entities/EncryptedMessage.md new file mode 100644 index 0000000..5165a21 --- /dev/null +++ b/content/zh-cn/entities/EncryptedMessage.md @@ -0,0 +1,91 @@ +--- +title: EncryptedMessage +description: 表示一条加密消息。 +menu: + docs: + parent: entities +aliases: [ + "/entities/encryptedmessage", + "/entities/EncryptedMessage", + "/entities/encryptedmessage", + "/entities/EncryptedMessage", +] +draft: true +--- + +{{< hint style="info" >}} +此实体当前未使用。 +{{}} + +## 示例 + +```json +``` + +## 属性 + +### `id` {#id} + +**描述:** EncryptedMessage 在数据库中的 ID。\ +**类型:** 字符串 (从整数转换而来，但不保证是数字)\ +**版本历史:**\ +3.2.0 - 添加 + +### `account_id` {#account_id} + +**描述:** 发送此消息的 Account 的 ID。\ +**类型:** 字符串 (从整数转换而来，但不保证是数字)\ +**版本历史:**\ +3.2.0 - 添加 + +### `device_id` {#device_id} + +**描述:** 发送此消息的 Device 的 ID。\ +**类型:** 字符串 (从整数转换而来，但不保证是数字)\ +**版本历史:**\ +3.2.0 - 添加 + +### `type` {#type} + +**描述:** 消息是预共享密钥消息（用于建立新会话）还是正常加密消息（现有会话的一部分）。\ +**类型:** 字符串 (枚举类型, oneOf)\ +`0` = 预共享密钥消息（用于建立新会话）\ +`1` = 正常加密消息（现有会话的一部分）\ +**版本历史:**\ +3.2.0 - 添加 + +### `body` {#body} + +**描述:** 加密的消息内容。\ +**类型:** 字符串\ +**版本历史:**\ +3.2.0 - 添加 + +### `digest` {#digest} + +**描述:** 消息的 HMAC SHA-256 摘要哈希值。\ +**类型:** 字符串 (SHA256)\ +**版本历史:**\ +3.2.0 - 添加 + +### `message_franking` {#message_franking} + +**描述:** 一个签名值，用于举报消息正文的内容。\ +**类型:** 字符串\ +**版本历史:**\ +3.2.0 - 添加 + +### `created_at` {#created_at} + +**描述:** 消息创建的时间戳。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +3.2.0 - 添加 + +## 参见 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/encrypted_message_serializer.rb" caption="app/serializers/rest/encrypted_message_serializer.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/pull/13820" caption="添加端到端加密 API (#13820)" >}} + +{{< translation-status-zh-cn raw_title="EncryptedMessage" raw_link="/entities/EncryptedMessage/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Error.md b/content/zh-cn/entities/Error.md new file mode 100644 index 0000000..72679a0 --- /dev/null +++ b/content/zh-cn/entities/Error.md @@ -0,0 +1,122 @@ +--- +title: Error +description: 表示一条错误消息。 +menu: + docs: + parent: entities +aliases: [ + "/entities/error", + "/entities/Error", + "/api/entities/error", + "/api/entities/Error", +] +--- + +## 示例 + +```json +{ + "error": "invalid_grant", + "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client." +} +``` + +{{< hint style="info" >}} +**错误响应中最重要的是 HTTP 状态码。** 遵循标准语义。 错误的 body 是一个 JSON 对象，包含更多信息（如果可用）。 +{{< /hint >}} + +## 属性 + +### `error` {#error} + +**描述:** 错误消息。\ +**类型:** 字符串\ +**版本历史:**\ +0.6.0 - 添加 + +### `error_description` {{%optional%}} {#error_description} + +**描述:** 错误的更长描述，主要与 OAuth API 一起提供。\ +**类型:** 字符串\ +**版本历史:**\ +0.6.0 - 添加 + +## 可能的原因 {#reasons} + +### 400 - 非法请求 + +#### ParameterMissing {#parameter-missing} + +错误: {string}。 当 API 调用中缺少必需的参数时出现。 + +### 401 - 未授权 {#401} + +#### require_authenticated_user! {#auth} + +错误: 此 API 要求用户进行身份验证。 当实例处于安全模式时出现，该模式禁用 API 方法的所有公共使用。 + +### 403 - 禁止访问 {#403} + +#### NotPermitted {#not-permitted} + +错误: 不允许此操作。 尝试调用你没有权限的方法（例如管理或工作人员方法），或执行不允许你执行的操作（例如关注阻止你的用户）时出现。 + +#### current_user.disabled? {#disabled} + +错误: 你的账户当前已被禁用。 当 OAuth 令牌的授权用户已由管理员禁用其帐户时出现。 + +#### !current_user.confirmed? {#unconfirmed} + +错误: 你的账户缺少已确认的电子邮件地址。 当与 OAuth 令牌的授权用户的帐户关联的电子邮件地址尚未确认时出现。 + +#### !current_user.approved? {#unapproved} + +错误: 你的账户当前正在等待批准。 当 OAuth 令牌的授权用户在需要批准注册的实例上注册，并且用户尚未由管理员批准其帐户时出现。 + +### 404 - 未找到 {#404} + +#### RecordNotFound {#not-found} + +错误: 未找到记录。 当实体记录不存在，或者授权用户不在私有实体的访问范围内时出现。 + +### 422 - 无法处理的实体 {#422} + +#### RecordInvalid {#invalid} + +错误: {string}。 当实体创建失败时可能会出现。 + +#### RecordNotUnique {#not-unique} + +错误: 重复记录。 当你尝试置顶一个已置顶的帐户或嘟文时出现。 + +#### !current_user {#user-required} + +错误: 此方法需要经过身份验证的用户。 尝试调用需要处理用户的 API 方法时，在使用没有授权用户的 OAuth 令牌（或根本没有令牌）时出现。 + +### 429 - 请求过于频繁 {#429} + +错误: {translated string}。 当你超过速率限制时出现。 有关更多信息，请参见 [速率限制]({{< relref "api/rate-limits" >}})。 + +### 503 - 服务不可用 {#503} + +#### UnexpectedResponseError {#unexpected-response} + +错误: 无法获取外站数据。 当 Mastodon 调用返回错误的外站服务（例如来自另一个实例的 WebFinger）时出现。 + +#### SSLError {#ssl} + +错误: 无法验证外站 SSL 证书。 调用外站服务时，但它具有无效的 SSL 证书时出现。 + +#### NetworkingError {#networking-error} + +错误: 为你的请求提供服务时出现临时问题，请重试。 当对 S3 存储实例的调用失败时出现。 + +#### RaceConditionError {#race-condition} + +错误: 为你的请求提供服务时出现临时问题，请重试。 由于实例端代码中存在争用情况导致错误时出现。 + +## 另请查看 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/base_controller.rb" caption="app/controllers/api/base_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="Error" raw_link="/entities/Error/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/ExtendedDescription.md b/content/zh-cn/entities/ExtendedDescription.md new file mode 100644 index 0000000..d7d88d5 --- /dev/null +++ b/content/zh-cn/entities/ExtendedDescription.md @@ -0,0 +1,46 @@ +--- +title: ExtendedDescription +description: 表示实例的详细描述，将显示在其“关于”页面上。 +menu: + docs: + parent: entities +aliases: [ + "/entities/extendeddescription", + "/entities/ExtendedDescription", + "/api/entities/extendeddescription", + "/api/entities/ExtendedDescription", +] +--- + +## 示例 + +```json +{ + "updated_at":"2022-11-03T04:09:07Z", + "content":"

For inquiries not related specifically to the operation of this server, such as press inquiries, please contact press@joinmastodon.org.

\n\n

Funding

\n\n

This server is crowdfunded by Patreon donations. For a list of sponsors, see joinmastodon.org.

\n\n

Reporting and moderation

\n\n

When reporting accounts, please make sure to include at least a few posts that show rule-breaking behaviour, when applicable. If there is any additional context that might help make a decision, please also include it in the comment. This is especially important when the content is in a language nobody on the moderation team speaks.

\n\n

We usually handle reports within 24 hours. Please mind that you are not notified when a report you have made has led to a punitive action, and that not all punitive actions are externally visible. For first time offenses, we may opt to delete offending content, escalating to harsher measures on repeat offenses.

\n\n

Impressum

\n\n

Mastodon gGmbH
\nMühlenstraße 8a
\n14167 Berlin
\nGermany

\n\n

E-Mail-Adresse: hello@joinmastodon.org

\n\n

Vertretungsberechtigt: Eugen Rochko (Geschäftsführer)

\n\n

Umsatzsteuer Identifikationsnummer (USt-ID): DE344258260

\n\n

Handelsregister
\nGeführt bei: Amtsgericht Charlottenburg
\nNummer: HRB 230086 B

\n" +} +``` + +## 属性 + +### `updated_at` {#updated_at} + +**描述:** 扩展描述上次更新的时间戳。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +4. 0.0 - 添加 + +### `content` {#content} + +**描述:** 扩展描述 HTML 渲染后的内容。\ +**类型:** 字符串 (HTML)\ +**版本历史:**\ +4. 0.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/instance#extended_description" caption="GET /api/v1/instance/extended_description" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/extended_description_serializer.rb" caption="app/serializers/rest/extended_description_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="ExtendedDescription" raw_link="/entities/ExtendedDescription/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/FamiliarFollowers.md b/content/zh-cn/entities/FamiliarFollowers.md new file mode 100644 index 0000000..81900d8 --- /dev/null +++ b/content/zh-cn/entities/FamiliarFollowers.md @@ -0,0 +1,66 @@ +--- +title: FamiliarFollowers +description: 表示你的关注者中，同时也关注了其他用户的子集。 +menu: + docs: + parent: entities +aliases: [ + "/entities/familiarfollowers", + "/entities/FamiliarFollowers", + "/api/entities/familiarfollowers", + "/api/entities/FamiliarFollowers", +] +--- + +## 示例 + +```json +[ + { + "id":"1", + "accounts":[ + { + "id":"1087990", + "username":"moss", + "acct":"moss@goblin.camp", + // ... + }, + { + "id":"1092723", + "username":"vivianrose", + "acct":"vivianrose", + // ... + }, + // ... + ] + }, + { + "id":"2", + "accounts":[] + } +] +``` + +## 属性 + +### `id` {#id} + +**描述:** 数据库中账户的ID。\ +**类型:** 字符串（从整数转换而来，但不保证一定是数字）\ +**版本历史:**\ +3.5.0 - 添加 + +### `accounts` {#accounts} + +**描述:** 你关注的，并且也关注了这个账户的其他账户。\ +**类型:** [Account]({{< relref "entities/Account" >}}) 数组\ +**版本历史:**\ +3.5.0 - 添加 + +## 另请参阅 + +{{< page-relref ref="methods/accounts#familiar_followers" caption="GET /api/v1/accounts/:id/familiar_followers" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/familiar_followers_serializer.rb" caption="app/serializers/rest/familiar_followers_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="FamiliarFollowers" raw_link="/entities/FamiliarFollowers/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/FeaturedTag.md b/content/zh-cn/entities/FeaturedTag.md new file mode 100644 index 0000000..c7a7305 --- /dev/null +++ b/content/zh-cn/entities/FeaturedTag.md @@ -0,0 +1,70 @@ +--- +title: FeaturedTag +description: 表示账户上显示的精选话题标签。 +menu: + docs: + parent: entities +aliases: [ + "/entities/featuredtag", + "/entities/FeaturedTag", + "/api/entities/featuredtag", + "/api/entities/FeaturedTag", +] +--- + +## 示例 + +```json +{ + "id": "627", + "name": "nowplaying", + "url": "https://mastodon.social/@trwnh/tagged/nowplaying", + "statuses_count": "70", + "last_status_at": "2022-08-29" +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 精选话题标签在数据库中的内部 ID。\ +**类型:** 字符串（从整数转换而来，但不保证一定是数字）\ +**版本历史:**\ +3.0.0 - 添加 + +### `name` {#name} + +**描述:** 精选话题标签的名称。\ +**类型:** 字符串\ +**版本历史:**\ +3.0.0 - 添加 + +### `url` {#url} + +**描述:** 指向用户包含此话题标签的所有嘟文的链接。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +3.3.0 - 添加 + +### `statuses_count` {#statuses_count} + +**描述:** 包含此话题标签的已发布嘟文的数量。\ +**类型:** 字符串\ +**版本历史:**\ +3.0.0 - 添加 + +### `last_status_at` {#last_status_at} + +**描述:** 包含此话题标签的最新发布嘟文的日期。\ +**类型:** 字符串 ([Date](/api/datetime-format#date))\ +**版本历史:**\ +3.0.0 - 添加 + +## 另请参阅 + +{{< page-relref ref="methods/featured_tags" caption="featured_tags API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/featured_tag_serializer.rb" caption="app/serializers/rest/featured_tag_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="FeaturedTag" raw_link="/entities/FeaturedTag/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Filter.md b/content/zh-cn/entities/Filter.md new file mode 100644 index 0000000..35691f7 --- /dev/null +++ b/content/zh-cn/entities/Filter.md @@ -0,0 +1,112 @@ +--- +title: Filter +description: 表示用户定义的过滤规则，用于确定哪些嘟文不应向用户显示。 +menu: + docs: + parent: entities +aliases: [ + "/entities/filter", + "/entities/Filter", + "/api/entities/filter", + "/api/entities/Filter", +] +--- + +## 示例 + +```json +{ + "id": "19972", + "title": "Test filter", + "context": [ + "home" + ], + "expires_at": "2022-09-20T17:27:39.296Z", + "filter_action": "warn", + "keywords": [ + { + "id": "1197", + "keyword": "bad word", + "whole_word": false + } + ], + "statuses": [ + { + "id": "1", + "status_id": "109031743575371913" + } + ] +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 数据库中过滤规则的 ID。\ +**类型:** 字符串 (从整数强制转换，但不保证一定是数字)\ +**版本历史:**\ +4.0.0 - 添加 + +### `title` {#title} + +**描述:** 用户为过滤规则指定的标题。\ +**类型:** 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `context` {#context} + +**描述:** 过滤规则的应用到场景。\ +**类型:** 字符串数组 (可枚举，anyOf)\ +`home` = 首页时间线和列表\ +`notifications` = 通知时间线\ +`public` = 公共时间线\ +`thread` = 展开的嘟文串\ +`account` = 查看账户时\ +**版本历史:**\ +4.0.0 - 添加 + +### `expires_at` {#expires_at} + +**描述:** 过滤规则何时不再生效。\ +**类型:** {{}} 字符串 ([Datetime](/api/datetime-format#datetime))，如果过滤规则永不过期，则为 null\ +**版本历史:**\ +4.0.0 - 添加 + +### `filter_action` {#filter_action} + +**描述:** 当嘟文与此过滤规则匹配时要采取的操作。\ +**类型:** 字符串 (可枚举，oneOf)\ +`warn` = 显示警告，警告内容为命中的过滤规则的标题，并允许用户展开被过滤的嘟文。这是默认值（并且未知值应被视为等同于“warn”）。\ +`hide` = 如果匹配到对应的嘟文，则不显示\ +`blur` = 隐藏/模糊媒体附件，并显示警告，警告内容为命中的过滤规则的标题 +**版本历史:**\ +4.0.0 - 添加\ +4.4.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 5) - 将 `blur` 值添加到 `filter_action` 属性 + +### `keywords` {#keywords} + +**描述:** 此过滤规则下的关键词。\ +**类型:** [FilterKeyword]({{< relref "entities/FilterKeyword" >}}) 数组\ +**版本历史:**\ +4.0.0 - 添加 + +### `statuses` {#statuses} + +**描述:** 此过滤规则下的嘟文。\ +**类型:** [FilterStatus]({{< relref "entities/FilterStatus" >}}) 数组\ +**版本历史:**\ +4.0.0 - 添加 + +## 参见 + +{{< page-relref ref="api/guidelines#filters" caption="过滤的实现指引" >}} + +{{< page-relref ref="entities/V1_Filter" caption="V1::Filter（适用于 Mastodon 3.5 及更早版本）" >}} + +{{< page-relref ref="methods/filters" caption="/api/v2/filters 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/filter_serializer.rb" caption="app/serializers/rest/filter_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Filter" raw_link="/entities/Filter/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/FilterKeyword.md b/content/zh-cn/entities/FilterKeyword.md new file mode 100644 index 0000000..ec6172e --- /dev/null +++ b/content/zh-cn/entities/FilterKeyword.md @@ -0,0 +1,56 @@ +--- +title: FilterKeyword +description: 表示一个关键词，如果匹配，则应采取过滤规则操作。 +menu: + docs: + parent: entities +aliases: [ + "/entities/filterkeyword", + "/entities/FilterKeyword", + "/api/entities/filterkeyword", + "/api/entities/FilterKeyword", +] +--- + +## 示例 + +```json +{ + "id": "1197", + "keyword": "bad word", + "whole_word": false +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 数据库中 FilterKeyword 的 ID。\ +**类型:** 字符串 (从整数转换而来，但不保证一定为数字)\ +**版本历史:**\ +4.0.0 - 添加 + +### `keyword` {#keyword} + +**描述:** 要匹配的短语。\ +**类型:** 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `whole_word` {#whole_word} + +**描述:** 过滤规则是否应考虑单词边界？ 请参阅[过滤规则实现指引]({{< relref "api/guidelines#filters" >}})。\ +**类型:** 布尔值\ +**版本历史:**\ +4.0.0 - 添加 + +## 参见 + +{{< page-relref ref="api/guidelines#filters" caption="过滤规则实现指引" >}} + +{{< page-relref ref="methods/filters" caption="/api/v2/filters 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/filter_keyword_serializer.rb" caption="app/serializers/rest/filter_keyword_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="FilterKeyword" raw_link="/entities/FilterKeyword/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/FilterResult.md b/content/zh-cn/entities/FilterResult.md new file mode 100644 index 0000000..93643aa --- /dev/null +++ b/content/zh-cn/entities/FilterResult.md @@ -0,0 +1,68 @@ +--- +title: FilterResult +description: 表示关键词与给定嘟文匹配的过滤规则。 +menu: + docs: + parent: entities +aliases: [ + "/entities/filterresult", + "/entities/FilterResult", + "/api/entities/filterresult", + "/api/entities/FilterResult", +] +--- + +## 示例 + +```json +{ + "filter": { + "id": "3", + "title": "Hide completely", + "context": [ + "home" + ], + "expires_at": "2022-09-20T17:27:39.296Z", + "filter_action": "hide" + }, + "keyword_matches": [ + "bad word" + ], + "status_matches": [ + "109031743575371913" + ] +} +``` + +## 属性 + +### `filter` {#filter} + +**描述:** 命中的过滤规则。\ +**类型:** [Filter]({{< relref "entities/Filter" >}})\ +**版本历史:**\ +4.0.0 - 添加 + +### `keyword_matches` {#keyword_matches} + +**描述:** 过滤规则中命中的关键词。\ +**类型:** {{}} 字符串数组，或 null\ +**版本历史:**\ +4.0.0 - 添加 + +### `status_matches` {#status_matches} + +**描述:** 过滤规则中命中的嘟文 ID。\ +**类型:** {{}} 字符串数组，或 null\ +**版本历史:**\ +4.0.0 - 添加 + +## 参见 + +{{< page-relref ref="api/guidelines#filters" caption="过滤规则实现指引" >}} + +{{< page-relref ref="methods/filters" caption="/api/v2/filters 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/filter_result_serializer.rb" caption="app/serializers/rest/filter_result_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="FilterResult" raw_link="/entities/FilterResult/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/FilterStatus.md b/content/zh-cn/entities/FilterStatus.md new file mode 100644 index 0000000..32d830a --- /dev/null +++ b/content/zh-cn/entities/FilterStatus.md @@ -0,0 +1,48 @@ +--- +title: FilterStatus +description: 表示一条嘟文 ID，如果匹配，则应采取过滤规则操作。 +menu: + docs: + parent: entities +aliases: [ + "/entities/filterstatus", + "/entities/FilterStatus", + "/api/entities/filterstatus", + "/api/entities/FilterStatus", +] +--- + +## 示例 + +```json +{ + "id": "1", + "status_id": "109031743575371913" +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 数据库中 FilterStatus 的 ID。\ +**类型:** 字符串（从整数转换而来，但不保证是一个数字）\ +**版本历史:**\ +4.0.0 - 添加 + +### `status_id` {#keyword} + +**描述:** 将被过滤的嘟文的 ID。\ +**类型:** 字符串（从整数转换而来，但不保证是一个数字）\ +**版本历史:**\ +4.0.0 - 添加 + +## 参见 + +{{< page-relref ref="api/guidelines#filters" caption="过滤规则实现指引" >}} + +{{< page-relref ref="methods/filters" caption="/api/v2/filters 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/filter_status_serializer.rb" caption="app/serializers/rest/filter_status_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="FilterStatus" raw_link="/entities/FilterStatus/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/IdentityProof.md b/content/zh-cn/entities/IdentityProof.md new file mode 100644 index 0000000..35de2d6 --- /dev/null +++ b/content/zh-cn/entities/IdentityProof.md @@ -0,0 +1,72 @@ +--- +title: IdentityProof +description: 表示来自外部身份提供者的证明。 +menu: + docs: + parent: entities +aliases: [ + "/entities/identityproof", + "/entities/IdentityProof", + "/api/entities/identityproof", + "/api/entities/IdentityProof", +] +--- + +{{< hint style="danger" >}} +身份证明已在 3.5.0 及更高版本中弃用。 在此之前，唯一受支持的证明提供商是 Keybase，但自从被 Zoom 收购以来，Keybase 的开发已完全停滞。 +{{< /hint >}} + +```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" +} +``` + +## 属性 + +### `provider` {#provider} + +**描述:** 身份提供者的名称。\ +**类型:** 字符串\ +**版本历史:**\ +2.8.0 - 添加 + +### `provider_username` {#provider_username} + +**描述:** 帐户所有者在身份提供者服务上的用户名。\ +**类型:** 字符串\ +**版本历史:**\ +2.8.0 - 添加 + +### `updated_at` {#updated_at} + +**描述:** 身份证明最近一次更新的时间。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +2.8.0 - 添加 + +### `proof_url` {#proof_url} + +**描述:** 指向身份证明声明的链接，由身份提供商托管。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +2.8.0 - 添加 + +### `profile_url` {#profile_url} + +**描述:** 帐户所有者在身份提供者上的账户 URL。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +2.8.0 - 添加 + +## 另请参考 + +{{< page-relref ref="methods/accounts#identity_proofs" caption="GET /api/v1/accounts/:id/identity_proofs" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/pull/17045" caption="Remove Keybase integration (#17045)" >}} + +{{< translation-status-zh-cn raw_title="IdentityProof" raw_link="/entities/IdentityProof/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Instance.md b/content/zh-cn/entities/Instance.md new file mode 100644 index 0000000..14fc947 --- /dev/null +++ b/content/zh-cn/entities/Instance.md @@ -0,0 +1,594 @@ +--- +title: Instance +description: 表示在此域名上运行的 Mastodon 实例。 +menu: + docs: + parent: entities +aliases: [ + "/entities/instance", + "/entities/Instance", + "/api/entities/instance", + "/api/entities/Instance", +] +--- + +## 示例 + +```json +{ + "domain": "mastodon.social", + "title": "Mastodon", + "version": "4.0.0rc1", + "source_url": "https://github.com/mastodon/mastodon", + "description": "The original server operated by the Mastodon gGmbH non-profit", + "usage": { + "users": { + "active_month": 123122 + } + }, + "thumbnail": { + "url": "https://files.mastodon.social/site_uploads/files/000/000/001/@1x/57c12f441d083cde.png", + "blurhash": "UeKUpFxuo~R%0nW;WCnhF6RjaJt757oJodS$", + "versions": { + "@1x": "https://files.mastodon.social/site_uploads/files/000/000/001/@1x/57c12f441d083cde.png", + "@2x": "https://files.mastodon.social/site_uploads/files/000/000/001/@2x/57c12f441d083cde.png" + } + }, + "icon": [ + { + "src": "https://files.mastodon.social/site_uploads/files/000/000/003/36/accf17b0104f18e5.png", + "size": "36x36" + }, + { + "src": "https://files.mastodon.social/site_uploads/files/000/000/003/72/accf17b0104f18e5.png", + "size": "72x72" + }, + { + "src": "https://files.mastodon.social/site_uploads/files/000/000/003/192/accf17b0104f18e5.png", + "size": "192x192" + }, + { + "src": "https://files.mastodon.social/site_uploads/files/000/000/003/512/accf17b0104f18e5.png", + "size": "512x512" + } + ], + "languages": [ + "en" + ], + "configuration": { + "urls": { + "streaming": "wss://mastodon.social" + }, + "vapid": { + "public_key": "BCkMmVdKDnKYwzVCDC99Iuc9GvId-x7-kKtuHnLgfF98ENiZp_aj-UNthbCdI70DqN1zUVis-x0Wrot2sBagkMc=" + }, + "accounts": { + "max_featured_tags": 10, + "max_pinned_statuses": 4 + }, + "statuses": { + "max_characters": 500, + "max_media_attachments": 4, + "characters_reserved_per_url": 23 + }, + "media_attachments": { + "supported_mime_types": [ + "image/jpeg", + "image/png", + "image/gif", + "image/heic", + "image/heif", + "image/webp", + "video/webm", + "video/mp4", + "video/quicktime", + "video/ogg", + "audio/wave", + "audio/wav", + "audio/x-wav", + "audio/x-pn-wave", + "audio/vnd.wave", + "audio/ogg", + "audio/vorbis", + "audio/mpeg", + "audio/mp3", + "audio/webm", + "audio/flac", + "audio/aac", + "audio/m4a", + "audio/x-m4a", + "audio/mp4", + "audio/3gpp", + "video/x-ms-asf" + ], + "description_limit": 1500, + "image_size_limit": 10485760, + "image_matrix_limit": 16777216, + "video_size_limit": 41943040, + "video_frame_rate_limit": 60, + "video_matrix_limit": 2304000 + }, + "polls": { + "max_options": 4, + "max_characters_per_option": 50, + "min_expiration": 300, + "max_expiration": 2629746 + }, + "translation": { + "enabled": true + } + }, + "registrations": { + "enabled": false, + "approval_required": false, + "reason_required": false, + "message": null, + "min_age": 16 + }, + "api_versions": { + "mastodon": 1, + }, + "contact": { + "email": "staff@mastodon.social", + "account": { + "id": "1", + "username": "Gargron", + "acct": "Gargron", + "display_name": "Eugen 💀", + "locked": false, + "bot": false, + "discoverable": true, + "group": false, + "created_at": "2016-03-16T00:00:00.000Z", + "note": "

Founder, CEO and lead developer @Mastodon, Germany.

", + "url": "https://mastodon.social/@Gargron", + "avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", + "avatar_static": "https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", + "header": "https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", + "header_static": "https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", + "followers_count": 133026, + "following_count": 311, + "statuses_count": 72605, + "last_status_at": "2022-10-31", + "noindex": false, + "emojis": [], + "fields": [ + { + "name": "Patreon", + "value": "https://www.patreon.com/mastodon", + "verified_at": null + } + ] + } + }, + "rules": [ + { + "id": "1", + "text": "Sexually explicit or violent media must be marked as sensitive when posting" + }, + { + "id": "2", + "text": "No racism, sexism, homophobia, transphobia, xenophobia, or casteism" + }, + { + "id": "3", + "text": "No incitement of violence or promotion of violent ideologies" + }, + { + "id": "4", + "text": "No harassment, dogpiling or doxxing of other users" + }, + { + "id": "5", + "text": "No content illegal in Germany" + }, + { + "id": "7", + "text": "Do not share intentionally false or misleading information" + } + ] +} +``` + +## 属性 + +### `domain` {#domain} + +**描述:** 实例的域名。\ +**类型:** 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `title` {#title} + +**描述:** 站点的标题。\ +**类型:** 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `version` {#version} + +**描述:** 实例上安装的 Mastodon 版本。\ +**类型:** 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `source_url` {#source_url} + +**描述:** 根据 AGPL 许可要求，运行在此实例上的软件的源代码的 URL。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +4.0.0 - 添加 + +### `description` {#description} + +**描述:** 管理员定义的简短纯文本描述。\ +**类型:** 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `usage` {#usage} + +**描述:** 此实例的使用数据。\ +**类型:** Hash\ +**版本历史:**\ +4.0.0 - 添加 + +#### `usage[users]` {#users} + +**描述:** 与此实例上的用户相关的使用数据。\ +**类型:** Hash\ +**版本历史:**\ +4.0.0 - 添加 + +##### `usage[users][active_month]` {#active_month} + +**描述:** 过去 4 周内的活跃用户数。\ +**类型:** 整数\ +**版本历史:**\ +4.0.0 - 添加 + +### `thumbnail` {#thumbnail} + +**描述:** 用于表示此实例的图像。\ +**类型:** Hash\ +**版本历史:**\ +4.0.0 - 添加 + +#### `thumbnail[url]` {#thumbnail-url} + +**描述:** 缩略图图像的 URL。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +4.0.0 - 添加 + +#### `thumbnail[blurhash]` {{}} {#blurhash} + +**描述:** 一种由 [BlurHash 算法](https://github.com/woltapp/blurhash) 计算出的哈希值，用于在媒体尚未下载时生成彩色预览缩略图。\ +**类型:** 字符串 (Blurhash)\ +**版本历史:**\ +4.0.0 - 添加 + +#### `thumbnail[versions]` {{}} {#thumbnail-versions} + +**描述:** 指向缩放分辨率图像的链接，适用于高 DPI 屏幕。\ +**类型:** Hash\ +**版本历史:**\ +4.0.0 - 添加 + +##### `thumbnail[versions][@1x]` {{}} {#1x} + +**描述:** 1x 分辨率的缩略图图像的 URL。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +4.0.0 - 添加 + +##### `thumbnail[versions][@2x]` {{}} {#2x} + +**描述:** 2x 分辨率的缩略图图像的 URL。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +4.0.0 - 添加 + +### `icon` {#icon} + +**描述:** 为此实例配置的图标的可用尺寸变体的列表。\ +**类型:** [InstanceIcon](#InstanceIcon) 数组\ +**版本历史:**\ +4.3.0 - 添加 + +### `languages` {#languages} + +**描述:** 网站及其工作人员的主要语言。\ +**类型:** 字符串 (ISO 639-1 双字符代码) 数组\ +**版本历史:**\ +4.0.0 - 添加 + +### `configuration` {#configuration} + +**描述:** 此网站的配置值和限制。\ +**类型:** Hash\ +**版本历史:**\ +4.0.0 - 添加 + +#### `configuration[urls]` {#urls} + +**描述:** 客户端应用感兴趣的 URL。\ +**类型:** Hash\ +**版本历史:**\ +4.0.0 - 添加 + +##### `configuration[urls][streaming]` {#streaming} + +**描述:** 用于连接到流式 API 的 Websockets URL。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +4.0.0 - 添加 + +### `configuration[vapid][public_key]` {#vapid_public_key} +**描述:** 实例的 VAPID 公钥，用于推送通知，与 [WebPushSubscription#server_key]({{< relref "entities/WebPushSubscription#server_key" >}}) 相同。\ +**类型:** 字符串\ +**版本历史:**\ +4.3.0 - 添加 + +#### `configuration[accounts]` {#accounts} + +**描述:** 与帐户相关的限制。\ +**类型:** Hash\ +**版本历史:**\ +4.0.0 - 添加 + +##### `configuration[accounts][max_featured_tags]` {#max_featured_tags} + +**描述:** 每个帐户允许的最大精选话题标签数。\ +**类型:** 整数\ +**版本历史:**\ +4.0.0 - 添加 + +##### `configuration[accounts][max_pinned_statuses]` {#max_pinned_statuses} + +**描述:** 每个帐户允许的最大置顶嘟文数。\ +**类型:** 整数\ +**版本历史:**\ +4.3.0 - 添加 + +#### `configuration[statuses]` {#statuses} + +**描述:** 与撰写嘟文相关的限制。\ +**类型:** Hash\ +**版本历史:**\ +4.0.0 - 添加 + +##### `configuration[statuses][max_characters]` {#max_characters} + +**描述:** 每条嘟文允许的最大字符数。\ +**类型:** 整数\ +**版本历史:**\ +4.0.0 - 添加 + +##### `configuration[statuses][max_media_attachments]` {#max_media_attachments} + +**描述:** 可以添加到嘟文的最大媒体附件数。\ +**类型:** 整数\ +**版本历史:**\ +4.0.0 - 添加 + +##### `configuration[statuses][characters_reserved_per_url]` {#characters_reserved_per_url} + +**描述:** 嘟文中的每个 URL 将被假定为占用的字符数。\ +**类型:** 整数\ +**版本历史:**\ +4.0.0 - 添加 + +#### `configuration[media_attachments]` {#media_attachments} + +**描述:** 有关将接受哪些附件的提示。\ +**类型:** Hash\ +**版本历史:**\ +4.0.0 - 添加 + +##### `configuration[media_attachments][supported_mime_types]` {#supported_mime_types} + +**描述:** 包含可以上传的 MIME 类型。\ +**类型:** 字符串数组\ +**版本历史:**\ +4.0.0 - 添加 + +##### `configuration[media_attachments][description_limit]` {#description_limit} + +**描述:** 描述的最大大小（以字符为单位）。\ +**类型:** 整数\ +**版本历史:**\ +4.4.0 - 添加 + +##### `configuration[media_attachments][image_size_limit]` {#image_size_limit} + +**描述:** 任何上传图像的最大大小（以字节为单位）。\ +**类型:** 整数\ +**版本历史:**\ +4.0.0 - 添加 + +##### `configuration[media_attachments][image_matrix_limit]` {#image_matrix_limit} + +**描述:** 图像上传的最大像素数（宽度乘以高度）。\ +**类型:** 整数\ +**版本历史:**\ +4.0.0 - 添加 + +##### `configuration[media_attachments][video_size_limit]` {#video_size_limit} + +**描述:** 任何上传视频的最大大小（以字节为单位）。\ +**类型:** 整数\ +**版本历史:**\ +4.0.0 - 添加 + +##### `configuration[media_attachments][video_frame_rate_limit]` {#video_frame_rate_limit} + +**描述:** 任何上传视频的最大帧速率。\ +**类型:** 整数\ +**版本历史:**\ +4.0.0 - 添加 + +##### `configuration[media_attachments][video_matrix_limit]` {#video_matrix_limit} + +**描述:** 视频上传的最大像素数（宽度乘以高度）。\ +**类型:** 整数\ +**版本历史:**\ +4.0.0 - 添加 + +#### `configuration[polls]` {#polls} + +**描述:** 与投票相关的限制。\ +**类型:** Hash\ +**版本历史:**\ +4.0.0 - 添加 + +##### `configuration[polls][max_options]` {#max_options} + +**描述:** 每个投票最多允许的选项数。\ +**类型:** 整数\ +**版本历史:**\ +4.0.0 - 添加 + +##### `configuration[polls][max_characters_per_option]` {#max_characters_per_option} + +**描述:** 每个投票选项允许的字符数。\ +**类型:** 整数\ +**版本历史:**\ +4.0.0 - 添加 + +##### `configuration[polls][min_expiration]` {#min_expiration} + +**描述:** 允许的最短投票持续时间（以秒为单位）。\ +**类型:** 整数\ +**版本历史:**\ +4.0.0 - 添加 + +##### `configuration[polls][max_expiration]` {#max_expiration} + +**描述:** 允许的最长投票持续时间（以秒为单位）。\ +**类型:** 整数\ +**版本历史:**\ +4.0.0 - 添加 + +#### `configuration[translation]` {#translation} + +**描述:** 与翻译相关的提示。\ +**类型:** Hash\ +**版本历史:**\ +4.0.0 - 添加 + +##### `configuration[translation][enabled]` {#translation-enabled} + +**描述:** 此实例是否提供 Translations API。\ +**类型:** 布尔值\ +**版本历史:**\ +4.0.0 - 添加 + +### `registrations` + +**描述:** 有关注册此网站的信息。\ +**类型:** Hash\ +**版本历史:**\ +4.0.0 - 添加 + +#### `registrations[enabled]` {#registrations-enabled} + +**描述:** 是否启用注册。\ +**类型:** 布尔值\ +**版本历史:**\ +4.0.0 - 添加 + +#### `registrations[approval_required]` {#approval_required} + +**描述:** 注册是否需要管理员批准。\ +**类型:** 布尔值\ +**版本历史:**\ +4.0.0 - 添加 + +#### `registrations[message]` {#registrations-message} + +**描述:** 注册关闭时显示的自定义消息。\ +**类型:** {{}} 字符串 (HTML) or null\ +**版本历史:**\ +4.0.0 - 添加 + +#### `registrations[min_age]` {#registrations-min_age} + +**描述:** 若配置，则为注册所需的最小年龄。\ +**类型:** {{}} 整数或 null\ +**版本历史:**\ +4.4.0 - 添加 + +#### `registrations[reason_required]` {#registrations-reason_required} + +**描述:** 注册是否需要用户提供加入理由。仅当 `registrations[approval_required]` 为 true 时适用。\ +**类型:** {{}} 布尔值\ +**版本历史:**\ +4.4.0 - 添加 + +### `api_versions` {#api-versions} + +**描述:** 有关此实例实现的 API 版本的信息。它至少包含一个 `mastodon` 属性，其他实现可能具有自己的附加属性。\ +**类型:** Hash\ +**版本历史:**\ +4.3.0 - 添加 + +### `api_versions[mastodon]` + +**描述:** 此实例实现的 API 版本号。 从 Mastodon v4.3.0 开始，API 更改将附带一个版本号，客户端可以根据此值进行检查。\ +**类型:** 整数\ +**版本历史:**\ +4.3.0 - 添加 + +### `contact` {#contact} + +**描述:** 与联系网站代表相关的提示。\ +**类型:** Hash\ +**版本历史:**\ +4.0.0 - 添加 + +#### `contact[email]` {#contact-email} + +**描述:** 可以发送消息以询问或举报问题的电子邮件地址。\ +**类型:** 字符串 (Email)\ +**版本历史:**\ +4.0.0 - 添加 + +#### `contact[account]` {#contact-account} + +**描述:** 可以通过网络联系以询问或举报问题的帐户。\ +**类型:** {{}} [Account]({{< relref "entities/Account" >}}) or null\ +**版本历史:**\ +4.0.0 - 添加 + +### `rules` {#rules} + +**描述:** 此网站的规则的详细列表。\ +**类型:** [Rule]({{< relref "entities/Rule" >}}) 数组\ +**版本历史:**\ +4.0.0 - 添加 + +## InstanceIcon 属性 {#InstanceIcon} + +### `src` {#src} + +**描述:** 此图标的 URL。\ +**类型:** 字符串\ +**版本历史:**\ +4.3.0 - 添加 + +### `size` {#size} + +**描述:** 此图标的大小。\ +**类型:** 字符串 (格式形如 `12x34`, 其中 `12` 是图标宽度，`34` 是图标高度)\ +**版本历史:**\ +4.3.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/instance#v2" caption="GET /api/v2/instance" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/instance_serializer.rb" caption="app/serializers/rest/instance_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Instance" raw_link="/entities/Instance/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/List.md b/content/zh-cn/entities/List.md new file mode 100644 index 0000000..c3fc10c --- /dev/null +++ b/content/zh-cn/entities/List.md @@ -0,0 +1,58 @@ +--- +title: List +description: 表示用户所关注的一些用户的列表。 +menu: + docs: + parent: entities +aliases: [ + "/entities/list", + "/entities/List", + "/api/entities/list", + "/api/entities/List", +] +--- + +## 示例 + +```json +{ + "id": "12249", + "title": "Friends" +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 列表的内部数据库 ID。\ +**类型:** 字符串（从整数转换而来，但不保证是一个数字）\ +**版本历史:**\ +2.1.0 - 添加 + +### `title` {#title} + +**描述:** 用户自定义的列表标题。\ +**类型:** 字符串\ +**版本历史:**\ +2.1.0 - 添加 + +### `replies_policy` {#replies_policy} + +**描述:** 应在列表中显示哪些回复。\ +**类型:** 字符串（可枚举的 oneOf）\ +`followed` = 显示对任何已关注用户的回复\ +`list` = 显示对列表成员的回复\ +`none` = 不显示对任何人的回复\ +**版本历史:**\ +3.3.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/accounts#lists" caption="GET /api/v1/accounts/:id/lists" >}} + +{{< page-relref ref="methods/lists" caption="lists API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/list_serializer.rb" caption="app/serializers/rest/list_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="List" raw_link="/entities/List/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Marker.md b/content/zh-cn/entities/Marker.md new file mode 100644 index 0000000..8916d30 --- /dev/null +++ b/content/zh-cn/entities/Marker.md @@ -0,0 +1,52 @@ +--- +title: Marker +description: 表示用户在时间线中最后阅读的位置。 +menu: + docs: + parent: entities +aliases: [ + "/entities/marker", + "/entities/Marker", + "/api/entities/marker", + "/api/entities/Marker", +] +--- + +## 示例 + +```json +{ + "last_read_id": "103194548672408537", + "version": 462, + "updated_at": "2019-11-24T19:39:39.337Z" +} +``` + +## 属性 + +### `last_read_id` {#last_read_id} + +**描述:** 最近查看的实体的 ID。\ +**类型:** 字符串（从整数转换而来，但不保证一定是数字）\ +3.0.0 - 添加 + +### `version` {#version} + +**描述:** 一个递增的计数器，用于锁定以防止写冲突。\ +**类型:** 整数\ +**版本历史:**\ +3.0.0 - 添加 + +### `updated_at` {#updated_at} + +**描述:** 标记被设置的时间戳。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +3.0.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/markers" caption="markers API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/marker_serializer.rb" caption="app/serializers/rest/marker_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Marker" raw_link="/entities/Marker/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/MediaAttachment.md b/content/zh-cn/entities/MediaAttachment.md new file mode 100644 index 0000000..571572a --- /dev/null +++ b/content/zh-cn/entities/MediaAttachment.md @@ -0,0 +1,242 @@ +--- +title: MediaAttachment +description: 表示可以被添加到嘟文的的文件或媒体附件。 +menu: + docs: + parent: entities +aliases: [ + "/entities/attachment", + "/entities/Attachment", + "/entities/mediaattachment", + "/entities/MediaAttachment", + "/api/entities/attachment", + "/api/entities/Attachment", + "/api/entities/mediaattachment", + "/api/entities/MediaAttachment", +] +--- + +## 示例 + +### 图像 + +```json +{ + "id": "22345792", + "type": "image", + "url": "https://files.mastodon.social/media_attachments/files/022/345/792/original/57859aede991da25.jpeg", + "preview_url": "https://files.mastodon.social/media_attachments/files/022/345/792/small/57859aede991da25.jpeg", + "remote_url": null, + "text_url": "https://mastodon.social/media/2N4uvkuUtPVrkZGysms", + "meta": { + "original": { + "width": 640, + "height": 480, + "size": "640x480", + "aspect": 1.3333333333333333 + }, + "small": { + "width": 461, + "height": 346, + "size": "461x346", + "aspect": 1.3323699421965318 + }, + "focus": { + "x": -0.27, + "y": 0.51 + } + }, + "description": "测试媒体描述文本", + "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}" +} +``` + +### 视频 + +```json +{ + "id": "22546306", + "type": "video", + "url": "https://files.mastodon.social/media_attachments/files/022/546/306/original/dab9a597f68b9745.mp4", + "preview_url": "https://files.mastodon.social/media_attachments/files/022/546/306/small/dab9a597f68b9745.png", + "remote_url": null, + "text_url": "https://mastodon.social/media/wWd1HJIBmH1MZGDfg50", + "meta": { + "length": "0:01:28.65", + "duration": 88.65, + "fps": 24, + "size": "1280x720", + "width": 1280, + "height": 720, + "aspect": 1.7777777777777777, + "audio_encode": "aac (LC) (mp4a / 0x6134706D)", + "audio_bitrate": "44100 Hz", + "audio_channels": "stereo", + "original": { + "width": 1280, + "height": 720, + "frame_rate": "6159375/249269", + "duration": 88.654, + "bitrate": 862056 + }, + "small": { + "width": 400, + "height": 225, + "size": "400x225", + "aspect": 1.7777777777777777 + } + }, + "description": null, + "blurhash": "U58E0g8_0M.94T?bIr00?bD%NGoM?bD%oLt7" +} +``` + +### GIFV + +```json +{ + "id": "21130559", + "type": "gifv", + "url": "https://files.mastodon.social/media_attachments/files/021/130/559/original/bc84838f77991326.mp4", + "preview_url": "https://files.mastodon.social/media_attachments/files/021/130/559/small/bc84838f77991326.png", + "remote_url": null, + "text_url": "https://mastodon.social/media/2ICiasGyjezmi7cQYM8", + "meta": { + "length": "0:00:01.11", + "duration": 1.11, + "fps": 33, + "size": "600x332", + "width": 600, + "height": 332, + "aspect": 1.8072289156626506, + "original": { + "width": 600, + "height": 332, + "frame_rate": "100/3", + "duration": 1.11, + "bitrate": 1627639 + }, + "small": { + "width": 400, + "height": 221, + "size": "400x221", + "aspect": 1.8099547511312217 + } + }, + "description": null, + "blurhash": "URHT%Jm,2a1d%MRO%LozkrNH$*n*oMn$Rjt7" +} +``` + +### 音频 + +```json +{ + "id": "21165404", + "type": "audio", + "url": "https://files.mastodon.social/media_attachments/files/021/165/404/original/a31a4a46cd713cd2.mp3", + "preview_url": "https://files.mastodon.social/media_attachments/files/021/165/404/small/a31a4a46cd713cd2.mp3", + "remote_url": null, + "text_url": "https://mastodon.social/media/5O4uILClVqBWx0NNgvo", + "meta": { + "length": "0:06:42.86", + "duration": 402.86, + "audio_encode": "mp3", + "audio_bitrate": "44100 Hz", + "audio_channels": "stereo", + "original": { + "duration": 402.860408, + "bitrate": 166290 + } + }, + "description": null, + "blurhash": null +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 附件在数据库中的 ID。\ +**类型:** 字符串 (从整数转换而来，但不保证为数字)\ +**版本历史:**\ +0.6.0 - 添加 + +### `type` {#type} + +**描述:** 附件的类型。\ +**类型:** 字符串 (可枚举，oneOf)\ +`unknown` = 不支持或无法识别的文件类型\ +`image` = 静态图像\ +`gifv` = 循环播放、无声动画\ +`video` = 视频剪辑\ +`audio` = 音轨\ +**版本历史:**\ +0.6.0 - 添加\ +2.9.1 - 添加 `audio` + +### `url` {#url} + +**描述:** 原始完整尺寸附件的位置。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +0.6.0 - 添加 + +### `preview_url` {#preview_url} + +**描述:** 附件的缩略图的位置。\ +**类型:** {{}} 字符串 (URL)\ +**版本历史:**\ +0.6.0 - 添加 + +### `remote_url` {#remote_url} + +**描述:** 外站的完整尺寸原始附件的位置。\ +**类型:** {{}} 字符串 (URL)，如果附件是本站的，则为 null\ +**版本历史:**\ +0.6.0 - 添加 + +### `meta` {#meta} + +**描述:** Paperclip 返回的元数据。\ +**类型:** Hash\ +**版本历史:**\ +1.5.0 - 添加\ +2.3.0 - 添加 `meta.focus` + +可以包含 `small` 和 `original` 子树，及各种其他顶层属性。 + +更重要的是，从 2.3.0 开始，图像上可能还有另一个顶层 `focus` Hash 对象，其坐标可用于智能缩略图裁剪——请参阅[裁剪媒体缩略图的焦点]({{< relref "api/guidelines#focal-points" >}}) 获取更多信息。 + +### `description` {#description} + +**描述:** 用于描述媒体附件内容的替代文本，适用于视障人士或媒体附件未加载时的情况。\ +**类型:** {{}} 字符串，如果未为媒体附件提供替代文本，则为 null\ +**版本历史:**\ +2.0.0 - 添加 + +### `blurhash` {#blurhash} + +**描述:** 由 [BlurHash 算法](https://github.com/woltapp/blurhash) 计算的哈希值，用于在媒体尚未下载时生成彩色预览缩略图。\ +**类型:** {{}} 字符串 (Blurhash)\ +**版本历史:**\ +2.8.1 - 添加 + +### `text_url` {{%removed%}} {#text_url} + +**描述:** 附件的短 URL。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +0.6.0 - 添加\ +3.5.0 - 移除 + +## 参见 + +{{< page-relref ref="entities/Status#media_attachments" caption="Status (`media_attachments` attribute)" >}} + +{{< page-relref ref="methods/media" caption="media API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/media_attachment_serializer.rb" caption="app/serializers/rest/media_attachment_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="MediaAttachment" raw_link="/entities/MediaAttachment/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Notification.md b/content/zh-cn/entities/Notification.md new file mode 100644 index 0000000..b94f511 --- /dev/null +++ b/content/zh-cn/entities/Notification.md @@ -0,0 +1,158 @@ +--- +title: Notification +description: 表示与用户相关的事件通知。 +menu: + docs: + parent: entities +aliases: [ + "/entities/notification", + "/entities/Notification", + "/entities/notification", + "/entities/Notification", +] +--- + +## 属性 + +### `id` {#id} + +**描述:** 数据库中通知的 ID。\ +**类型:** 字符串 (从整数转换而来，但不保证是一个数字)\ +**版本历史:**\ +0.9.9 - 添加 + +### `type` {#type} + +**描述:** 导致通知的事件类型。\ +**类型:** 字符串 (可枚举 oneOf)\ +`mention` = 有人在他们的嘟文中提到了你\ +`status` = 你启用了发嘟通知的用户发布了嘟文\ +`reblog` = 有人转发了你的一条嘟文\ +`follow` = 有人关注了你\ +`follow_request` = 有人请求关注你\ +`favourite` = 有人喜欢了你的一条嘟文\ +`poll` = 你投票或创建的投票已结束\ +`update` = 你转发的嘟文已被编辑\ +`admin.sign_up` = 有人注册了（可选择发送给管理员）\ +`admin.report` = 有新的举报被提交\ +`severed_relationships` = 由于管理或屏蔽事件，你的一些关注关系已被切断\ +`moderation_warning` = 管理员已对你的帐户采取了行动或向你发送了警告\ +**版本历史:**\ +0.9.9 - 添加\ +2.8.0 - 添加 `poll`\ +3.1.0 - 添加 `follow_request`\ +3.3.0 - 添加 `status`\ +3.5.0 - 添加 `update` and `admin.sign_up`\ +4.0.0 - 添加 `admin.report`\ +4.3.0 - 添加 `severed_relationships` and `moderation_warning` + +### `group_key` {#group_key} + +**描述:** 类似通知共享的群组键，用于分组通知功能。应被视为不透明，但可以假定未分组的通知具有 `group_key` 形式 `ungrouped-{notification_id}`。 +**类型:** 字符串\ +**版本历史:**\ +4.3.0 - 添加 + +### `created_at` {#created_at} + +**描述:** 通知的时间戳。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +0.9.9 - 添加 + +### `account` {#account} + +**描述:** 执行了生成通知的操作的帐户。\ +**类型:** [Account]({{< relref "entities/Account" >}})\ +**版本历史:**\ +0.9.9 - 添加 + +### `status` {{%optional%}} {#status} + +**描述:** 作为通知对象的嘟文。当通知的 `type` 为 `favourite`、`reblog`、`status`、`mention`、`poll` 或 `update` 时附加。\ +**类型:** [Status]({{< relref "entities/Status" >}})\ +**版本历史:**\ +0.9.9 - 添加 + +### `report` {{%optional%}} {#report} + +**描述:** 作为通知对象的举报。当通知的 `type` 为 `admin.report` 时附加。\ +**类型:** [Report]({{< relref "entities/Report" >}})\ +**版本历史:**\ +4.0.0 - 添加 + +### `event` {{%optional%}} {#relationship_severance_event} + +**描述:** 导致关注关系中断的事件摘要。当通知的 `type` 为 `severed_relationships` 时附加。\ +**类型:** [RelationshipSeveranceEvent]({{< relref "entities/RelationshipSeveranceEvent" >}})\ +**版本历史:**\ +4.3.0 - 添加 + +### `moderation_warning` {{%optional%}} {#moderation_warning} + +**描述:** 导致通知的管理警告。当通知的 `type` 为 `moderation_warning` 时附加。\ +**类型:** [AccountWarning]({{< relref "entities/AccountWarning" >}})\ +**版本历史:**\ +4.3.0 - 添加 + +## 示例 + +### Mention + +```json + + { + "id": "34975861", + "type": "mention", + "created_at": "2019-11-23T07:49:02.064Z", + "account": { + "id": "971724", + "username": "zsc", + "acct": "zsc", + // ... + }, + "status": { + "id": "103186126728896492", + "created_at": "2019-11-23T07:49:01.940Z", + "in_reply_to_id": "103186038209478945", + "in_reply_to_account_id": "14715", + // ... + } + } +``` + +### Favourite + +```json + { + "id": "34975535", + "type": "favourite", + "created_at": "2019-11-23T07:29:18.903Z", + "account": { + "id": "297420", + "username": "haskal", + "acct": "haskal@cybre.space", + // ... + }, + "status": { + "id": "103186046267791694", + "created_at": "2019-11-23T07:28:34.210Z", + // ... + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + // ... + }, + // ... + } + } +``` + +## 另请参考 + +{{< page-relref ref="methods/notifications" caption="notifications API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/notification_serializer.rb" caption="app/serializers/rest/notification_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Notification" raw_link="/entities/Notification/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/NotificationPolicy.md b/content/zh-cn/entities/NotificationPolicy.md new file mode 100644 index 0000000..e4773d5 --- /dev/null +++ b/content/zh-cn/entities/NotificationPolicy.md @@ -0,0 +1,94 @@ +--- +title: NotificationPolicy +description: 表示用户的通知过滤策略。 +menu: + docs: + parent: entities +aliases: [ + "/entities/NotificationPolicy", +] +--- + +## 属性 + +### `for_not_following` {#for_not_following} + +**描述:** 是否 `accept`（接受）、`filter`（过滤）或 `drop`（丢弃）来自用户未关注帐户的通知。`drop` 将完全阻止通知对象的创建（不会阻止底层活动），`filter` 会将其标记为已过滤，而 `accept` 不会影响其处理。\ +**类型:** 字符串 (`accept`, `filter` or `drop` 之一)\ +**版本历史:**\ +4.3.0 - 新增 + +### `for_not_followers` {#for_not_followers} + +**描述:** 是否 `accept`（接受）、`filter`（过滤）或 `drop`（丢弃）来自未关注用户的帐户的通知。`drop` 将完全阻止通知对象的创建（不会阻止底层活动），`filter` 会将其标记为已过滤，而 `accept` 不会影响其处理。\ +**类型:** 字符串 (`accept`, `filter` or `drop` 之一)\ +**版本历史:**\ +4.3.0 - 新增 + +### `for_new_accounts` {#for_new_accounts} + +**描述:** 是否 `accept`（接受）、`filter`（过滤）或 `drop`（丢弃）来自过去 30 天内创建的帐户的通知。`drop` 将完全阻止通知对象的创建（不会阻止底层活动），`filter` 会将其标记为已过滤，而 `accept` 不会影响其处理。\ +**类型:** 字符串 (`accept`, `filter` or `drop` 之一)\ +**版本历史:**\ +4.3.0 - 新增 + +### `for_private_mentions` {#for_private_mentions} + +**描述:** 是否 `accept`（接受）、`filter`（过滤）或 `drop`（丢弃）来自私有提及的通知。`drop` 将完全阻止通知对象的创建（不会阻止底层活动），`filter` 会将其标记为已过滤，而 `accept` 不会影响其处理。对用户发起的私有提及的回复，以及用户关注的帐户，始终被允许，无论此值如何。\ +**类型:** 字符串 (`accept`, `filter` or `drop` 之一)\ +**版本历史:**\ +4.3.0 - 新增 + +### `for_limited_accounts` {#for_limited_accounts} + +**描述:** 是否 `accept`（接受）、`filter`（过滤）或 `drop`（丢弃）来自被管理员限制的帐户的通知。`drop` 将完全阻止通知对象的创建（不会阻止底层活动），`filter` 会将其标记为已过滤，而 `accept` 不会影响其处理。\ +**类型:** 字符串 (`accept`, `filter` or `drop` 之一)\ +**版本历史:**\ +4.3.0 - 新增 + +### `summary` {#summary} + +**描述:** 已过滤通知的摘要。\ +**类型:** Hash\ +**版本历史:**\ +4.3.0 - 新增 + +### `summary[pending_requests_count]` {#pending_requests_count} + +**描述:** 用户收到的过滤后且未处理通知的来源帐户的数量。上限为 100。\ +**类型:** 整数\ +**版本历史:**\ +4.3.0 - 新增 + +### `summary[pending_notifications_count]` {#pending_notifications_count} + +**描述:** 过滤后未处理的通知总数。可能不准确。\ +**类型:** 整数\ +**版本历史:**\ +4.3.0 - 新增 + +## 示例 + +```json + +{ + "for_not_following": "accept", + "for_not_followers": "accept", + "for_new_accounts": "accept", + "for_private_mentions": "drop", + "for_limited_accounts": "filter", + "summary": { + "pending_requests_count": 0, + "pending_notifications_count": 0 + } +} + +``` + +## 另请参考 + +{{< page-relref ref="methods/notifications" caption="notifications API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/notification_policy_serializer.rb" caption="app/serializers/rest/notification_policy_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="NotificationPolicy" raw_link="/entities/NotificationPolicy/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/NotificationRequest.md b/content/zh-cn/entities/NotificationRequest.md new file mode 100644 index 0000000..0b93f90 --- /dev/null +++ b/content/zh-cn/entities/NotificationRequest.md @@ -0,0 +1,106 @@ +--- +title: NotificationRequest +description: 表示来自特定用户的被过滤的通知组。 +menu: + docs: + parent: entities +aliases: [ + "/entities/NotificationRequest", +] +--- + +## 属性 + +### `id` {#id} + +**描述:** 数据库中通知请求的 ID。\ +**类型:** 字符串 (从整数转换而来，但不保证为数字)\ +**版本历史:**\ +4.3.0 - 添加 + +### `created_at` {#created_at} + +**描述:** 通知请求的时间戳，即来自该用户的第一个被过滤的通知的创建时间。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +4.3.0 - 添加 + +### `updated_at` {#updated_at} + +**描述:** 上次更新通知请求的时间戳。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +4.3.0 - 添加 + +### `account` {#account} + +**描述:** 执行了生成过滤通知的操作的帐户。\ +**类型:** [Account]({{< relref "entities/Account" >}})\ +**版本历史:**\ +4.3.0 - 添加 + +### `notifications_count` {#notifications_count} + +**描述:** 此帐户有多少通知被过滤。\ +**类型:** 字符串\ +**版本历史:**\ +4.3.0 - 添加 + +### `last_status` {{%optional%}} {#last_status} + +**描述:** 与该帐户的过滤通知关联的最新嘟文。\ +**类型:** [Status]({{< relref "entities/Status" >}})\ +**版本历史:**\ +4.3.0 - 添加 + +## 示例 + +```json + +{ + "id": "112456967201894256", + "created_at": "2024-05-17T14:45:41.171Z", + "updated_at": "2024-05-17T14:45:41.171Z", + "notifications_count": "1", + "account": { + "id": "971724", + "username": "zsc", + "acct": "zsc", + // ... + }, + "last_status": { + "id": "103186126728896492", + "created_at": "2019-11-23T07:49:01.940Z", + "in_reply_to_id": "103186038209478945", + "in_reply_to_account_id": "14715", + // ... + "content": "

@trwnh sup!

", + // ... + "account": { + "id": "971724", + "username": "zsc", + "acct": "zsc", + // ... + }, + // ... + "mentions": [ + { + "id": "14715", + "username": "trwnh", + "url": "https://mastodon.social/@trwnh", + "acct": "trwnh" + } + ], + // ... + } +} + +``` + +## 另请参阅 + +{{< page-relref ref="methods/notifications" caption="notifications API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/notification_request_serializer.rb" caption="app/serializers/rest/notification_request_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="NotificationRequest" raw_link="/entities/NotificationRequest/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Poll.md b/content/zh-cn/entities/Poll.md new file mode 100644 index 0000000..dd847d8 --- /dev/null +++ b/content/zh-cn/entities/Poll.md @@ -0,0 +1,139 @@ +--- +title: Poll +description: 表示被附加到嘟文的投票。 +menu: + docs: + parent: entities +aliases: [ + "/entities/poll", + "/entities/Poll", + "/api/entities/poll", + "/api/entities/Poll", +] +--- + +## 示例 + +```json +{ + "id": "34830", + "expires_at": "2019-12-05T04:05:08.302Z", + "expired": true, + "multiple": false, + "votes_count": 10, + "voters_count": null, + "voted": true, + "own_votes": [ + 1 + ], + "options": [ + { + "title": "accept", + "votes_count": 6 + }, + { + "title": "deny", + "votes_count": 4 + } + ], + "emojis": [] +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 数据库中投票的ID。\ +**类型:** 字符串（从整数转换而来，但不保证是数字）\ +**版本历史:**\ +2.8.0 - 添加 + +### `expires_at` {#expires_at} + +**描述:** 投票结束的时间。\ +**类型:** {{}} 字符串 ([Datetime](/api/datetime-format#datetime))，如果投票永不结束，则为 null\ +**版本历史:**\ +2.8.0 - 添加 + +### `expired` {#expired} + +**描述:** 投票当前是否已结束？\ +**类型:** 布尔值\ +**版本历史:**\ +2.8.0 - 添加 + +### `multiple` {#multiple} + +**描述:** 投票是否允许多选？\ +**类型:** 布尔值\ +**版本历史:**\ +2.8.0 - 添加 + +### `votes_count` {#votes_count} + +**描述:** 投票收到的票数。\ +**类型:** 整数\ +**版本历史:**\ +2.8.0 - 添加 + +### `voters_count` {#voters_count} + +**描述:** 在一个多选投票中，有多少个独立账户进行了投票。\ +**类型:** {{}} 整数，如果 `multiple` 为 false，则为 null。\ +**版本历史:**\ +2.8.0 - 添加 + +### `options` {#options} + +**描述:** 投票的选项。\ +**类型:** [Poll::Option](#Option) 数组\ +**版本历史:**\ +2.8.0 - 添加 + +### `emojis` {#emojis} + +**描述:** 用于渲染投票选项的自定义表情。\ +**类型:** [CustomEmoji]({{< relref "entities/CustomEmoji" >}}) 数组\ +**版本历史:**\ +2.8.0 - 添加 + +### `voted` {{%optional%}} {#voted} + +**描述:** 当使用用户令牌调用对应的 API 时，该令牌的授权用户是否已投票？\ +**类型:** 布尔值\ +**版本历史:**\ +2.8.0 - 添加 + +### `own_votes` {{%optional%}} {#own_votes} + +**描述:** 当使用用户令牌调用对应的 API 时，该令牌的授权用户选择了哪些选项？ 包含 `options` 的索引值数组。\ +**类型:** 整数数组\ +**版本历史:**\ +2.8.0 - 添加 + +## Poll::Option 属性 {#Option} + +### `title` {#option-title} + +**描述:** 投票选项的文本值。\ +**类型:** 字符串\ +**版本历史:**\ +2.8.0 - 添加 + +#### `votes_count` {#option-votes_count} + +**描述:** 此选项收到的总票数。\ +**类型:** {{}} 整数，如果结果尚未发布，则为 null。\ +**版本历史:**\ +2.8.0 - 添加 + +## 参见 + +{{< page-relref ref="entities/Status#poll" caption="嘟文 (`poll` 属性)" >}} + +{{< page-relref ref="methods/polls" caption="polls API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/poll_serializer.rb" caption="app/serializers/rest/poll_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Poll" raw_link="/entities/Poll/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Preferences.md b/content/zh-cn/entities/Preferences.md new file mode 100644 index 0000000..208bfbd --- /dev/null +++ b/content/zh-cn/entities/Preferences.md @@ -0,0 +1,77 @@ +--- +title: Preferences +description: 表示用户的偏好设置。 +menu: + docs: + parent: entities +aliases: [ + "/entities/preferences", + "/entities/Preferences", + "/api/entities/preferences", + "/api/entities/Preferences", +] +--- + +## 示例 + +```json +{ + "posting:default:visibility": "public", + "posting:default:sensitive": false, + "posting:default:language": null, + "reading:expand:media": "default", + "reading:expand:spoilers": false +} +``` + +## 属性 + +### `posting:default:visibility` {#posting-default-visibility} + +**描述:** 新嘟文的默认可见性。等同于 [CredentialAccount#source\[privacy\]]({{< relref "entities/Account#source-privacy" >}})。\ +**类型:** 字符串 (枚举, 取值之一)\ +`public` = 公开\ +`unlisted` = 悄悄公开\ +`private` = 仅关注者可见\ +`direct` = 私下提及\ +**版本历史:**\ +2.8.0 - 添加 + +### `posting:default:sensitive` {#posting-default-sensitive} + +**描述:** 新嘟文的默认敏感标记。等同于 [CredentialAccount#source\[sensitive\]]({{< relref "entities/Account#source-sensitive" >}})。\ +**类型:** 布尔值\ +**版本历史:**\ +2.8.0 - 添加 + +### `posting:default:language` {#posting-default-language} + +**描述:** 新嘟文的默认语言。等同于 [CredentialAccount#source\[language\]]({{< relref "entities/Account#source-language" >}})\ +**类型:** {{}} 字符串 (ISO 639-1 双字符语言代码), 或 null\ +**版本历史:**\ +2.8.0 - 添加 + +### `reading:expand:media` {#reading-expand-media} + +**描述:** 媒体附件是否应自动显示或模糊/隐藏。\ +**类型:** 字符串 (枚举, 取值之一)\ +`default` = 隐藏标记为敏感的媒体\ +`show_all` = 默认始终显示所有媒体，无论是否敏感\ +`hide_all` = 默认始终隐藏所有媒体，无论是否敏感\ +**版本历史:**\ +2.8.0 - 添加 + +### `reading:expand:spoilers` {#reading-expand-spoilers} + +**描述:** CW(内容警告) 是否应默认展开。\ +**类型:** 布尔值\ +**版本历史:**\ +2.8.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/preferences" caption="preferences API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/preferences_serializer.rb" caption="app/serializers/rest/preferences_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Preferences" raw_link="/entities/Preferences/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/PreviewCard.md b/content/zh-cn/entities/PreviewCard.md new file mode 100644 index 0000000..55a8ab3 --- /dev/null +++ b/content/zh-cn/entities/PreviewCard.md @@ -0,0 +1,294 @@ +--- +title: PreviewCard +description: 表示使用来自 URL 的 OpenGraph 标签生成的富媒体预览卡片。 +menu: + docs: + parent: entities +aliases: [ + "/entities/card", + "/entities/Card", + "/entities/previewcard", + "/entities/PreviewCard", + "/api/entities/card", + "/api/entities/Card", + "/api/entities/previewcard", + "/api/entities/PreviewCard", +] +--- + +## 示例 + +### 视频 + +```json +{ + "url": "https://www.youtube.com/watch?v=OMv_EPMED8Y", + "title": "♪ Brand New Friend (Christmas Song!)", + "description": "", + "type": "video", + "author_name": "YOGSCAST Lewis & Simon", + "author_url": "https://www.youtube.com/user/BlueXephos", + "provider_name": "YouTube", + "provider_url": "https://www.youtube.com/", + "html": "", + "width": 480, + "height": 270, + "image": "https://files.mastodon.social/preview_cards/images/014/179/145/original/9cf4b7cf5567b569.jpeg", + "embed_url": "", + "blurhash": "UvK0HNkV,:s9xBR%njog0fo2W=WBS5ozofV@" +} +``` + +### 图片 + +```json +{ + "url": "https://www.flickr.com/photos/tomfenskephotography/49088768431/", + "title": "Oregon", + "description": "", + "type": "photo", + "author_name": "Tom Fenske Photography", + "author_url": "https://www.flickr.com/photos/tomfenskephotography/", + "provider_name": "Flickr", + "provider_url": "https://www.flickr.com/", + "html": "", + "width": 1024, + "height": 427, + "image": "https://files.mastodon.social/preview_cards/images/014/287/139/original/651b1c6976817824.jpeg", + "embed_url": "https://live.staticflickr.com/65535/49088768431_6a4322b3bb_b.jpg", + "blurhash": "UnE{@jt6M_oIAhjYs+ayT2WBf9ayRkkDXAj[" +} +``` + +### 链接 + +```json +{ + "url": "https://www.theguardian.com/money/2019/dec/07/i-lost-my-193000-inheritance-with-one-wrong-digit-on-my-sort-code", + "title": "‘I lost my £193,000 inheritance – with one wrong digit on my sort code’", + "description": "When Peter Teich’s money went to another Barclays customer, the bank offered £25 as a token gesture", + "type": "link", + "authors": [], + "author_name": "", + "author_url": "", + "provider_name": "", + "provider_url": "", + "html": "", + "width": 0, + "height": 0, + "image": null, + "embed_url": "", + "blurhash": null +} +``` + +## 属性 + +### `url` {#url} + +**描述:** 链接资源的地址。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +1.0.0 - 添加 + +### `title` {#title} + +**描述:** 链接资源的标题。\ +**类型:** 字符串\ +**版本历史:**\ +1.0.0 - 添加 + +### `description` {#description} + +**描述:** 预览的描述。\ +**类型:** 字符串\ +**版本历史:**\ +1.0.0 - 添加 + +### `type` {#type} + +**描述:** 预览卡片的类型。\ +**类型:** 字符串 (可枚举, oneOf)\ +`link` = 链接 OEmbed\ +`photo` = 图片 OEmbed\ +`video` = 视频 OEmbed\ +`rich` = iframe OEmbed。当前不接受，因此实际上不会显示。\ +**版本历史:**\ +1.3.0 - 添加 + +### `authors` {#authors} + +**描述:** 原始资源的作者的 Fediverse 账号。\ +**类型:** Array of [PreviewCardAuthor]({{< relref "entities/PreviewCardAuthor">}})\ +**版本历史:**\ +4.3.0 - 添加 + +### `author_name` {#author_name} + +**描述:** 原始资源的作者。自 4.3.0 起已弃用，客户端应改用 `authors`。\ +**类型:** 字符串\ +**版本历史:**\ +1.3.0 - 添加\ +4.3.0 - deprecated + +### `author_url` {#author_url} + +**描述:** 指向原始资源作者的链接。自 4.3.0 起已弃用，客户端应改用 `authors`。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +1.3.0 - 添加\ +4.3.0 - deprecated + +### `provider_name` {#provider_name} + +**描述:** 原始资源的提供者。\ +**类型:** 字符串\ +**版本历史:**\ +1.3.0 - 添加 + +### `provider_url` {#provider_url} + +**描述:** 指向原始资源提供者的链接。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +1.3.0 - 添加 + +### `html` {#html} + +**描述:** 用于生成预览卡片的 HTML。\ +**类型:** 字符串 (HTML)\ +**版本历史:**\ +1.3.0 - 添加 + +### `width` {#height} + +**描述:** 预览的宽度，以像素为单位。\ +**类型:** 整数\ +**版本历史:**\ +1.3.0 - 添加 + +### `height` {#height} + +**描述:** 预览的高度，以像素为单位。\ +**类型:** 整数\ +**版本历史:**\ +1.3.0 - 添加 + +### `image` {#image} + +**描述:** 预览缩略图。\ +**类型:** {{}} 字符串 (URL)\ +**版本历史:**\ +1.0.0 - 添加 + +### `embed_url` {#embed_url} + +**描述:** 用于照片嵌入，替代自定义的 `html`。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +2.1.0 - 添加 + +### `blurhash` {#blurhash} + +**描述:** 由 [BlurHash 算法](https://github.com/woltapp/blurhash)计算出的哈希值，用于在媒体尚未下载时生成彩色预览缩略图。\ +**类型:** {{}} 字符串\ +**版本历史:**\ +3.2.0 - 添加 + +## Trends::Link 实体属性 {#trends-link} + +```json +{ + "url": "https://www.nbcnews.com/specials/plan-your-vote-2022-elections/index.html", + "title": "Plan Your Vote: 2022 Elections", + "description": "Everything you need to know about the voting rules where you live, including registration, mail-in voting, changes since 2020, and more.", + "type": "link", + "author_name": "NBC News", + "author_url": "", + "provider_name": "NBC News", + "provider_url": "", + "html": "", + "width": 400, + "height": 225, + "image": "https://files.mastodon.social/cache/preview_cards/images/045/027/478/original/0783d5e91a14fd49.jpeg", + "embed_url": "", + "blurhash": "UcQmF#ay~qofj[WBj[j[~qof9Fayofofayay", + "history": [ + { + "day": "1661817600", + "accounts": "7", + "uses": "7" + }, + { + "day": "1661731200", + "accounts": "23", + "uses": "23" + }, + { + "day": "1661644800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1661558400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1661472000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1661385600", + "accounts": "0", + "uses": "0" + }, + { + "day": "1661299200", + "accounts": "0", + "uses": "0" + } + ] +} +``` + +### `history` {#history} + +**描述:** 给定日期的使用统计信息（通常是过去一周）。\ +**类型:** 哈希值的数组\ +**版本历史:**\ +3.5.0 - 添加 + +#### `history[][day]` {#history-day} + +**描述:** 给定日期午夜的 UNIX 时间戳。\ +**类型:** 字符串 (UNIX 时间戳)\ +**版本历史:**\ +3.5.0 - 添加 + +#### `history[][accounts]` {#history-accounts} + +**描述:** 当天使用该链接的已计数帐户数。\ +**类型:** 字符串 (从整数转换而来)\ +**版本历史:**\ +3.5.0 - 添加 + +#### `history[][uses]` {#history-uses} + +**描述:** 当天使用该链接的已计数嘟文数。\ +**类型:** 字符串 (从整数转换而来)\ +**版本历史:**\ +3.5.0 - 添加 + +## 参见 + +{{< page-relref ref="entities/Status#card" caption="Status (`card` 属性)" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/preview_card_serializer.rb" caption="app/serializers/rest/preview_card_serializer.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/trends/link_serializer.rb" caption="app/serializers/rest/trends/link_serializer.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/trends/links.rb" caption="app/models/trends/links.rb" >}} + +{{< translation-status-zh-cn raw_title="PreviewCard" raw_link="/entities/PreviewCard/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/PreviewCardAuthor.md b/content/zh-cn/entities/PreviewCardAuthor.md new file mode 100644 index 0000000..5ac3021 --- /dev/null +++ b/content/zh-cn/entities/PreviewCardAuthor.md @@ -0,0 +1,41 @@ +--- +title: PreviewCardAuthor +description: 表示富媒体预览卡片中的作者。 +menu: + docs: + parent: entities +aliases: [ + "/entities/PreviewCardAuthor", +] +--- + +## 属性 + +### `name` {#name} + +**描述:** 原始资源的作者姓名。替换预览卡片中已弃用的 `author_name` 属性。\ +**类型:** 字符串\ +**版本历史:**\ +4.3.0 - 添加 + +### `url` {#url} + +**描述:** 指向原始资源作者的链接。替换预览卡片中已弃用的 `author_url` 属性。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +4.3.0 - 添加 + +### `account` {{%nullable%}} {#account} + +**描述:** 作者的联邦宇宙账号。\ +**类型:** [Account]({{< relref "entities/Account">}})\ +**版本历史:**\ +4.3.0 - 添加 + +## 另请参考 + +{{< page-relref ref="entities/PreviewCard#authors" caption="PreviewCard (`authors` 属性)" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/preview_card_serializer.rb" caption="app/serializers/rest/preview_card_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="PreviewCardAuthor" raw_link="/entities/PreviewCardAuthor/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/PrivacyPolicy.md b/content/zh-cn/entities/PrivacyPolicy.md new file mode 100644 index 0000000..b5a4c94 --- /dev/null +++ b/content/zh-cn/entities/PrivacyPolicy.md @@ -0,0 +1,46 @@ +--- +title: PrivacyPolicy +description: 表示实例的隐私政策。 +menu: + docs: + parent: entities +aliases: [ + "/entities/privacypolicy", + "/entities/PrivacyPolicy", + "/api/entities/privacypolicy", + "/api/entities/PrivacyPolicy", +] +--- + +## 示例 + +```json +{ + "updated_at": "2022-10-07T00:00:00+00:00", + "content": "

This privacy policy describes how example.com ("example.com", "we", "us") collects,\nprotects and uses the personally identifiable information you may provide\nthrough the example.com website or its API.

\n\n

What information do we collect?

\n\n
    \n
  • Basic account information: If you register on this server, you may be\nasked to enter a username, an e-mail address and a password.
    • \n
  • Posts, following and other public information: The list of people you\nfollow is listed publicly, the same is true for your followers.
    • \n
  • Direct and followers-only posts: All posts are stored and processed on the\nserver. You may\ntoggle an option to approve and reject new followers manually in the settings.\nPlease keep in mind that the operators of the server and any receiving\nserver may view such messages, and that recipients may screenshot, copy or\notherwise re-share them. Do not share any sensitive information over\nMastodon.
    • \n
  • IPs and other metadata: When you log in, we record the IP address you log\nin from, as well as the name of your browser application.
    • \n
\n\n
\n\n

This document is CC-BY-SA. Originally adapted from the Discourse privacy\npolicy.

\n" +} +``` + +## 属性 + +### `updated_at` {#updated_at} + +**描述:** 隐私政策上次更新的时间戳。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `content` {#content} + +**描述:** 隐私政策的渲染后的 HTML 内容。\ +**类型:** 字符串 (HTML)\ +**版本历史:**\ +4.0.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/instance#privacy_policy" caption="GET /api/v1/instance/privacy_policy" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/privacy_policy_serializer.rb" caption="app/serializers/rest/privacy_policy_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="PrivacyPolicy" raw_link="/entities/PrivacyPolicy/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Reaction.md b/content/zh-cn/entities/Reaction.md new file mode 100644 index 0000000..3aa9580 --- /dev/null +++ b/content/zh-cn/entities/Reaction.md @@ -0,0 +1,83 @@ +--- +title: Reaction +description: 表示对公告的一个表情回应。 +menu: + docs: + parent: entities +aliases: [ + "/entities/announcementreaction", + "/entities/AnnouncementReaction", + "/entities/reaction", + "/entities/Reaction", + "/api/entities/announcementreaction", + "/api/entities/AnnouncementReaction", + "/api/entities/reaction", + "/api/entities/Reaction", +] +--- + +## 示例 + +```json +[ + { + "name": "bongoCat", + "count": 9, + "me": false, + "url": "https://files.mastodon.social/custom_emojis/images/000/067/715/original/fdba57dff7576d53.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/067/715/static/fdba57dff7576d53.png" + }, + { + "name": "🤔", + "count": 1, + "me": true + } +] +``` + +## 属性 + +### `name` {#name} + +**描述:** 用于回应的表情。可以是 Unicode 表情，也可以是自定义表情的短代码。\ +**类型:** 字符串\ +**版本历史:**\ +3.1.0 - 添加 + +### `count` {#count} + +**描述:** 添加此回应的用户总数。\ +**类型:** 整数\ +**版本历史:**\ +3.1.0 - 添加 + +### `me` {{%optional%}} {#me} + +**描述:** 如果存在当前已授权用户：该授权用户是否添加了此回应？\ +**类型:** 布尔值\ +**版本历史:**\ +3.1.0 - 添加 + +### `url` {{%optional%}} {#url} + +**描述:** 如果回应是自定义表情：指向自定义表情的链接。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +3.1.0 - 添加 + +### `static_url` {{%optional%}} {#static_url} + +**描述:** 如果回应是自定义表情：指向非动画版本自定义表情的链接。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +3.1.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/announcements#put-reactions" caption="向公告添加回应" >}} + +{{< page-relref ref="methods/announcements#delete-reactions" caption="从公告中删除回应" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/reaction_serializer.rb" caption="app/serializers/rest/reaction_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Reaction" raw_link="/entities/Reaction/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Relationship.md b/content/zh-cn/entities/Relationship.md new file mode 100644 index 0000000..c3050fc --- /dev/null +++ b/content/zh-cn/entities/Relationship.md @@ -0,0 +1,149 @@ +--- +title: Relationship +description: 表示账户之间的关系，例如关注/屏蔽/隐藏等。 +menu: + docs: + parent: entities +aliases: [ + "/entities/relationship", + "/entities/Relationship", + "/api/entities/relationship", + "/api/entities/Relationship", +] +--- + +## 示例 + +```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, + "requested_by": false, + "domain_blocking": false, + "endorsed": false, + "note": "" +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 账户 ID。\ +**类型:** 字符串 (从整数转换而来，但不保证一定是数字)\ +**版本历史:** +0.6.0 - 添加 + +### `following` {#following} + +**描述:** 你是否正在关注此用户？\ +**类型:** 布尔值\ +**版本历史:** +0.6.0 - 添加 + +### `showing_reblogs` {#showing_reblogs} + +**描述:** 你是否在你的首页时间线中接收此用户的转发？\ +**类型:** 布尔值\ +**版本历史:** +2.1.0 - 添加 + +### `notifying` {#notifying} + +**描述:** 你是否为此用户启用了通知？\ +**类型:** 布尔值\ +**版本历史:** +3.3.0 - 添加 + +### `languages` {#languages} + +**描述:** 你正在关注此用户的哪些语言？\ +**类型:** 字符串数组 (ISO 639-1 双字符语言代码)\ +**版本历史:** +4.0.0 - 添加 + +### `followed_by` {#followed_by} + +**描述:** 此用户是否正在关注你？\ +**类型:** 布尔值\ +**版本历史:** +0.6.0 - 添加 + +### `blocking` {#blocking} + +**描述:** 你是否正在屏蔽此用户？\ +**类型:** 布尔值\ +**版本历史:** +0.6.0 - 添加 + +### `blocked_by` {#blocked_by} + +**描述:** 此用户是否正在屏蔽你？\ +**类型:** 布尔值\ +**版本历史:** +2.8.0 - 添加 + +### `muting` {#muting} + +**描述:** 你是否正在隐藏此用户？\ +**类型:** 布尔值\ +**版本历史:** +1.1.0 - 添加 + +### `muting_notifications` {#muting_notifications} + +**描述:** 你是否正在隐藏来自此用户的通知？\ +**类型:** 布尔值\ +**版本历史:** +2.1.0 - 添加 + +### `requested` {#requested} + +**描述:** 你是否有对此用户待处理的关注请求？\ +**类型:** 布尔值\ +**版本历史:** +0.9.9 - 添加 + +### `requested_by` {#requested_by} + +**描述:** 此用户是否请求关注你？\ +**类型:** 布尔值\ +**版本历史:** +4.1.0 - 添加 + +### `domain_blocking` {#domain_blocking} + +**描述:** 你是否正在屏蔽此用户的域名？\ +**类型:** 布尔值\ +**版本历史:** +1.4.0 - 添加 + +### `endorsed` {#endorsed} + +**描述:** 你是否在你的账户上推荐此用户？\ +**类型:** 布尔值\ +**版本历史:** +2.5.0 - 添加 + +### `note` {#note} + +**描述:** 此用户的账户简介\ +**类型:** 字符串\ +**版本历史:** +3.2.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/accounts#relationships" caption="GET /api/v1/accounts/relationships" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/relationship_serializer.rb" caption="app/serializers/rest/relationship_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Relationship" raw_link="/entities/Relationship/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/RelationshipSeveranceEvent.md b/content/zh-cn/entities/RelationshipSeveranceEvent.md new file mode 100644 index 0000000..5edaf6d --- /dev/null +++ b/content/zh-cn/entities/RelationshipSeveranceEvent.md @@ -0,0 +1,67 @@ +--- +title: RelationshipSeveranceEvent +description: 导致关注关系断开的管理或屏蔽事件的摘要。 +menu: + docs: + parent: entities +aliases: [ + "/entities/RelationshipSeveranceEvent", + "/api/entities/RelationshipSeveranceEvent", +] +--- + +## 属性 + +### `id` {#id} + +**描述:** 数据库中关系断开事件的 ID。\ +**类型:** 字符串 (从整数转换而来)\ +**版本历史:**\ +4.3.0 - 添加 + +### `type` {#type} + +**描述:** 事件类型。\ +**类型:** 字符串 (可枚举的 oneOf)\ +`domain_block` = 审核员封禁了整个域名\ +`user_domain_block` = 用户屏蔽了整个域名\ +`account_suspension` = 审核员封禁了特定帐户\ +**版本历史:**\ +4.3.0 - 添加 + +### `purged` {#purged} + +**描述:** 由于导致该事件的问题已被清除，断开的关系列表是否不可用。\ +**类型:** 布尔值\ +**版本历史:**\ +4.3.0 - 添加 + +### `target_name` {#target_name} + +**描述:** 审核/屏蔽事件的目标名称。 这可以是域名或用户名，具体取决于事件类型。\ +**类型:** 字符串\ +**版本历史:**\ +4.3.0 - 添加 + +### `followers_count` {#followers_count} + +**描述:** 由于该事件而被移除的关注者数量。\ +**类型:** 整数\ +**版本历史:**\ +4.3.0 - 添加 + +### `following_count` {#following_count} + +**描述:** 用户由于该事件而停止关注的帐户数量。\ +**类型:** 整数\ +**版本历史:**\ +4.3.0 - 添加 + +### `created_at` {#created_at} + +**描述:** 事件发生的时间。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +4.3.0 - 添加 + +{{< translation-status-zh-cn raw_title="RelationshipSeveranceEvent" raw_link="/entities/RelationshipSeveranceEvent/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Report.md b/content/zh-cn/entities/Report.md new file mode 100644 index 0000000..3c3e2d3 --- /dev/null +++ b/content/zh-cn/entities/Report.md @@ -0,0 +1,139 @@ +--- +title: Report +description: 举报用户和/或嘟文，供审核员采取行动。 +menu: + docs: + parent: entities +aliases: [ + "/entities/report", + "/entities/Report", + "/api/entities/report", + "/api/entities/Report", +] +--- + +## 示例 + +```json +{ + "id": "48914", + "action_taken": false, + "action_taken_at": null, + "category": "spam", + "comment": "Spam account", + "forwarded": false, + "created_at": "2022-08-25T09:56:16.763Z", + "status_ids": [ + "108882889550545820" + ], + "rule_ids": null, + "target_account": { + "id": "108366849347798387", + "username": "Baluke", + "acct": "Baluke", + "display_name": "Baluke Dental Studios", + "locked": false, + "bot": false, + "discoverable": false, + "group": false, + "created_at": "2022-05-26T00:00:00.000Z", + "note": "

Baluke Dental Studios is a full service dental lab offering fabrication, staining, and digital services. Advanced technologies and a meticulous process ensure reduced chair time, lower costs, and better patient outcomes with beautiful smiles. Talk to a representative today.

https://baluke.com/

", + "url": "https://mastodon.social/@Baluke", + "avatar": "https://files.mastodon.social/accounts/avatars/108/366/849/347/798/387/original/dbcfe99ed5def0f4.png", + "avatar_static": "https://files.mastodon.social/accounts/avatars/108/366/849/347/798/387/original/dbcfe99ed5def0f4.png", + "header": "https://static-cdn.mastodon.social/headers/original/missing.png", + "header_static": "https://static-cdn.mastodon.social/headers/original/missing.png", + "followers_count": 0, + "following_count": 0, + "statuses_count": 38, + "last_status_at": "2022-08-25", + "emojis": [], + "fields": [] + } +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 数据库中举报的 ID。\ +**类型:** 字符串 (从整数转换而来)\ +**版本历史:** +1.1.0 - 添加 + +### `action_taken` {#action_taken} + +**描述:** 是否已采取行动。\ +**类型:** 布尔值\ +**版本历史:** +1.1.0 - 添加 + +### `action_taken_at` {#action_taken_at} + +**描述:** 针对举报采取行动的时间。\ +**类型:** {{}} 字符串 ([Datetime](/api/datetime-format#datetime)) or null\ +**版本历史:** +4.0.0 - 添加 + +### `category` {#category} + +**描述:** 举报的一般原因。\ +**类型:** 字符串 (可枚举的 oneOf)\ +`spam` = 不受欢迎或重复的内容\ +`violation` = 违反了特定规则\ +`other` = 其他原因\ +**版本历史:** +4.0.0 - 添加 + +### `comment` {#comment} + +**描述:** 举报的原因。\ +**类型:** 字符串\ +**版本历史:** +4.0.0 - 添加 + +### `forwarded` {#forwarded} + +**描述:** 举报是否已转发到外站。\ +**类型:** 布尔值\ +**版本历史:** +4.0.0 - 添加 + +### `created_at` {#created_at} + +**描述:** 举报的创建时间。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:** +4.0.0 - 添加 + +### `status_ids` {#status_ids} + +**描述:** 附加到此举报的嘟文 ID，用于提供额外上下文信息。\ +**类型:** {{}} Array of String (从整数转换而来), or null\ +**版本历史:** +4.0.0 - 添加 + +### `rule_ids` {#rule_ids} + +**描述:** 此举报中引用的、被违反的规则 ID。\ +**类型:** {{}} Array of String (从整数转换而来), or null\ +**版本历史:** +4.0.0 - 添加 + +### `target_account` {#target_account} + +**描述:** 被举报的帐户。\ +**类型:** [Account]({{< relref "entities/account" >}})\ +**版本历史:** +4.0.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/reports" caption="举报 API 方法" >}} + +{{< page-relref ref="entities/Notification#report" caption="通知 (`report` 属性)" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/report_serializer.rb" caption="app/serializers/rest/report_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Report" raw_link="/entities/Report/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Role.md b/content/zh-cn/entities/Role.md new file mode 100644 index 0000000..09b202c --- /dev/null +++ b/content/zh-cn/entities/Role.md @@ -0,0 +1,132 @@ +--- +title: Role +description: 表示带有自定义权限设定的用户组。 +menu: + docs: + parent: entities +aliases: [ + "/entities/role", + "/entities/Role", + "/api/entities/role", + "/api/entities/Role", +] +--- + +## 示例 + +```json +{ + "id": "3", + "name": "Owner", + "color": "#ff3838", + "permissions": "1048575", + "highlighted": true +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 数据库中用户组的 ID。\ +**类型:** 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `name` {#name} + +**描述:** 用户组的名称。\ +**类型:** 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `color` {#color} + +**描述:** 分配给此用户组的十六进制代码。如果未分配十六进制代码，则字符串将为空。\ +**类型:** 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `permissions` {#permissions} + +**描述:** 一个位掩码，表示授予该用户组的所有权限的总和。\ +**类型:** 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +### `highlighted` {#highlighted} + +**描述:** 是否在用户账户页上公开显示该用户组徽章。\ +**类型:** 布尔值\ +**版本历史:**\ +4.0.0 - 添加 + +## 权限标志 + +要确定特定用户组可用的权限，请将 `permissions` 属性转换为二进制，然后从最低有效位开始进行比较。为了方便起见（并防止术语变得太长），权限将在下面使用十六进制值表示。 + +0x1 +: **Administrator（管理员）**。拥有此权限的用户将绕过所有权限。 + +0x2 +: **Devops（运维）**。允许用户访问 Sidekiq 和 PgHero 仪表板。 + +0x4 +: **View Audit Log（查看审计日志）**。允许用户查看管理员操作的历史记录。 + +0x8 +: **View Dashboard（查看仪表板）**。允许用户访问仪表板和各种指标。 + +0x10 +: **Manage Reports（管理举报）**。允许用户审查举报并对其执行管理操作。 + +0x20 +: **Manage Federation（管理联合）**。允许用户阻止或允许与其他域的联合，并控制可交付性。 + +0x40 +: **Manage Settings（管理设置）**。允许用户更改站点设置。 + +0x80 +: **Manage Blocks（管理屏蔽）**。允许用户屏蔽电子邮件提供商和 IP 地址。 + +0x100 +: **Manage Taxonomies（管理热门内容）**。允许用户查看热门内容并更新话题标签设置。 + +0x200 +: **Manage Appeals（管理申诉）**。允许用户审查针对管理操作的申诉。 + +0x400 +: **Manage Users（管理用户）**。允许用户查看其他用户的详细信息并对其执行管理操作。 + +0x800 +: **Manage Invites（管理邀请）**。允许用户浏览和停用邀请链接。 + +0x1000 +: **Manage Rules（管理规则）**。允许用户更改实例规则。 + +0x2000 +: **Manage Announcements（管理公告）**。允许用户管理实例上的公告。 + +0x4000 +: **Manage Custom Emojis（管理自定义表情）**。允许用户管理实例上的自定义表情。 + +0x8000 +: **Manage Webhooks（管理 Webhook）**。允许用户为管理事件设置 Webhook。 + +0x10000 +: **Invite Users（邀请用户）**。允许用户邀请新人加入实例。 + +0x20000 +: **Manage Roles（管理用户组）**。允许用户管理和分配权限低于其用户组权限的用户组。 + +0x40000 +: **Manage User Access（管理用户权限）**。允许用户禁用其他用户的双因素身份验证、更改其电子邮件地址和重置其密码。 + +0x80000 +: **Delete User Data（删除用户数据）**。允许用户立即删除其他用户的数据。 + +## 另请参见 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/role_serializer.rb" caption="app/serializers/rest/role_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Role" raw_link="/entities/Role/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Rule.md b/content/zh-cn/entities/Rule.md new file mode 100644 index 0000000..116e17d --- /dev/null +++ b/content/zh-cn/entities/Rule.md @@ -0,0 +1,56 @@ +--- +title: Rule +description: 表示实例用户应遵守的规则。 +menu: + docs: + parent: entities +aliases: [ + "/entities/rule", + "/entities/Rule", + "/api/entities/rule", + "/api/entities/Rule", +] +--- + +## 示例 + +```json +{ + "id": "2", + "text": "No racism, sexism, homophobia, transphobia, ableism, xenophobia, or casteism.", + "hint": "Transphobic behavior such as intentional misgendering and deadnaming is strictly prohibited. Promotion of \"conversion therapy\" is strictly prohibited. Criticism of governments and religions is permissible unless being used as a proxy for discrimination." +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 规则的标识符。\ +**类型:** 字符串 (从整数转换而来，但不保证一定是数字)\ +**版本历史:**\ +3.4.0 - 添加 + +### `text` {#text} + +**描述:** 需要遵守的规则内容。\ +**类型:** 字符串 \ +**版本历史:**\ +3.4.0 - 添加 + +### `hint` {#hint} + +**描述:** 规则的详细描述。\ +**类型:** 字符串 \ +**版本历史:**\ +4.3.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/instance#rules" caption="GET /api/v1/instance/rules" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/rule.rb" caption="app/models/rule.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/rule_serializer.rb" caption="app/serializers/rest/rule_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Rule" raw_link="/entities/Rule/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/ScheduledStatus.md b/content/zh-cn/entities/ScheduledStatus.md new file mode 100644 index 0000000..009e7d0 --- /dev/null +++ b/content/zh-cn/entities/ScheduledStatus.md @@ -0,0 +1,219 @@ +--- +title: ScheduledStatus +description: 表示一条计划在未来日期发布的嘟文。 +menu: + docs: + parent: entities +aliases: [ + "/entities/scheduledstatus", + "/entities/ScheduledStatus", + "/api/entities/scheduledstatus", + "/api/entities/ScheduledStatus", +] +--- + +## 示例 + +`POST /api/v1/statuses?status=test post&scheduled_at=2022-09-29` 返回： + +```json +{ + "id": "1", + "scheduled_at": "2022-09-29T00:00:00.000Z", + "params": { + "text": "test post", + "media_ids": null, + "sensitive": null, + "spoiler_text": null, + "visibility": null, + "language": null, + "scheduled_at": null, + "poll": null, + "idempotency": null, + "with_rate_limit": false, + "in_reply_to_id": null, + "application_id": 3 + }, + "media_attachments": [] +} +``` + +`GET /api/v1/scheduled_statuses` 返回： + +```json +{ + "id": "1", + "scheduled_at": "2022-09-29T00:00:00.000Z", + "params": { + "poll": null, + "text": "test post", + "language": null, + "media_ids": null, + "sensitive": null, + "visibility": null, + "idempotency": null, + "scheduled_at": null, + "spoiler_text": null, + "application_id": 3, + "in_reply_to_id": null, + "with_rate_limit": false + }, + "media_attachments": [] +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 数据库中定时嘟文的 ID。\ +**类型:** 字符串 (由整数转换而来，但不保证为数字)\ +**版本历史:**\ +2.7.0 - 添加 + +### `scheduled_at` {#scheduled_at} + +**描述:** 嘟文计划被发布的 Unix 时间戳。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +2.7.0 - 添加 + +### `params` {#params} + +**描述:** 调度嘟文时使用的参数，将在发布嘟文时使用。\ +**类型:** 哈希\ +**版本历史:**\ +2.7.0 - 添加 + +#### `params[text]` {#params-text} + +**描述:** 将用作嘟文内容的文本。\ +**类型:** 字符串\ +**版本历史:**\ +2.7.0 - 添加 + +#### `params[poll]` {#params-poll} + +**描述:** 要附加到嘟文的投票。\ +**类型:** {{}} 哈希\ +**版本历史:**\ +2.8.0 - 添加 + +##### `params[poll][options[]]` {#params-poll-options} + +**描述:** 要使用的投票选项。\ +**类型:** 字符串数组\ +**版本历史:**\ +2.8.0 - 添加 + +##### `params[poll][expires_in]` {#params-poll-expires_in} + +**描述:** 投票在关闭前应持续多少秒。\ +**类型:** 字符串（从整数转换）\ +**版本历史:**\ +2.8.0 - 添加 + +##### `params[poll][multiple]` {#params-poll-multiple} + +**描述:** 投票是否允许多选。\ +**类型:** {{}} 布尔值\ +**版本历史:**\ +2.8.0 - 添加 + +##### `params[poll][hide_totals]` {#params-poll-hide_totals} + +**描述:** 投票是否应隐藏总票数，直到投票结束后再显示。\ +**类型:** {{}} 布尔值\ +**版本历史:**\ +2.8.0 - 添加 + +#### `params[media_ids]` {#params-media_ids} + +**描述:** 将附加到嘟文的 MediaAttachment 的 ID。\ +**类型:** {{}} 字符串数组\ +**版本历史:**\ +2.7.0 - 添加 + +#### `params[sensitive]` {#params-sensitive} + +**描述:** 嘟文是否将被标记为敏感。\ +**类型:** {{}} 布尔值\ +**版本历史:**\ +2.7.0 - 添加 + +#### `params[spoiler_text]` {#params-spoiler_text} + +**描述:** 嘟文的内容警告或摘要的文本。\ +**类型:** {{}} 字符串\ +**版本历史:**\ +2.7.0 - 添加 + +#### `params[visibility]` {#params-visibility} + +**描述:** 嘟文发布后将具有的可见性。\ +**类型:** 字符串 (可枚举 oneOf)\ +`public` = 对所有人可见，显示在公共时间线中。\ +`unlisted` = 对公众可见，但不包含在公共时间线中。\ +`private` = 仅对关注者和任何被提及的用户可见。\ +`direct` = 仅对被提及的用户可见。\ +**版本历史:**\ +2.7.0 - 添加 + +#### `params[in_reply_to_id]` {#params-in_reply_to_id} + +**描述:** 将回复的嘟文的 ID。\ +**类型:** {{}} 整数\ +**版本历史:**\ +2.7.0 - 添加 + +#### `params[language]` {#params-language} + +**描述:** 将用于嘟文的语言。\ +**类型:** {{}} 字符串 (ISO 639-1 双字母语言代码)\ +**版本历史:**\ +2.7.0 - 添加 + +#### `params[application_id]` {{%deprecated%}} {#params-application_id} + +**描述:** 发布嘟文的应用的内部 ID。 仅为保留后向兼容性提供，可以忽略。\ +**类型:** 整数\ +**版本历史:**\ +2.7.0 - 添加 + +#### `params[scheduled_at]` {#params-scheduled_at} + +**描述:** 嘟文的定时发布时间。 这将为 null，因为嘟文只被计划一次。\ +**类型:** {{}} Null\ +**版本历史:**\ +2.7.0 - 添加 + +#### `params[idempotency]` {#params-idempotency} + +**描述:** 幂等性键，用于防止重复发布嘟文。\ +**类型:** {{}} 字符串\ +**版本历史:**\ +2.7.0 - 添加 + +#### `params[with_rate_limit]` {{%deprecated%}} {#params-with_rate-limit} + +**描述:** 嘟文创建是否受速率限制。 仅为保留后向兼容性提供，可以忽略。\ +**类型:** 布尔值\ +**版本历史:**\ +2.7.0 - 添加 + +### `media_attachments` {#media_attachments} + +**描述:** 发布嘟文时将附加的媒体。\ +**类型:** [MediaAttachment]({{< relref "entities/MediaAttachment" >}}) 数组\ +**版本历史:**\ +2.7.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/statuses#create" caption="POST /api/v1/statuses (带有 `scheduled_at` 参数)" >}} + +{{< page-relref ref="methods/scheduled_statuses" caption="scheduled_statuses API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/scheduled_status_serializer.rb" caption="app/serializers/rest/scheduled_status_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="ScheduledStatus" raw_link="/entities/ScheduledStatus/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Search.md b/content/zh-cn/entities/Search.md new file mode 100644 index 0000000..1388b0f --- /dev/null +++ b/content/zh-cn/entities/Search.md @@ -0,0 +1,120 @@ +--- +title: Search +description: 表示搜索结果。 +menu: + docs: + parent: entities +aliases: [ + "/entities/results", + "/entities/Results", + "/entities/search", + "/entities/Search", + "/api/entities/results", + "/api/entities/Results", + "/api/entities/search", + "/api/entities/Search", +] +--- + +## 示例 + +关于 q=cats limit=2 的搜索结果采样片段 + +```json +{ + "accounts": [ + { + "id": "180744", + "username": "catstar", + "acct": "catstar@catgram.jp", + "display_name": "catstar", + // ... + }, + { + "id": "214293", + "username": "catsareweird", + "acct": "catsareweird", + "display_name": "Cats Are Weird", + // ... + } + ], + "statuses": [ + { + "id": "103085519055545958", + "created_at": "2019-11-05T13:23:09.000Z", + // ... + "content": "

cats
cats never change

", + // ... + }, + { + "id": "101068121469614510", + "created_at": "2018-11-14T06:31:48.000Z", + // ... + "spoiler_text": "Cats", + // ... + "content": "

Cats are inherently good at self-care.

#cats", + // ... + }, + // ... + ], + "hashtags": [ + { + "name": "cats", + "url": "https://mastodon.social/tags/cats", + "history": [ + { + "day": "1574553600", + "uses": "10", + "accounts": "9" + }, + // ... + ] + }, + { + "name": "catsofmastodon", + "url": "https://mastodon.social/tags/catsofmastodon", + "history": [ + { + "day": "1574553600", + "uses": "6", + "accounts": "5" + }, + // ... + ] + } + ] +} +``` + +## 属性 + +### `accounts` {#accounts} + +**描述:** 与给定关键词匹配的帐户。\ +**类型:** [Account]({{< relref "entities/Account" >}}) 数组\ +**版本历史:**\ +1.1.0 - 添加 + +### `statuses` {#statuses} + +**描述:** 与给定关键词匹配的嘟文。\ +**类型:** [Status]({{< relref "entities/Status" >}}) 数组\ +**版本历史:**\ +1.1.0 - 添加 + +### `hashtags` {#hashtags} + +**描述:** 与给定关键词匹配的话题标签。\ +**类型:** [Tag]({{< relref "entities/Tag" >}}) 数组\ +**版本历史:**\ +1.1.0 - 添加\ +2.4.1 - v1/search 已弃用，因为它返回字符串数组。添加了返回标签数组的 v2/search。\ +3.0.0 - 删除了 v1/search + +## 参见 + +{{< page-relref ref="methods/search" caption="搜索 API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/search_serializer.rb" caption="app/serializers/rest/search_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Search" raw_link="/entities/Search/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Status.md b/content/zh-cn/entities/Status.md new file mode 100644 index 0000000..b10ecc6 --- /dev/null +++ b/content/zh-cn/entities/Status.md @@ -0,0 +1,397 @@ +--- +title: Status +description: 表示帐户发布的嘟文。 +menu: + docs: + parent: entities +aliases: [ + "/entities/mention", + "/entities/Mention", + "/entities/status", + "/entities/Status", + "/api/entities/mention", + "/api/entities/Mention", + "/api/entities/status", + "/api/entities/Status", +] +--- + +## 示例 + +```json +{ + "id": "103270115826048975", + "created_at": "2019-12-08T03:48:33.901Z", + "in_reply_to_id": null, + "in_reply_to_account_id": null, + "sensitive": false, + "spoiler_text": "", + "visibility": "public", + "language": "en", + "uri": "https://mastodon.social/users/Gargron/statuses/103270115826048975", + "url": "https://mastodon.social/@Gargron/103270115826048975", + "replies_count": 5, + "reblogs_count": 6, + "favourites_count": 11, + "favourited": false, + "reblogged": false, + "muted": false, + "bookmarked": false, + "content": "

"I lost my inheritance with one wrong digit on my sort code"

https://www.theguardian.com/money/2019/dec/07/i-lost-my-193000-inheritance-with-one-wrong-digit-on-my-sort-code", + "reblog": null, + "application": { + "name": "Web", + "website": null + }, + "account": { + "id": "1", + "username": "Gargron", + "acct": "Gargron", + "display_name": "Eugen", + "locked": false, + "bot": false, + "discoverable": true, + "group": false, + "created_at": "2016-03-16T14:34:26.392Z", + "note": "

Developer of Mastodon and administrator of mastodon.social. I post service announcements, development updates, and personal stuff.

", + "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": 322930, + "following_count": 459, + "statuses_count": 61323, + "last_status_at": "2019-12-10T08:14:44.811Z", + "emojis": [], + "fields": [ + { + "name": "Patreon", + "value": "https://www.patreon.com/mastodonhttps://zeonfederated.com}})\ +**版本历史:**\ +0.1.0 - 添加 + +### `content` {#content} + +**描述:** HTML 格式的嘟文内容。\ +**类型:** 字符串 (HTML)\ +**版本历史:**\ +0.1.0 - 添加 + +### `visibility` {#visibility} + +**描述:** 此嘟文的可见性。\ +**类型:** 字符串（可枚举的 oneOf 类型）\ +`public` = 公开可见，显示在公共时间线中。\ +`unlisted` = 公开可见，但不包含在公共时间线中。\ +`private` = 仅对关注者以及任何被提及的用户可见。\ +`direct` = 仅对被提及的用户可见。\ +**版本历史:**\ +0.9.9 - 添加 + +### `sensitive` {#sensitive} + +**描述:** 此嘟文是否标记为敏感内容？\ +**类型:** 布尔值\ +**版本历史:**\ +0.9.9 - 添加 + +### `spoiler_text` {#spoiler_text} + +**描述:** 主题或摘要，嘟文内容将被折叠在该文本之后，直到被展开为止。\ +**类型:** 字符串\ +**版本历史:**\ +1.0.0 - 添加 + +### `media_attachments` {#media_attachments} + +**描述:** 附加到此嘟文的媒体。\ +**类型:** [MediaAttachment]({{< relref "entities/MediaAttachment" >}}) 数组\ +**版本历史:**\ +0.6.0 - 添加 + +### `application` {{%optional%}} {#application} + +**描述:** 用于发布此嘟文的应用。\ +**类型:** 哈希\ +**版本历史:**\ +0.9.9 - 添加 + +#### `application[name]` {#application-name} + +**描述:** 发布此嘟文的应用的名称。\ +**类型:** 字符串\ +**版本历史:**\ +0.9.9 - 添加 + +#### `application[website]` {#application-website} + +**描述:** 与发布此嘟文的应用关联的网站。\ +**类型:** {{}} 字符串 (URL) 或 null\ +**版本历史:**\ +0.9.9 - 添加\ +3.5.1 - this property is now nullable + +### `mentions` {#mentions} + +**描述:** 在嘟文内容中提及的用户。\ +**类型:** [Status::Mention](#Mention) 数组\ +**版本历史:**\ +0.6.0 - 添加 + +### `tags` {#tags} + +**描述:** 在嘟文内容中使用的话题标签。\ +**类型:** [Status::Tag](#Tag) 数组\ +**版本历史:**\ +0.6.0 - 添加 + +### `emojis` {#emojis} + +**描述:** 渲染嘟文内容时要使用的自定义表情。\ +**类型:** [CustomEmoji]({{< relref "entities/CustomEmoji" >}}) 数组\ +**版本历史:**\ +2.0.0 - 添加 + +### `reblogs_count` {#reblogs_count} + +**描述:** 此嘟文的被转发数。\ +**类型:** 整数\ +**版本历史:**\ +0.1.0 - 添加 + +### `favourites_count` {#favorites_count} + +**描述:** 此嘟文已收到的点赞数。\ +**类型:** 整数\ +**版本历史:**\ +0.1.0 - 添加 + +### `replies_count` {#replies_count} + +**描述:** 此嘟文已收到的回复数。\ +**类型:** 整数\ +**版本历史:**\ +2.5.0 - 添加 + +### `url` {#url} + +**描述:** 指向嘟文的 HTML 表示的链接。\ +**类型:** {{}} 字符串 (URL) 或 null\ +**版本历史:**\ +0.1.0 - 添加 + +### `in_reply_to_id` {#in_reply_to_id} + +**描述:** 要回复的嘟文的 ID。\ +**类型:** {{}} 字符串（从整数转换而来，但不保证是数字）或 null\ +**版本历史:**\ +0.1.0 - 添加 + +### `in_reply_to_account_id` {#in_reply_to_account_id} + +**描述:** 撰写要回复的嘟文的帐户的 ID。\ +**类型:** {{}} 字符串（从整数转换而来，但不保证是数字）或 null\ +**版本历史:**\ +0.1.0 - 添加 + +### `reblog` {#reblog} + +**描述:** 要转发的嘟文。\ +**类型:** {{}} [Status]({{< relref "entities/status" >}}) 或 null\ +**版本历史:**\ +0.1.0 - 添加 + +### `poll` {#poll} + +**描述:** 附加到嘟文的投票。\ +**类型:** {{}} [Poll]({{< relref "entities/Poll" >}}) 或 null\ +**版本历史:**\ +2.8.0 - 添加 + +### `card` {#card} + +**描述:** 嘟文内容中包含的链接的预览卡片。\ +**类型:** {{}} [PreviewCard]({{< relref "entities/PreviewCard" >}}) 或 null\ +**版本历史:**\ +2.6.0 - 添加 + +### `language` {#language} + +**描述:** 此嘟文的主要语言。\ +**类型:** {{}} 字符串（ISO 639 第 1 部分两位字母语言代码）或 null\ +**版本历史:**\ +1.4.0 - 添加 + +### `text` {#text} + +**描述:** 嘟文的原始纯文本。当嘟文被删除时返回，而不是返回 `content`，因此用户可以从源文本中重新起草，而无需客户端从 HTML 内容中逆向得到原始文本。\ +**类型:** {{}} 字符串或 null\ +**版本历史:**\ +2.9.0 - 添加 + +### `edited_at` {#edited_at} + +**描述:** 上次编辑嘟文的时间戳。\ +**类型:** {{}} ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +3.5.0 - 添加 + +### `favourited` {{%optional%}} {#favourited} + +**描述:** 如果当前令牌具有授权用户：该授权用户是否喜欢了此嘟文？\ +**类型:** 布尔值\ +**版本历史:**\ +0.1.0 - 添加 + +### `reblogged` {{%optional%}} {#reblogged} + +**描述:** 如果当前令牌具有授权用户：该授权用户是否已转发此嘟文？\ +**类型:** 布尔值\ +**版本历史:**\ +0.1.0 - 添加 + +### `muted` {{%optional%}} {#muted} + +**描述:** 如果当前令牌具有授权用户：该授权用户是否隐藏了有关此嘟文的通知？\ +**类型:** 布尔值\ +**版本历史:**\ +1.4.0 - 添加 + +### `bookmarked` {{%optional%}} {#bookmarked} + +**描述:** 如果当前令牌具有授权用户：该授权用户是否已将此嘟文添加到书签？\ +**类型:** 布尔值\ +**版本历史:**\ +3.1.0 - 添加 + +### `pinned` {{%optional%}} {#pinned} + +**描述:** 如果当前令牌具有授权用户：该授权用户是否已置顶此嘟文？仅当嘟文可置顶时才会返回。\ +**类型:** 布尔值\ +**版本历史:**\ +1.6.0 - 添加 + +### `filtered` {{%optional%}} {#filtered} + +**描述:** 如果当前令牌具有授权用户：此嘟文命中的过滤规则和关键词。\ +**类型:** [FilterResult]({{< relref "entities/FilterResult" >}}) 数组\ +**版本历史:**\ +4.0.0 - 添加 + +## Status::Mention 属性 {#Mention} + +### `id` {#Mention-id} + +**描述:** 被提及用户的帐户 ID。\ +**类型:** 字符串（从整数类型转换而来，但不保证是数字）\ +**版本历史:**\ +0.6.0 - 添加 + +### `username` {#Mention-username} + +**描述:** 被提及用户的用户名。\ +**类型:** 字符串\ +**版本历史:**\ +0.6.0 - 添加 + +### `url` {#Mention-url} + +**描述:** 被提及用户的账户位置。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +0.6.0 - 添加 + +### `acct` {#Mention-acct} + +**描述:** 被提及用户的 webfinger acct: URI。对于本站用户，等同于 `username`，对于外站用户，等同于 `username@domain`。\ +**类型:** 字符串\ +**版本历史:**\ +0.6.0 - 添加 + +## Status::Tag 属性 {#Tag} + +### `name` {#Tag-name} + +**描述:** # 符号后的话题标签名。\ +**类型:** 字符串\ +**版本历史:**\ +0.9.0 - 添加 + +### `url` {#Tag-url} + +**描述:** 指向实例上话题标签的链接。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +0.9.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/accounts#statuses" caption="GET /api/v1/accounts/:id/statuses" >}} + +{{< page-relref ref="methods/search#v2" caption="POST /api/v2/search/" >}} + +{{< page-relref ref="methods/statuses" caption="statuses methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/status_serializer.rb" caption="app/serializers/rest/status_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Status" raw_link="/entities/Status/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/StatusEdit.md b/content/zh-cn/entities/StatusEdit.md new file mode 100644 index 0000000..04e7257 --- /dev/null +++ b/content/zh-cn/entities/StatusEdit.md @@ -0,0 +1,146 @@ +--- +title: StatusEdit +description: 表示已被编辑的嘟文的一个修订版本。 +menu: + docs: + parent: entities +aliases: [ + "/entities/statusedit", + "/entities/StatusEdit", + "/api/entities/statusedit", + "/api/entities/StatusEdit", +] +--- + +## 示例 + +```json +{ + "content": "

this is a status that has been edited three times. this time a poll has been added.

", + "spoiler_text": "", + "sensitive": false, + "created_at": "2022-09-05T00:03:32.480Z", + "poll": { + "options": [ + { + "title": "cool" + }, + { + "title": "uncool" + }, + { + "title": "spiderman (this option has been changed)" + } + ] + }, + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + // ... + }, + "media_attachments": [], + "emojis": [] +} +``` + +## 属性 + +### `content` {#content} + +**描述:** 此修订版本中嘟文的内容。\ +**类型:** 字符串 (HTML)\ +**版本历史:**\ +3.5.0 - 添加 +**版本历史：**\ +3.5.0 - 添加 + +### `spoiler_text` {#spoiler_text} + +**描述:** 此修订版本中的主题或内容警告。\ +**类型:** 字符串 (HTML)\ +**版本历史:**\ +3.5.0 - 添加 +**版本历史：**\ +3.5.0 - 添加 + +### `sensitive` {#sensitive} + +**描述:** 此修订版本中嘟文是否标记为敏感。\ +**类型:** 布尔值\ +**版本历史:**\ +3.5.0 - 添加 +**版本历史：**\ +3.5.0 - 添加 + +### `created_at` {#created_at} + +**描述:** 发布此修订版本的时间戳。\ +**类型:** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史:**\ +3.5.0 - 添加 +**版本历史：**\ +3.5.0 - 添加 + +### `account` {#account} + +**描述:** 发布此修订版本的帐户。\ +**类型:** [Account]({{}})\ +**版本历史:**\ +3.5.0 - 添加 +**版本历史：**\ +3.5.0 - 添加 + +### `poll` {{%optional%}} {#poll} + +**描述:** 此修订版本中的投票。请注意，更改投票选项的编辑将被合并为一次编辑，因为此操作会重置投票。\ +**类型:** Hash\ +**版本历史:**\ +3.5.0 - 添加 +**版本历史：**\ +3.5.0 - 添加 + +#### `poll.options[]` {#poll-options} + +**描述:** 此修订版本中的投票选项。\ +**类型:** 哈希值的数组\ +**版本历史:**\ +3.5.0 - 添加 +**版本历史：**\ +3.5.0 - 添加 + +#### `poll.options[].title` {#poll-options-title} + +**描述:** 投票选项的文本。\ +**类型:** 字符串\ +**版本历史:**\ +3.5.0 - 添加 +**版本历史：**\ +3.5.0 - 添加 + +### `media_attachments` {#media_attachments} + +**描述:** 此修订版本中的媒体附件。\ +**类型:** Array of [MediaAttachment]({{}})\ +**版本历史:**\ +3.5.0 - 添加 +**版本历史：**\ +3.5.0 - 添加 + +### `emojis` {#emojis} + +**描述:** 当前修订版本中使用的任何自定义表情。\ +**类型:** Array of [CustomEmoji]({{}})\ +**版本历史:**\ +3.5.0 - 添加 +**版本历史：**\ +3.5.0 - 添加 + +## 另请参阅 + +{{< page-relref ref="methods/statuses#history" caption="GET /api/v1/statuses/:id/history" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/status_edit_serializer.rb" caption="app/serializers/rest/status_edit_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="StatusEdit" raw_link="/entities/StatusEdit/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/StatusSource.md b/content/zh-cn/entities/StatusSource.md new file mode 100644 index 0000000..b883f33 --- /dev/null +++ b/content/zh-cn/entities/StatusSource.md @@ -0,0 +1,54 @@ +--- +title: StatusSource +description: 以纯文本形式表示嘟文的来源。 +menu: + docs: + parent: entities +aliases: [ + "/entities/statussource", + "/entities/StatusSource", + "/api/entities/statussource", + "/api/entities/StatusSource", +] +--- + +## 示例 + +```json +{ + "id": "108942703571991143", + "text": "this is a status that will be edited", + "spoiler_text": "" +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 嘟文在数据库中的 ID。\ +**类型:** 字符串 (从整数转换而来，但不保证一定为数字)\ +**版本历史:**\ +3.5.0 - 新增 + +### `text` {#text} + +**描述:** 用于构成嘟文的纯文本。\ +**类型:** 字符串\ +**版本历史:**\ +3.5.0 - 新增 + +### `spoiler_text` {#spoiler_text} + +**描述:** 用于构成嘟文的主题或内容警告的纯文本。\ +**类型:** 字符串\ +**版本历史:**\ +3.5.0 - 新增 + +## 参见 + +{{< page-relref ref="methods/statuses#source" caption="GET /api/v1/statuses/:id/source" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/status_source_serializer.rb" caption="app/serializers/rest/status_source_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="StatusSource" raw_link="/entities/StatusSource/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Suggestion.md b/content/zh-cn/entities/Suggestion.md new file mode 100644 index 0000000..4797cae --- /dev/null +++ b/content/zh-cn/entities/Suggestion.md @@ -0,0 +1,71 @@ +--- +title: Suggestion +description: 表示一个推荐关注的帐户以及推荐的原因。 +menu: + docs: + parent: entities +aliases: [ + "/entities/suggestion", + "/entities/Suggestion", + "/api/entities/suggestion", + "/api/entities/Suggestion", +] +--- + +## 示例 + +```json +{ + "source": "staff", + "account": { + "id": "109031732217496096", + "username": "alice", + "acct": "alice", + // ... + } +} +``` + +## 属性 + +### `source` {#source} + +**描述：** 推荐此帐户的原因。\ +**类型：** 字符串 (可枚举的 oneOf)\ +`staff` = 此帐户由你的实例的管理团队手动推荐\ +`past_interactions` = 你之前与此帐户互动过\ +`global` = 此帐户在过去 30 天内拥有大量的转嘟、喜欢或活跃的本站关注者\ +**版本历史：**\ +3.4.0 - 添加\ +4.3.0 - 已弃用，请改用 `sources` + +### `sources` {#sources} + +**描述：** 推荐此帐户的一系列原因。 这取代了 `source`\ +**类型：** 字符串数组 (可枚举的 oneOf)\ +`featured` = 此帐户由你的管理团队手动推荐。 相当于 `source` 的 `staff` 值\ +`most_followed` = 此帐户拥有许多活跃的本站关注者\ +`most_interactions` = 此帐户在过去 30 天内有很多转嘟和喜欢\ +`similar_to_recently_followed` = 此帐户的账户与你最近关注的帐户相似\ +`friends_of_friends` = 此帐户被你关注的人关注\ +**版本历史：**\ +4.3.0 - 添加 + +### `account` {#account} + +**描述：** 推荐关注的帐户。\ +**类型：** [帐户]({{< relref "entities/Account" >}})\ +**版本历史：**\ +3.4.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/suggestions#v2" caption="GET /api/v2/suggestions" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/suggestion_serializer.rb" caption="app/serializers/rest/suggestion_serializer.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/account_suggestions.rb" caption="app/models/account_suggestions.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/account_suggestions/" caption="app/models/account_suggestions/" >}} + +{{< translation-status-zh-cn raw_title="Suggestion" raw_link="/entities/Suggestion/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Tag.md b/content/zh-cn/entities/Tag.md new file mode 100644 index 0000000..2966301 --- /dev/null +++ b/content/zh-cn/entities/Tag.md @@ -0,0 +1,199 @@ +--- +title: Tag +description: 表示嘟文内容中使用的话题标签。 +menu: + docs: + parent: entities +aliases: [ + "/entities/tag", + "/entities/Tag", + "/api/entities/tag", + "/api/entities/Tag", +] +--- + +## 示例 + +```json +{ + "name": "nowplaying", + "url": "https://mastodon.social/tags/nowplaying", + "history": [ + { + "day": "1574553600", + "uses": "200", + "accounts": "31" + }, + { + "day": "1574467200", + "uses": "272", + "accounts": "39" + }, + { + "day": "1574380800", + "uses": "345", + "accounts": "40" + }, + { + "day": "1574294400", + "uses": "366", + "accounts": "46" + }, + { + "day": "1574208000", + "uses": "226", + "accounts": "32" + }, + { + "day": "1574121600", + "uses": "217", + "accounts": "42" + }, + { + "day": "1574035200", + "uses": "214", + "accounts": "34" + } + ], + "following": false +} +``` + +## 属性 + +### `name` {#name} + +**描述:** # 符号后的话题标签名。\ +**类型:** 字符串\ +**版本历史:**\ +0.9.0 - 添加 + +### `url` {#url} + +**描述:** 实例上话题标签的链接。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +0.9.0 - 添加 + +### `history` {#history} + +**描述:** 给定时间段（通常为过去一周）的使用统计信息。\ +**类型:** 哈希值的数组\ +**版本历史:**\ +2.4.1 - 添加 + +#### `history[][day]` {#history-day} + +**描述:** 给定时间段午夜的 UNIX 时间戳。\ +**类型:** 字符串 (UNIX 时间戳)\ +**版本历史:**\ +2.4.1 - 添加 + +#### `history[][uses]` {#history-uses} + +**描述:** 该话题标签在当前时段被使用的次数。\ +**类型:** 字符串 (从整数转换而来)\ +**版本历史:**\ +2.4.1 - 添加 + +#### `history[][accounts]` {#history-accounts} + +**描述:** 当前时段使用该话题标签的帐户总数。\ +**类型:** 字符串 (从整数转换而来)\ +**版本历史:**\ +2.4.1 - 添加 + +### `following` {{%optional%}} {#following} + +**描述:** 当前令牌的授权用户是否正在关注此话题标签。\ +**类型:** 布尔值\ +**版本历史:**\ +4.0.0 - 添加 + +## Admin::Tag 属性 {#admin} + +```json +{ + "name": "caturday", + "url": "https://mastodon.example/tags/caturday", + "history": [ + { + "day": "1669507200", + "accounts": "53", + "uses": "56" + }, + { + "day": "1669420800", + "accounts": "142", + "uses": "171" + }, + { + "day": "1669334400", + "accounts": "11", + "uses": "11" + }, + { + "day": "1669248000", + "accounts": "8", + "uses": "9" + }, + { + "day": "1669161600", + "accounts": "8", + "uses": "20" + }, + { + "day": "1669075200", + "accounts": "11", + "uses": "11" + }, + { + "day": "1668988800", + "accounts": "17", + "uses": "22" + } + ], + "id": "802", + "trendable": true, + "usable": true, + "requires_review": false +} +``` + +### `id` {#id} + +**描述:** 话题标签在数据库中的 ID。\ +**类型:** 字符串 (从整数转换而来，但不保证是数字)\ +**版本历史:**\ +3.5.0 - 添加 + +### `trendable` {#trendable} + +**描述:** 该话题标签是否已被批准成为热门话题标签。\ +**类型:** 布尔值\ +**版本历史:**\ +3.5.0 - 添加 + +### `usable` {#usable} + +**描述:** 是否未禁用自动链接到此话题标签。\ +**类型:** 布尔值\ +**版本历史:**\ +3.5.0 - 添加 + +### `requires_review` {#requires_review} + +**描述:** 该话题标签是否尚未被批准成为成为热门话题标签。\ +**类型:** 布尔值\ +**版本历史:**\ +3.5.0 - 添加 + +## 参见 + +{{< page-relref ref="entities/Search#tags" caption="搜索（`tags` 属性）" >}} + +{{< page-relref ref="methods/tags" caption="tags API 方法" >}} + +{{< page-relref ref="methods/featured_tags#suggestions" caption="GET /api/v1/featured_tags/suggestions" >}} + +{{< translation-status-zh-cn raw_title="Tag" raw_link="/entities/Tag/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Token.md b/content/zh-cn/entities/Token.md new file mode 100644 index 0000000..60df616 --- /dev/null +++ b/content/zh-cn/entities/Token.md @@ -0,0 +1,66 @@ +--- +title: Token +description: 表示用于与 API 进行身份验证和执行操作的 OAuth 令牌。 +menu: + docs: + parent: entities +aliases: [ + "/entities/token", + "/entities/Token", + "/api/entities/token", + "/api/entities/Token", +] +--- + +## 示例 + +```json +{ + "access_token": "ZA-Yj3aBD8U8Cm7lKUp-lm9O9BmDgdhHzDeqsY8tlL0", + "token_type": "Bearer", + "scope": "read write follow push", + "created_at": 1573979017 +} +``` + +## 属性 + +### `access_token` {#access_token} + +**描述:** 用于授权的 OAuth 令牌。\ +**类型:** 字符串\ +**版本历史:**\ +0.1.0 - 添加 + +### `token_type` {#token_type} + +**描述:** OAuth 令牌类型。 Mastodon 使用 `Bearer` 令牌。\ +**类型:** 字符串\ +**版本历史:**\ +0.1.0 - 添加 + +### `scope` {#scope} + +**描述:** 此令牌授予的 OAuth 作用域，以空格分隔。\ +**类型:** 字符串\ +**版本历史:**\ +0.1.0 - 添加 + +### `created_at` {#created_at} + +**描述:** 令牌生成的时间。\ +**类型:** Number (UNIX 时间戳)\ +**版本历史:**\ +0.1.0 - 添加 + +## 另请参阅 + +{{< page-relref ref="oauth-scopes" caption="OAuth 作用域" >}} + +{{< page-relref ref="methods/oauth" caption="oauth 方法" >}} + +{{< page-ref page="client/token" >}} + +{{< page-ref page="client/authorized" >}} + +{{< translation-status-zh-cn raw_title="Token" raw_link="/entities/Token/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/Translation.md b/content/zh-cn/entities/Translation.md new file mode 100644 index 0000000..9493cbc --- /dev/null +++ b/content/zh-cn/entities/Translation.md @@ -0,0 +1,147 @@ +--- +title: Translation +description: 表示机器翻译某些嘟文内容的结果 +menu: + docs: + parent: entities +aliases: [ + "/api/entities/Translation", + "/api/entities/translation", +] +--- + +## 示例 + +包含内容警告和媒体的嘟文翻译 + +```json +{ + "content": "

Hello world

", + "spoiler_text": "Greatings ahead", + "media_attachments": [ + { + "id": "22345792", + "description": "Status author waving at the camera" + } + ], + "poll": null, + "detected_source_language": "es", + "provider": "DeepL.com" +} +``` + +包含投票的嘟文翻译： +```json +{ + "content": "

Should I stay or should I go?

", + "spoiler_text": "", + "media_attachments": [], + "poll": { + "id": "34858", + "options": [ + { + "title": "Stay" + }, + { + "title": "Go" + } + ] + }, + "detected_source_language": "ja", + "provider": "DeepL.com" +} +``` + + +## 属性 + +### `content` {#content} + +**描述:** 嘟文的HTML编码的翻译内容。\ +**类型:** 字符串 (HTML)\ +**版本历史:**\ +4.0.0 - 添加 + +### `spoiler_text` {#spoiler_text} + +**描述:** 嘟文翻译后的内容警告。\ +**类型:** 字符串\ +**版本历史:**\ +4.2.0 - 添加 + +### `poll` {{%optional%}} {#poll} + +**描述:** 嘟文翻译后的投票。\ +**类型:** [Translation::Poll](#Poll)\ +**版本历史:**\ +4.2.0 - 添加 + +### `media_attachments` {#media_attachments} + +**描述:** 嘟文翻译后的媒体描述。\ +**类型:** [Translation::Attachment](#Attachment) 的数组\ +**版本历史:**\ +4.2.0 - 添加 + +### `detected_source_language` {#detected_source_language} + +**描述:** 源文本的语言，由机器翻译提供商自动检测。\ +**类型:** 字符串 (ISO 639 语言代码)\ +**版本历史:**\ +4.0.0 - 添加 + +### `provider` {#provider} + +**描述:** 机器翻译提供商。 +**类型:** 字符串\ +**版本历史:**\ +4.0.0 - 添加 + +## Translation::Poll 属性 {#Poll} + +### `id` {#Poll-id} + +**描述:** 投票的 ID。\ +**类型:** 字符串（从整数转换而来，但不保证是数字）\ +**版本历史:**\ +4.2.0 - 添加 + +### `options` {#Poll-options} + +**描述:** 翻译后的投票选项。\ +**类型:** [Translation::Poll::Option](#Option) 的数组\ +**版本历史:**\ +4.2.0 - 添加 + +## Translation::Poll::Option 属性 {#Option} + +### `title` {#Option-title} + +**描述:** 投票选项的翻译后的标题。\ +**类型:** 字符串\ +**版本历史:**\ +4.2.0 - 添加 + +## Translation::Attachment 属性 {#Attachment} + +### `id` {#Attachment-id} + +**描述:** 附件的 id。\ +**类型:** 字符串（从整数转换而来，但不保证是数字）\ +**版本历史:**\ +4.2.0 - 添加 + +### `description` {#Attachment-description} + +**描述:** 媒体附件翻译后的描述。\ +**类型:** 字符串\ +**版本历史:**\ +4.2.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/statuses#translate" caption="POST /api/v1/statuses/:id/translate" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/translation_serializer.rb" caption="app/serializers/rest/translation_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="Translation" raw_link="/entities/Translation/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/V1_Filter.md b/content/zh-cn/entities/V1_Filter.md new file mode 100644 index 0000000..dc3db51 --- /dev/null +++ b/content/zh-cn/entities/V1_Filter.md @@ -0,0 +1,91 @@ +--- +title: V1::Filter +description: 表示用户自定义的过滤规则，用于确定哪些嘟文不应向用户显示。包含单个关键词或短语。 +menu: + docs: + parent: entities +aliases: [ + "/entities/v1_filter/", + "/entities/V1_Filter", + "/api/entities/v1_filter/", + "/api/entities/V1_Filter", +] +--- + +## 示例 + +```json +{ + "id": "8449", + "phrase": "test", + "context": [ + "home", + "notifications", + "public", + "thread" + ], + "whole_word": false, + "expires_at": "2019-11-26T09:08:06.254Z", + "irreversible": true +} +``` + +## 属性 + +### `id` {#id} + +**描述:** 数据库中过滤规则的 ID。\ +**类型:** 字符串 (从整数转换而来，但不保证一定是数字)\ +**版本历史:**\ +2.4.3 - 添加 + +### `phrase` {#phrase} + +**描述:** 要过滤的文本。\ +**类型:** 字符串\ +**版本历史:**\ +2.4.3 - 添加 + +### `context` {#context} + +**描述:** 过滤规则的应用场景。\ +**类型:** 字符串数组 (可枚举的 anyOf)\ +`home` = 首页时间线和列表\ +`notifications` = 通知时间线\ +`public` = 公共时间线\ +`thread` = 展开后的嘟文串\ +`account` = 查看账户时\ +**版本历史:**\ +2.4.3 - 添加\ +3.1.0 - 添加 `account` + +### `expires_at` {#expires_at} + +**描述:** 过滤规则应不再生效的时间。\ +**类型:** {{}} 字符串 ([Datetime](/api/datetime-format#datetime))，如果过滤规则永不过期，则为 null\ +**版本历史:**\ +2.4.3 - 添加 + +### `irreversible` {#irreversible} + +**描述:** 实例是否应该删除首页和通知中该过滤规则命中的实体？请参阅[过滤规则实现指引]({{< relref "api/guidelines#filters" >}})。\ +**类型:** 布尔值\ +**版本历史:**\ +2.4.3 - 添加 + +### `whole_word` {#whole_word} + +**描述:** 过滤规则是否应考虑单词边界？请参阅[过滤规则实现指引]({{< relref "api/guidelines#filters" >}})。\ +**类型:** 布尔值\ +**版本历史:**\ +2.4.3 - 添加 + +## 另请参阅 + +{{< page-relref ref="api/guidelines#filters" caption="过滤规则实现指引" >}} + +{{< page-relref ref="methods/filters#v1" caption="v1 过滤规则 API" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/v1/filter_serializer.rb" caption="app/serializers/rest/v1/filter_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="V1::Filter" raw_link="/entities/V1_Filter/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/V1_Instance.md b/content/zh-cn/entities/V1_Instance.md new file mode 100644 index 0000000..4f7a0e6 --- /dev/null +++ b/content/zh-cn/entities/V1_Instance.md @@ -0,0 +1,421 @@ +--- +title: V1::Instance +description: 表示在此域名上运行的 Mastodon 软件实例。 +menu: + docs: + parent: entities +aliases: [ + "/entities/v1_instance", + "/entities/V1_Instance", + "/api/entities/v1_instance", + "/api/entities/V1_Instance", +] +--- + +## 示例 + +```json +{ + "uri":"mastodon.social", + "title":"Mastodon", + "short_description":"The original server operated by the Mastodon gGmbH non-profit", + "description":"", + "email":"staff@mastodon.social", + "version":"3.5.3", + "urls":{ + "streaming_api":"wss://mastodon.social" + }, + "stats":{ + "user_count":812303, + "status_count":38151616, + "domain_count":25255 + }, + "thumbnail":"https://files.mastodon.social/site_uploads/files/000/000/001/original/vlcsnap-2018-08-27-16h43m11s127.png", + "languages":[ + "en" + ], + "registrations":false, + "approval_required":false, + "invites_enabled":true, + "configuration":{ + "statuses":{ + "max_characters":500, + "max_media_attachments":4, + "characters_reserved_per_url":23 + }, + "media_attachments":{ + "supported_mime_types":[ + "image/jpeg", + "image/png", + "image/gif", + "image/webp", + "video/webm", + "video/mp4", + "video/quicktime", + "video/ogg", + "audio/wave", + "audio/wav", + "audio/x-wav", + "audio/x-pn-wave", + "audio/vnd.wave", + "audio/ogg", + "audio/vorbis", + "audio/mpeg", + "audio/mp3", + "audio/webm", + "audio/flac", + "audio/aac", + "audio/m4a", + "audio/x-m4a", + "audio/mp4", + "audio/3gpp", + "video/x-ms-asf" + ], + "image_size_limit":10485760, + "image_matrix_limit":16777216, + "video_size_limit":41943040, + "video_frame_rate_limit":60, + "video_matrix_limit":2304000 + }, + "polls":{ + "max_options":4, + "max_characters_per_option":50, + "min_expiration":300, + "max_expiration":2629746 + } + }, + "contact_account":{ + "id":"1", + "username":"Gargron", + "acct":"Gargron", + "display_name":"Eugen", + "locked":false, + "bot":false, + "discoverable":true, + "group":false, + "created_at":"2016-03-16T00:00:00.000Z", + "note":"\u003cp\u003eFounder, CEO and lead developer \u003cspan class=\"h-card\"\u003e\u003ca href=\"https://mastodon.social/@Mastodon\" class=\"u-url mention\"\u003e@\u003cspan\u003eMastodon\u003c/span\u003e\u003c/a\u003e\u003c/span\u003e, Germany.\u003c/p\u003e", + "url":"https://mastodon.social/@Gargron", + "avatar":"https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", + "avatar_static":"https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", + "header":"https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", + "header_static":"https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", + "followers_count":118944, + "following_count":305, + "statuses_count":72309, + "last_status_at":"2022-08-24", + "emojis":[ + + ], + "fields":[ + { + "name":"Patreon", + "value":"\u003ca href=\"https://www.patreon.com/mastodon\" target=\"_blank\" rel=\"nofollow noopener noreferrer me\"\u003e\u003cspan class=\"invisible\"\u003ehttps://www.\u003c/span\u003e\u003cspan class=\"\"\u003epatreon.com/mastodon\u003c/span\u003e\u003cspan class=\"invisible\"\u003e\u003c/span\u003e\u003c/a\u003e", + "verified_at":null + } + ] + }, + "rules":[ + { + "id":"1", + "text":"Sexually explicit or violent media must be marked as sensitive when posting" + }, + { + "id":"2", + "text":"No racism, sexism, homophobia, transphobia, xenophobia, or casteism" + }, + { + "id":"3", + "text":"No incitement of violence or promotion of violent ideologies" + }, + { + "id":"4", + "text":"No harassment, dogpiling or doxxing of other users" + }, + { + "id":"5", + "text":"No content illegal in Germany" + }, + { + "id":"7", + "text":"Do not share intentionally false or misleading information" + } + ] +} +``` + +## 属性 + +### `uri` {#uri} + +**描述:** 实例的域名。\ +**类型:** 字符串\ +**版本历史:**\ +1.1.0 - 添加 + +### `title` {#title} + +**描述:** 网站的标题。\ +**类型:** 字符串\ +**版本历史:**\ +1.1.0 - 添加 + +### `short_description` {#short_description} + +**描述:** 由管理员定义的简短纯文本描述。\ +**类型:** 字符串\ +**版本历史:**\ +2.9.2 - 添加 + +### `description` {#description} + +**描述:** 允许使用 HTML 的 Mastodon 站点描述。\ +**类型:** 字符串\ +**版本历史:**\ +1.1.0 - 添加 + +### `email` {#email} + +**描述:** 可供任何咨询联系的电子邮件地址。\ +**类型:** 字符串\ +**版本历史:**\ +1.1.0 - 添加 + +### `version` {#version} + +**描述:** 实例上安装的 Mastodon 版本。\ +**类型:** 字符串\ +**版本历史:**\ +1.3.0 - 添加 + +### `urls` {#urls} + +**描述:** 客户端应用感兴趣的 URL。\ +**类型:** Hash\ +**版本历史:**\ +1.4.2 - 添加 + +#### `urls[streaming_api]` {#streaming_api} + +**描述:** 用于连接到流式 API 的 Websockets URL。\ +**类型:** 字符串 (URL)\ +**版本历史:**\ +1.4.2 - 添加 + +### `stats` {#stats} + +**描述:** 关于实例包含多少信息的统计数据。\ +**类型:** Hash\ +**版本历史:**\ +1.6.0 - 添加 + +#### `stats[user_count]` {#user_count} + +**描述:** 此实例上的用户总数。\ +**类型:** 整数\ +**版本历史:**\ +1.6.0 - 添加 + +#### `stats[status_count]` {#status_count} + +**描述:** 此实例上的嘟文总数。\ +**类型:** 整数\ +**版本历史:**\ +1.6.0 - 添加 + +#### `stats[domain_count]` {#domain_count} + +**描述:** 此实例发现的域名总数。\ +**类型:** 整数\ +**版本历史:**\ +1.6.0 - 添加 + +### `thumbnail` {#thumbnail} + +**描述:** 网站的横幅图片。\ +**类型:** {{}} 字符串 (URL)\ +**版本历史:**\ +1.6.1 - 添加 + +### `languages` {#languages} + +**描述:** 网站及其工作人员的主要语言。\ +**类型:** Array of String (ISO 639-1 双字母代码)\ +**版本历史:**\ +2.3.0 - 添加 + +### `registrations` {#registrations} + +**描述:** 是否允许注册。\ +**类型:** 布尔值\ +**版本历史:**\ +2.7.2 - 添加 + +### `approval_required` {#approval_required} + +**描述:** 注册是否需要管理员批准。\ +**类型:** 布尔值\ +**版本历史:**\ +2.9.2 - 添加 + +### `invites_enabled` {#invites_enabled} + +**描述:** 是否启用了邀请。\ +**类型:** 布尔值\ +**版本历史:**\ +3.1.4 - 添加 + +### `configuration` {#configuration} + +**描述:** 此网站的配置值和限制。\ +**类型:** Hash\ +**版本历史:**\ +3.4.2 - 添加 + +#### `configuration[accounts]` {#accounts} + +**描述:** 与帐户相关的限制。\ +**类型:** Hash\ +**版本历史:**\ +4.0.0 - 添加 + +##### `configuration[accounts][max_featured_tags]` {#max_featured_tags} + +**描述:** 每个帐户允许的最大特色话题标签数。\ +**类型:** 整数\ +**版本历史:**\ +4.0.0 - 添加 + +#### `configuration[statuses]` {#statuses} + +**描述:** 与发布嘟文相关的限制。\ +**类型:** Hash\ +**版本历史:**\ +3.4.2 - 添加 + +##### `configuration[statuses][max_characters]` {#max_characters} + +**描述:** 每条嘟文允许的最大字符数。\ +**类型:** 整数\ +**版本历史:**\ +3.4.2 - 添加 + +##### `configuration[statuses][max_media_attachments]` {#max_media_attachments} + +**描述:** 可以添加到嘟文的媒体附件的最大数量。\ +**类型:** 整数\ +**版本历史:**\ +3.4.2 - 添加 + +##### `configuration[statuses][characters_reserved_per_url]` {#characters_reserved_per_url} + +**描述:** 嘟文中的每个 URL 将被假定占据的字符数。\ +**类型:** 整数\ +**版本历史:**\ +3.4.2 - 添加 + +#### `configuration[media_attachments]` {#media_attachments} + +**描述:** 有关可接受的媒体附件格式范围的提示。\ +**类型:** Hash\ +**版本历史:**\ +3.4.2 - 添加 + +##### `configuration[media_attachments][supported_mime_types]` {#supported_mime_types} + +**描述:** 包含可以上传的 MIME 类型。\ +**类型:** 字符串数组\ +**版本历史:**\ +3.4.2 - 添加 + +##### `configuration[media_attachments][image_size_limit]` {#image_size_limit} + +**描述:** 所有上传图像的最大大小（以字节为单位）。\ +**类型:** 整数\ +**版本历史:**\ +3.4.2 - 添加 + +##### `configuration[media_attachments][image_matrix_limit]` {#image_matrix_limit} + +**描述:** 图像上传的最大像素数（宽度乘以高度）。\ +**类型:** 整数\ +**版本历史:**\ +3.4.2 - 添加 + +##### `configuration[media_attachments][video_size_limit]` {#video_size_limit} + +**描述:** 所有上传视频的最大大小（以字节为单位）。\ +**类型:** 整数\ +**版本历史:**\ +3.4.2 - 添加 + +##### `configuration[media_attachments][video_frame_rate_limit]` {#video_frame_rate_limit} + +**描述:** 所有上传视频的最大帧速率。\ +**类型:** 整数\ +**版本历史:**\ +3.4.2 - 添加 + +##### `configuration[media_attachments][video_matrix_limit]` {#video_matrix_limit} + +**描述:** 视频上传的最大像素数（宽度乘以高度）。\ +**类型:** 整数\ +**版本历史:**\ +3.4.2 - 添加 + +#### `configuration[polls]` {#polls} + +**描述:** 与投票相关的限制。\ +**类型:** Hash\ +**版本历史:**\ +3.4.2 - 添加 + +##### `configuration[polls][max_options]` {#max_options} + +**描述:** 每次投票最多允许的选项数。\ +**类型:** 整数\ +**版本历史:**\ +3.4.2 - 添加 + +##### `configuration[polls][max_characters_per_option]` {#max_characters_per_option} + +**描述:** 每个投票选项允许包含的字符数。\ +**类型:** 整数\ +**版本历史:**\ +3.4.2 - 添加 + +##### `configuration[polls][min_expiration]` {#min_expiration} + +**描述:** 允许的最短投票持续时间（以秒为单位）。\ +**类型:** 整数\ +**版本历史:**\ +3.4.2 - 添加 + +##### `configuration[polls][max_expiration]` {#max_expiration} + +**描述:** 允许的最长投票持续时间（以秒为单位）。\ +**类型:** 整数\ +**版本历史:**\ +3.4.2 - 添加 + +### `contact_account` {#contact_account} + +**描述:** 可供联系的用户，作为 `email` 的替代方案。\ +**类型:** {{}} [Account]({{< relref "entities/Account" >}}) or null\ +**版本历史:**\ +2.3.0 - 添加 + +### `rules` {#rules} + +**描述:** 此网站的规则的详细列表。\ +**类型:** [Rule]({{< relref "entities/Rule" >}}) 的数组\ +**版本历史:**\ +3.4.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/instance#v1" caption="GET /api/v1/instance" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/v1/instance_serializer.rb" caption="app/serializers/rest/v1/instance_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="V1::Instance" raw_link="/entities/V1_Instance/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/V1_NotificationPolicy.md b/content/zh-cn/entities/V1_NotificationPolicy.md new file mode 100644 index 0000000..da59805 --- /dev/null +++ b/content/zh-cn/entities/V1_NotificationPolicy.md @@ -0,0 +1,92 @@ +--- +title: V1::NotificationPolicy +description: 表示用户的通知过滤策略。 +menu: + docs: + parent: entities +aliases: [ + "/entities/v1_NotificationPolicy", +] +--- + +{{< hint style="warning" >}} +此版本的通知过滤策略 API 已弃用，且未在任何版本中发布。请参考[当前版本]({{< relref "entities/NotificationPolicy">}}) 。 +{{}} + +## 属性 + +### `filter_not_following` {#filter_not_following} + +**描述:** 是否过滤来自用户未关注帐户的通知。\ +**类型:** 布尔值\ +**版本历史:**\ +4.3.0 - 添加 + +### `filter_not_followers` {#filter_not_followers} + +**描述:** 是否过滤来自未关注用户的帐户的通知。\ +**类型:** 布尔值\ +**版本历史:**\ +4.3.0 - 添加 + +### `filter_new_accounts` {#filter_new_accounts} + +**描述:** 是否过滤来自过去 30 天内创建的帐户的通知。\ +**类型:** 布尔值\ +**版本历史:**\ +4.3.0 - 添加 + +### `filter_private_mentions` {#filter_private_mentions} + +**描述:** 是否过滤私下提及的通知。对由用户发起的私下提及的回复，以及用户关注的帐户发起的私下提及永远不会被过滤。\ +**类型:** 布尔值\ +**版本历史:**\ +4.3.0 - 添加 + +### `summary` {#summary} + +**描述:** 已过滤通知的摘要 +**类型:** Hash\ +**版本历史:**\ +4.3.0 - 添加 + +### `summary[pending_requests_count]` {#pending_requests_count} + +**描述:** 用户收到但未忽略的已过滤通知的来源帐户的数量。上限为 100。 +**类型:** 整数\ +**版本历史:**\ +4.3.0 - 添加 + +### `summary[pending_notifications_count]` {#pending_notifications_count} + +**描述:** 未忽略的已过滤通知的总数。可能不准确。 +**类型:** 整数\ +**版本历史:**\ +4.3.0 - 添加 + +## 示例 + +```json + +{ + "filter_not_following": false, + "filter_not_followers": false, + "filter_new_accounts": false, + "filter_private_mentions": true, + "summary": { + "pending_requests_count": 0, + "pending_notifications_count": 0 + } +} + +``` + +## 另请参考 + +{{< page-relref ref="entities/NotificationPolicy" caption="NotificationPolicy（已发布版本）" >}} + +{{< page-relref ref="methods/notifications" caption="notifications API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/v1/notification_policy_serializer.rb" caption="app/serializers/rest/v1/notification_policy_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="V1::NotificationPolicy" raw_link="/entities/V1_NotificationPolicy/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/entities/WebPushSubscription.md b/content/zh-cn/entities/WebPushSubscription.md new file mode 100644 index 0000000..a22d7a3 --- /dev/null +++ b/content/zh-cn/entities/WebPushSubscription.md @@ -0,0 +1,155 @@ +--- +title: WebPushSubscription +description: 表示一个对流式推送的订阅。 +menu: + docs: + parent: entities +aliases: [ + "/entities/pushsubscription", + "/entities/PushSubscription", + "/entities/webpushsubscription", + "/entities/WebPushSubscription", + "/api/entities/pushsubscription", + "/api/entities/PushSubscription", + "/api/entities/webpushsubscription", + "/api/entities/WebPushSubscription", +] +--- + +## 示例 + +```json +{ + "id": 328183, + "endpoint": "https://yourdomain.example/listener", + "standard": true, + "alerts": { + "follow": false, + "favourite": false, + "reblog": false, + "mention": true, + "poll": false + }, + "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" +} +``` + +## 属性 + +### `id` {#id} + +**描述:** Web Push 订阅在数据库中的ID。\ +**类型:** 字符串 (从整数转换而来，但不保证一定为数字)\ +**版本历史:**\ +2.4.0 - 添加 + +### `endpoint` {#endpoint} + +**描述:** 推送通知将发送到的地址。\ +**类型:** 字符串（URL）\ +**版本历史:**\ +2.4.0 - 添加 + +### `standard` {#standard} + +**描述:** 推送消息是否遵循标准化规范 (RFC8030+RFC8291+RFC8292)。若为 `false`，则遵循该规范的旧版本（RFC8291 的第 4 版草案和 RFC8292 的第 1 版草案）。 +**类型:** 布尔值\ +**版本历史:**\ +4.4.0 - 添加 + +### `server_key` {#server_key} + +**描述:** 流式推送实例的 VAPID 密钥。\ +**类型:** 字符串\ +**版本历史:**\ +2.4.0 - 添加 + +### `alerts` {#alerts} + +**描述:** 哪些提醒会被传递到 `endpoint`。\ +**类型:** 哈希\ +**版本历史:**\ +2.4.0 - 添加\ +2.8.0 - 添加 `alerts[poll]`\ +3.1.0 - 添加 `alerts[follow_request]`\ +3.3.0 - 添加 `alerts[status]`\ +3.5.0 - 添加 `alerts[update]` 和 `alerts[admin.sign_up]`\ +4.0.0 - 添加 `alerts[admin.report]` + +#### `alerts[mention]` {#mention} + +**描述:** 当有人在嘟文中提及你时，是否接收推送通知？\ +**类型:** 布尔值\ +**版本历史:**\ +2.4.0 - 添加 + +#### `alerts[status]` {#status} + +**描述:** 当启用了发嘟通知的帐户发布嘟文时，是否接收推送通知？\ +**类型:** 布尔值\ +**版本历史:**\ +3.3.0 - 添加 + +#### `alerts[reblog]` {#reblog} + +**描述:** 当你创建的嘟文被其他人转发时，是否接收推送通知？\ +**类型:** 布尔值\ +**版本历史:**\ +2.4.0 - 添加 + +#### `alerts[follow]` {#follow} + +**描述:** 当有人关注你时，是否接收推送通知？\ +**类型:** 布尔值\ +**版本历史:**\ +2.4.0 - 添加 + +#### `alerts[follow_request]` {#follow_request} + +**描述:** 当有人请求关注你时，是否接收推送通知？\ +**类型:** 布尔值\ +**版本历史:**\ +3.1.0 - 添加 + +#### `alerts[favourite]` {#favourite} + +**描述:** 当你创建的嘟文被其他人喜欢时，是否接收推送通知？\ +**类型:** 布尔值\ +**版本历史:**\ +2.4.0 - 添加 + +#### `alerts[poll]` {#poll} + +**描述:** 当你投票或创建的投票结束时，是否接收推送通知？\ +**类型:** 布尔值\ +**版本历史:**\ +2.8.0 - 添加 + +#### `alerts[update]` {#update} + +**描述:** 当你互动过的嘟文被编辑时，是否接收推送通知？\ +**类型:** 布尔值\ +**版本历史:**\ +3.5.0 - 添加 + +#### `alerts[admin.sign_up]` {#admin-sign_up} + +**描述:** 当有新用户注册时，是否接收推送通知？\ +**类型:** 布尔值\ +**版本历史:**\ +3.5.0 - 添加 + +#### `alerts[admin.report]` {#admin-report} + +**描述:** 当提交新的举报时，是否接收推送通知？\ +**类型:** 布尔值\ +**版本历史:**\ +4.0.0 - 添加 + +## 参见 + +{{< page-relref ref="methods/push" caption="push API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/web_push_subscription_serializer.rb" caption="app/serializers/rest/web_push_subscription_serializer.rb" >}} + +{{< translation-status-zh-cn raw_title="WebPushSubscription" raw_link="/entities/WebPushSubscription/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/accounts.md b/content/zh-cn/methods/accounts.md new file mode 100644 index 0000000..536de97 --- /dev/null +++ b/content/zh-cn/methods/accounts.md @@ -0,0 +1,2365 @@ +--- +title: accounts API 方法 +description: 关于账户和账户资料的方法。 +menu: + docs: + weight: 20 + name: accounts + parent: methods + identifier: methods-accounts +aliases: [ + "/methods/accounts", + "/api/methods/accounts" +] +--- + + + +## 注册账户 {#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 +: {{}} 提供此标头与 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +username +: {{}} 字符串。账户所需的用户名。 + +email +: {{}} 字符串。用于登录的电子邮件地址。 + +password +: {{}} 字符串。用于登录的密码。 + +agreement +: {{}} 布尔值。用户是否同意本站规则、条款和政策。应向用户展示这些内容，以便他们在将此参数设置为 TRUE 之前表示同意。 + +locale +: {{}} 字符串。将发送的确认电子邮件的语言。 + +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 +: {{}} 提供此标头与 `Bearer `，以获得对此 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": "

i have approximate knowledge of many things. perpetual student. (nb/ace/they)

xmpp/email: a@trwnh.com
https://trwnh.com
help me live: https://liberapay.com/at or https://paypal.me/trwnh

- my triggers are moths and glitter
- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise
- dm me if i did something wrong, so i can improve
- purest person on fedi, do not lewd in my presence
- #1 ami cole fan account

:fatyoshi:

", + "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": "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 + } + ] +} +``` + +##### 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 +: {{}} 提供此标头与 `Bearer `，以获得对此 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": "

i have approximate knowledge of many things. perpetual student. (nb/ace/they)

xmpp/email: a@trwnh.com
https://trwnh.com
help me live: https://liberapay.com/at or https://paypal.me/trwnh

- my triggers are moths and glitter
- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise
- dm me if i did something wrong, so i can improve
- purest person on fedi, do not lewd in my presence
- #1 ami cole fan account

:fatyoshi:

", + "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": "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 + } + ] +} +``` + +##### 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 +: {{}} 字符串。数据库中账户的 ID。 + +##### 标头 + +Authorization +: 提供此标头与 `Bearer `，以获得对此 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": "

Developer of Mastodon and administrator of mastodon.social. I post service announcements, development updates, and personal stuff.

", + "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": "https://www.patreon.com/mastodon", + "verified_at": null + }, + { + "name": "Homepage", + "value": "https://zeonfederated.com", + "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": "

:ms_rainbow_flag:​ :ms_bisexual_flag:​ :ms_nonbinary_flag:​ #awoo.space #admin ~ #bi ~ #nonbinary ~ compsci student ~ likes video #games and weird/ old electronics and will post obsessively about both ~ avatar by @dzuk

", + "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": "@noiob", + "verified_at": null + }, + { + "name": "Bots", + "value": "@darksouls, @nierautomata, code for @awoobot", + "verified_at": null + }, + { + "name": "Website", + "value": "http://shork.xyz", + "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": "

Developer of Mastodon and administrator of mastodon.social. I post service announcements, development updates, and personal stuff.

", + "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": "https://www.patreon.com/mastodon", + "verified_at": null + }, + { + "name": "Homepage", + "value": "https://zeonfederated.com", + "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 +: {{}} 字符串。数据库中账户的 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 +: {{}} 字符串。数据库中账户的 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 响应分页]({{}})。 + +```http +Link: ; rel="next", ; 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 +: {{}} 字符串。数据库中账户的 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 响应分页]({{}})。 + +```http +Link: ; rel="next", ; 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 +: {{}} 字符串。数据库中账户的 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 +: {{}} 字符串。数据库中账户的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头并附带 `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 +: {{}} 字符串。数据库中账户的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头并附带 `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 +: {{}} 字符串。数据库中账户的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头并附带 `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 +: {{}} 字符串。账户在数据库中的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，格式为 `Bearer `，以获取对此 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 +: {{}} 字符串。账户在数据库中的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，格式为 `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" +} +``` + +--- + +## 隐藏账户 {#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 +: {{}} 字符串。账户在数据库中的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，格式为 `Bearer `，以获取对此 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 +: {{}} 字符串。账户在数据库中的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，格式为 `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": "访问令牌无效" +} +``` + +##### 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 +: {{}} 字符串。账户在数据库中的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，格式为 `Bearer `，以获取对此 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 +: {{}} 字符串。账户在数据库中的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，格式为 `Bearer `，以获取对此 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 +: {{}} 字符串。账户在数据库中的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，格式为 `Bearer `，以获取对此 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 +: {{}} 提供此标头，格式为 `Bearer `，以获取对此 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 +: {{}} 提供此标头，格式为 `Bearer `，以获取对此 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 +: {{}} （必填）提供此请求头，格式为 `Bearer `，以获得对该 API 方法的授权访问权限。 + +##### 查询参数 + +q +: {{}} （必填）字符串。账户的搜索查询。 + +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 +: {{}} （必填）字符串。要查询的用户名或 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 +: {{}} （必填）字符串。数据库中账户的 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-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/admin/_index.md b/content/zh-cn/methods/admin/_index.md new file mode 100644 index 0000000..01b8cbc --- /dev/null +++ b/content/zh-cn/methods/admin/_index.md @@ -0,0 +1,12 @@ +--- +title: admin API 方法 +description: 查看和管理管理信息。 +menu: + docs: + weight: 80 + name: admin + parent: methods + identifier: methods-admin +--- + +{{< translation-status-zh-cn raw_title="admin API methods" raw_link="/methods/admin/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/admin/accounts.md b/content/zh-cn/methods/admin/accounts.md new file mode 100644 index 0000000..5c348c0 --- /dev/null +++ b/content/zh-cn/methods/admin/accounts.md @@ -0,0 +1,1037 @@ +--- +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-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/admin/canonical_email_blocks.md b/content/zh-cn/methods/admin/canonical_email_blocks.md new file mode 100644 index 0000000..40a590e --- /dev/null +++ b/content/zh-cn/methods/admin/canonical_email_blocks.md @@ -0,0 +1,315 @@ +--- +title: canonical_email_blocks API 方法 +description: 通过哈希值屏蔽某些电子邮件地址。 +menu: + docs: + name: canonical_email_blocks + parent: methods-admin + identifier: methods-admin-canonical_email_blocks +aliases: [ + "/methods/admin/canonical_email_blocks", + "/api/methods/admin/canonical_email_blocks", +] +--- + + + +## 列出所有标准电子邮件屏蔽 {#get} + +```http +GET /api/v1/admin/canonical_email_blocks HTTP/1.1 +``` + +**返回：** [Admin::CanonicalEmailBlock]({{< relref "entities/Admin_CanonicalEmailBlock" >}}) 数组\ +**OAuth：** 用户令牌 + `admin:read:canonical_email_blocks`\ +**权限：** 管理屏蔽\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +since_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +min_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +limit +: 整数。要返回的最大结果数。默认为 100 个屏蔽。最多 200 个屏蔽。 + +#### 响应 +##### 200: OK + +```json +[ + { + "id": "1", + "canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c" + }, + // ... +] +``` + +由于 CanonicalEmailBlock ID 通常不通过任何 API 响应公开，因此你必须解析 HTTP `Link` 标头以加载较旧或较新的结果。有关详细信息，请参阅[通过 API 响应分页]({{}})。 + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 403: Forbidden + +授权用户缺少权限，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## 显示单个标准电子邮件屏蔽 {#get-one} + +```http +GET /api/v1/admin/canonical_email_blocks/:id HTTP/1.1 +``` + +**返回：** [Admin::CanonicalEmailBlock]({{< relref "entities/Admin_CanonicalEmailBlock" >}})\ +**OAuth：** 用户令牌 + `admin:read:canonical_email_blocks`\ +**权限：** 管理屏蔽\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 Admin::CanonicalEmailBlock 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{ + "id": "1", + "canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c" +} +``` + +##### 403: Forbidden + +授权用户缺少权限，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +标准电子邮件屏蔽不存在或已被删除 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 测试 {#test} + +```http +POST /api/v1/admin/canonical_email_blocks/test HTTP/1.1 +``` + +标准并哈希电子邮件地址。 + +**返回：** [Admin::CanonicalEmailBlock]({{< relref "entities/Admin_CanonicalEmailBlock" >}}) 数组\ +**OAuth：** 用户令牌 + `admin:read:canonical_email_blocks`\ +**权限：** 管理屏蔽\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +email +: {{}} 字符串。要进行规范化和哈希的电子邮件地址。 + +#### 响应 +##### 200: OK + +返回所有匹配的标准电子邮件屏蔽。 + +```json +[ + { + "id": "1", + "canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c" + } +] +``` + +##### 403: Forbidden + +授权用户缺少权限，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 500: Server error + +未提供电子邮件 + +--- + +## 屏蔽标准电子邮件 {#create} + +```http +POST /api/v1/admin/canonical_email_blocks HTTP/1.1 +``` + +**返回：** [Admin::CanonicalEmailBlock]({{< relref "entities/Admin_CanonicalEmailBlock" >}})\ +**OAuth：** 用户令牌 + `admin:write:canonical_email_blocks`\ +**权限：** 管理屏蔽\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +email +: {{}} 字符串。要进行规范化、哈希和屏蔽的电子邮件地址。若提供了此参数，则将忽略 `canonical_email_hash`。 + +canonical_email_hash +: 字符串。要测试的哈希值。若未提供 `email`，则需要此参数。 + +#### 响应 +##### 200: OK + +标准电子邮件已成功屏蔽 + +```json +{ + "id": "1", + "canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c" +} +``` + +##### 403: Forbidden + +授权用户缺少权限，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 422: Unprocessable entity + +标准电子邮件哈希已被屏蔽 + +```json +{ + "error":"Validation failed: Canonical email hash has already been taken" +} +``` + +--- + +## 删除标准电子邮件屏蔽 {#delete} + +```http +DELETE /api/v1/admin/canonical_email_blocks/:id HTTP/1.1 +``` + +**返回：** [Admin::CanonicalEmailBlock]({{< relref "entities/Admin_CanonicalEmailBlock" >}})\ +**OAuth：** 用户令牌 + `admin:write:canonical_email_blocks`\ +**权限：** 管理屏蔽\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 Admin::CanonicalEmailBlock 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +标准电子邮件屏蔽已成功删除。 + +```json +{} +``` + +##### 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/canonical_email_blocks_controller.rb" caption="app/controllers/api/v1/admin/canonical_email_blocks_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="canonical_email_blocks API methods" raw_link="/methods/admin/canonical_email_blocks/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/admin/dimensions.md b/content/zh-cn/methods/admin/dimensions.md new file mode 100644 index 0000000..4546077 --- /dev/null +++ b/content/zh-cn/methods/admin/dimensions.md @@ -0,0 +1,260 @@ +--- +title: dimensions API 方法 +description: 获取有关实例的定性指标。 +menu: + docs: + name: dimensions + parent: methods-admin + identifier: methods-admin-dimensions +aliases: [ + "/methods/admin/dimensions", + "/api/methods/admin/dimensions", +] +--- + + + +## 获取维度数据 {#get} + +```http +POST /api/v1/admin/dimensions HTTP/1.1 +``` + +获取有关某些帐户、实例、语言等受欢迎程度的信息。 + +**返回：** [Admin::Dimension]({{< relref "entities/Admin_Dimension" >}}) 数组\ +**OAuth：** 用户令牌 + `admin:read`\ +**权限：** 查看管理面板\ +**版本历史：**\ +3.5.0 - 添加\ +4.0.0 - 支持自定义用户组和权限 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +keys[] +: {{}} 字符串数组。按对应的键字符串请求特定维度。支持的维度包括： +- `languages` = 此实例上最常用的语言 +- `sources` = 此实例上最常用的客户端应用 +- `servers` = 嘟文最多的外站实例 +- `space_usage` = 你的软件堆栈使用了多少空间 +- `software_versions` = 你的软件堆栈的版本号 +- `tag_servers` = 包含热门话题标签的嘟文的最常见实例 +- `tag_languages` = 包含热门话题标签的嘟文的最常用语言 +- `instance_accounts` = 来自外站实例的最受关注的帐户 +- `instance_languages` = 来自外站实例的最常用的语言 + +start_at +: ([Datetime](/api/datetime-format#datetime)) 字符串。时间段的开始日期。若提供了时间，它将被忽略。 + +end_at +: ([Datetime](/api/datetime-format#datetime)) 字符串。时间段的结束日期。若提供了时间，它将被忽略。 + +limit +: 整数。要为来源、实例、语言、标签或实例维度返回的最大结果数。 + +tag_servers[id] +: 字符串。当 `tag_servers` 是请求的键之一时，你必须提供一个热门话题标签 ID 才能获得有关哪些实例正在发布该标签的信息。 + +tag_languages[id] +: 字符串。当 `tag_languages` 是请求的键之一时，你必须提供一个热门话题标签 ID 才能获得有关哪些语言正在发布该标签的信息。 + +instance_accounts[domain] +: 字符串。当 `instance_accounts` 是请求的键之一时，你必须提供一个域名才能获得有关来自该实例的受欢迎帐户的信息。 + +instance_languages[domain] +: 字符串。当 `instance_accounts` 是请求的键之一时，你必须提供一个域名才能获得有关来自该实例的受欢迎语言的信息。 + +#### 响应 + +##### 200: OK + +请求 mastodon.social 上的数据以及给定热门话题标签，条目限制为 2。 + +```json +[ + { + "key": "languages", + "data": [ + { + "key": "en", + "human_key": "English", + "value": "10" + }, + { + "key": "es", + "human_key": "Spanish", + "value": "1" + } + ] + }, + { + "key": "sources", + "data": [ + { + "key": "web", + "human_key": "Website", + "value": "3" + } + ] + }, + { + "key": "servers", + "data": [ + { + "key": "botsin.space", + "human_key": "botsin.space", + "value": "13738" + }, + { + "key": "monads.online", + "human_key": "monads.online", + "value": "8928" + } + ] + }, + { + "key": "space_usage", + "data": [ + { + "key": "postgresql", + "human_key": "PostgreSQL", + "value": "49581359907", + "unit": "bytes", + "human_value": "46.2 GB" + }, + { + "key": "redis", + "human_key": "Redis", + "value": "100765744", + "unit": "bytes", + "human_value": "96.1 MB" + }, + { + "key": "media", + "human_key": "Media storage", + "value": "837837315424", + "unit": "bytes", + "human_value": "780 GB" + } + ] + }, + { + "key": "software_versions", + "data": [ + { + "key": "mastodon", + "human_key": "Mastodon", + "value": "3.5.1+chitter", + "human_value": "3.5.1+chitter" + }, + { + "key": "ruby", + "human_key": "Ruby", + "value": "3.0.3p157", + "human_value": "3.0.3p157" + }, + { + "key": "postgresql", + "human_key": "PostgreSQL", + "value": "14.3", + "human_value": "14.3" + }, + { + "key": "redis", + "human_key": "Redis", + "value": "6.2.7", + "human_value": "6.2.7" + } + ] + }, + { + "key": "instance_languages", + "data": [ + { + "key": "en", + "human_key": "English", + "value": "5848" + }, + { + "key": "de", + "human_key": "German", + "value": "155" + } + ] + }, + { + "key": "instance_accounts", + "data": [ + { + "key": "fribbledom", + "human_key": "fribbledom", + "value": "33" + }, + { + "key": "ShugoWah", + "human_key": "ShugoWah", + "value": "26" + } + ] + }, + { + "key": "tag_servers", + "data": [ + { + "key": "live.hatnix.net", + "human_key": "live.hatnix.net", + "value": "6" + }, + { + "key": "linuxrocks.online", + "human_key": "linuxrocks.online", + "value": "4" + } + ] + }, + { + "key": "tag_languages", + "data": [ + { + "key": "und", + "human_key": "und", + "value": "8" + }, + { + "key": "en", + "human_key": "English", + "value": "7" + } + ] + } +] +``` + +##### 403: Forbidden + +授权用户缺少权限，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/dimensions_controller.rb" caption="app/controllers/api/v1/admin/dimensions_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/dimension.rb" caption="app/lib/admin/metrics/dimension.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/dimension/" caption="app/lib/admin/metrics/dimension/" >}} + +{{< translation-status-zh-cn raw_title="dimensions API methods" raw_link="/methods/admin/dimensions/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/admin/domain_allows.md b/content/zh-cn/methods/admin/domain_allows.md new file mode 100644 index 0000000..0b2cb28 --- /dev/null +++ b/content/zh-cn/methods/admin/domain_allows.md @@ -0,0 +1,272 @@ +--- +title: domain_allows API 方法 +description: 允许特定域名进行联合。 +menu: + docs: + name: domain_allows + parent: methods-admin + identifier: methods-admin-domain_allows +aliases: [ + "/methods/admin/domain_allows", + "/api/methods/admin/domain_allows", +] +--- + + + +## 列出所有允许的域名 {#get} + +```http +GET /api/v1/admin/domain_allows HTTP/1.1 +``` + +显示关于所有允许的域名的信息。 + +**返回:** [Admin::DomainAllow]({{< relref "entities/Admin_DomainAllow" >}}) 数组\ +**OAuth:** 用户令牌 + `admin:read:domain_allows`\ +**权限:** 管理联合\ +**版本历史:**\ +4.0.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含`Bearer `，以获得对此API方法的访问授权。 + +##### 查询参数 + +max_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +since_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +min_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +limit +: 整数。要返回的最大结果数。 默认为 100 个允许的域名。 最大 200 个允许的域名。 + +#### 响应 + +##### 200: OK + +```json +[ + { + "id": "2", + "domain": "mastodon", + "created_at": "2022-09-14T21:24:15.360Z" + }, + { + "id": "1", + "domain": "mastodon.social", + "created_at": "2022-09-14T21:23:02.755Z" + } +] +``` + +由于 DomainAllow ID 通常不通过任何 API 响应公开，因此你必须解析 HTTP `Link` 标头以加载较旧或较新的结果。 有关更多信息，请参见[通过 API 响应进行分页]({{}})。 + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 403: Forbidden + +授权用户不允许执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## 获取单个允许的域名 {#get-one} + +```http +GET /api/v1/admin/domain_allows/:id HTTP/1.1 +``` +显示有关单个允许的域名的信息。 + +**返回:** [Admin::DomainAllow]({{< relref "entities/Admin_DomainAllow" >}})\ +**OAuth:** 用户令牌 + `admin:read:domain_allows`\ +**权限:** 管理联合\ +**版本历史:**\ +4.0.0 - 添加 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 DomainAllow 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含`Bearer `，以获得对此API方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{ + "id": "1", + "domain": "mastodon.social", + "created_at": "2022-09-14T21:23:02.755Z" +} +``` + +##### 403: Forbidden + +授权用户不允许执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +具有给定 ID 的 DomainAllow 不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 允许一个域名进行联合 {#create} + +```http +POST /api/v1/admin/domain_allows HTTP/1.1 +``` + +将一个域名添加到允许进行联合的域名列表中，当实例处于有限联合模式时使用。 + +**返回:** [Admin::DomainAllow]({{< relref "entities/Admin_DomainAllow" >}})\ +**OAuth:** 用户令牌 + `admin:write:domain_allows`\ +**权限:** 管理联合\ +**版本历史:**\ +4.0.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含`Bearer `，以获得对此API方法的访问授权。 + +##### 表单数据参数 + +domain +: {{}} 字符串。要允许与其进行联合的域名。 + +#### 响应 +##### 200: OK + +域名已被允许进行联合，或者已经被允许进行联合 + +```json +{ + "id": "1", + "domain": "mastodon.social", + "created_at": "2022-09-14T21:23:02.755Z" +} +``` + +##### 403: Forbidden + +授权用户不允许执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 422: Unprocessable entity + +未提供域名参数或域名参数无效 + +```json +{ + "error": "Validation failed: Domain can't be blank" +} +``` + +--- + +## 删除一个允许的域名 {#delete} + +```http +DELETE /api/v1/admin/domain_allows/:id HTTP/1.1 +``` + +从允许的域名列表中删除一个域名。 + +**返回:** [Admin::DomainAllow]({{< relref "entities/Admin_DomainAllow" >}})\ +**OAuth:** 用户令牌 + `admin:write:domain_allows`\ +**权限:** 管理联合\ +**版本历史:**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 DomainAllow 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含`Bearer `，以获得对此API方法的访问授权。 + +#### 响应 +##### 200: OK + +允许的域名已从允许列表中删除 + +```json +{ + "id": "4", + "domain": "*", + "created_at": "2022-09-14T21:32:44.945Z" +} +``` +##### 403: Forbidden + +授权用户不允许执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +具有给定 ID 的 DomainAllow 不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/domain_allows_controller.rb" caption="app/controllers/api/v1/admin/domain_allows_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="domain_allows API methods" raw_link="/methods/admin/domain_allows/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/admin/domain_blocks.md b/content/zh-cn/methods/admin/domain_blocks.md new file mode 100644 index 0000000..0be6ece --- /dev/null +++ b/content/zh-cn/methods/admin/domain_blocks.md @@ -0,0 +1,406 @@ +--- +title: admin/domain_blocks API 方法 +description: 禁止某些域名参与联合。 +menu: + docs: + name: domain_blocks + parent: methods-admin + identifier: methods-admin-domain_blocks +aliases: [ + "/methods/admin/domain_blocks", + "/api/methods/admin/domain_blocks", +] +--- + + + +## 列出所有被屏蔽的域名 {#get} + +```http +GET /api/v1/admin/domain_blocks HTTP/1.1 +``` + +显示所有被屏蔽的域名的信息。 + +**返回：** [Admin::DomainBlock]({{< relref "entities/Admin_DomainBlock" >}}) 数组\ +**OAuth：** 用户令牌 + `admin:read:domain_blocks`\ +**权限：** 管理联合\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +since_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +min_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +limit +: 整数。要返回的最大结果数。默认为 100 个屏蔽域名。最多 200 个屏蔽域名。 + +#### 响应 + +##### 200: OK + +```json +[ + { + "id": "1", + "domain": "example.com", + "digest": "a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce1947", + "created_at": "2022-11-16T08:15:34.238Z", + "severity": "noop", + "reject_media": false, + "reject_reports": false, + "private_comment": null, + "public_comment": null, + "obfuscate": false + }, + // ... +] +``` + +由于 DomainBlock ID 通常不会通过任何 API 响应公开，因此你必须解析 HTTP `Link` 标头以加载较旧或较新的结果。 有关更多信息，请参见[通过 API 响应进行分页]({{}})。 + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 403: Forbidden + +授权用户无权执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## 获取单个被屏蔽的域名 {#get-one} + +```http +GET /api/v1/admin/domain_blocks/:id HTTP/1.1 +``` +显示有关单个被屏蔽域名的信息。 + +**返回：** [Admin::DomainBlock]({{< relref "entities/Admin_DomainBlock" >}})\ +**OAuth：** 用户令牌 + `admin:read:domain_blocks`\ +**权限：** 管理联合\ +**版本历史：**\ +4.0.0 - 添加 + +##### 路径参数 + +:id +: {{}} 字符串。 数据库中 DomainBlock 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{ + "id": "1", + "domain": "example.com", + "digest": "a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce1947", + "created_at": "2022-11-16T08:15:34.238Z", + "severity": "noop", + "reject_media": false, + "reject_reports": false, + "private_comment": null, + "public_comment": null, + "obfuscate": false +} +``` + +##### 403: Forbidden + +授权用户无权执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +不存在具有给定 ID 的 DomainBlock + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 阻止域名参与联合 {#create} + +```http +POST /api/v1/admin/domain_blocks HTTP/1.1 +``` + +将域名添加到被阻止参与联合的域名列表中。 + +**返回：** [Admin::DomainBlock]({{< relref "entities/Admin_DomainBlock" >}})\ +**OAuth：** 用户令牌 + `admin:write:domain_blocks`\ +**权限：** 管理联合\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +domain +: {{}} 字符串。 要阻止联合的域名。 + +severity +: 字符串。 是否对域名应用 `silence`、`suspend` 或 `noop`。 默认为 `silence` + +reject_media +: 布尔值。 是否应拒绝媒体附件。 默认为 false + +reject_reports +: 布尔值。 是否应拒绝来自此域名的举报。 默认为 false + +private_comment +: 字符串。 关于此域名屏蔽的私密注释，仅管理员可见。 + +public_comment +: 字符串。 关于此域名屏蔽的公开注释，可以选择在“关于”页面上显示。 + +obfuscate +: 布尔值。 是否在公开显示时部分遮挡该域名。 默认为 false + +#### 响应 +##### 200: OK + +该域名已被阻止参与联合。 + +```json +{ + "id": "1", + "domain": "example.com", + "digest": "a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce1947", + "created_at": "2022-11-16T08:15:34.238Z", + "severity": "noop", + "reject_media": false, + "reject_reports": false, + "private_comment": null, + "public_comment": null, + "obfuscate": false +} +``` + +##### 403: Forbidden + +授权用户无权执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 422: Unprocessable entity-缺少参数 + +未提供域名参数 + +```json +{ + "error": "Validation failed: Domain can't be blank" +} +``` + +##### 422: Unprocessable entity-已有域名屏蔽 + +域名参数已包含在现有的域名屏蔽中。 + +```json +{ + "error": "You have already imposed stricter limits on example.com." + "existing_domain_block": { + "id": "1", + "domain": "example.com", + "digest": "a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce1947", + "created_at": "2022-11-16T08:15:34.238Z", + "severity": "noop", + "reject_media": false, + "reject_reports": false, + "private_comment": null, + "public_comment": null, + "obfuscate": false + } +} +``` + +--- + +## 更新域名屏蔽 {#update} + +```http +PUT /api/v1/admin/domain_blocks/:id HTTP/1.1 +``` + +更改现有域名屏蔽的参数。 + +**返回：** [Admin::DomainBlock]({{< relref "entities/Admin_DomainBlock" >}})\ +**OAuth：** 用户令牌 + `admin:write:domain_blocks`\ +**权限：** 管理联合\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。 数据库中 DomainAllow 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +severity +: 字符串。 是否对域名应用 `silence`、`suspend` 或 `noop`。 默认为 `silence` + +reject_media +: 布尔值。 是否应拒绝媒体附件。 默认为 false + +reject_reports +: 布尔值。 是否应拒绝来自此域名的举报。 默认为 false + +private_comment +: 字符串。 关于此域名屏蔽的私密注释，仅管理员可见。 + +public_comment +: 字符串。 关于此域名屏蔽的公开注释，可以选择在“关于”页面上显示。 + +obfuscate +: 布尔值。 是否在公开显示时部分审查该域名。 默认为 false + +#### 响应 +##### 200: OK + +域名屏蔽已更新 + +```json +{ + "id": "1", + "domain": "example.com", + "digest": "a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce1947", + "created_at": "2022-11-16T08:15:34.238Z", + "severity": "noop", + "reject_media": false, + "reject_reports": false, + "private_comment": null, + "public_comment": null, + "obfuscate": false +} +``` + +##### 403: Forbidden + +授权用户无权执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 500: 实例错误 + +屏蔽级别无效 + +--- + +## 删除域名屏蔽 {#delete} + +```http +DELETE /api/v1/admin/domain_blocks/:id HTTP/1.1 +``` + +取消对域名的屏蔽。 + +**返回：** [Admin::DomainBlock]({{< relref "entities/Admin_DomainBlock" >}})\ +**OAuth：** 用户令牌 + `admin:write:domain_blocks`\ +**权限：** 管理联合\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。 数据库中 DomainAllow 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +该域名已从屏蔽列表中删除 + +```json +{} +``` +##### 403: Forbidden + +授权用户无权执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +不存在具有给定 ID 的 DomainBlock + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/domain_blocks_controller.rb" caption="app/controllers/api/v1/admin/domain_blocks_controller.rb" >}} +{{< translation-status-zh-cn raw_title="domain_blocks API methods" raw_link="/methods/admin/domain_blocks/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/admin/email_domain_blocks.md b/content/zh-cn/methods/admin/email_domain_blocks.md new file mode 100644 index 0000000..8a1a457 --- /dev/null +++ b/content/zh-cn/methods/admin/email_domain_blocks.md @@ -0,0 +1,377 @@ +--- +title: email_domain_blocks API 方法 +description: 禁止使用某些电子邮件域名注册。 +menu: + docs: + name: email_domain_blocks + parent: methods-admin + identifier: methods-admin-email_domain_blocks +aliases: [ + "/methods/admin/email_domain_blocks", + "/api/methods/admin/email_domain_blocks", +] +--- + + + +## 列出所有被屏蔽的电子邮件域名 {#get} + +```http +GET /api/v1/admin/email_domain_blocks HTTP/1.1 +``` + +显示有关所有被屏蔽注册的电子邮件域名信息。 + +**返回：** [Admin::EmailDomainBlock]({{< relref "entities/Admin_EmailDomainBlock" >}}) 数组\ +**OAuth：** 用户令牌 + `admin:read:email_domain_blocks`\ +**权限：** 管理屏蔽\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +since_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +min_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +limit +: 整数。要返回的最大结果数。默认为 100 个屏蔽条目。最大 200 个屏蔽条目。 + +#### 响应 + +##### 200: OK + +```json +[ + { + "id": "1", + "domain": "foo", + "created_at": "2022-11-16T06:09:36.176Z", + "history": [ + { + "day": "1668556800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668470400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668384000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668297600", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668211200", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668124800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668038400", + "accounts": "0", + "uses": "0" + } + ] + }, + // ... +] +``` + +##### 403: Forbidden + +授权用户不允许执行此操作，或缺少或无效的 Authorization 标头。 + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## 获取单个被屏蔽的电子邮件域名 {#get-one} + +```http +GET /api/v1/admin/email_domain_blocks/:id HTTP/1.1 +``` +显示有关被屏蔽注册的单个电子邮件域名信息。 + +**返回：** [Admin::EmailDomainBlock]({{< relref "entities/Admin_EmailDomainBlock" >}})\ +**OAuth：** 用户令牌 + `admin:read:email_domain_blocks`\ +**权限：** 管理屏蔽\ +**版本历史：**\ +4.1.0 - 添加 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 DomainBlock 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{ + "id": "1", + "domain": "foo", + "created_at": "2022-11-16T06:09:36.176Z", + "history": [ + { + "day": "1668556800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668470400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668384000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668297600", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668211200", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668124800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668038400", + "accounts": "0", + "uses": "0" + } + ] +} +``` + +##### 403: Forbidden + +授权用户不允许执行此操作，或缺少或无效的 Authorization 标头。 + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +具有给定 ID 的 EmailDomainBlock 不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 屏蔽电子邮件域名 {#create} + +```http +POST /api/v1/admin/email_domain_blocks HTTP/1.1 +``` + +将域名添加到被屏蔽的电子邮件域名列表中。 + +**返回：** [Admin::EmailDomainBlock]({{< relref "entities/Admin_EmailDomainBlock" >}})\ +**OAuth：** 用户令牌 + `admin:write:email_domain_blocks`\ +**权限：** 管理屏蔽\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +domain +: {{}} 字符串。要屏蔽与其联合的域名。 + +#### 响应 +##### 200: OK + +电子邮件域名已被屏蔽注册。 + +```json +{ + "id": "1", + "domain": "foo", + "created_at": "2022-11-16T06:09:36.176Z", + "history": [ + { + "day": "1668556800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668470400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668384000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668297600", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668211200", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668124800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668038400", + "accounts": "0", + "uses": "0" + } + ] +} +``` + +##### 403: Forbidden + +授权用户不允许执行此操作，或缺少或无效的 Authorization 标头。 + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 422: Unprocessable entity + +未提供 domain 参数 + +```json +{ + "error": "Validation failed: Domain can't be blank" +} +``` + +或者，提供的域名包含无效字符 + +```json +{ + "error": "Validation failed: Domain is invalid, Domain is not a valid domain name" +} +``` + +--- + +## 删除电子邮件域名屏蔽 {#delete} + +```http +DELETE /api/v1/admin/email_domain_blocks/:id HTTP/1.1 +``` + +取消对电子邮件域名的屏蔽。 + +**返回：** [Admin::EmailDomainBlock]({{< relref "entities/Admin_EmailDomainBlock" >}})\ +**OAuth：** 用户令牌 + `admin:write:email_domain_blocks`\ +**权限：** 管理屏蔽\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 DomainAllow 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +电子邮件域名已从屏蔽列表中删除 + +```json +{} +``` +##### 403: Forbidden + +授权用户不允许执行此操作，或缺少或无效的 Authorization 标头。 + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +具有给定 ID 的 EmailDomainBlock 不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/email_domain_blocks_controller.rb" caption="app/controllers/api/v1/admin/email_domain_blocks_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="email_domain_blocks API methods" raw_link="/methods/admin/email_domain_blocks/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/admin/ip_blocks.md b/content/zh-cn/methods/admin/ip_blocks.md new file mode 100644 index 0000000..a5af499 --- /dev/null +++ b/content/zh-cn/methods/admin/ip_blocks.md @@ -0,0 +1,352 @@ +--- +title: ip_blocks API 方法 +description: 禁止某些 IP 地址段注册。 +menu: + docs: + name: ip_blocks + parent: methods-admin + identifier: methods-admin-ip_blocks +aliases: [ + "/methods/admin/domain_blocks", + "/api/methods/admin/domain_blocks", +] +--- + + + +## 列出所有 IP 屏蔽 {#get} + +```http +GET /api/v1/admin/ip_blocks HTTP/1.1 +``` + +显示有关所有被屏蔽的 IP 段的信息。 + +**返回：** [Admin::IpBlock]({{< relref "entities/Admin_IpBlock" >}}) 数组\ +**OAuth：** 用户令牌 + `admin:read:ip_blocks`\ +**权限：** 管理屏蔽\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +since_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +min_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +limit +: 整数。要返回的最大结果数。默认为 100 个屏蔽。最多 200 个屏蔽。 + +#### 响应 + +##### 200: OK + +```json +[ + { + "id": "1", + "ip": "8.8.8.8/32", + "severity": "no_access", + "comment": "", + "created_at": "2022-11-16T07:22:00.501Z", + "expires_at": null + }, + // ... +] +``` + +由于 IpBlock ID 通常不会通过任何 API 响应公开，因此你必须解析 HTTP `Link` 标头才能加载较旧或较新的结果。 有关更多信息，请参阅[通过 API 响应进行分页]({{}})。 + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 403: Forbidden + +授权用户不允许执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## 获取单个 IP 屏蔽条目 {#get-one} + +```http +GET /api/v1/admin/ip_blocks/:id HTTP/1.1 +``` + +显示有关单个 IP 屏蔽的信息。 + +**返回：** [Admin::IpBlock]({{< relref "entities/Admin_IpBlock" >}})\ +**OAuth：** 用户令牌 + `admin:read:ip_blocks`\ +**权限：** 管理屏蔽\ +**版本历史：**\ +4.0.0 - 添加 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 IpBlock 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{ + "id": "1", + "ip": "8.8.8.8/32", + "severity": "no_access", + "comment": "", + "created_at": "2022-11-16T07:22:00.501Z", + "expires_at": null +} +``` + +##### 403: Forbidden + +授权用户不允许执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +具有给定 ID 的 IpBlock 不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 屏蔽 IP 地址段 {#create} + +```http +POST /api/v1/admin/ip_blocks HTTP/1.1 +``` + +将 IP 地址段添加到 IP 屏蔽列表。 + +**返回：** [Admin::IpBlock]({{< relref "entities/Admin_IpBlock" >}})\ +**OAuth：** 用户令牌 + `admin:write:ip_blocks`\ +**权限：** 管理屏蔽\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +ip +: 字符串。要屏蔽的 IP 地址和前缀。默认为 `0.0.0.0/32` + +severity +: {{}} 字符串。应用于此 IP 段的策略：`sign_up_requires_approval`、`sign_up_block` 或 `no_access` + +comment +: 字符串。此 IP 屏蔽的原因。 + +expires_in +: 整数。此 IP 屏蔽距离过期的秒数。 + +#### 响应 +##### 200: OK + +IP 已被屏蔽注册。 + +```json +{ + "id": "1", + "ip": "8.8.8.8/32", + "severity": "no_access", + "comment": "", + "created_at": "2022-11-16T07:22:00.501Z", + "expires_at": null +} +``` + +##### 403: Forbidden + +授权用户不允许执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 422: Unprocessable entity + +IP 已被屏蔽，并且/或者未提供严重性 + +```json +{ + "error": "Validation failed: Severity can't be blank, Ip has already been taken" +} +``` + +--- + +## 更新 IP 屏蔽 {#update} + +```http +PUT /api/v1/admin/ip_blocks/:id HTTP/1.1 +``` + +更改现有 IP 屏蔽的参数。 + +**返回：** [Admin::IpBlock]({{< relref "entities/Admin_IpBlock" >}})\ +**OAuth：** 用户令牌 + `admin:write:ip_blocks`\ +**权限：** 管理屏蔽\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 IpBlock 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +ip +: 字符串。要屏蔽的 IP 地址和前缀。默认为 `0.0.0.0/32` + +severity +: 字符串。应用于此 IP 段的策略：`sign_up_requires_approval`、`sign_up_block` 或 `no_access` + +comment +: 字符串。此 IP 屏蔽的原因。 + +expires_in +: 整数。此 IP 屏蔽距离过期的秒数。 + +#### 响应 +##### 200: OK + +IP 屏蔽已更新 + +```json +{ + "id": "1", + "ip": "8.8.4.4/32", + "severity": "no_access", + "comment": "", + "created_at": "2022-11-16T07:22:00.501Z", + "expires_at": null +} +``` + +##### 403: Forbidden + +授权用户不允许执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## 删除 IP 屏蔽 {#delete} + +```http +DELETE /api/v1/admin/ip_blocks/:id HTTP/1.1 +``` + +解除对 IP 段的屏蔽。 + +**返回：** [Admin::IpBlock]({{< relref "entities/Admin_IpBlock" >}})\ +**OAuth：** 用户令牌 + `admin:write:domain_blocks`\ +**权限：** 管理屏蔽\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 DomainAllow 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +已从屏蔽列表中删除 IP + +```json +{} +``` +##### 403: Forbidden + +授权用户不允许执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +具有给定 ID 的 IpBlock 不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/ip_blocks_controller.rb" caption="app/controllers/api/v1/admin/ip_blocks_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="ip_blocks API methods" raw_link="/methods/admin/ip_blocks/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} + diff --git a/content/zh-cn/methods/admin/measures.md b/content/zh-cn/methods/admin/measures.md new file mode 100644 index 0000000..d7fde28 --- /dev/null +++ b/content/zh-cn/methods/admin/measures.md @@ -0,0 +1,300 @@ +--- +title: measures API 方法 +description: 获取关于实例的统计指标。 +menu: + docs: + name: measures + parent: methods-admin + identifier: methods-admin-measures +aliases: [ + "/methods/admin/measures", + "/api/methods/admin/measures", +] +--- + + + +## 获取统计数据 {#get} + +```http +POST /api/v1/admin/measures HTTP/1.1 +``` + +获取你的实例的统计数据。 + +**返回：** [Admin::Measure]({{< relref "entities/Admin_Measure" >}})数组\ +**OAuth:** 用户令牌 + `admin:read`\ +**权限：** 查看管理面板\ +**版本历史：**\ +3.5.0 - 添加\ +4.0.0 - 支持自定义用户组和权限 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +keys[] +: {{}} 字符串数组。通过对应的键字符串请求特定类别的统计数据。支持的类别包括： +- `active_users` = 当前时间段内你实例上的活跃用户总数 +- `new_users` = 当前时间段内加入你实例的用户数 +- `interactions` = 当前时间段内本站嘟文的总互动数（喜欢、转发、回复） +- `opened_reports` = 当前时间段内提交的举报总数 +- `resolved_reports` = 当前时间段内已解决的举报总数 +- `tag_accounts` = 当前时间段内在至少一条嘟文中使用过话题标签的总帐户数 +- `tag_uses` = 当前时间段内使用话题标签的嘟文总数 +- `tag_servers` = 当前时间段内使用话题标签的嘟文的外站实例总数 +- `instance_accounts` = 当前时间段内来自外站域名的帐户总数 +- `instance_media_attachments` = 当前时间段内来自外站域名的媒体附件使用的总空间 +- `instance_reports` = 当前时间段内针对来自外站域名的帐户提交的举报总数 +- `instance_statuses` = 当前时间段内来自外站域名的嘟文总数 +- `instance_follows` = 当前时间段内本站用户关注来自外站域名的帐户总数 +- `instance_followers` = 当前时间段内来自外站域名的帐户关注本站帐户总数 + +start_at +: {{}} ([Datetime](/api/datetime-format#datetime)) 字符串。时间段的开始日期。若提供了时间，将被忽略。 + +end_at +: {{}} ([Datetime](/api/datetime-format#datetime)) 字符串。时间段的结束日期。若提供了时间，将被忽略。 + +tag_accounts[id] +: 字符串。当 `tag_accounts` 是请求的键之一时，你必须提供一个话题标签 ID，以获取在给定时间段内有多少帐户在至少一条嘟文中使用了该话题标签的数据。 + +tag_uses[id] +: 字符串。当 `tag_uses` 是请求的键之一时，你必须提供一个话题标签 ID，以获取在给定时间段内有多少嘟文使用了该话题标签的数据。 + +tag_servers[id] +: 字符串。当 `tag_servers` 是请求的键之一时，你必须提供一个话题标签 ID，以获取在给定时间段内有多少实例在至少一条嘟文中使用了该话题标签的数据。 + +instance_accounts[domain] +: 字符串。当 `instance_accounts` 是请求的键之一时，你必须提供一个外站域名，以获取在给定时间段内从该实例发现了多少帐户的数据。 + +instance_media_attachments[domain] +: 字符串。当 `instance_media_attachments` 是请求的键之一时，你必须提供一个外站域名，以获取在给定时间段内该实例的媒体附件使用了多少空间的数据。 + +instance_reports[domain] +: 字符串。当 `instance_reports` 是请求的键之一时，你必须提供一个外站域名，以获取在给定时间段内针对该实例的帐户提交了多少举报的数据。 + +instance_statuses[domain] +: 字符串。当 `instance_statuses` 是请求的键之一时，你必须提供一个外站域名，以获取在给定时间段内有多少嘟文来自该实例的数据。 + +instance_follows[domain] +: 字符串。当 `instance_follows` 是请求的键之一时，你必须提供一个外站域名，以获取在给定时间段内本站帐户对来自该实例的帐户执行了多少关注的数据。 + +instance_followers[domain] +: 字符串。当 `instance_followers` 是请求的键之一时，你必须提供一个外站域名，以获取在给定时间段内来自该实例的帐户对本站帐户执行了多少关注的数据。 + +#### 响应 +##### 200: OK + +返回每个数据的数量数据，包括聚合数据以及按数据桶划分的数据。 + +```json +[ + { + "key": "active_users", + "unit": null, + "total": "2", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00Z", + "value": "0" + }, + // ... + ] + }, + { + "key": "new_users", + "unit": null, + "total": "2", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + // ... + ] + }, + { + "key": "interactions", + "unit": null, + "total": "0", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00Z", + "value": "0" + }, + // ... + ] + }, + { + "key": "opened_reports", + "unit": null, + "total": "0", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + // ... + ] + }, + { + "key": "resolved_reports", + "unit": null, + "total": "0", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + // ... + ] + }, + { + "key": "tag_accounts", + "unit": null, + "total": "1", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00Z", + "value": "0" + }, + // ... + ] + }, + { + "key": "tag_uses", + "unit": null, + "total": "2", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00Z", + "value": "0" + }, + // ... + ] + }, + { + "key": "tag_servers", + "unit": null, + "total": "0", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + // ... + ] + }, + { + "key": "instance_accounts", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + // ... + ] + }, + { + "key": "instance_media_attachments", + "unit": "bytes", + "total": "0", + "human_value": "0 Bytes", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "" + }, + // ... + ] + }, + { + "key": "instance_reports", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + // ... + ] + }, + { + "key": "instance_statuses", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + // ... + ] + }, + { + "key": "instance_follows", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + // ... + ] + }, + { + "key": "instance_followers", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + // ... + ] + } +] +``` + +##### 403: Forbidden + +授权用户缺少权限，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/measures_controller.rb" caption="app/controllers/api/v1/admin/measures_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/measure.rb" caption="app/lib/admin/metrics/measure.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/measure/" caption="app/lib/admin/metrics/measure/" >}} + +{{< translation-status-zh-cn raw_title="measures API methods" raw_link="/methods/admin/measures/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/admin/reports.md b/content/zh-cn/methods/admin/reports.md new file mode 100644 index 0000000..c641d38 --- /dev/null +++ b/content/zh-cn/methods/admin/reports.md @@ -0,0 +1,552 @@ +--- +title: admin/reports API 方法 +description: 根据举报执行管理操作。 +menu: + docs: + name: reports + parent: methods-admin + identifier: methods-admin-reports +aliases: [ + "/methods/admin/reports", + "/api/methods/admin/reports", +] +--- + + + +## 查看所有举报 {#get} + +```http +GET /api/v1/admin/reports HTTP/1.1 +``` + +查看所有举报的信息。 + +**返回：** [Admin::Report]({{< relref "entities/Admin_Report" >}}) 数组\ +**OAuth:** 用户令牌 + `admin:read:reports`\ +**权限：** 管理举报\ +**版本历史：**\ +2.9.1 - 添加\ +4.0.0 - 支持自定义用户组和权限 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，格式为 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +resolved +: 布尔值。是否过滤已解决的举报？ + +account_id +: 字符串。筛选由此帐户提交的举报。 + +target_account_id +: 字符串。筛选以此帐户为目标账户的举报。 + +max_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +since_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +min_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +limit +: 整数。要返回的最大结果数。默认为 100 个举报。最大为 200 个举报。 + +#### 响应 +##### 200: OK + +```json +[ + { + "id": "3", + "action_taken": false, + "action_taken_at": null, + "category": "spam", + "comment": "", + "forwarded": false, + "created_at": "2022-09-09T21:19:23.085Z", + "updated_at": "2022-09-09T21:19:23.085Z", + "account": { + "id": "108965218747268792", + "username": "admin", + "domain": null, + "created_at": "2022-09-08T22:48:07.985Z", + "email": "admin@mastodon.local", + // ... + "account": { + "id": "108965218747268792", + "username": "admin", + "acct": "admin", + // ... + } + }, + "target_account": { + "id": "108965430868193066", + "username": "goody", + "domain": null, + "created_at": "2022-09-08T23:42:04.731Z", + "email": "goody@mastodon.local", + // ... + "account": { + "id": "108965430868193066", + "username": "goody", + "acct": "goody", + // ... + } + }, + "assigned_account": null, + "action_taken_by_account": null, + "statuses": [], + "rules": [] + }, + // ... +] +``` + +由于举报 ID 通常不会通过任何 API 响应公开，因此你必须解析 HTTP `Link` 标头才能加载更早或更新的结果。 有关更多信息，请参考[通过 API 响应进行分页]({{}})。 + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 403: Forbidden + +授权用户不允许执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## 查看单个举报 {#get-one} + +```http +GET /api/v1/admin/reports/:id HTTP/1.1 +``` + +**返回：** [Admin::Report]({{< relref "entities/Admin_Report" >}})\ +**OAuth:** 用户令牌 + `admin:read:reports`\ +**权限：** 管理举报\ +**版本历史：**\ +2.9.1 - 添加\ +4.0.0 - 支持自定义用户组和权限 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中举报的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，格式为 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{ + "id": "2", + "action_taken": true, + "action_taken_at": "2022-09-09T21:38:54.679Z", + "category": "spam", + "comment": "", + "forwarded": false, + "created_at": "2022-09-09T21:19:44.021Z", + "updated_at": "2022-09-09T21:38:54.681Z", + "account": { + "id": "108965218747268792", + "username": "admin", + "domain": null, + "created_at": "2022-09-08T22:48:07.985Z", + "email": "admin@mastodon.local", + // ... + "account": { + "id": "108965218747268792", + "username": "admin", + "acct": "admin", + // ... + } + }, + "target_account": { + "id": "108965430868193066", + "username": "goody", + "domain": null, + "created_at": "2022-09-08T23:42:04.731Z", + "email": "goody@mastodon.local", + // ... + "account": { + "id": "108965430868193066", + "username": "goody", + "acct": "goody", + // ... + } + }, + "assigned_account": null, + "action_taken_by_account": { + "id": "108965218747268792", + "username": "admin", + "domain": null, + "created_at": "2022-09-08T22:48:07.985Z", + "email": "admin@mastodon.local", + // ... + "account": { + "id": "108965218747268792", + "username": "admin", + "acct": "admin", + // ... + } + }, + "statuses": [], + "rules": [] +} +``` + +##### 403: Forbidden + +授权用户不允许执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## 更新举报 {#update} + +```http +PUT /api/v1/admin/reports/:id HTTP/1.1 +``` + +更改举报的元数据。 + +**返回：** [Admin::Report]({{< relref "entities/Admin_Report" >}})\ +**OAuth:** 用户令牌 + `admin:write:reports`\ +**权限：** 管理举报\ +**版本历史：**\ +3.5.0 - 添加\ +4.0.0 - 支持自定义用户组和权限 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中举报的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，格式为 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +category +: 字符串。将举报的分类更改为 `spam`、`violation` 或 `other`。 + +rule_ids[] +: 整数数组。对于 `violation` 类别的举报，指定违反的确切规则的 ID。规则及其 ID 可通过 [GET /api/v1/instance/rules]({{< relref "methods/instance#rules" >}}) 和 [GET /api/v1/instance]({{< relref "methods/instance#get" >}}) 获取。 + +#### 响应 +##### 200: OK + +举报类别和/或规则 ID 现在应该已更新。 + +```json +{ + "id": "3", + "action_taken": false, + "action_taken_at": null, + "category": "other", + // ... + "rules": [] +} +``` + +##### 403: Forbidden + +授权用户不允许执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## 将举报分配给自己 {#assign_to_self} + +```http +POST /api/v1/admin/reports/:id/assign_to_self HTTP/1.1 +``` + +声明对此举报的处理权。 + +**返回：** [Admin::Report]({{< relref "entities/Admin_Report" >}})\ +**OAuth:** 用户令牌 + `admin:write:reports`\ +**权限：** 管理举报\ +**版本历史：**\ +2.9.1 - 添加\ +4.0.0 - 支持自定义用户组和权限 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中举报的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，格式为 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +举报现在应该已分配给你，或者它已经分配给你。 + +```json +{ + "id": "3", + "action_taken": false, + "action_taken_at": null, + "category": "other", + "comment": "", + "forwarded": false, + "created_at": "2022-09-09T21:21:01.204Z", + "updated_at": "2022-09-11T14:39:01.531Z", + // ... + "assigned_account": { + "id": "108965218747268792", + "username": "admin", + "domain": null, + "created_at": "2022-09-08T22:48:07.985Z", + "email": "admin@mastodon.local", + // ... + "account": { + "id": "108965218747268792", + "username": "admin", + "acct": "admin", + // ... + } + }, + "action_taken_by_account": null, + "statuses": [], + "rules": [] +} +``` + +##### 403: Forbidden + +授权用户不允许执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## 取消举报分配 {#unassign} + +```http +POST /api/v1/admin/reports/:id/unassign HTTP/1.1 +``` + +取消分配举报，以便其他人可以认领它。 + +**返回：** [Admin::Report]({{< relref "entities/Admin_Report" >}})\ +**OAuth:** 用户令牌 + `admin:write:reports`\ +**权限：** 管理举报\ +**版本历史：**\ +2.9.1 - 添加 +4. 0.0 - 支持自定义用户组和权限 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中举报的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，格式为 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +举报应该不再分配给你，或者它已经没有分配给任何人。 + +```json +{ + "id": "3", + "action_taken": false, + "action_taken_at": null, + "category": "other", + "comment": "", + "forwarded": false, + "created_at": "2022-09-09T21:21:01.204Z", + "updated_at": "2022-09-11T14:39:01.531Z", + // ... + "assigned_account": null, + "action_taken_by_account": null, + "statuses": [], + "rules": [] +} +``` + +##### 403: Forbidden + +授权用户不允许执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## 将举报标记为已解决 {#resolve} + +```http +POST /api/v1/admin/reports/:id/resolve HTTP/1.1 +``` + +将举报标记为已解决，无需采取进一步措施。 + +**返回：** [Admin::Report]({{< relref "entities/Admin_Report" >}})\ +**OAuth:** 用户令牌 + `admin:write:reports`\ +**权限：** 管理举报\ +**版本历史：**\ +2.9.1 - 添加\ +4.0.0 - 支持自定义用户组和权限 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中举报的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，格式为 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +举报现在已解决，或者它已经解决。 + +```json +{ + "id": "2", + "action_taken": true, + "action_taken_at": "2022-09-11T14:46:22.936Z", + "category": "spam", + "comment": "", + "forwarded": false, + "created_at": "2022-09-09T21:19:44.021Z", + "updated_at": "2022-09-11T14:46:22.945Z", + // ... +} +``` + +##### 403: Forbidden + +授权用户不允许执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` +--- + +## 重新打开已关闭的举报 {#reopen} + +```http +POST /api/v1/admin/reports/:id/reopen HTTP/1.1 +``` + +若举报已关闭，则重新打开当前已关闭的举报。 + +**返回：** [Admin::Report]({{< relref "entities/Admin_Report" >}})\ +**OAuth:** 用户令牌 + `admin:write:reports`\ +**权限：** 管理举报\ +**版本历史：**\ +2.9.1 - 添加\ +4.0.0 - 支持自定义用户组和权限 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中举报的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，格式为 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +该举报不再有任何已采取的措施，或者它已经没有任何已采取的措施。 + +```json +{ + "id": "2", + "action_taken": false, + "action_taken_at": null, + "category": "spam", + "comment": "", + "forwarded": false, + "created_at": "2022-09-09T21:19:44.021Z", + "updated_at": "2022-09-11T14:42:21.855Z", + // ... +} +``` + +##### 403: Forbidden + +授权用户不允许执行此操作，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## 另请参考 + +{{< page-relref ref="methods/admin/accounts#action" caption="POST /api/v1/admin/accounts/:id/action" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/reports_controller.rb" caption="app/controllers/api/v1/admin/reports_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="reports API methods" raw_link="/methods/admin/reports/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/admin/retention.md b/content/zh-cn/methods/admin/retention.md new file mode 100644 index 0000000..faefe0f --- /dev/null +++ b/content/zh-cn/methods/admin/retention.md @@ -0,0 +1,175 @@ +--- +title: retention API 方法 +description: 展示对应时段的留存率数据。 +menu: + docs: + name: retention + parent: methods-admin + identifier: methods-admin-retention +aliases: [ + "/methods/admin/retention", + "/api/methods/admin/retention", +] +--- + + + +## 计算留存率数据 {#create} + +```http +POST /api/v1/admin/retention HTTP/1.1 +``` + +为给定的时间段和桶生成留存率数据报告。 + +**返回:** [Admin::Cohort]({{< relref "entities/Admin_Cohort" >}}) 数组\ +**OAuth:** 用户令牌 + `admin:read`\ +**权限:** 查看管理面板\ +**版本历史:**\ +3.5.0 - 添加\ +4.0.0 - 支持自定义用户组和权限 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，格式为 `Bearer `，以获得对此 API 方法的访问授权。 + +##### Form data parameters + +start_at +: {{}} ([Datetime](/api/datetime-format#datetime)) 字符串。时间段的开始日期。若提供了时间，则将被忽略。 + +end_at +: {{}} ([Datetime](/api/datetime-format#datetime)) 字符串。时间段的结束日期。若提供了时间，则将被忽略。 + +frequency +: {{}} 字符串（枚举值之一）。指定是否使用 `day` 或 `month` 存储桶。若提供任何其他值，则默认为 `day`。 + +#### 响应 +##### 200: OK + +2022 年 9 月的每月留存率数据，假设 2 个用户在 2022 年 9 月注册，并且在该月至少活跃一次。 + +```json +[ + { + "period": "2022-09-01T00:00:00+00:00", + "frequency": "month", + "data": [ + { + "date": "2022-09-01T00:00:00+00:00", + "rate": 1.0, + "value": "2" + } + ] + } +] +``` + +2022 年 9 月 8 日至 2022 年 9 月 14 日之间的一周的每日留存率数据，假设 2 个用户在 2022 年 9 月 8 日注册，并且其中 1 个用户在 2022 年 9 月 9 日之后停止活跃。 + +```json +[ + { + "period": "2022-09-08T00:00:00+00:00", + "frequency": "day", + "data": [ + { + "date": "2022-09-08T00:00:00+00:00", + "rate": 1, + "value": "2" + }, + { + "date": "2022-09-09T00:00:00+00:00", + "rate": 1, + "value": "2" + }, + { + "date": "2022-09-10T00:00:00+00:00", + "rate": 0.5, + "value": "1" + }, + // ... + { + "date": "2022-09-14T00:00:00+00:00", + "rate": 0.5, + "value": "1" + } + ] + }, + { + "period": "2022-09-09T00:00:00+00:00", + "frequency": "day", + "data": [ + { + "date": "2022-09-09T00:00:00+00:00", + "rate": 0, + "value": "0" + }, + // ... + { + "date": "2022-09-14T00:00:00+00:00", + "rate": 0, + "value": "0" + } + ] + }, + { + "period": "2022-09-10T00:00:00+00:00", + "frequency": "day", + "data": [ + { + "date": "2022-09-10T00:00:00+00:00", + "rate": 0, + "value": "0" + }, + // ... + { + "date": "2022-09-14T00:00:00+00:00", + "rate": 0, + "value": "0" + } + ] + }, + // ... + { + "period": "2022-09-14T00:00:00+00:00", + "frequency": "day", + "data": [ + { + "date": "2022-09-14T00:00:00+00:00", + "rate": 0, + "value": "0" + } + ] + } +] +``` + +若缺少任何参数，同类组计算将失败并返回一个空数组。 + +```json +[] +``` + +##### 403: Forbidden + +授权用户缺少权限，或者 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/retention_controller.rb" caption="app/controllers/api/v1/admin/retention_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="retention API methods" raw_link="/methods/admin/retention/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/admin/trends.md b/content/zh-cn/methods/admin/trends.md new file mode 100644 index 0000000..27ba484 --- /dev/null +++ b/content/zh-cn/methods/admin/trends.md @@ -0,0 +1,263 @@ +--- +title: admin/trends API 方法 +description: TODO +menu: + docs: + name: trends + parent: methods-admin + identifier: methods-admin-trends +aliases: [ + "/methods/admin/measures", + "/api/methods/admin/measures", +] +--- + + + +## 查看热门链接 {#links} + +```http +GET /api/v1/admin/trends/links HTTP/1.1 +``` + +比其他链接分享更多的链接，包括未批准和未审核的链接。 + +**返回:** [Trends::Link]({{< relref "entities/PreviewCard#trends-link" >}}) 数组\ +**OAuth:** 用户令牌 + `admin:read`\ +**权限:** 管理分类\ +**版本历史:**\ +3.5.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +[ + { + "url": "https://twitter.com/arufa_faru/status/1594262272007753728", + "title": "ARuFa on Twitter", + "description": "“言葉をマネするぬいぐるみを改造してエレキギターを直接繋いでみました”", + "type": "link", + "author_name": "", + "author_url": "", + "provider_name": "Twitter", + "provider_url": "", + "html": "", + "width": 400, + "height": 225, + "image": "https://media.chitter.xyz/cache/preview_cards/images/002/162/720/original/b5360261e8ce17fc.jpeg", + "embed_url": "", + "blurhash": "UNFiDM~o-oD%x[xtaxM|xaNHRkjsoft7ofWB", + "history": [ + { + "day": "1669507200", + "accounts": "9", + "uses": "9" + }, + { + "day": "1669420800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1669334400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1669248000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1669161600", + "accounts": "0", + "uses": "0" + }, + { + "day": "1669075200", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668988800", + "accounts": "0", + "uses": "0" + } + ] + }, + // ... +] +``` + +##### 403: Forbidden + +授权用户缺少权限，或 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +## 查看热门嘟文 {#statuses} + +```http +GET /api/v1/admin/trends/statuses HTTP/1.1 +``` + +比其他嘟文互动更多的嘟文，包括未批准和未审核的嘟文。 + +**返回:** [Status]({{< relref "entities/Status" >}}) 数组\ +**OAuth:** 用户令牌 + `admin:read`\ +**权限:** 管理分类\ +**版本历史:**\ +3.5.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +[ + { + "id": "109415512969053017", + "created_at": "2022-11-27T11:23:52.000Z", + "in_reply_to_id": null, + "in_reply_to_account_id": null, + // ... + "account": { + "id": "109332240210946752", + // ... + }, + "media_attachments": [], + "mentions": [], + "tags": [], + "emojis": [], + "card": null, + "poll": null + }, + // ... +] +``` + +##### 403: Forbidden + +授权用户缺少权限，或 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +## 查看热门话题标签 {#tags} + +```http +GET /api/v1/admin/trends/tags HTTP/1.1 +``` + +过去一周内使用频率更高的话题标签，包括未批准和未审核的话题标签。 + +**返回:** [Admin::Tag]({{< relref "entities/Tag#admin" >}}) 数组\ +**OAuth:** 用户令牌 + `admin:read`\ +**权限:** 管理分类\ +**版本历史:**\ +3.5.0 - 添加\ +4.0.0 - 由于错误，返回 Tag 数组\ +4.1.0 - 修复错误 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +[ + { + "name": "caturday", + "url": "https://mastodon.example/tags/caturday", + "history": [ + { + "day": "1669507200", + "accounts": "53", + "uses": "56" + }, + { + "day": "1669420800", + "accounts": "142", + "uses": "171" + }, + { + "day": "1669334400", + "accounts": "11", + "uses": "11" + }, + { + "day": "1669248000", + "accounts": "8", + "uses": "9" + }, + { + "day": "1669161600", + "accounts": "8", + "uses": "20" + }, + { + "day": "1669075200", + "accounts": "11", + "uses": "11" + }, + { + "day": "1668988800", + "accounts": "17", + "uses": "22" + } + ], + "id": "802", + "trendable": true, + "usable": true, + "requires_review": false + }, +] +``` + +##### 403: Forbidden + +授权用户缺少权限，或 Authorization 标头无效或缺失 + +```json +{ + "error": "This action is not allowed" +} +``` + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/trends/links_controller.rb" caption="app/controllers/api/v1/admin/trends/links_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/trends/statuses_controller.rb" caption="app/controllers/api/v1/admin/trends/statuses_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/trends/tags_controller.rb" caption="app/controllers/api/v1/admin/trends/tags_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="trends API methods" raw_link="/methods/admin/trends/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/announcements.md b/content/zh-cn/methods/announcements.md new file mode 100644 index 0000000..67056d5 --- /dev/null +++ b/content/zh-cn/methods/announcements.md @@ -0,0 +1,294 @@ +--- +title: announcements API 方法 +description: 用于管理设置的公告。 +menu: + docs: + weight: 90 + name: announcements + parent: methods-instance + identifier: methods-announcements +aliases: [ + "/methods/announcements", + "/api/methods/announcements", + "/methods/instance/announcements", +] +--- + + + +## 查看所有公告 {#get} + +```http +GET /api/v1/announcements HTTP/1.1 +``` + +查看管理员设置的所有当前生效的公告。 + +**返回：** [Announcement]({{< relref "entities/announcement">}}) 数组\ +**OAuth:** 用户令牌\ +**版本历史：**\ +3.1.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +当前生效的公告 + +```json +[ + { + "id": "8", + "content": "

Looks like there was an issue processing audio attachments without embedded art since yesterday due to an experimental new feature. That issue has now been fixed, so you may see older posts with audio from other servers pop up in your feeds now as they are being finally properly processed. Sorry!

", + "starts_at": null, + "ends_at": null, + "all_day": false, + "published_at": "2020-07-03T01:27:38.726Z", + "updated_at": "2020-07-03T01:27:38.752Z", + "read": true, + "mentions": [], + "statuses": [], + "tags": [], + "emojis": [], + "reactions": [ + { + "name": "bongoCat", + "count": 9, + "me": false, + "url": "https://files.mastodon.social/custom_emojis/images/000/067/715/original/fdba57dff7576d53.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/067/715/static/fdba57dff7576d53.png" + }, + { + "name": "thonking", + "count": 1, + "me": false, + "url": "https://files.mastodon.social/custom_emojis/images/000/098/690/original/a8d36edc4a7032e8.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/098/690/static/a8d36edc4a7032e8.png" + }, + { + "name": "AAAAAA", + "count": 1, + "me": false, + "url": "https://files.mastodon.social/custom_emojis/images/000/071/387/original/AAAAAA.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/071/387/static/AAAAAA.png" + }, + { + "name": "🤔", + "count": 1, + "me": true + } + ] + } +] +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 忽略公告 {#dismiss} + +```http +POST /api/v1/announcements/:id/dismiss HTTP/1.1 +``` + +允许用户将公告标记为已读。 + +**返回：** 空\ +**OAuth:** 用户令牌 + `write:accounts`\ +**版本历史：**\ +3.1.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。 数据库中公告的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK +```json +{} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not Found + +具有给定iID的公告不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 向公告添加回应 {#put-reactions} + +```http +PUT /api/v1/announcements/:id/reactions/:name HTTP/1.1 +``` + +使用表情对公告做出回应。 + +**返回：** 空\ +**OAuth:** 用户令牌 + `write:favourites`\ +**版本历史：**\ +3.1.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。 数据库中公告的ID。 + +:name +: {{}} 字符串。 Unicode 表情，或自定义表情的短代码。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +具有给定ID的公告不存在 + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +```json +{ + "error": "Validation failed: Name is not a recognized emoji" +} +``` + +--- + +## 从公告中删除回应 {#delete-reactions} + +```http +DELETE /api/v1/announcements/:id/reactions/:name HTTP/1.1 +``` + +撤消对公告的表情回应。 + +**返回：** 空\ +**OAuth:** 用户令牌 + `write:favourites`\ +**版本历史：**\ +3.1.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。 数据库中公告的 ID。 + +:name +: {{}} 字符串。 Unicode 表情，或自定义表情的短代码。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +具有给定 ID 的公告不存在 + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +```json +{ + "error": "Validation failed: Name is not a recognized emoji" +} +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/announcements_controller.rb" caption="app/controllers/api/v1/announcements_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/announcements/reactions_controller.rb" caption="app/controllers/api/v1/announcements/reactions_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="announcements API methods" raw_link="/methods/announcements/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/apps.md b/content/zh-cn/methods/apps.md new file mode 100644 index 0000000..afdd876 --- /dev/null +++ b/content/zh-cn/methods/apps.md @@ -0,0 +1,196 @@ +--- +title: apps API 方法 +description: 注册可用于获取 OAuth 令牌的客户端应用。 +menu: + docs: + weight: 10 + name: apps + parent: methods + identifier: methods-apps +aliases: ["/methods/apps", "/api/methods/apps"] +--- + + + +## 创建一个应用 {#create} + +```http +POST /api/v1/apps HTTP/1.1 +``` + +创建一个新的应用以获取 OAuth2 凭据。 + +{{< hint style="danger" >}} +在 4.3 之前的 Mastodon 版本中，OAuth 应用可能会在特定条件下被“清理”并从数据库中移除，这意味着你的应用的 `client_id` 和 `client_secret` 将不会被 Mastodon 实例识别。\ +这种自动删除应用的机制已在 Mastodon 4.3 中移除。\ +\ +对于低于 4.3 的 Mastodon 版本，解决方案之一是注册你的应用，然后立即请求一个 [Client Credential]({{< relref "client/Token#flow" >}}) 令牌，这将永久确保你的应用始终具有有效的访问令牌，并且不会被移除。 +{{< /hint >}} + +{{< hint style="info" >}} +目前，Mastodon 仅支持配置机密客户端，也就是说，你始终会在 [CredentialApplication]({{< relref "entities/Application#CredentialApplication" >}}) 实体中收到 `client_secret` 和 `client_secret_expires_at` 属性。\ +\ +有关更多信息，请参见：[OAuth 2 客户端类型]({{< relref "spec/oauth#client-types" >}}) +{{< /hint >}} + +**返回：** [CredentialApplication]({{< relref "entities/Application#CredentialApplication" >}})\ +**OAuth：** 公开\ +**版本历史：**\ +0.0.0 - 添加\ +2.7.2 - 现在返回 `vapid_key`\ +4.3.0 - 弃用 `vapid_key`，请参见 [api/v2/instance]({{< relref "methods/Instance#v2">}})\ +4.3.0 - 添加了对表单数据参数中多个 `redirect_uris` 的支持\ +4.3.0 - 添加了 `redirect_uris` 响应属性\ +4.3.0 - 弃用 `redirect_uri` 响应属性，因为若注册了多个 `redirect_uris`，这可能不是一个 URI，请改用 `redirect_uris`\ +4.3.0 - 将实体类型从 [Application]({{< relref "entities/Application">}}) 更改为 [CredentialApplication]({{< relref "entities/Application#CredentialApplication">}}) + +#### 请求 {#create-request-example} + +请求示例： + +``` +POST /api/v1/apps HTTP/1.1 +Content-Type: application/json + +{ + "client_name": "Test Application", + "redirect_uris": ["https://app.example/callback", "https://app.example/register"], + "scopes": "read write push", + "website": "https://app.example" +} +``` + +##### 表单数据参数 + +client_name +: {{}} 字符串。你的应用的名称。 + +redirect_uris +: {{}} 字符串或字符串数组。授权后用户应重定向到的位置。要向用户显示授权码，而不是重定向到网页，请在此参数中使用 `urn:ietf:wg:oauth:2.0:oob`。 + +scopes +: 字符串。以空格分隔的作用域列表。若未提供，则默认为 `read`。有关可能的作用域列表，请参见 [OAuth 作用域]({{< relref "api/oauth-scopes" >}})。 + +website +: 字符串。你的应用主页的 URL。 + +#### 响应 + +##### 200: OK + +将 `client_id` 和 `client_secret` 存储在你的缓存中，因为这些将用于获取 OAuth 令牌。 + +{{< hint style="warning" >}} +将 `client_id` 和 `client_secret` 属性视为密码。我们建议你在存储在缓存中时对其进行加密，以防止凭据泄露。 +{{< /hint >}} + +```json +{ + "id": "563419", + "name": "Test Application", + "website": "https://app.example", + "scopes": ["read", "write", "push"], + "redirect_uri": "urn:ietf:wg:oauth:2.0:oob", + "redirect_uris": ["urn:ietf:wg:oauth:2.0:oob"], + "client_id": "TWhM-tNSuncnqN7DBJmoyeLnk6K3iJJ71KKXxgL1hPM", + "client_secret": "ZEaFUFmF0umgBX1qKJDjaU99Q31lDkOU8NutzTOoliw" +} +``` + +或者使用多个重定向 URI： + +```json +{ + "id": "563419", + "name": "Test Application", + "website": "https://app.example", + "scopes": ["read", "write", "push"], + "redirect_uri": "https://app.example/callback\nhttps://app.example/register", + "redirect_uris": [ + "https://app.example/callback", + "https://app.example/register" + ], + "client_id": "TWhM-tNSuncnqN7DBJmoyeLnk6K3iJJ71KKXxgL1hPM", + "client_secret": "ZEaFUFmF0umgBX1qKJDjaU99Q31lDkOU8NutzTOoliw" +} +``` + +{{< hint style="info" >}} +自 4.3.0 起，以上示例中的 `redirect_uri` 属性被视为已被弃用，不应使用，而应使用 `redirect_uris` 属性。 +{{< /hint >}} + +##### 422: Unprocessable entity + +若缺少必需的参数或格式不正确，则请求失败。 + +```json +{ + "error": "Validation failed: Redirect URI must be an absolute URI." +} +``` + +--- + +## 验证你的应用是否有效 {#verify_credentials} + +```http +GET /api/v1/apps/verify_credentials HTTP/1.1 +``` + +确认应用的 OAuth2 凭据是否有效。 + +**返回：** [Application]({{< relref "entities/application" >}})\ +**OAuth：** 应用令牌\ +**版本历史：**\ +2.0.0 - 添加\ +2.7.2 - 现在返回 `vapid_key`\ +4.3.0 - 弃用 `vapid_key`，请参见 [api/v2/instance]({{< relref "methods/Instance#v2">}})\ +4.3.0 - 移除需使用 `read` 作用域才能访问此 API 的要求，现在可以使用任何有效的应用令牌\ +4.3.0 - 添加了 `scopes` 和 `redirect_uris` 属性 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头以及 `Bearer ` 以获得对此 API 方法的访问授权。`` 可以是从 [`/oauth/token`]({{< relref "methods/oauth#token" >}}) 返回的 `client_credential` 或 `access_token`。 + +#### 响应 + +##### 200: OK + +若 Authorization 标头提供了有效的令牌，你应该看到你的应用作为 Application 实体返回。 + +```json +{ + "name": "Test Application", + "website": "https://app.example", + "scopes": ["read", "write", "push"], + "redirect_uris": [ + "https://app.example/callback", + "https://app.example/register" + ] +} +``` + +##### 401: Unauthorized + +若 Authorization 标头包含无效的令牌、格式不正确或不存在，则将返回提示授权失败的错误。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/apps_controller.rb" caption="app/controllers/api/v1/apps_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/apps/credentials_controller.rb" caption="app/controllers/api/v1/apps/credentials_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="apps API methods" raw_link="/methods/apps/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/blocks.md b/content/zh-cn/methods/blocks.md new file mode 100644 index 0000000..df7c408 --- /dev/null +++ b/content/zh-cn/methods/blocks.md @@ -0,0 +1,104 @@ +--- +title: blocks API 方法 +description: 查看你的屏蔽用户列表。另请参阅 accounts/:id/{block,unblock} +menu: + docs: + weight: 40 + name: blocks + parent: methods-accounts + identifier: methods-blocks +aliases: [ + "/methods/blocks", + "/api/methods/blocks", + "/methods/accounts/blocks", +] +--- + + + +## 查看屏蔽用户 {#get} + +```http +GET /api/v1/blocks HTTP/1.1 +``` + +**返回:** [Account]({{< relref "entities/account" >}}) 数组\ +**OAuth:** 用户令牌 + `read:blocks`\ +**版本历史:**\ +0.0.0 - 添加\ +3.3.0 - 现在可以同时使用 `min_id` 和 `max_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": "585315", + "username": "admin", + "acct": "admin@happylittle.cloudns.cc", + "display_name": "☁️ ⛅ Happy Little Clouds ⛅ ☁️", + // ... + }, + { + "id": "650568", + "username": "Nikolai_Kingsley", + "acct": "Nikolai_Kingsley@dobbs.town", + "display_name": "Rev.Dr. Nikolai Kingsley", + // ... + } +] +``` + +由于屏蔽 ID 通常不会通过任何 API 响应公开，因此你必须解析 HTTP `Link` 标头才能加载较旧或较新的结果。 有关更多信息，请参见[通过 API 响应进行分页]({{}})。 + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 另请参阅 + +{{< page-relref ref="methods/accounts#block" caption="POST /api/v1/accounts/:id/block" >}} + +{{< page-relref ref="methods/accounts#unblock" caption="POST /api/v1/accounts/:id/unblock" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/blocks_controller.rb" caption="app/controllers/api/v1/blocks_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="blocks API methods" raw_link="/methods/blocks/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/bookmarks.md b/content/zh-cn/methods/bookmarks.md new file mode 100644 index 0000000..6f2043a --- /dev/null +++ b/content/zh-cn/methods/bookmarks.md @@ -0,0 +1,110 @@ +--- +title: bookmarks API 方法 +description: 查看你的书签。另请参阅 statuses/:id/{bookmark,unbookmark} +menu: + docs: + weight: 10 + name: bookmarks + parent: methods-accounts + identifier: methods-bookmarks +aliases: [ + "/methods/bookmarks", + "/api/methods/bookmarks", + "/methods/accounts/bookmarks", +] +--- + + + +## 查看已添加书签的嘟文 {#get} + +```http +GET /api/v1/bookmarks HTTP/1.1 +``` + +用户已添加书签的嘟文。 + +**返回：** [Status]({{< relref "entities/status" >}})数组\ +**OAuth：** 用户令牌 + `read:bookmarks`\ +**版本历史：**\ +3.1.0 - 添加\ +3.3.0 - 现在可以同时使用 `min_id` 和 `max_id` + +### 请求 +##### 标头 + +Authorization +: {{}} 提供此标头，并使用 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +since_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +min_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +limit +: 整数。要返回的最大结果数。默认为 20 条嘟文。最大 40 条嘟文。 + +#### 响应 +##### 200: OK + +```json +[ + { + "id": "108724195870225687", + "created_at": "2022-07-28T09:12:47.000Z", + "in_reply_to_id": null, + "in_reply_to_account_id": null, + "sensitive": false, + "spoiler_text": "", + "visibility": "public", + // ... + }, + { + "id": "108200780982641655", + "created_at": "2022-04-26T22:41:28.492Z", + "in_reply_to_id": "108200775562138405", + "in_reply_to_account_id": "806143", + "sensitive": false, + "spoiler_text": "", + "visibility": "public", + // ... + }, + // ... +] +``` + +由于书签 ID 通常不会通过任何 API 响应公开，因此你必须解析 HTTP `Link` 标头才能加载较旧或较新的结果。 有关更多信息，请参见[通过 API 响应进行分页]({{}})。 + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 另请参阅 + +{{< page-relref ref="methods/statuses#bookmark" caption="POST /api/v1/statuses/:id/bookmark" >}} + +{{< page-relref ref="methods/statuses#unbookmark" caption="POST /api/v1/statuses/:id/unbookmark" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/bookmarks_controller.rb" caption="app/controllers/api/v1/bookmarks_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="bookmarks API methods" raw_link="/methods/bookmarks/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/conversations.md b/content/zh-cn/methods/conversations.md new file mode 100644 index 0000000..eb3234e --- /dev/null +++ b/content/zh-cn/methods/conversations.md @@ -0,0 +1,247 @@ +--- +title: conversations API 方法 +description: >- + 与其他参与者直接进行的会话。（目前仅包含具有“直接”可见性的嘟文的主题。） +menu: + docs: + weight: 10 + name: conversations + parent: methods-timelines + identifier: methods-conversations +aliases: [ + "/methods/conversations", + "/api/methods/conversations", + "/methods/timelines/conversations", +] +--- + + + +## 查看所有会话 {#get} + +```http +GET /api/v1/conversations HTTP/1.1 +``` + +**返回：** [Conversations]({{< relref "entities/conversation" >}}) 数组\ +**OAuth:** 用户令牌 + `read:statuses`\ +**版本历史：**\ +2.6.0 - 添加\ +3.3.0 - 现在可以同时使用 `min_id` 和 `max_id` + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，并使用 `Bearer ` 来获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +since_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +min_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +limit +: 整数。要返回的最大结果数。默认为 20 个会话。最多 40 个会话。 + +#### 响应 + +##### 200: OK + +使用 limit=2 截断结果的 API 调用结果示例如下： + +```json +[ + { + "id": "418450", + "unread": true, + "accounts": [ + { + "id": "482403", + "username": "amic", + "acct": "amic@nulled.red", + // ... + } + ], + "last_status": { + "id": "103196583826321184", + "created_at": "2019-11-25T04:08:24.000Z", + "in_reply_to_id": "103196540587943467", + "in_reply_to_account_id": "14715", + // ... + } + }, + { + "id": "418374", + "unread": false, + "accounts": [ + { + "id": "464472", + "username": "freon", + "acct": "freon@letsalllovela.in", + // ... + } + ], + "last_status": { + "id": "103195253010396431", + "created_at": "2019-11-24T22:29:56.331Z", + "in_reply_to_id": "103195239650546339", + "in_reply_to_account_id": "14715", + // ... + } + } +] +``` + +由于通常不会通过任何 API 响应公开 AccountConversation ID，因此你必须解析 HTTP `Link` 标头才能加载较旧或较新的结果。 有关更多信息，请参见[通过 API 响应进行分页]({{}})。 + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 删除一个会话 {#delete} + +```http +DELETE /api/v1/conversations/:id HTTP/1.1 +``` + +从你的会话列表中删除一个会话。 + +**返回：** 空白\ +**OAuth:** 用户令牌 + `write:conversations`\ +**版本历史：**\ +2.6.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中会话的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，并使用 `Bearer ` 来获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +该会话不存在，或者不属于你。 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 标记会话为已读 {#read} + +```http +POST /api/v1/conversations/:id/read HTTP/1.1 +``` + +**返回：** [Conversations]({{< relref "entities/conversation" >}})\ +**OAuth:** 用户令牌 + `write:conversations`\ +**版本历史：**\ +2.6.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中会话的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，并使用 `Bearer ` 来获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +`unread` 的值已更改为 false。 + +```json +{ + "id": "418450", + "unread": false, + "accounts": [ + { + "id": "482403", + // ... + } + ], + "last_status": { + "id": "103196583826321184", + // ... + } +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +该会话不存在，或者不属于你。 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/conversations_controller.rb" caption="app/controllers/api/v1/conversations_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="conversations API methods" raw_link="/methods/conversations/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/custom_emojis.md b/content/zh-cn/methods/custom_emojis.md new file mode 100644 index 0000000..c65b1bf --- /dev/null +++ b/content/zh-cn/methods/custom_emojis.md @@ -0,0 +1,89 @@ +--- +title: custom_emojis API 方法 +description: >- + 每个站点都可以定义和上传自己的自定义表情，以便附加到个人资料或嘟文。 +menu: + docs: + weight: 30 + name: custom_emojis + parent: methods-instance + identifier: methods-custom_emojis +aliases: [ + "/methods/custom_emojis", + "/api/methods/custom_emojis", + "/methods/instance/custom_emojis" +] +--- + + + +## 查看所有自定义表情 {#get} + +```http +GET /api/v1/custom_emojis HTTP/1.1 +``` + +返回实例上可用的自定义表情。 + +**返回：** [CustomEmoji]({{< relref "entities/CustomEmoji" >}})数组\ +**OAuth：** 公开\ +**版本历史：**\ +2.0.0 - 添加\ +3.0.0 - 响应中添加了可选的 `category` + +#### 响应 +##### 200: OK + +来自 mastodon.social 的示例响应 + +```json +[ + { + "shortcode": "aaaa", + "url": "https://files.mastodon.social/custom_emojis/images/000/007/118/original/aaaa.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/007/118/static/aaaa.png", + "visible_in_picker": true + }, + { + "shortcode": "AAAAAA", + "url": "https://files.mastodon.social/custom_emojis/images/000/071/387/original/AAAAAA.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/071/387/static/AAAAAA.png", + "visible_in_picker": true + }, + + // [...] + + { + "shortcode": "blobaww", + "url": "https://files.mastodon.social/custom_emojis/images/000/011/739/original/blobaww.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/011/739/static/blobaww.png", + "visible_in_picker": true, + "category": "Blobs" + }, + + // [...] + + { + "shortcode": "yikes", + "url": "https://files.mastodon.social/custom_emojis/images/000/031/275/original/yikes.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/031/275/static/yikes.png", + "visible_in_picker": true + }, + { + "shortcode": "ziltoid", + "url": "https://files.mastodon.social/custom_emojis/images/000/017/094/original/05252745eb087806.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/017/094/static/05252745eb087806.png", + "visible_in_picker": true + } +] +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/custom_emojis_controller.rb" caption="app/controllers/api/v1/custom_emojis_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="custom_emojis API methods" raw_link="/methods/custom_emojis/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/directory.md b/content/zh-cn/methods/directory.md new file mode 100644 index 0000000..2dcce25 --- /dev/null +++ b/content/zh-cn/methods/directory.md @@ -0,0 +1,80 @@ +--- +title: directory API 方法 +description: 你的网站所知的用户目录。 +menu: + docs: + weight: 20 + name: directory + parent: methods-instance + identifier: methods-directory +aliases: [ + "/methods/directory", + "/api/methods/directory", + "/methods/instance/directory", +] +--- + + + +## 查看用户目录 {#get} + +```http +GET /api/v1/directory HTTP/1.1 +``` + +列出目录中可见的用户。 + +**返回：** [Account]({{< relref "entities/account" >}})数组\ +**OAuth：** 公开\ +**版本历史：**\ +3.0.0 - 添加 + +#### 请求 + +##### 查询参数 + +offset +: 数字。跳过前 n 个结果。 + +limit +: 数字。加载多少个用户。默认为 40 个用户。最多 80 个用户。 + +order +: 字符串。使用 `active` 按最近发布的嘟文排序（默认），或者使用 `new` 按用户的创建时间降序排序。 + +local +: 布尔值。若为 true，则仅返回本站帐户。 + +#### 响应 +##### 200: OK + +limit=2 的示例结果 + +```json +[ + { + "id": "796927", + "username": "eternalNo3", + "acct": "eternalNo3@best-friends.chat", + "display_name": "ESD＠┓（谷）┏", + // ... + }, + { + "id": "787648", + "username": "ariel", + "acct": "ariel@best-friends.chat", + "display_name": "あやっしー🧜🏻‍♀️", + // ... + } +] +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/directories_controller.rb" caption="app/controllers/api/v1/directories_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="directory API methods" raw_link="/methods/directory/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/domain_blocks.md b/content/zh-cn/methods/domain_blocks.md new file mode 100644 index 0000000..d9193ad --- /dev/null +++ b/content/zh-cn/methods/domain_blocks.md @@ -0,0 +1,215 @@ +--- +title: domain_blocks API 方法 +description: 管理用户屏蔽的域名。 +menu: + docs: + weight: 50 + name: domain_blocks + parent: methods-accounts + identifier: methods-domain_blocks +aliases: [ + "/methods/domain_blocks", + "/api/methods/domain_blocks", + "/methods/accounts/domain_blocks"] +--- + + + +## 获取域名屏蔽列表 {#get} + +```http +GET /api/v1/domain_blocks HTTP/1.1 +``` + +查看用户已屏蔽的域名。 + +**返回:** 字符串数组\ +**OAuth:** 用户令牌 + `read:blocks` 或 `follow`\ +**版本:**\ +1.4.0 - 添加\ +3.3.0 - 现在可以同时使用 `min_id` 和 `max_id` + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供此标头，并使用 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +since_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +min_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +limit +: 整数。 要返回的最大结果数。 默认为 100 个被屏蔽的域名。 最大值为 200 个被屏蔽的域名。 + +#### 响应 +##### 200: OK + +使用 limit=2 的示例调用。 + +```json +["nsfw.social","artalley.social"] +``` + +由于 AccountDomainBlock ID 通常不会通过任何 API 响应公开，因此你必须解析 HTTP `Link` 标头以加载更旧或更新的结果。 有关更多信息，请参见[通过 API 响应进行分页]({{}})。 + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 屏蔽域名 {#block} + +```http +POST /api/v1/domain_blocks HTTP/1.1 +``` + +屏蔽域名以： +- 隐藏来自该域名的所有公开嘟文 +- 隐藏来自该域名的所有通知 +- 删除来自该域名的所有关注者 +- 阻止关注来自该域名的新用户（但不会删除现有的关注关系） + +**返回:** 空\ +**OAuth:** 用户令牌 + `write:blocks` 或 `follow`\ +**版本:**\ +1.4.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，并使用 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +domain +: {{}} 字符串。 要屏蔽的域名。 + +#### 响应 +##### 200: OK + +若调用成功，将返回一个空对象。 请注意，即使域名已被屏蔽、域名不存在或域名不是合法域名，调用也会成功。 + +```json +{} +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +若未提供 `domain`，则请求将失败。 + +```json +{ + "error": "Validation failed: Domain can't be blank" +} +``` + +若 `domain` 包含空格，则请求将失败。 + +```json +{ + "error": "Validation failed: Domain is not a valid domain name" +} +``` + +--- + +## 取消屏蔽域名 {#unblock} + +```http +DELETE /api/v1/domain_blocks HTTP/1.1 +``` + +若域名存在于用户的已屏蔽域名数组中，则删除域名屏蔽。 + +**返回:** 空\ +**OAuth:** 用户令牌 + `write:blocks` 或 `follow`\ +**版本历史记录:**\ +1.4.0 - 添加 + +##### 标头 + +Authorization +: {{}} 提供此标头，并使用 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +domain +: {{}} 字符串。 要取消屏蔽的域名。 + +#### 响应 +##### 200: OK + +若调用成功，将返回一个空对象。 请注意，即使该域名此前未被屏蔽，调用也会成功。 + +```json +{} +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +若未提供 `domain`，则请求将失败。 + +```json +{ + "error": "Validation failed: Domain can't be blank" +} +``` + +若 `domain` 包含空格，则请求将失败。 + +```json +{ + "error": "Validation failed: Domain is not a valid domain name" +} +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/domain_blocks_controller.rb" caption="app/controllers/api/v1/domain_blocks_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="domain_blocks API methods" raw_link="/methods/domain_blocks/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/emails.md b/content/zh-cn/methods/emails.md new file mode 100644 index 0000000..2dc121f --- /dev/null +++ b/content/zh-cn/methods/emails.md @@ -0,0 +1,80 @@ +--- +title: emails API 方法 +description: 请求新的确认邮件，可以发送到新的电子邮件地址。 +menu: + docs: + weight: 20 + name: emails + parent: methods-apps + identifier: methods-emails +aliases: [ + "/methods/emails", + "/api/methods/emails", + "/methods/apps/emails", +] +--- + + + +## 重新发送确认邮件 {#confirmation} + +```http +POST /api/v1/emails/confirmations HTTP/1.1 +``` + +重新发送一封新的确认邮件。若提供了电子邮件地址，会在重新发送确认邮件之前更新未确认用户的电子邮件地址。 + +**返回:** 空\ +**OAuth:** 颁发给创建未确认用户的客户端的用户令牌\ +**版本历史:**\ +3.4.0 - 添加 + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供此标头，值为 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +email +: 字符串。若提供，会在重新发送确认邮件之前更新未确认用户的电子邮件地址。 + +#### 响应 +##### 200: OK + +```json +{} +``` + +##### 403: Forbidden + +与令牌关联的客户端并不关联该未确认用户。 + +```json +{ + "error": "This method is only available to the application the user originally signed-up with" +} +``` + +或者，用户已经确认了他们的电子邮件地址。 + +```json +{ + "error": "This method is only available while the e-mail is awaiting confirmation" +} +``` + +--- + +## 另请参考 + +{{< page-relref ref="methods/apps#create" caption="POST /api/v1/apps" >}} + +{{< page-relref ref="methods/accounts#create" caption="POST /api/v1/accounts" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/emails/confirmations_controller.rb" caption="app/controllers/api/v1/emails/confirmations_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="emails API methods" raw_link="/methods/emails/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/endorsements.md b/content/zh-cn/methods/endorsements.md new file mode 100644 index 0000000..9653ca6 --- /dev/null +++ b/content/zh-cn/methods/endorsements.md @@ -0,0 +1,138 @@ +--- +title: endorsements API 方法 +description: 在你自己的账户中推荐其他账户。另请参见 accounts/:id/{pin,unpin} +menu: + docs: + weight: 90 + name: endorsements + parent: methods-accounts + identifier: methods-endorsements +aliases: [ + "/methods/endorsements", + "/api/methods/endorsements", + "/methods/accounts/endorsements", +] +--- + + + +## 查看当前推荐的账户 {#get} + +```http +GET /api/v1/endorsements HTTP/1.1 +``` + +用户当前在其账户中推荐的帐户。 + +**返回：** [Account]({{< relref "entities/account" >}})数组\ +**OAuth：** 用户令牌 + `read:accounts`\ +**版本历史：**\ +2.5.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供带有 `Bearer ` 的标头，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +since_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +limit +: 整数。要返回的最大结果数。默认为 40 个帐户。最大 80 个帐户。 + +#### 响应 + +##### 200: OK + +带有 limit=2 的示例调用。 + +```json +[ + { + "id": "952529", + "username": "alayna", + "acct": "alayna@desvox.es", + "display_name": "Alayna Desirae", + "locked": true, + "bot": false, + "created_at": "2019-10-26T23:12:06.570Z", + "note": "experiencing ________ difficulties
22y/o INFP in Oklahoma", + "url": "https://desvox.es/users/alayna", + "avatar": "https://files.mastodon.social/accounts/avatars/000/952/529/original/6534122046d050d5.png", + "avatar_static": "https://files.mastodon.social/accounts/avatars/000/952/529/original/6534122046d050d5.png", + "header": "https://files.mastodon.social/accounts/headers/000/952/529/original/496f1f817e042ade.png", + "header_static": "https://files.mastodon.social/accounts/headers/000/952/529/original/496f1f817e042ade.png", + "followers_count": 0, + "following_count": 0, + "statuses_count": 955, + "last_status_at": "2019-11-23T07:05:50.682Z", + "emojis": [], + "fields": [] + }, + { + "id": "832844", + "username": "a9", + "acct": "a9@broadcast.wolfgirl.engineering", + "display_name": "vivienne :collar: ", + "locked": true, + "bot": false, + "created_at": "2019-06-12T18:55:12.053Z", + "note": "borderline nsfw, considered a schedule I drug by nixon
waiting for the year of the illumos desktop", + "url": "https://broadcast.wolfgirl.engineering/users/a9", + "avatar": "https://files.mastodon.social/accounts/avatars/000/832/844/original/ae1de0b8fb63d1c6.png", + "avatar_static": "https://files.mastodon.social/accounts/avatars/000/832/844/original/ae1de0b8fb63d1c6.png", + "header": "https://files.mastodon.social/accounts/headers/000/832/844/original/5088e4a16e6d8736.png", + "header_static": "https://files.mastodon.social/accounts/headers/000/832/844/original/5088e4a16e6d8736.png", + "followers_count": 43, + "following_count": 67, + "statuses_count": 5906, + "last_status_at": "2019-11-23T05:23:47.911Z", + "emojis": [ + { + "shortcode": "collar", + "url": "https://files.mastodon.social/custom_emojis/images/000/106/920/original/80953b9cd96ec4dc.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/106/920/static/80953b9cd96ec4dc.png", + "visible_in_picker": true + } + ], + "fields": [] + } +] +``` + +AccountPin ID 通常不会通过任何 API 响应公开，所以你必须解析 HTTP `Link` 标头才能加载较旧或较新的结果。有关更多信息，请参见[通过 API 响应进行分页]({{}})。 + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 另请参考 + +{{< page-relref ref="methods/accounts#pin" caption="POST /api/v1/accounts/:id/pin" >}} + +{{< page-relref ref="methods/accounts#unpin" caption="POST /api/v1/accounts/:id/unpin" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/endorsements_controller.rb" caption="app/controllers/api/v1/endorsements_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="endorsements API methods" raw_link="/methods/endorsements/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/favourites.md b/content/zh-cn/methods/favourites.md new file mode 100644 index 0000000..4c195d7 --- /dev/null +++ b/content/zh-cn/methods/favourites.md @@ -0,0 +1,143 @@ +--- +title: favourites API 方法 +description: 查看你的喜欢。另请参阅 statuses/:id/{favourite,unfavourite} +menu: + docs: + weight: 20 + name: favourites + parent: methods-accounts + identifier: methods-favourites +aliases: [ + "/methods/favourites", + "/api/methods/favourites", + "/methods/accounts/favourites", +] +--- + + + +## 查看喜欢的嘟文 {#get} + +```http +GET /api/v1/favourites HTTP/1.1 +``` + +用户喜欢的嘟文。 + +**返回：** [Status]({{< relref "entities/status" >}}) 数组\ +**OAuth:** 用户令牌 + `read:favourites`\ +**版本：**\ +0.0.0 - 添加\ +2.6.0 - 添加 `min_id`\ +3.3.0 - 现在可以同时使用 `min_id` 和 `max_id` + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供此标头，并使用 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +since_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +min_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +limit +: 整数。要返回的最大结果数。默认为 20 条嘟文。最多 40 条嘟文。 + +#### 响应 +##### 200: OK + +一个 limit=2 的示例调用。 + +```json +[ + { + "id": "103186075217296344", + "created_at": "2019-11-23T07:35:52.000Z", + "in_reply_to_id": null, + "in_reply_to_account_id": null, + "sensitive": false, + "spoiler_text": "", + "visibility": "unlisted", + "language": "enCy", + "uri": "https://cybre.space/users/haskal/statuses/103186075002013902", + "url": "https://cybre.space/@haskal/103186075002013902", + "replies_count": 0, + "reblogs_count": 1, + "favourites_count": 1, + "favourited": true, + "reblogged": false, + "muted": false, + "bookmarked": false, + "content": "

the pirate gay

", + "reblog": null, + "account": { + "id": "297420", + "username": "haskal", + "acct": "haskal@cybre.space", + "display_name": "soft nb friend :blobcatsleep:", + // ... + }, + "media_attachments": [], + "mentions": [], + "tags": [], + "emojis": [], + "card": null, + "poll": null + }, + { + "id": "103186044372624124", + "created_at": "2019-11-23T07:28:03.000Z", + // ... + "content": "

cute,,,

", + "reblog": null, + "account": { + "id": "297420", + "username": "haskal", + "acct": "haskal@cybre.space", + "display_name": "soft nb friend :blobcatsleep:", + "locked": false, + "bot": false, + // ... + }, + // ... + } +] +``` + +由于喜欢 ID 通常不会通过任何 API 响应公开，因此你必须解析 HTTP `Link` 标头才能加载较旧或较新的结果。有关更多信息，请参阅[通过 API 响应进行分页]({{}})。 + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 另请参阅 + +{{< page-relref ref="methods/statuses#favourite" caption="POST /api/v1/statuses/:id/favourite" >}} + +{{< page-relref ref="methods/statuses#unfavourite" caption="POST /api/v1/statuses/:id/unfavourite" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/favourites_controller.rb" caption="app/controllers/api/v1/favourites_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="favourites API methods" raw_link="/methods/favourites/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/featured_tags.md b/content/zh-cn/methods/featured_tags.md new file mode 100644 index 0000000..5e61f13 --- /dev/null +++ b/content/zh-cn/methods/featured_tags.md @@ -0,0 +1,314 @@ +--- +title: featured_tags API 方法 +description: 你的账户的精选话题标签。 +menu: + docs: + weight: 100 + name: featured_tags + parent: methods-accounts + identifier: methods-featured_tags +aliases: [ + "/methods/featured_tags", + "/api/methods/featured_tags", + "/methods/accounts/featured_tags", +] +--- + + + +## 查看你的账户的精选话题标签 {#get} + +```http +GET /api/v1/featured_tags HTTP/1.1 +``` + +列出你的账户中所有的精选话题标签。 + +**返回：** [FeaturedTag]({{< relref "entities/featuredtag" >}}) 数组\ +**OAuth:** 用户令牌 + `read:accounts`\ +**版本历史：**\ +3.0.0 - 添加 + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +[ + { + "id": "627", + "name": "nowplaying", + "url": "https://mastodon.social/@trwnh/tagged/nowplaying", + "statuses_count": 70, + "last_status_at": "2022-08-29T12:03:35.061Z" + } +] +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 添加精选话题标签 {#feature} + +```http +POST /api/v1/featured_tags HTTP/1.1 +``` + +向你的账户页添加一个精选话题标签。 + +**返回：** [FeaturedTag]({{< relref "entities/featuredtag" >}})\ +**OAuth:** 用户令牌+ `write:accounts`\ +**版本历史：**\ +3.0.0 - 添加 + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +name +: {{}} 字符串。要突出显示的标签，不带井号。 + +#### 响应 +##### 200: OK + +将使用指定的 `name` 创建一个 FeaturedTag。 + +```json +{ + "id": "13174", + "name": "circasurvive", + "url": "https://mastodon.social/@trwnh/tagged/circasurvive", + "statuses_count": 23, + "last_status_at": "2021-10-22T14:47:35.357Z" +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +若 `name` 不是有效的话题标签，例如包含非法字符或仅包含数字，则返回此错误。 + +```json +{ + "error": "Validation failed: Tag is invalid" +} +``` + +--- + +## 取消精选话题标签 {#unfeature} + +```http +DELETE /api/v1/featured_tags/:id HTTP/1.1 +``` + +停止在你的账户页中展示对应的精选话题标签。 + +**返回：** 空\ +**OAuth:** 用户令牌+ `write:accounts`\ +**版本历史：**\ +3.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 FeaturedTag 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +标签已取消突出显示。 + +```json +{} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +该 FeaturedTag 不属于你或不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 查看当前的精选话题标签 {#suggestions} + +```http +GET /api/v1/featured_tags/suggestions HTTP/1.1 +``` + +最多显示 10 个最近使用的精选话题标签。 + +**返回：** [Tag]({{< relref "entities/Tag" >}}) 数组\ +**OAuth:** 用户令牌+ `read:accounts`\ +**版本历史：**\ +3.0.0 - 添加 + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +下面是截断后的结果，仅展示第一个和最后一个话题标签。 + +```json +[ + { + "name": "nowplaying", + "url": "https://mastodon.social/tags/nowplaying", + "history": [ + { + "day": "1574553600", + "uses": "200", + "accounts": "31" + }, + { + "day": "1574467200", + "uses": "272", + "accounts": "39" + }, + { + "day": "1574380800", + "uses": "345", + "accounts": "40" + }, + { + "day": "1574294400", + "uses": "366", + "accounts": "46" + }, + { + "day": "1574208000", + "uses": "226", + "accounts": "32" + }, + { + "day": "1574121600", + "uses": "217", + "accounts": "42" + }, + { + "day": "1574035200", + "uses": "214", + "accounts": "34" + } + ] + }, + // ... + { + "name": "mastothemes", + "url": "https://mastodon.social/tags/mastothemes", + "history": [ + { + "day": "1574553600", + "uses": "0", + "accounts": "0" + }, + { + "day": "1574467200", + "uses": "0", + "accounts": "0" + }, + { + "day": "1574380800", + "uses": "0", + "accounts": "0" + }, + { + "day": "1574294400", + "uses": "0", + "accounts": "0" + }, + { + "day": "1574208000", + "uses": "0", + "accounts": "0" + }, + { + "day": "1574121600", + "uses": "0", + "accounts": "0" + }, + { + "day": "1574035200", + "uses": "0", + "accounts": "0" + } + ] + } +] +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/featured_tags_controller.rb" caption="app/controllers/api/v1/featured_tags_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/featured_tags/suggestions_controller.rb" caption="app/controllers/api/v1/featured_tags/suggestions_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="featured_tags API methods" raw_link="/methods/featured_tags/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/filters.md b/content/zh-cn/methods/filters.md new file mode 100644 index 0000000..caf812f --- /dev/null +++ b/content/zh-cn/methods/filters.md @@ -0,0 +1,1415 @@ +--- +title: filters API 方法 +description: 创建和管理过滤规则。 +menu: + docs: + weight: 60 + name: filters + parent: methods-accounts + identifier: methods-filters +aliases: [ + "/methods/filters", + "/api/methods/filters", + "/methods/accounts/filters", +] +--- + +## 服务端 (v2) 方法 {#v2} + +自 Mastodon 4.0 起，过滤规则可以包含多个关键词，并在服务端进行匹配。客户端会基于[嘟文的 `filtered` 属性]({{< relref "entities/Status#filtered" >}})应用过滤操作。 + +--- + +### 查看所有过滤规则 {#get} + +```http +GET /api/v2/filters HTTP/1.1 +``` + +获取当前用户的所有过滤规则的列表。 + +**返回：**[Filter]({{< relref "entities/Filter" >}}) 数组\ +**OAuth:** 用户令牌 + `read:filters`\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +[ + { + "id": "20060", + "title": "Remove Twitter crossposts from public timeline", + "context": [ + "public" + ], + "expires_at": null, + "filter_action": "hide", + "keywords": [ + { + "id": "1311", + "keyword": "from birdsite", + "whole_word": true + }, + { + "id": "1324", + "keyword": "@twitter.com", + "whole_word": false + }, + { + "id": "1325", + "keyword": "https://t.co/", + "whole_word": false + } + ], + "statuses": [] + }, + // ... +] +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +### 查看特定过滤规则 {#get-one} + +```http +GET /api/v2/filters/:id HTTP/1.1 +``` + +获取当前用户的单条过滤规则。 + +**返回：**[Filter]({{< relref "entities/Filter" >}})\ +**OAuth:** 用户令牌 + `read:filters`\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 Filter 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{ + "id": "20060", + "title": "Remove Twitter crossposts from public timeline", + "context": [ + "public" + ], + "expires_at": null, + "filter_action": "hide", + "keywords": [ + { + "id": "1311", + "keyword": "from birdsite", + "whole_word": true + }, + { + "id": "1324", + "keyword": "@twitter.com", + "whole_word": false + }, + { + "id": "1325", + "keyword": "https://t.co/", + "whole_word": false + } + ], + "statuses": [] +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +你并未拥有该过滤规则，或该过滤规则不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +### 创建过滤规则 {#create} + +```http +POST /api/v2/filters HTTP/1.1 +``` + +使用给定参数创建过滤规则。 + +**返回：**[Filter]({{< relref "entities/Filter" >}})\ +**OAuth:** 用户令牌 + `write:filters`\ +**版本历史：**\ +4.0.0 - 添加\ +4.4.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 5) - 将 `blur` 值添加到 `filter_action` 属性 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +title +: {{}} 字符串。过滤组的名称。 + +context[] +: {{}} 字符串数组。应在何处应用过滤规则。指定 `home`、`notifications`、`public`、`thread`、`account` 中的至少一个。 + +filter_action +: 字符串。匹配过滤规则时要应用的策略。指定 `warn`、`hide` 或 `blur`。 + +expires_in +: 整数。从现在开始，过滤规则应在多少秒后过期？ + +keywords_attributes[][keyword] +: 字符串。要添加到新创建的过滤规则的关键词。 + +keywords_attributes[][whole_word] +: 布尔值。关键词是否应考虑单词边界。 + + + +#### 响应 + +##### 200: OK + +通过调用创建的 Filter 的示例： + +```text +POST https://mastodon.example/api/v2/filters +?title=test +&context[]=public +&keywords_attributes[][keyword]=foo +&keywords_attributes[][whole_word]=false +&keywords_attributes[][keyword]=bar +&keywords_attributes[][whole_word]=true +``` + +```json +{ + "id": "25933", + "title": "test", + "context": [ + "public" + ], + "expires_at": null, + "filter_action": "warn", + "keywords": [ + { + "id": "34978", + "keyword": "foo", + "whole_word": false + }, + { + "id": "34979", + "keyword": "bar", + "whole_word": true + } + ], + "statuses": [] +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +未指定过滤规则关键词 ID + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +```json +{ + "error": "Validation failed: Title can't be blank, Context can't be blank, Context None or invalid context supplied" +} +``` + +--- + +### 更新过滤规则 {#update} + +```http +PUT /api/v2/filters/:id HTTP/1.1 +``` + +使用给定参数更新过滤规则。 + +**返回：**[Filter]({{< relref "entities/Filter" >}})\ +**OAuth:** 用户令牌 + `write:filters`\ +**版本历史：**\ +4.0.0 - 添加\ +4.4.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 5) - 将 `blur` 值添加到 `filter_action` 属性 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 Filter 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +title +: 字符串。过滤组的名称。 + +context[] +: 字符串数组。应在何处应用过滤规则。指定 `home`、`notifications`、`public`、`thread`、`account` 中的至少一个。 + +filter_action +: 字符串。匹配过滤规则时要应用的策略。指定 `warn`、`hide` 或 `blur`。 + +expires_in +: 整数。从现在开始，过滤规则应在多少秒后过期？ + +keywords_attributes[][keyword] +: 字符串。要添加到新创建的过滤规则的关键词。 + +keywords_attributes[][whole_word] +: 布尔值。关键词是否应考虑单词边界。 + +keywords_attributes[][id] +: 字符串。提供现有关键词的 ID 以修改它，而不是创建新关键词。 + +keywords_attributes[][_destroy] +: 布尔值。若为 true，将删除具有给定 ID 的关键词。 + +#### 响应 +##### 200: OK + +示例调用： + +``` +PUT /api/v2/filters/25933 +?keywords_attributes[][id]=34978 +&keywords_attributes[][_destroy]=true +&keywords_attributes[][id]=34979 +&keywords_attributes[][keyword]=baz +``` + +这将删除关键词 34978 ("foo")，并将关键词 34979 ("bar") 替换为新关键词 ("baz") + +```json +{ + "id": "25933", + "title": "test", + "context": [ + "public" + ], + "expires_at": null, + "filter_action": "warn", + "keywords": [ + { + "id": "34979", + "keyword": "baz", + "whole_word": true + } + ], + "statuses": [] +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +你未拥有该过滤规则，或该过滤规则不存在。或者，在请求中提供了 `keywords_attributes[][id]`，但此 Filter 中没有具有给定 id 的关键词。 + +```json +{ + "error": "Record not found" +} +``` + +--- + +### 删除过滤规则 {#delete} + +```http +DELETE /api/v2/filters/:id HTTP/1.1 +``` + +删除具有给定 id 的过滤规则。 + +**返回：**空\ +**OAuth:** 用户令牌 + `write:filters`\ +**版本历史：**\ +4.0.0 - 添加 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 Filter 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +过滤规则已成功删除 + +```json +{} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +你未拥有该过滤规则，或该过滤规则不存在。 + +```json +{ + "error": "Record not found" +} +``` + +--- + +### 查看添加到过滤规则的关键词 {#keywords-get} + +```http +GET /api/v2/filters/:filter_id/keywords HTTP/1.1 +``` + +列出附加到当前过滤规则的所有关键词。 + +**返回：**[FilterKeyword]({{< relref "entities/FilterKeyword" >}}) 数组\ +**OAuth:** 用户令牌 + `read:filters`\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:filter_id +: {{}} 字符串。数据库中 Filter 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +[ + { + "id": "34979", + "keyword": "baz", + "whole_word": true + }, + // ... +] +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +你未拥有该过滤规则，或该过滤规则不存在。 + +```json +{ + "error": "Record not found" +} +``` + +--- + +### 将关键词添加到过滤规则 {#keywords-create} + +```http +POST /api/v2/filters/:filter_id/keywords HTTP/1.1 +``` + +将给定的关键词添加到指定的过滤规则 + +**返回：**[FilterKeyword]({{< relref "entities/FilterKeyword" >}})\ +**OAuth:** 用户令牌 + `write:filters`\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:filter_id +: {{}} 字符串。数据库中 Filter 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +keyword +: {{}} 字符串。要添加到过滤规则的关键词。 + +whole_word +: 布尔值。关键词是否应考虑单词边界。 + +#### 响应 +##### 200: OK + +```json +{ + "id": "35583", + "keyword": "some", + "whole_word": false +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +你未拥有该过滤规则，或该过滤规则不存在。 + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +未提供关键词 + +```json +{ + "error": "Validation failed: Keyword can't be blank" +} +``` + +--- + +### 查看单个关键词 {#keywords-get-one} + +```http +GET /api/v2/filters/keywords/:id HTTP/1.1 +``` + +通过给定的 id 获取一个过滤规则关键词。 + +**返回：**[FilterKeyword]({{< relref "entities/FilterKeyword" >}})\ +**OAuth:** 用户令牌 + `read:filters`\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 FilterKeyword 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{ + "id": "34979", + "keyword": "baz", + "whole_word": true +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +你未拥有该过滤规则，或者该过滤规则或过滤规则关键词不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +### 编辑过滤规则中的关键词 {#keywords-update} + +```http +PUT /api/v2/filters/keywords/:id HTTP/1.1 +``` + +更新给定的过滤规则关键词。 + +**返回：**[FilterKeyword]({{< relref "entities/FilterKeyword" >}})\ +**OAuth:** 用户令牌 + `write:filters`\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 FilterKeyword 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +keyword +: {{}} 字符串。要添加到过滤规则的关键词。 + +whole_word +: 布尔值。关键词是否应考虑单词边界。 + +#### 响应 +##### 200: OK + +关键词 "some" 已更新为关键词 "other" + +```json +{ + "id": "35583", + "keyword": "other", + "whole_word": false +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +你未拥有 FilterKeyword，或者它不存在 + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +未提供关键词 + +```json +{ + "error": "Validation failed: Keyword can't be blank" +} +``` + +--- + +### 从过滤规则中删除关键词 {#keywords-delete} + +```http +DELETE /api/v2/filters/keywords/:id HTTP/1.1 +``` + +删除给定的过滤规则关键词。 + +**返回：**空\ +**OAuth:** 用户令牌 + `write:filters`\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 FilterKeyword 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +FilterKeyword 已成功删除 + +```json +{} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +你并未拥有 FilterKeyword，或者它不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +### 查看所有嘟文过滤规则 {#statuses-get} + +```http +GET /api/v2/filters/:filter_id/statuses HTTP/1.1 +``` + +获取此过滤规则中的所有嘟文过滤规则的列表。 + +**返回：**[FilterStatus]({{< relref "entities/FilterStatus" >}}) 数组\ +**OAuth:** 用户令牌 + `read:filters`\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:filter_id +: {{}} 字符串。数据库中 Filter 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +[ + { + "id": "897", + "status_id": "109416512469928632" + }, + // ... +] +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +你未拥有该过滤规则或该过滤规则不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +### 将嘟文添加到过滤规则 {#statuses-add} + +```http +POST /api/v2/filters/:filter_id/statuses HTTP/1.1 +``` + +将对应嘟文添加到当前过滤规则。 + +**返回：**[FilterStatus]({{< relref "entities/FilterStatus" >}})\ +**OAuth:** 用户令牌 + `write:filters`\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:filter_id +: {{}} 字符串。数据库中 Filter 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +status_id +: {{}} 字符串。要添加到过滤规则的嘟文 ID。 + +#### 响应 +##### 200: OK + +在当前过滤规则中成功创建 FilterStatus + +```json +{ + "id": "897", + "status_id": "109416512469928632" +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +你未拥有该过滤规则或该过滤规则不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +### 查看单条嘟文过滤规则 {#statuses-get-one} + +```http +GET /api/v2/filters/statuses/:id HTTP/1.1 +``` + +获取单条嘟文过滤规则。 + +**返回：**[FilterStatus]({{< relref "entities/FilterStatus" >}})\ +**OAuth:** 用户令牌 + `read:filters`\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 FilterStatus 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{ + "id": "897", + "status_id": "109416512469928632" +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +你未拥有 FilterStatus 或者它不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +### 从过滤规则中删除嘟文 {#statuses-remove} + +```http +DELETE /api/v2/filters/statuses/:id HTTP/1.1 +``` + +从当前过滤规则中删除嘟文过滤规则。 + +**返回：**空\ +**OAuth:** 用户令牌 + `write:filters`\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 FilterStatus 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +FilterStatus 已成功删除 + +```json +{} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +你并未拥有 FilterStatus，或者它不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 客户端 (v1) 方法 {#v1} + +在 Mastodon 4.0 之前，过滤规则的匹配是在客户端完成的，并且过滤规则只能包含一个要过滤的短语。 + +--- + +### 查看你的过滤规则 {{%deprecated%}} {#get-v1} + +```http +GET /api/v1/filters HTTP/1.1 +``` + +**返回：**[V1::Filter]({{< relref "entities/V1_Filter" >}}) 的列表\ +**OAuth:** 用户令牌 + `read:filters`\ +**版本历史：**\ +2.4.3 - 添加\ +4.0.0 - 弃用。出于兼容目的，现在返回 V1::Filter 的列表，其中每个 V1::Filter 代表一个 FilterKeyword（`keyword` 在 `phrase` 属性中呈现） + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +不同上下文中各种过滤规则的摘录。 + +```json +[ + { + "id": "6191", + "phrase": ":eurovision2019:", + "context": [ + "home" + ], + "whole_word": true, + "expires_at": "2019-05-21T13:47:31.333Z", + "irreversible": false + }, + // ... + { + "id": "5580", + "phrase": "@twitter.com", + "context": [ + "home", + "notifications", + "public", + "thread" + ], + "whole_word": false, + "expires_at": null, + "irreversible": true + }, + // ... +] +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +### 查看单条过滤规则 {{%deprecated%}} {#get-one-v1} + +```http +GET /api/v1/filters/:id HTTP/1.1 +``` + +**返回：**[V1::Filter]({{< relref "entities/V1_Filter" >}})\ +**OAuth:** 用户令牌 + `read:filters`\ +**版本历史：**\ +2.4.3 - 添加\ +4.0.0 - 弃用。出于兼容性目的，现在返回一个 V1::Filter，它代表一个 FilterKeyword (`keyword` 显示在 `phrase` 属性中)。 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 FilterKeyword 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{ + "id": "8449", + "phrase": "test", + "context": [ + "home", + "notifications", + "public", + "thread" + ], + "whole_word": false, + "expires_at": "2019-11-26T09:08:06.254Z", + "irreversible": true +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +过滤规则 ID 不存在，或者不属于你 + +```json +{ + "error": "Record not found" +} +``` + +--- + +### 创建过滤规则 {{%deprecated%}} {#create-v1} + +```http +POST /api/v1/filters HTTP/1.1 +``` + +**返回：**[V1::Filter]({{< relref "entities/V1_Filter" >}})\ +**OAuth:** 用户令牌 + `write:filters`\ +**版本历史：**\ +2.4.3 - 添加\ +3.1.0 - 向账户视图中的过滤规则添加了 `account` 上下文\ +4.0.0 - 弃用。出于兼容性目的，现在返回一个 V1::Filter，它代表一个 FilterKeyword (`keyword` 显示在 `phrase` 属性中)。 此方法将创建一个仅包含一个 FilterKeyword 的 Filter。 Filter 的 `title` 和 FilterKeyword 的 `keyword` 将等于提供的 `phrase`。 + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +phrase +: {{}} 字符串。要过滤的正文文本。 + +context[] +: {{}} 字符串数组。应在何处应用过滤规则。指定 `home`、`notifications`、`public`、`thread`、`account` 中的至少一个。 + +irreversible +: 布尔值。实例是否应不可逆地从主页和通知中删除匹配的实体？ 默认为 false。 + +whole_word +: 布尔值。过滤规则是否应考虑此关键词的单词边界？ 默认为 false。 + +expires_in +: 整数。 从现在开始计算，过滤规则应过期的秒数。 对于不过期的过滤规则为 `null`。 + +#### 响应 +##### 200: OK + +将返回新创建的过滤规则。 + +```json +{ + "id": "8449", + "phrase": "test", + "context": [ + "home", + "notifications", + "public", + "thread" + ], + "whole_word": false, + "expires_at": "2019-11-26T09:08:06.254Z", + "irreversible": true +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +若未正确提供短语： + +```json +{ + "error": "Validation failed: Phrase can't be blank" +} +``` + +若未正确提供上下文: + +```json +{ + "error": "Validation failed: Context can't be blank, Context None or invalid context supplied" +} +``` + +--- + +### 更新过滤规则 {{%deprecated%}} {#update-v1} + +```http +PUT /api/v1/filters/:id HTTP/1.1 +``` + +就地替换过滤规则的参数。 + +**返回：**[V1::Filter]({{< relref "entities/V1_Filter" >}})\ +**OAuth:** 用户令牌 + `write:filters`\ +**版本历史：**\ +2.4.3 - 添加\ +3.1.0 - 向账户视图中的过滤规则添加了 `account` 上下文\ +4.0.0 - 弃用。出于兼容性目的，现在返回一个 V1::Filter，它代表一个 FilterKeyword (`keyword` 显示在 `phrase` 属性中)。 若你尝试更改具有多个关键词的过滤规则的 `expires_in`、`irreversible` 或 `context`，此方法将返回错误。 更改 `phrase` 和 `whole_word` 始终是安全的。 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 FilterKeyword 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +phrase +: {{}} 字符串。要过滤的正文文本。 + +context[] +: {{}} 字符串数组。 指定 `home`、`notifications`、`public`、`thread` 或 `account` 中的至少一个。 + +irreversible +: 布尔值。实例是否应从主页和通知中不可逆地删除命中的实体？ 默认为 false。 + +whole_word +: 布尔值。过滤规则是否应考虑单词边界？ 默认为 false。 + +expires_in +: 整数。 从现在开始，过滤规则应过期的秒数。 否则，对于不过期的过滤规则为 `null`。 + +#### 响应 +##### 200: OK + +过滤规则已更新 + +```json +{ + "id": "8449", + "phrase": "test", + "context": [ + "home", + "notifications", + "public", + "thread" + ], + "whole_word": false, + "expires_at": null, + "irreversible": true +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +过滤规则不存在或不属于你 + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +若未正确提供短语： + +```json +{ + "error": "Validation failed: Phrase can't be blank" +} +``` + +若未正确提供上下文: + +```json +{ + "error": "Validation failed: Context can't be blank, Context None or invalid context supplied" +} +``` + +--- + +### 删除过滤规则 {{%deprecated%}} {#delete-v1} + +```http +DELETE /api/v1/filters/:id HTTP/1.1 +``` + +**返回：**空\ +**OAuth:** 用户令牌 + `write:filters`\ +**版本历史：**\ +2.4.3 - 添加\ +4.0.0 - 弃用。 此方法将仅从其上级过滤规则中删除 FilterKeyword。 要删除上级过滤规则，你必须使用 v2 过滤规则 API。 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 Filter 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +过滤规则已成功删除，因此将返回一个空对象。 + +```json +{} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +过滤规则不存在或不属于你 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 另请参考 + +{{< page-relref ref="api/guidelines#filters" caption="过滤规则实现指南" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v2/filters_controller.rb" caption="app/controllers/api/v2/filters_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/filters/keywords_controller.rb" caption="app/controllers/api/v1/filters/keywords_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/filters/statuses_controller.rb" caption="app/controllers/api/v1/filters/statuses_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/filters_controller.rb" caption="app/controllers/api/v1/filters_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="filters API methods" raw_link="/methods/filters/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/follow_requests.md b/content/zh-cn/methods/follow_requests.md new file mode 100644 index 0000000..9020038 --- /dev/null +++ b/content/zh-cn/methods/follow_requests.md @@ -0,0 +1,230 @@ +--- +title: follow_requests API 方法 +description: 查看和管理关注请求。 +menu: + docs: + weight: 80 + name: follow_requests + parent: methods-accounts + identifier: methods-follow_requests +aliases: [ + "/methods/follow_requests", + "/api/methods/follow_requests", + "/methods/accounts/follow_requests", +] +--- + + + +## 查看待处理的关注请求 {#get} + +```http +GET /api/v1/follow_requests HTTP/1.1 +``` + +**返回：** [Account]({{< relref "entities/account" >}}) 数组\ +**OAuth：** 用户令牌 + `read:follows` 或 `follow`\ +**版本历史：**\ +0.0.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +since_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +limit +: 整数。要返回的最大结果数。默认为 40 个帐户。最大 80 个帐户。 + +#### 响应 +##### 200: OK + +请求关注的帐户的示例调用，其中 limit=2 + +```json +[ + { + "id":"108119793981152178", + "username":"spcpro3022", + "acct":"spcpro3022@shitposter.club", + "display_name":"spcpro3022", + // ... + }, + { + "id":"106780475844882270", + "username":"EricStoner", + "acct":"EricStoner@freeatlantis.com", + "display_name":"EricStoner", + // ... + } +] +``` + +由于 FollowRequest ID 通常不会通过任何 API 响应公开，因此你必须解析 HTTP `Link` 标头才能加载较旧或较新的结果。有关更多信息，请参阅[通过 API 响应进行分页]({{}})。 + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 接受关注请求 {#accept} + +```http +POST /api/v1/follow_requests/:account_id/authorize HTTP/1.1 +``` + +**返回：** [Relationship]({{< relref "entities/relationship" >}})\ +**OAuth：** 用户令牌 + `write:follows` 或 `follow`\ +**版本历史：**\ +0.0.0 - 添加\ +3.0.0 - 现在返回 Relationship，而不是什么都不返回 + +#### 请求 + +##### 路径参数 + +:account_id +: {{}} 字符串。数据库中 Account 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +你与此帐户的关系应已更新，现在你与该帐户的关系为 `followed_by`。 + +```json +{ + "id": "8889777", + "following": false, + "showing_reblogs": 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" +} +``` + +##### 404: Not found + +没有来自该帐户 ID 的待处理关注请求 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 拒绝关注请求 {#reject} + +```http +POST /api/v1/follow_requests/:account_id/reject HTTP/1.1 +``` + +**返回：** [Relationship]({{< relref "entities/relationship" >}})\ +**OAuth：** 用户令牌 + `write:follows` 或 `follow`\ +**版本历史：**\ +0.0.0 - 添加\ +3.0.0 - 现在返回 Relationship，而不是什么都不返回 + +#### 请求 + +##### 路径参数 + +:account_id +: {{}} 字符串。数据库中 Account 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +你与此帐户的关系应保持不变。 + +```json +{ + "id": "8889777", + "following": false, + "showing_reblogs": 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" +} +``` + +##### 404: Not found + +没有来自该帐户 ID 的待处理关注请求 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/follow_requests_controller.rb" caption="app/controllers/api/v1/follow_requests_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="follow_requests API methods" raw_link="/methods/follow_requests/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/followed_tags.md b/content/zh-cn/methods/followed_tags.md new file mode 100644 index 0000000..f17f2b9 --- /dev/null +++ b/content/zh-cn/methods/followed_tags.md @@ -0,0 +1,134 @@ +--- +title: followed_tags API 方法 +description: 查看你关注的话题标签。 +menu: + docs: + weight: 120 + name: followed_tags + parent: methods-accounts + identifier: methods-followed_tags +aliases: [ + "/methods/followed_tags", + "/api/methods/followed_tags", +] +--- + + + +## 查看所有关注的话题标签 {#get} + +```http +GET /api/v1/followed_tags HTTP/1.1 +``` + +列出你关注的全部话题话题标签。 + +**返回：** [Tag]({{< relref "entities/Tag" >}}) 数组\ +**OAuth:** 用户令牌 + `read:follows`\ +**版本历史：**\ +4.0.0 - 添加\ +4.1.0 - 添加分页标头 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +since_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +min_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +limit +: 整数。要返回的最大结果数。默认为 100 个话题标签。最多 200 个话题标签。 + +#### 响应 +##### 200: OK + +关注的话题标签列表 + +```json +[ + { + "name": "Test", + "url": "http://mastodon.example/tags/test", + "history": [ + { + "day": "1668556800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668470400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668384000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668297600", + "accounts": "1", + "uses": "1" + }, + { + "day": "1668211200", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668124800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668038400", + "accounts": "0", + "uses": "0" + } + ], + "following": true + }, + // ... +] +``` + +由于 TagFollow ID 通常不会通过任何 API 响应公开，因此你必须解析 HTTP `Link` 标头才能加载较旧或较新的结果。 有关更多信息，请参阅[通过API响应进行分页]({{}})。 + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 另请参考 + +{{< page-relref ref="methods/tags#follow" caption="POST /api/v1/tags/:id/follow" >}} + +{{< page-relref ref="methods/tags#unfollow" caption="POST /api/v1/tags/:id/unfollow" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/followed_tags_controller.rb" caption="app/controllers/api/v1/followed_tags_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="followed_tags API methods" raw_link="/methods/followed_tags/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/grouped_notifications.md b/content/zh-cn/methods/grouped_notifications.md new file mode 100644 index 0000000..9a12556 --- /dev/null +++ b/content/zh-cn/methods/grouped_notifications.md @@ -0,0 +1,672 @@ +--- +title: Grouped notifications API 方法 +description: 接收关于你的帐户或嘟文活动的已分组通知。 +menu: + docs: + weight: 50 + name: grouped notifications + parent: methods + identifier: methods-grouped-notifications +aliases: [ + "/methods/grouped_notifications", + "/api/methods/grouped_notifications", +] +--- + + + +此页面介绍分组通知，我们在服务端实现了分组通知，以便： +- 分组在各个客户端之间保持一致 +- 客户端不会遇到遍历整个页面但未产生任何新组的问题；通知已经在服务端进行了去重 + +API 的结构与非分组通知略有不同，因为大型通知组通常涉及相同的帐户，并且将帐户移动到根键可以避免大量重复，从而减少服务端的工作量并减轻网络负载。 + +## 获取所有分组通知 {#get-grouped} + +```http +GET /api/v2/notifications HTTP/1.1 +``` + +返回与用户相关的分组通知。此 API 返回包含指向下一页/上一页链接的 Link 标头。但是，链接也可以使用查询参数和 `id` 值嘟文构建。 + +在相近时间段内发生的类型为 `favourite`、`follow`、`reblog` 或 `admin.sign_up` 且类型和目标相同的通知将由实例赋予相同的 `group_key`，查询此端点将返回聚合通知，每个 `group_key` 只有一个对象。将来可能会对其他通知类型进行分组。客户端应使用 `grouped_types` 参数显式列出其支持显示分组通知的类型。 + +可筛选的类型包括： +- `mention` = 有人在他们的嘟文中提到了你 +- `status` = 你启用了通知的人发布了嘟文 +- `reblog` = 有人转发了你的一条嘟文 +- `follow` = 有人关注了你 +- `follow_request` = 有人请求关注你 +- `favourite` = 有人喜欢了你的一条嘟文 +- `poll` = 你已投票或创建的投票已结束 +- `update` = 你转发的嘟文已被编辑 +- `admin.sign_up` = 有人注册了（可以选择发送给管理员） +- `admin.report` = 已提交新举报 + +**返回：** [GroupedNotificationsResults](#GroupedNotificationsResults)\ +**OAuth：** 用户令牌 + `read:notifications`\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加\ +4.4.0 - 将 `admin.sign_up` 添加到分组通知类型 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 请提供带有 `Bearer ` 的标头，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: 字符串。返回的所有结果都将严格早于此通知 ID 的通知。事实上设置了结果的上限。 + +since_id +: 字符串。返回的所有结果都将严格晚于此通知 ID 的通知。事实上设置了结果的下限。 + +min_id +: 字符串。返回关于紧接在此通知 ID 之后的新通知的结果。事实上在此 ID 处设置一个游标并向前分页。 + +limit +: 整数。要返回的最大结果数。默认为 40 个通知组。最多 80 个通知组。 + +types[] +: 字符串数组。要包含在结果中的类型。 + +exclude_types[] +: 字符串数组。要从结果中排除的类型。 + +account_id +: 字符串。仅返回从指定帐户收到的通知。 + +expand_accounts +: 字符串。`full`（默认）或 `partial_avatars` 之一。当设置为 `partial_avatars` 时，某些帐户将不会在返回的 `accounts` 列表中完整呈现，而是以精简形式在 `partial_accounts` 列表中返回。通知组中最新的帐户始终在 `accounts` 属性中完整呈现。 + +grouped_types[] +: 字符串数组。限制可以分组的通知类型。若你的客户端不支持对某些通知类型进行分组，请使用此参数。若省略，实例将对它支持的所有类型的通知进行分组（目前为 `favourite`、`follow`、`reblog` 和 `admin.sign_up`）。若你不希望任何通知分组，请改用 [GET `/api/v1/notifications`]({{< relref "methods/notifications#get" >}})。在未提供此参数时会被分组的通知类型下的通知将作为具有唯一 `group_key` 的单个通知组返回，该 `group_key` 可以假定为 `ungrouped-{notification_id}` 的形式。请注意，流式 API 和单个通知 API 均不知晓此参数，并且将始终包含一个“正确的” `group_key`，该 `group_key` 可能与此处返回的内容不同，这意味着你可能必须忽略你不希望分组的通知的 `group_key`，并使用 `ungrouped-{notification_id}` 来保持一致性。 + +include_filtered +: 布尔值。是否包括用户[NotificationPolicy]({{< relref "entities/NotificationPolicy" >}})筛选的通知。默认为 false。 + +#### 响应 + +limit=2 的示例调用。 + +```http +GET https://mastodon.social/api/v2/notifications?limit=2 HTTP/1.1 +Authorization: Bearer xxx +``` + +##### 200: OK + +响应体包含一页分组通知。你可以使用 HTTP Link 标头进行进一步的分页。 + +```http +Link: ; rel="next", ; rel="prev"; +``` + +```json +{ + "accounts": [ + { + "id": "16", + "username": "eve", + "acct": "eve", + // … + }, + { + "id": "3547", + "username": "alice", + "acct": "alice", + // … + }, + { + "id": "31460", + "username": "bob", + "acct": "bob", + // … + }, + { + "id": "36509", + "username": "mallory", + "acct": "mallory", + // … + } + ], + "statuses": [ + { + "id": "113010503322889311", + "created_at": "2024-08-23T08:57:12.057Z", + "account": { + "id": "55911", + "username": "user", + "acct": "user", + // … + }, + // … + }, + { + "id": "113006771938929950", + "created_at": "2024-08-22T17:08:15.654Z", + "account": { + "id": "55911", + "username": "user", + "acct": "user", + // … + }, + // … + } + ], + "notification_groups": [ + { + "group_key": "favourite-113010503322889311-479000", + "notifications_count": 2, + "type": "favourite", + "most_recent_notification_id": 196014, + "page_min_id": "196013", + "page_max_id": "196014", + "latest_page_notification_at": "2024-08-23T08:59:56.743Z", + "sample_account_ids": [ + "16", + "3547" + ], + "status_id": "113010503322889311" + }, + { + "group_key": "favourite-113006771938929950-478999", + "notifications_count": 2, + "type": "favourite", + "most_recent_notification_id": 196012, + "page_min_id": "196012", + "page_max_id": "196012", + "latest_page_notification_at": "2024-08-23T08:16:32.112Z", + "sample_account_ids": [ + "31460", + "36509" + ], + "status_id": "113006771938929950" + } + ] +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 获取单个通知组 {#get-notification-group} + +```http +GET /api/v2/notifications/:group_key HTTP/1.1 +``` + +查看有关具有给定分组键的特定通知组的信息。 + +**返回：** [GroupedNotificationsResults](#GroupedNotificationsResults)\ +**OAuth：** 用户令牌 + `read:notifications`\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### 请求 + +##### 路径参数 + +:group_key +: {{}} 字符串。通知组的分组键。 + +##### 标头 + +Authorization +: {{}} 请提供带有 `Bearer ` 的标头，以获得对此 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +成功后，返回一个带有单个通知组的 [GroupedNotificationsResults](#GroupedNotificationsResults)。 + +```json +{ + "accounts": [ + { + "id": "16", + "username": "eve", + "acct": "eve", + // … + }, + { + "id": "3547", + "username": "alice", + "acct": "alice", + // … + } + ], + "statuses": [ + { + "id": "113010503322889311", + "created_at": "2024-08-23T08:57:12.057Z", + "account": { + "id": "55911", + "username": "user", + "acct": "user", + // … + }, + // … + } + ], + "notification_groups": [ + { + "group_key": "favourite-113010503322889311-479000", + "notifications_count": 2, + "type": "favourite", + "most_recent_notification_id": 196014, + "sample_account_ids": [ + "16", + "3547" + ], + "status_id": "113010503322889311" + } + ] +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 消除单个通知组 {#dismiss-group} + +```http +POST /api/v2/notifications/:group_key/dismiss HTTP/1.1 +``` + +从实例中消除单个通知组。 + +**返回：** 空\ +**OAuth：** 用户令牌 + `write:notifications`\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### 请求 + +##### 路径参数 + +:group_key +: {{}} 字符串。要丢弃的通知的分组键。 + +##### 标头 + +Authorization +: {{}} 请提供带有 `Bearer ` 的标头，以获得对此 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +在成功请求后，具有给定分组键的通知将被成功消除。 + +```json +{} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 获取通知组中所有通知的关联帐户 {#get-group-accounts} + +```http +GET /api/v2/notifications/:group_key/accounts HTTP/1.1 +``` + +**返回：** [Account]({{< relref "entities/Account" >}})数组\ +**OAuth：** 用户令牌 + `write:notifications`\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### 请求 + +##### 路径参数 + +:group_key +: {{}} 字符串。要从中获取帐户的通知的分组键。 + +##### 标头 + +Authorization +: {{}} 请提供带有 `Bearer ` 的标头，以获得对此 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +```json +[ + { + "id": "16", + "username": "eve", + "acct": "eve" + // … + }, + { + "id": "3547", + "username": "alice", + "acct": "alice" + // … + } +] +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 获取未读通知的数量 {#unread-group-count} + +```http +GET /api/v2/notifications/unread_count HTTP/1.1 +``` + +获取当前用户的未读通知组的（上限）数量。 +若通知比[通知读取标记]({{< relref "methods/markers" >}})更新，则认为该通知未读。 +由于计数取决于参数，因此每次请求都会重新计算该数值，因此这是一个相对较慢的操作（尽管比获取完整的相应通知更快），因此返回的通知数量受到限制。 + +**返回：** 带有单个 `count` 键的哈希\ +**OAuth：** 用户令牌 + `read:notifications`\ +**版本历史**:\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供带有 `Bearer ` 的标头，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +limit +: 整数。要返回的最大结果数。默认为 100 个通知。最多 1000 个通知。 + +types[] +: 字符串数组。应计入未读通知的通知类型。 + +exclude_types[] +: 字符串数组。不应计入未读通知的通知类型。 + +account_id +: 字符串。仅计算从指定帐户收到的未读通知。 + +grouped_types[] +: 字符串数组。限制可以分组的通知类型。若你的客户端不支持对某些通知类型进行分组，请使用此参数。若省略，实例将对它支持的所有类型的通知进行分组（目前为 `favourite`、`follow` 和 `reblog`）。若你不想要任何通知分组，请改用 [GET `/api/v1/notifications/unread_count`]({{< relref "methods/notifications#unread-count" >}})。 + +#### 响应 + +##### 200: OK + +响应体包含未读通知的上限计数。 + +```json +{ + "count": 42, +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## `GroupedNotificationsResults` 实体 {#GroupedNotificationsResults} + +### 属性 + +#### `accounts` + +**描述：** 分组通知引用的帐户。\ +**类型：** [Account]({{< relref "entities/Account" >}})数组\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `partial_accounts` {{%optional%}} + +**描述：** 分组通知引用的部分帐户。这些仅在使用 `expand_accounts=partial_avatars` 请求分组通知时返回。 +**类型：** [PartialAccountWithAvatar](#PartialAccountWithAvatar)数组\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `statuses` + +**描述：** 分组通知引用的嘟文。\ +**类型：** [Status]({{< relref "entities/Status" >}})数组\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `notification_groups` + +**描述：** 分组通知本身。 +**类型：** [NotificationGroup](#NotificationGroup)\ +**版本历史：** +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +### 示例 + +TODO + +--- + +## `PartialAccountWithAvatar` 实体 {#PartialAccountWithAvatar} + +这些是[Account]({{< relref "entities/Account" >}})的精简版本，仅包含显示头像列表以及其他一些有用的属性所需的内容。目的是减少昂贵的服务端序列化并减小通知组的网络载荷大小。 + +### 属性 + +#### `id` + +**描述：** 帐户 ID。\ +**类型：** 字符串（从整数转换，但不保证是数字）\ +**版本历史：**\ +4.3.0 - 添加 + +#### `acct` + +**描述：** Webfinger 帐户 URI。对于本站用户，等于 `username`，对于外站用户，等于 `username@domain`。\ +**类型：** 字符串\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `url` + +**描述：** 用户账户页面的位置。\ +**类型：** 字符串 (URL)\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `avatar` + +**描述：** 显示在嘟文旁边和账户页中的图像图标。\ +**类型：** 字符串 (URL)\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `avatar_static` + +**描述：** 头像的静态版本。若其值为静态图像，则等于 `avatar`；若 `avatar` 是动画 GIF，则不同。\ +**类型：** 字符串 (URL)\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `locked` + +**描述：** 帐户是否手动批准关注请求。\ +**类型：** 布尔值\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `bot` + +**描述：** 指示该帐户可能执行自动操作，可能未被监控，或被标识为机器人。\ +**类型：** 布尔值\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +### 示例 + +TODO + +-- + +## `NotificationGroup` 实体 {#NotificationGroup} + +### 属性 + +#### `group_key` + +**描述：** 标识分组通知的分组键。应视为不透明的值。\ +**类型：** 字符串\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `notifications_count` + +**描述：** 构成此通知组的单个通知的总数。\ +**类型：** 整数\\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `type` + +**描述：** 导致此组中通知的事件类型。\ +**类型：** 字符串（可枚举的 oneOf）\ +`mention` = 有人在他们的嘟文中提到了你\ +`status` = 你启用了通知的人发布了嘟文\ +`reblog` = 有人转发了你的一条嘟文\ +`follow` = 有人关注了你\ +`follow_request` = 有人请求关注你\ +`favourite` = 有人喜欢了你的一条嘟文\ +`poll` = 你已投票或创建的投票已结束\ +`update` = 你与之交互的嘟文已被编辑\ +`admin.sign_up` = 有人注册了（可以选择发送给管理员）\ +`admin.report` = 已提交新举报\ +`severed_relationships` = 由于审核或屏蔽事件，你的一些关注关系已被切断\ +`moderation_warning` = 管理员已对你的帐户采取措施或向你发送了警告\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `most_recent_notification_id` + +**描述：** 组中最新通知的 ID。\ +**类型：** 字符串\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `page_min_id` {{%optional%}} + +**描述：** 当前页面中表示的此通知组中最旧通知的 ID。仅在分页浏览通知组时返回。在轮询新通知时很有用。\ +**类型：** 字符串\ +**版本历史：** +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `page_max_id` {{%optional%}} + +**描述：** 当前页面中表示的此通知组中最新通知的 ID。仅在分页浏览通知组时返回。在轮询新通知时很有用。\ +**类型：** 字符串\ +**版本历史：** +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `latest_page_notification_at` {{%optional%}} + +**描述：** 当前页面中此通知组中最新通知的创建日期。仅在分页浏览通知组时返回。\ +**类型：** ([Datetime](/api/datetime-format#datetime)) 字符串\ +**版本历史：** +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `sample_account_ids` + +**描述：** 最近触发此通知组中通知的一些帐户的 ID。\ +**类型：** 字符串数组\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `status_id` {{%optional%}} + +**描述：** 作为通知对象的 [Status]({{< relref "entities/Status" >}})的 ID。当通知的 `type` 为 `favourite`、`reblog`、`status`、`mention`、`poll` 或 `update` 时附加。\ +**类型：** 字符串\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `report` {{%optional%}} + +**描述：** 作为通知对象的举报。当通知的 `type` 为 `admin.report` 时附加。\ +**类型：** [Report]({{< relref "entities/Report" >}})\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `event` {{%optional%}} + +**描述：** 导致关注关系被切断的事件的摘要。当通知的 `type` 为 `severed_relationships` 时附加。\ +**类型：** [RelationshipSeveranceEvent]({{< relref "entities/RelationshipSeveranceEvent" >}})\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +#### `moderation_warning` {{%optional%}} + +**描述：** 导致通知的管理警告。当通知的 `type` 为 `moderation_warning` 时附加。\ +**类型：** [AccountWarning]({{< relref "entities/AccountWarning" >}})\ +**版本历史：**\ +4.3.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 2) - 添加 + +### 示例 + +TODO + +--- + +## 另请参阅 + +{{< page-relref ref="methods/notifications" caption="Individual notification API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v2/notifications_controller.rb" caption="app/controllers/api/v2/notifications_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="Grouped notifications API methods" raw_link="/methods/grouped_notifications/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/instance.md b/content/zh-cn/methods/instance.md new file mode 100644 index 0000000..aa406fb --- /dev/null +++ b/content/zh-cn/methods/instance.md @@ -0,0 +1,772 @@ +--- +title: instance API 方法 +description: Mastodon 站点的识别信息。 +menu: + docs: + weight: 70 + name: instance + parent: methods + identifier: methods-instance +aliases: [ + "/methods/instance", + "/api/methods/instance", +] +--- + + + +## 查看实例信息 {#v2} + +```http +GET /api/v2/instance +``` + +获取关于实例的通用信息。 + +**返回：** [Instance]({{< relref "entities/Instance" >}})\ +**OAuth：** 公开\ +**版本历史：**\ +4.0.0 - 添加\ +4.3.0 - 添加 `configuration.vapid.public_key` + +#### 响应 + +##### 200: OK + +```json +{ + "domain": "mastodon.social", + "title": "Mastodon", + "version": "4.0.0rc1", + "source_url": "https://github.com/mastodon/mastodon", + "description": "The original server operated by the Mastodon gGmbH non-profit", + "usage": { + "users": { + "active_month": 123122 + } + }, + "thumbnail": { + "url": "https://files.mastodon.social/site_uploads/files/000/000/001/@1x/57c12f441d083cde.png", + "blurhash": "UeKUpFxuo~R%0nW;WCnhF6RjaJt757oJodS$", + "versions": { + "@1x": "https://files.mastodon.social/site_uploads/files/000/000/001/@1x/57c12f441d083cde.png", + "@2x": "https://files.mastodon.social/site_uploads/files/000/000/001/@2x/57c12f441d083cde.png" + } + }, + "icon": [ + { + "src": "https://files.mastodon.social/site_uploads/files/000/000/003/36/accf17b0104f18e5.png", + "size": "36x36" + }, + { + "src": "https://files.mastodon.social/site_uploads/files/000/000/003/72/accf17b0104f18e5.png", + "size": "72x72" + }, + { + "src": "https://files.mastodon.social/site_uploads/files/000/000/003/192/accf17b0104f18e5.png", + "size": "192x192" + }, + { + "src": "https://files.mastodon.social/site_uploads/files/000/000/003/512/accf17b0104f18e5.png", + "size": "512x512" + } + ], + "languages": [ + "en" + ], + "configuration": { + "urls": { + "streaming": "wss://mastodon.social" + }, + "vapid": { + "public_key": "BCkMmVdKDnKYwzVCDC99Iuc9GvId-x7-kKtuHnLgfF98ENiZp_aj-UNthbCdI70DqN1zUVis-x0Wrot2sBagkMc=" + }, + "accounts": { + "max_featured_tags": 10, + "max_pinned_statuses": 4 + }, + "statuses": { + "max_characters": 500, + "max_media_attachments": 4, + "characters_reserved_per_url": 23 + }, + "media_attachments": { + "supported_mime_types": [ + "image/jpeg", + "image/png", + "image/gif", + "image/heic", + "image/heif", + "image/webp", + "video/webm", + "video/mp4", + "video/quicktime", + "video/ogg", + "audio/wave", + "audio/wav", + "audio/x-wav", + "audio/x-pn-wave", + "audio/vnd.wave", + "audio/ogg", + "audio/vorbis", + "audio/mpeg", + "audio/mp3", + "audio/webm", + "audio/flac", + "audio/aac", + "audio/m4a", + "audio/x-m4a", + "audio/mp4", + "audio/3gpp", + "video/x-ms-asf" + ], + "description_limit": 1500, + "image_size_limit": 10485760, + "image_matrix_limit": 16777216, + "video_size_limit": 41943040, + "video_frame_rate_limit": 60, + "video_matrix_limit": 2304000 + }, + "polls": { + "max_options": 4, + "max_characters_per_option": 50, + "min_expiration": 300, + "max_expiration": 2629746 + }, + "translation": { + "enabled": true + } + }, + "registrations": { + "enabled": false, + "approval_required": false, + "message": null + }, + "contact": { + "email": "staff@mastodon.social", + "account": { + "id": "1", + "username": "Gargron", + "acct": "Gargron", + "display_name": "Eugen 💀", + "locked": false, + "bot": false, + "discoverable": true, + "group": false, + "created_at": "2016-03-16T00:00:00.000Z", + "note": "

Founder, CEO and lead developer @Mastodon, Germany.

", + "url": "https://mastodon.social/@Gargron", + "avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", + "avatar_static": "https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", + "header": "https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", + "header_static": "https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", + "followers_count": 133026, + "following_count": 311, + "statuses_count": 72605, + "last_status_at": "2022-10-31", + "noindex": false, + "emojis": [], + "fields": [ + { + "name": "Patreon", + "value": "https://www.patreon.com/mastodon", + "verified_at": null + } + ] + } + }, + "rules": [ + { + "id": "1", + "text": "Sexually explicit or violent media must be marked as sensitive when posting" + }, + { + "id": "2", + "text": "No racism, sexism, homophobia, transphobia, xenophobia, or casteism" + }, + { + "id": "3", + "text": "No incitement of violence or promotion of violent ideologies" + }, + { + "id": "4", + "text": "No harassment, dogpiling or doxxing of other users" + }, + { + "id": "5", + "text": "No content illegal in Germany" + }, + { + "id": "7", + "text": "Do not share intentionally false or misleading information" + } + ] +} +``` + +--- + +## 连接的域名列表 {#peers} + +```http +GET /api/v1/instance/peers HTTP/1.1 +``` + +此实例已知的域名。 + +**返回：** 字符串数组\ +**OAuth：** 公开\ +**版本历史：**\ +2.1.2 - 添加\ +3.0.0 - 若实例处于白名单模式，则需要用户令牌 + +#### 请求 + +##### 标头 + +Authorization +: 提供带有 `Bearer ` 的标头，以获得对此 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +```json +["tilde.zone","mspsocial.net",...,"conf.tube"] +``` + +##### 401: Unauthorized + +若实例处于白名单模式，并且缺少或无效授权标头，则返回此错误。 + +```json +{ + "error": "This API requires an authenticated user" +} +``` + +--- + +## 每周活动 {#activity} + +```http +GET /api/v1/instance/activity HTTP/1.1 +``` + +过去 3 个月的实例活动，按周统计。 + +**返回：** 哈希数组\ +**OAuth：** 公开\ +**版本历史：**\ +2.1.2 - 添加\ +3.0.0 - 若实例处于白名单模式，则需要用户令牌 + +#### 请求 + +##### 标头 + +Authorization +: 提供带有 `Bearer ` 的标头，以获得对此 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +数组中的每个哈希将包含以下属性： + +week +: 字符串（UNIX 时间戳）。 一周的第一天午夜。 + +statuses +: 字符串（从整数转换）。 自本周开始以来创建的嘟文数。 + +logins +: 字符串（从整数转换）。 自本周开始以来的登录的用户数。 + +registrations +: 字符串（从整数转换）。 自本周开始以来的用户注册数。 + +```json +[ + { + "week": "1574640000", + "statuses": "37125", + "logins": "14239", + "registrations": "542" + }, + { + "week": "1574035200", + "statuses": "244447", + "logins": "28820", + "registrations": "4425" + }, + { + "week": "1573430400", + "statuses": "270615", + "logins": "35388", + "registrations": "8781" + }, + { + "week": "1572825600", + "statuses": "309722", + "logins": "44433", + "registrations": "26165" + }, + { + "week": "1572220800", + "statuses": "116227", + "logins": "19739", + "registrations": "2926" + }, + { + "week": "1571616000", + "statuses": "119932", + "logins": "19247", + "registrations": "3188" + }, + { + "week": "1571011200", + "statuses": "117892", + "logins": "19164", + "registrations": "3107" + }, + { + "week": "1570406400", + "statuses": "109092", + "logins": "18763", + "registrations": "2986" + }, + { + "week": "1569801600", + "statuses": "107554", + "logins": "19614", + "registrations": "2904" + }, + { + "week": "1569196800", + "statuses": "118067", + "logins": "19703", + "registrations": "3295" + }, + { + "week": "1568592000", + "statuses": "110199", + "logins": "19791", + "registrations": "3026" + }, + { + "week": "1567987200", + "statuses": "106029", + "logins": "19089", + "registrations": "2769" + } +] +``` + +##### 401: Unauthorized + +若实例处于白名单模式，并且缺少或无效授权标头，则返回此错误。 + +```json +{ + "error": "This API requires an authenticated user" +} +``` + +--- + +## 规则列表 {#rules} + +```http +GET /api/v1/instance/rules HTTP/1.1 +``` + +此服务的用户应遵守的规则。 + +**返回：** [Rule]({{< relref "entities/rule" >}})数组\ +**OAuth：** 公开\ +**版本历史：**\ +3.4.0 - 添加 + +#### 响应 + +##### 200: OK + +```json +[ + { + "id": "1", + "text": "Sexually explicit or violent media must be marked as sensitive when posting" + }, + { + "id": "2", + "text": "No racism, sexism, homophobia, transphobia, xenophobia, or casteism" + }, + { + "id": "3", + "text": "No incitement of violence or promotion of violent ideologies" + }, + { + "id": "4", + "text": "No harassment, dogpiling or doxxing of other users" + }, + { + "id": "5", + "text": "No content illegal in Germany" + }, + { + "id": "7", + "text": "Do not share intentionally false or misleading information" + } +] +``` + +--- + +## 查看受限的实例 {#domain_blocks} + +```http +GET /api/v1/instance/domain_blocks HTTP/1.1 +``` + +获取已被屏蔽的域名列表。 + +**返回：** [DomainBlock]数组({{< relref "entities/DomainBlock" >}})\ +**OAuth：** 公开，或者若仅限于用户，则为用户令牌\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: 提供带有 `Bearer ` 的标头，以获得对此 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +此实例屏蔽的完整域名列表 + +```json +[ + { + "domain": "birb.elfenban.de", + "digest": "5d2c6e02a0cced8fb05f32626437e3d23096480b47efbba659b6d9e80c85d280", + "severity": "suspend", + "comment": "Third-party bots" + }, + { + "domain": "birdbots.leptonics.com", + "digest": "ce019d8d32cce8e369ac4367f4dc232103e6f489fbdd247fb99f9c8a646078a4", + "severity": "suspend", + "comment": "Third-party bots" + } + // ... +] +``` + +##### 401: Unauthorized + +若管理员选择向用户显示域名阻止列表，则提供无效或缺失的授权标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +管理员选择不向任何人显示域名阻止列表。 响应体为空； 只有 HTTP 404 错误代码相关。 + +```text + +``` + +--- + +## 查看详细描述 {#extended_description} + +```http +GET /api/v1/instance/extended_description HTTP/1.1 +``` + +获取此实例的详细描述 + +**返回：** [ExtendedDescription]({{< relref "entities/ExtendedDescription" >}})\ +**OAuth：** 公开\ +**版本历史：**\ +4.0.0 - 添加 + +#### 响应 + +##### 200: OK + +```json +{ + "updated_at": "2022-11-03T04:09:07Z", + "content": "

For inquiries not related specifically to the operation of this server, such as press inquiries, please contact press@joinmastodon.org.

\n\n

Funding

\n\n

This server is crowdfunded by Patreon donations. For a list of sponsors, see joinmastodon.org.

\n\n

Reporting and moderation

\n\n

When reporting accounts, please make sure to include at least a few posts that show rule-breaking behaviour, when applicable. If there is any additional context that might help make a decision, please also include it in the comment. This is especially important when the content is in a language nobody on the moderation team speaks.

\n\n

We usually handle reports within 24 hours. Please mind that you are not notified when a report you have made has led to a punitive action, and that not all punitive actions are externally visible. For first time offenses, we may opt to delete offending content, escalating to harsher measures on repeat offenses.

\n\n

Impressum

\n\n

Mastodon gGmbH
\nMühlenstraße 8a
\n14167 Berlin
\nGermany

\n\n

E-Mail-Adresse: hello@joinmastodon.org

\n\n

Vertretungsberechtigt: Eugen Rochko (Geschäftsführer)

\n\n

Umsatzsteuer Identifikationsnummer (USt-ID): DE344258260

\n\n

Handelsregister
\nGeführt bei: Amtsgericht Charlottenburg
\nNummer: HRB 230086 B

\n" +} +``` + +--- + +## 查看隐私政策 {#privacy_policy} + +```http +GET /api/v1/instance/privacy_policy HTTP/1.1 +``` + +获取此实例的隐私政策的内容。 + +**返回：** [PrivacyPolicy]({{< relref "entities/PrivacyPolicy" >}})\ +**OAuth：** 公开\ +**版本历史：**\ +4.0.0 - 添加 + +#### 响应 + +##### 200: OK + +```json +{ + "updated_at": "2022-10-07T00:00:00+00:00", + "content": "

This privacy policy describes how example.com ("example.com", "we", "us") collects,\nprotects and uses the personally identifiable information you may provide\nthrough the example.com website or its API.

\n\n

What information do we collect?

\n\n
    \n
  • Basic account information: If you register on this server, you may be\nasked to enter a username, an e-mail address and a password.
    • \n
  • Posts, following and other public information: The list of people you\nfollow is listed publicly, the same is true for your followers.
    • \n
  • Direct and followers-only posts: All posts are stored and processed on the\nserver. You may\ntoggle an option to approve and reject new followers manually in the settings.\nPlease keep in mind that the operators of the server and any receiving\nserver may view such messages, and that recipients may screenshot, copy or\notherwise re-share them. Do not share any sensitive information over\nMastodon.
    • \n
  • IPs and other metadata: When you log in, we record the IP address you log\nin from, as well as the name of your browser application.
    • \n
\n\n
\n\n

This document is CC-BY-SA. Originally adapted from the Discourse privacy\npolicy.

\n" +} +``` + +--- + +## 查看服务条款 {#terms_of_service} + +```http +GET /api/v1/instance/terms_of_service HTTP/1.1 +``` + +获取此实例的服务条款的内容（若已配置）。 + +**返回：** [PrivacyPolicy]({{< relref "entities/PrivacyPolicy" >}})\ +**OAuth：** 公开\ +**版本历史：**\ +4.4.0 - 添加 + +#### 响应 + +##### 200: OK + + + +##### 404: Not found + +未为此实例配置服务条款。 + +```json +{ + "error": "未找到记录" +} +``` + +--- + +## 查看翻译语言 {#translation_languages} + +```http +GET /api/v1/instance/translation_languages HTTP/1.1 +``` + +实例使用的翻译引擎支持的翻译语言对。 + +**返回：** 对象，源语言代码作为键，目标语言代码数组作为值。\ +**OAuth：** 公开\ +**版本历史：**\ +4.2.0 - 添加 + +#### 响应 + +##### 200: OK + +实例支持的所有源语言和目标语言对。 + +在以下示例响应中，显示支持将用英语（`en`）编写的嘟文翻译成德语（`de`）或西班牙语（`es`）。 源语言代码 `und` 表示实例支持自动检测具有空 `language` 属性的嘟文的语言，并将这些嘟文翻译成英式英语（`en-GB`）、德语或西班牙语。 + +```json +{ + "en": ["de", "es"], + // [...] + "und": ["en-GB", "de", "es"] +} +``` + +--- + +## 查看实例信息（v1）{{%deprecated%}} {#v1} + +```http +GET /api/v1/instance HTTP/1.1 +``` + +获取关于实例的通用信息。 请改用 [api/v2/instance]({{< relref "methods/Instance#v2">}})。 + +**返回：** [V1::Instance]({{< relref "entities/V1_Instance" >}})\ +**OAuth：** 公开\ +**版本历史：**\ +1.1.0 - 添加\ +3.0.0 - 若实例处于白名单模式，则需要用户令牌\ +3.1.4 - 将 `invites_enabled` 添加到响应\ +3.4.0 - 添加 `rules`\ +3.4.2 - 添加 `configuration`\ +4.0.0 - 弃用。 添加 `configuration[accounts]`。 + +#### 响应 + +##### 200: OK + +```json +{ + "uri": "mastodon.social", + "title": "Mastodon", + "short_description": "The original server operated by the Mastodon gGmbH non-profit", + "description": "", + "email": "staff@mastodon.social", + "version": "3.5.3", + "urls": { + "streaming_api": "wss://mastodon.social" + }, + "stats": { + "user_count": 812303, + "status_count": 38151616, + "domain_count": 25255 + }, + "thumbnail": "https://files.mastodon.social/site_uploads/files/000/000/001/original/vlcsnap-2018-08-27-16h43m11s127.png", + "languages": ["en"], + "registrations": false, + "approval_required": false, + "invites_enabled": true, + "configuration": { + "statuses": { + "max_characters": 500, + "max_media_attachments": 4, + "characters_reserved_per_url": 23 + }, + "media_attachments": { + "supported_mime_types": [ + "image/jpeg", + "image/png", + "image/gif", + "image/webp", + "video/webm", + "video/mp4", + "video/quicktime", + "video/ogg", + "audio/wave", + "audio/wav", + "audio/x-wav", + "audio/x-pn-wave", + "audio/vnd.wave", + "audio/ogg", + "audio/vorbis", + "audio/mpeg", + "audio/mp3", + "audio/webm", + "audio/flac", + "audio/aac", + "audio/m4a", + "audio/x-m4a", + "audio/mp4", + "audio/3gpp", + "video/x-ms-asf" + ], + "image_size_limit": 10485760, + "image_matrix_limit": 16777216, + "video_size_limit": 41943040, + "video_frame_rate_limit": 60, + "video_matrix_limit": 2304000 + }, + "polls": { + "max_options": 4, + "max_characters_per_option": 50, + "min_expiration": 300, + "max_expiration": 2629746 + } + }, + "contact_account":{ + "id":"1", + "username":"Gargron", + "acct":"Gargron", + "display_name":"Eugen", + "locked":false, + "bot":false, + "discoverable":true, + "group":false, + "created_at":"2016-03-16T00:00:00.000Z", + "note":"\u003cp\u003eFounder, CEO and lead developer \u003cspan class=\"h-card\"\u003e\u003ca href=\"https://mastodon.social/@Mastodon\" class=\"u-url mention\"\u003e@\u003cspan\u003eMastodon\u003c/span\u003e\u003c/a\u003e\u003c/span\u003e, Germany.\u003c/p\u003e", + "url":"https://mastodon.social/@Gargron", + "avatar":"https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", + "avatar_static":"https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", + "header":"https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", + "header_static":"https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", + "followers_count":118944, + "following_count":305, + "statuses_count":72309, + "last_status_at":"2022-08-24", + "emojis":[ + + ], + "fields":[ + { + "name": "Patreon", + "value": "\u003ca href=\"https://www.patreon.com/mastodon\" target=\"_blank\" rel=\"nofollow noopener noreferrer me\"\u003e\u003cspan class=\"invisible\"\u003ehttps://www.\u003c/span\u003e\u003cspan class=\"\"\u003epatreon.com/mastodon\u003c/span\u003e\u003cspan class=\"invisible\"\u003e\u003c/span\u003e\u003c/a\u003e", + "verified_at": null + } + ] + }, + "rules": [ + { + "id": "1", + "text": "Sexually explicit or violent media must be marked as sensitive when posting" + }, + { + "id": "2", + "text": "No racism, sexism, homophobia, transphobia, xenophobia, or casteism" + }, + { + "id": "3", + "text": "No incitement of violence or promotion of violent ideologies" + }, + { + "id": "4", + "text": "No harassment, dogpiling or doxxing of other users" + }, + { + "id": "5", + "text": "No content illegal in Germany" + }, + { + "id": "7", + "text": "Do not share intentionally false or misleading information" + } + ] +} +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/instances_controller.rb" caption="app/controllers/api/v1/instances_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/instances/activity_controller.rb" caption="app/controllers/api/v1/instances/activity_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/instances/peers_controller.rb" caption="app/controllers/api/v1/instances/peers_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/instances/rules_controller.rb" caption="app/controllers/api/v1/instances/rules_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/instances/privacy_policies_controller.rb" caption="app/controllers/api/v1/instances/privacy_policies_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/instances/terms_of_services_controller.rb" caption="app/controllers/api/v1/instances/terms_of_services_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="instance API methods" raw_link="/methods/instance/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/lists.md b/content/zh-cn/methods/lists.md new file mode 100644 index 0000000..6d2d651 --- /dev/null +++ b/content/zh-cn/methods/lists.md @@ -0,0 +1,593 @@ +--- +title: lists API 方法 +description: >- + 查看和管理列表。另请参阅：/api/v1/timelines/list/id 以加载列表时间线。 +menu: + docs: + weight: 20 + name: lists + parent: methods-timelines + identifier: methods-lists +aliases: [ + "/methods/lists", + "/api/methods/lists", + "/methods/timelines/lists", +] +--- + + + +## 查看你的列表 {#get} + +```http +GET /api/v1/lists HTTP/1.1 +``` + +获取用户拥有的所有列表。 + +**返回：**[List]({{< relref "entities/list" >}})数组\ +**OAuth：**用户令牌 + `read:lists`\ +**版本历史记录：**\ +2.1.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头以及 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +使用 `id` 作为相关 API 调用的参数。 + +```json +[ + { + "id": "12249", + "title": "Friends", + "replies_policy": "followed", + "exclusive": false + }, + { + "id": "13585", + "title": "test", + "replies_policy": "list", + "exclusive": true + } +] +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 显示单个列表 {#get-one} + +```http +GET /api/v1/lists/:id HTTP/1.1 +``` + +获取具有给定 ID 的列表。用于验证列表的标题，以及在该列表中显示哪些回复。 + +**返回：**[List]({{< relref "entities/list" >}})\ +**OAuth：**用户令牌 + `read:lists`\ +**版本历史记录：**\ +2.1.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中列表的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头以及 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +列表 12249 存在并且由你拥有 + +```json +{ + "id": "12249", + "title": "Friends", + "replies_policy": "followed", + "exclusive": false +} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +列表不存在或你并未拥有此列表 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 创建列表 {#create} + +```http +POST /api/v1/lists HTTP/1.1 +``` + +创建一个新列表。 + +**返回：**[List]({{< relref "entities/list" >}})\ +**OAuth：**用户令牌 + `write:lists`\ +**版本历史记录：**\ +2.1.0 - 添加\ +3.3.0 - 添加 `replies_policy`\ +4.2.0 - 添加 `exclusive` + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供此标头以及 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +title +: {{}} 字符串。要创建的列表的标题。 + +replies_policy +: 字符串。`followed`、`list` 或 `none` 之一。默认为 `list`。 + +exclusive +: 布尔值。此列表的成员的嘟文是否需要从首页时间线中删除 + +#### 响应 +##### 200: OK + +使用标题 “test” 创建了一个示例列表。 + +```json +{ + "id": "13585", + "title": "test", + "replies_policy": "list", + "exclusive": false +} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +若缺少标题： + +```json +{ + "error": "Validation failed: Title can't be blank" +} +``` + +若 replies_policy 非法： + +```json +{ + "error": "'some' is not a valid replies_policy" +} +``` +--> + +--- + +## 更新列表 {#update} + +```http +PUT /api/v1/lists/:id HTTP/1.1 +``` + +更改列表的标题，或更改回复显示范围。 + +**返回：**[List]({{< relref "entities/list" >}})\ +**OAuth：**用户令牌 + `write:lists`\ +**版本历史记录：**\ +2.1.0 - 添加\ +3.3.0 - 添加 `replies_policy` + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中列表的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头以及 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +title +: {{}} 字符串。要创建的列表的标题。 + +replies_policy +: 字符串。`followed`、`list` 或 `none` 之一。默认为 `list`。 + +exclusive +: 布尔值。此列表的成员的嘟文是否需要从首页时间线中移除。 + +#### 响应 +##### 200: OK + +列表 13585 的 `title` 已成功更新为“testing” + +```json +{ + "id": "13585", + "title": "test", + "replies_policy": "list", + "exclusive": false +} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +若缺少 `title`： + +```json +{ + "error": "Validation failed: Title can't be blank" +} +``` + +若 `replies_policy` 非法： + +```json +{ + "error": "'some' is not a valid replies_policy" +} +``` + +--- + +## 删除列表 {#delete} + +```http +DELETE /api/v1/lists/:id HTTP/1.1 +``` + +**返回：**空\ +**OAuth：**用户令牌 + `write:lists`\ +**版本历史记录：**\ +2.1.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中列表的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头以及 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +列表已成功删除 + +```json +{} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +列表不存在或你并未拥有此列表 + + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 查看列表中的帐户 {#accounts} + +```http +GET /api/v1/lists/:id/accounts HTTP/1.1 +``` + +**返回：**[帐户]({{< relref "entities/account" >}})数组\ +**OAuth：**用户令牌 + `read:lists`\ +**版本历史记录：**\ +2.1.0 - 添加\ +3.3.0 - 现在可以同时使用 `min_id` 和 `max_id` + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中列表的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头以及 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +since_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +min_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +limit +: 整数。结果的最大数量。默认为 40 个帐户。最多 80 个帐户。设置为 0 以获取所有帐户而不进行分页。 + +#### 响应 +##### 200: OK + +```json +[ + { + "id": "952529", + "username": "alayna", + "acct": "alayna@desvox.es", + // ... + }, + { + "id": "917388", + "username": "cole", + "acct": "cole@be.cutewith.me", + // ... + }, + { + "id": "869022", + "username": "alayna", + "acct": "alayna@be.cutewith.me", + // ... + }, + { + "id": "832844", + "username": "a9", + "acct": "a9@broadcast.wolfgirl.engineering", + // ... + }, + { + "id": "482403", + "username": "amic", + "acct": "amic@nulled.red", + // ... + } +] +``` + +因为你事先不知道列表中包含哪些帐户，你必须解析 HTTP `Link` 标头才能加载旧的或较新的结果。有关更多信息，请参见 [通过 API 响应进行分页]({{}})。 + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +列表不存在或你并未拥有此列表。 + + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 将帐户添加到列表 {#accounts-add} + +```http +POST /api/v1/lists/:id/accounts HTTP/1.1 +``` + +将帐户添加到给定列表。请注意，用户必须已关注这些帐户。 + +**返回：**空\ +**OAuth：**用户令牌 + `write:lists`\ +**版本历史记录：**\ +2.1.0 - 添加 + +### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中列表的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头以及 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +account_ids[] +: {{}} 字符串数组。应添加到列表中的帐户。 + +#### 响应 +##### 200: OK + +```json +{} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +你没有关注给定 ID 的账户，或者你并未拥有给定 ID 的列表，或者对应列表/帐户 ID 不存在 + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +具有提供的 ID 之一的帐户已在列表中 + +```json +{ + "error": "Validation failed: Account has already been taken" +} +``` + +--- + +## 从列表删除帐户 {#accounts-remove} + +```http +DELETE /api/v1/lists/:id/accounts HTTP/1.1 +``` + +从给定列表中删除帐户。 + +**返回：**空\ +**OAuth：**用户令牌 + `write:lists`\ +**版本历史记录：**\ +2.1.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中列表的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头以及 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +account_ids[] +: {{}} 字符串数组。应从列表中删除的帐户。 + +#### 响应 +##### 200: OK + +已成功从列表中删除帐户，或者该帐户已经不在列表中。 + +```json +{} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +你并未拥有此列表或列表不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 另请参阅 + +{{< page-relref ref="methods/accounts#lists" caption="GET /api/v1/accounts/:id/lists" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/lists_controller.rb" caption="app/controllers/api/v1/lists_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/lists/accounts_controller.rb" caption="app/controllers/api/v1/lists/accounts_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="lists API methods" raw_link="/methods/lists/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/markers.md b/content/zh-cn/methods/markers.md new file mode 100644 index 0000000..3876ebd --- /dev/null +++ b/content/zh-cn/methods/markers.md @@ -0,0 +1,151 @@ +--- +title: markers API 方法 +description: 保存和恢复你在时间线中的位置。 +menu: + docs: + weight: 30 + name: markers + parent: methods-timelines + identifier: methods-markers +aliases: [ + "/methods/markers", + "/api/methods/markers", + "/methods/timelines/markers", +] +--- + + + +## 获取已保存的时间线位置 {#get} + +```http +GET /api/v1/markers HTTP/1.1 +``` + +获取当前在时间线中的位置。 + +**返回：** 时间线键和其关联的 [Marker]({{< relref "entities/Marker" >}}) 的哈希值\ +**OAuth:** 用户令牌 + `read:statuses`\ +**版本历史：**\ +3.0.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，内容为 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +timeline[] +: 字符串数组。指定应获取 marker 的时间线。可能的值：`home`、`notifications`。若未提供，将返回一个空对象。 + +#### 响应 +##### 200: OK + +一个带有 `?timeline[]=home&timeline[]=notifications` 的请求 + +```json +{ + "notifications": { + "last_read_id": "35098814", + "version": 361, + "updated_at": "2019-11-26T22:37:25.239Z" + }, + "home": { + "last_read_id": "103206604258487607", + "version": 468, + "updated_at": "2019-11-26T22:37:25.235Z" + } +} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 保存你在时间线中的位置 {#create} + +```http +POST /api/v1/markers HTTP/1.1 +``` + +保存当前在时间线中的位置。 + +**返回：** [Marker]({{< relref "entities/marker" >}})\ +**OAuth:** 用户令牌 + `write:statuses`\ +**版本历史：**\ +3.0.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，内容为 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +home[last_read_id] +: 字符串。在首页时间线中读取的最后一条嘟文的 ID。 + +notifications[last_read_id] +: 字符串。读取的最后一条通知的 ID。 + +#### 响应 +##### 200: OK + +使用 `home[last_read_id]` 调用此 API 将导致为首页时间线创建一个 marker。 + +```json +{ + "home": { + "last_read_id": "103194548672408537", + "version": 462, + "updated_at": "2019-11-24T19:39:39.337Z" + } +} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +### 409: Conflict + +若在更新时对象已过时，则会发生错误。 + +```json +{ + "error": "Conflict during update, please try again" +} +``` + +--- + +## 另请参阅 + +{{< page-relref ref="methods/timelines#home" caption="GET /api/v1/timelines/home (带有 `min_id` 或 `since_id` 参数)" >}} + +{{< page-relref ref="methods/notifications#get" caption="GET /api/v1/notifications (带有 `min_id` 或 `since_id` 参数)" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/markers_controller.rb" caption="app/controllers/api/v1/markers_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="markers API methods" raw_link="/methods/markers/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/media.md b/content/zh-cn/methods/media.md new file mode 100644 index 0000000..10972c8 --- /dev/null +++ b/content/zh-cn/methods/media.md @@ -0,0 +1,522 @@ +--- +title: media API 方法 +description: >- + 将媒体附加到嘟文。有关大小和格式限制的更多信息，请参考“使用 Mastodon > 发布嘟文 > 附件”。 +menu: + docs: + weight: 10 + name: media + parent: methods-statuses + identifier: methods-media +aliases: [ + "/methods/media", + "/api/methods/media", + "/methods/statuses/media", +] +--- + + + +## 上传媒体为附件 (异步) {#v2} + +```http +POST /api/v2/media HTTP/1.1 +``` + +创建一个媒体附件，用于新发布嘟文。对于大型上传，完整大小的媒体附件将在后台异步处理。 + +**返回：** [MediaAttachment]({{< relref "entities/MediaAttachment" >}})，但没有 URL\ +**OAuth：** 用户令牌 + `write:media`\ +**版本历史：**\ +3.1.3 - 添加\ +3.2.0 - 添加 `thumbnail` 参数\ +4.0.0 - 较小的媒体格式（图像）将同步处理并返回 200 而不是 202。较大的媒体格式（视频、gifv、音频）将继续异步处理并返回 202。 + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +file +: {{}} 对象。要附加的文件，使用 multipart form data 编码。该文件必须携带 MIME 类型。 + +thumbnail +: 对象。要附加的媒体的自定义缩略图，使用 multipart form data 编码。 + +description +: 字符串。媒体的纯文本描述，用于辅助功能。 + +focus +: 字符串。两个浮点数 (x,y)，以逗号分隔，段从 -1.0 到 1.0。有关更多信息，请参见[用于裁剪媒体缩略图的焦点]({{< relref "api/guidelines#focal-points" >}})。 + +#### 响应 + +##### 200: OK + +MediaAttachment 创建成功，并且完整大小的文件已同步处理。 + +```json +{ + "id": "22348641", + "type": "image", + "url": "https://files.mastodon.social/media_attachments/files/022/348/641/original/e96382f26c72a29c.jpeg", + "preview_url": "https://files.mastodon.social/media_attachments/files/022/348/641/small/e96382f26c72a29c.jpeg", + "remote_url": null, + "text_url": "https://mastodon.social/media/4Zj6ewxzzzDi0g8JnZQ", + "meta": { + "focus": { + "x": -0.42, + "y": 0.69 + }, + "original": { + "width": 640, + "height": 480, + "size": "640x480", + "aspect": 1.3333333333333333 + }, + "small": { + "width": 461, + "height": 346, + "size": "461x346", + "aspect": 1.3323699421965318 + } + }, + "description": "test uploaded via api", + "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}" +} +``` + +##### 202: Accepted + +MediaAttachment 创建成功，但完整大小的文件仍在处理中。请注意，MediaAttachment 的 `url` 仍然为 null，因为媒体仍在后台处理中。但是，`preview_url` 应该可用。使用 [`GET /api/v1/media/:id`](#get) 检查媒体附件的嘟文。 + +```json +{ + "id": "22348641", + "type": "image", + "url": null, + "preview_url": "https://files.mastodon.social/media_attachments/files/022/348/641/small/cebc6d51be03e509.jpeg", + "remote_url": null, + "text_url": "https://mastodon.social/media/4Zj6ewxzzzDi0g8JnZQ", + "meta": { + "focus": { + "x": -0.69, + "y": 0.42 + }, + "original": { + "width": 640, + "height": 480, + "size": "640x480", + "aspect": 1.3333333333333333 + }, + "small": { + "width": 461, + "height": 346, + "size": "461x346", + "aspect": 1.3323699421965318 + } + }, + "description": "test uploaded via api", + "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}" +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +不支持的文件或文件类型无效。 + +```json +{ + "error": "Validation failed: File content type is invalid, File is invalid" +} +``` + +##### 500: Server error + +无法为附件生成缩略图 + +```json +{ + "error": "Error processing thumbnail for uploaded media" +} +``` + +--- + +## 获取媒体附件 {#get} + +```http +GET /api/v1/media/:id HTTP/1.1 +``` + +在媒体附件被接受和处理，但尚未被附加到嘟文中时获取媒体附件。使用此方法检查完整大小的媒体是否已完成处理。 + +**返回：** [MediaAttachment]({{< relref "entities/MediaAttachment" >}})\ +**OAuth：** 用户令牌 + `write:media`\ +**版本历史：**\ +3.1.3 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 MediaAttachment 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +媒体文件已处理，并且已处理媒体的 `url` 可用。 + +```json +{ + "id": "22348641", + "type": "image", + "url": "https://files.mastodon.social/media_attachments/files/022/348/641/original/e96382f26c72a29c.jpeg", + "preview_url": "https://files.mastodon.social/media_attachments/files/022/348/641/small/e96382f26c72a29c.jpeg", + "remote_url": null, + "text_url": "https://mastodon.social/media/4Zj6ewxzzzDi0g8JnZQ", + "meta": { + "focus": { + "x": -0.42, + "y": 0.69 + }, + "original": { + "width": 640, + "height": 480, + "size": "640x480", + "aspect": 1.3333333333333333 + }, + "small": { + "width": 461, + "height": 346, + "size": "461x346", + "aspect": 1.3323699421965318 + } + }, + "description": "test uploaded via api, but updated", + "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}" +} +``` + +##### 206: Partial content + +媒体附件仍在处理中 + +```json + +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +该 MediaAttachment 不属于你或不存在 + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +处理媒体附件时出错 + + +```json +{ + "error": "Validation failed: File content type is invalid, File is invalid" +} +``` + +--- + +## 删除媒体附件 {#delete} + +```http +DELETE /api/v1/media/:id +``` + +删除当前未附加到嘟文的媒体附件。 + +**返回：** 空\ +**OAuth：** 用户令牌 + `write:media`\ +**版本历史：**\ +- 4.4.0 (`mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 4) - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 MediaAttachment 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +## 更新媒体附件 {#update} + +```http +PUT /api/v1/media/:id HTTP/1.1 +``` + +更新 MediaAttachment 附加到嘟文并发布之前更新其参数。 + +**返回：** [MediaAttachment]({{< relref "entities/MediaAttachment" >}})\ +**OAuth：** 用户令牌 + `write:media`\ +**版本历史：**\ +0.0.0 - 添加\ +2.3.0 - 添加 `focus` 参数\ +3.2.0 - 添加 `thumbnail` + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 MediaAttachment 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +thumbnail +: 对象。要附加的媒体的自定义缩略图，使用 multipart form data 编码。 + +description +: 字符串。媒体的纯文本描述，用于辅助功能。 + +focus +: 字符串。两个浮点数 (x,y)，逗号分隔，段从 -1.0 到 1.0。有关更多信息，请参见[用于裁剪媒体缩略图的焦点]({{< relref "api/guidelines#focal-points" >}})。 + +#### 响应 + +##### 200: OK + +带有已更新 `description` 的附件 + +```json +{ + "id": "22348641", + "type": "image", + "url": "https://files.mastodon.social/media_attachments/files/022/348/641/original/e96382f26c72a29c.jpeg", + "preview_url": "https://files.mastodon.social/media_attachments/files/022/348/641/small/e96382f26c72a29c.jpeg", + "remote_url": null, + "text_url": "https://mastodon.social/media/4Zj6ewxzzzDi0g8JnZQ", + "meta": { + "focus": { + "x": -0.42, + "y": 0.69 + }, + "original": { + "width": 640, + "height": 480, + "size": "640x480", + "aspect": 1.3333333333333333 + }, + "small": { + "width": 461, + "height": 346, + "size": "461x346", + "aspect": 1.3323699421965318 + } + }, + "description": "test uploaded via api, but updated", + "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}" +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +该媒体附件不属于你或不存在 + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +```json +{ + "error": "Validation failed: File content type is invalid, File is invalid" +} +``` + +--- + +## 上传媒体附件 (v1) {{%deprecated%}} {#v1} + +```http +POST /api/v1/media HTTP/1.1 +``` + +创建一个用于新嘟文的媒体附件。此方法将在完整大小的媒体完成处理后返回。 + +**返回：** [MediaAttachment]({{< relref "entities/MediaAttachment" >}})\ +**OAuth：** 用户令牌 + `write:media`\ +**版本历史：**\ +0.0.0 - 添加\ +2.3.0 - 添加 `focus` 参数\ +3.1.3 - 弃用，推荐使用 [POST /api/v2/media](#v2)，该方法在所有方面都与 v1 相同，只是在正常情况下返回 HTTP 202，并且返回的 JSON 对象具有一个 null 的 url。这是因为虽然缩略图是同步准备的，但媒体附件的完整版本将在后台处理。\ +3.2.0 - 添加 `thumbnail` 参数 + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +file +: {{}} 对象。要附加的文件，使用 multipart form data 编码。该文件必须具有 MIME 类型。 + +thumbnail +: 对象。要附加的媒体的自定义缩略图，使用 multipart form data 编码。 + +description +: 字符串。媒体的纯文本描述，用于辅助功能。 + +focus +: 字符串。两个浮点数 (x,y)，逗号分隔，段从 -1.0 到 1.0。有关更多信息，请参见[用于裁剪媒体缩略图的焦点]({{< relref "api/guidelines#focal-points" >}})。 + +#### 响应 +##### 200: OK + +附件创建成功。请注意，即使由于处理失败而无法正确理解文件，也会创建 MediaAttachment。 + +正确文件的示例响应： + +```json +{ + "id": "22348641", + "type": "image", + "url": "https://files.mastodon.social/media_attachments/files/022/348/641/original/cebc6d51be03e509.jpeg", + "preview_url": "https://files.mastodon.social/media_attachments/files/022/348/641/small/cebc6d51be03e509.jpeg", + "remote_url": null, + "text_url": "https://mastodon.social/media/4Zj6ewxzzzDi0g8JnZQ", + "meta": { + "focus": { + "x": -0.69, + "y": 0.42 + }, + "original": { + "width": 640, + "height": 480, + "size": "640x480", + "aspect": 1.3333333333333333 + }, + "small": { + "width": 461, + "height": 346, + "size": "461x346", + "aspect": 1.3323699421965318 + } + }, + "description": "test uploaded via api", + "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}" +} +``` + +不正确文件的示例响应，这会导致“missing” url： + +```json +{ + "id": "22348456", + "type": "unknown", + "url": "https://mastodon.social/files/original/missing.png", + "preview_url": "https://mastodon.social/files/small/missing.png", + "remote_url": null, + "text_url": "https://mastodon.social/media/Ao2nvQoQNHROpKgEyoA", + "meta": { + "focus": { + "x": -0.69, + "y": 0.42 + } + }, + "description": "test uploaded via api", + "blurhash": null +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +不支持的文件或文件类型无效。 + +```json +{ + "error": "Validation failed: File content type is invalid, File is invalid" +} +``` + +--- + +## 另请参考 + +{{< page-relref ref="methods/instance" caption="GET /api/v2/instance（用于获取配置限制）">}} + +{{< page-relref ref="entities/instance#media_attachments" caption="Instance#configuration[media_attachments]">}} + +{{< page-relref ref="api/guidelines#focal-points" caption="裁剪媒体缩略图的焦点" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/media_controller.rb" caption="app/controllers/api/v1/media_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v2/media_controller.rb" caption="app/controllers/api/v2/media_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="media API methods" raw_link="/methods/media/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/mutes.md b/content/zh-cn/methods/mutes.md new file mode 100644 index 0000000..688c990 --- /dev/null +++ b/content/zh-cn/methods/mutes.md @@ -0,0 +1,102 @@ +--- +title: mutes API 方法 +description: 查看你的隐藏列表。另请参阅 accounts/:id/{mute,unmute} +menu: + docs: + weight: 30 + name: mutes + parent: methods-accounts + identifier: methods-mutes +aliases: [ + "/methods/mutes", + "/api/methods/mutes", + "/methods/accounts/mutes", +] +--- + + + +## 查看已隐藏账户 {#get} + +```http +GET /api/v1/mutes HTTP/1.1 +``` + +用户已隐藏的账户。 + +**返回：** [Account]({{}}) 数组\ +**OAuth：** 用户令牌 + `read:mutes` 或 `follow`\ +**版本历史：**\ +0.0.0 - 添加\ +3.3.0 - 添加 `mute_expires_at` + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供此标头，内容为 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: **内部参数。** 使用 HTTP `Link`标头进行分页。 + +since_id +: **内部参数。** 使用 HTTP `Link`标头进行分页。 + +limit +: Integer 类型。要返回的最大结果数。 默认为 40 个账户。 最大值为 80 个账户。 + +#### 响应 +##### 200: OK + +limit=2 的示例响应。 + +```json +[ + { + "id": "963076", + "username": "Simia91", + "acct": "Simia91", + "display_name": "", + // ... + }, + { + "id": "1001524", + "username": "hakogamae", + "acct": "hakogamae", + "display_name": "Hakogamae 🔞", + // ... + } +] +``` + +由于隐藏 ID 通常不会通过任何 API 响应公开，因此你必须解析 HTTP `Link` 标头才能加载较旧或较新的结果。 有关更多信息，请参阅 [通过 API 响应进行分页]({{}})。 + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +无效或缺少的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 另请参阅 + +{{< page-relref ref="methods/accounts#mute" caption="POST /api/v1/accounts/:id/mute" >}} + +{{< page-relref ref="methods/accounts#unmute" caption="POST /api/v1/accounts/:id/unmute" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/mutes_controller.rb" caption="app/controllers/api/v1/mutes_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="mutes API methods" raw_link="/methods/mutes/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/notifications.md b/content/zh-cn/methods/notifications.md new file mode 100644 index 0000000..84713f4 --- /dev/null +++ b/content/zh-cn/methods/notifications.md @@ -0,0 +1,997 @@ +--- +title: notifications API 方法 +description: 接收关于你的帐户或嘟文的活动的通知。 +menu: + docs: + weight: 50 + name: notifications + parent: methods + identifier: methods-notifications +aliases: [ + "/methods/notifications", + "/api/methods/notifications", +] +--- + + + +## 获取所有通知 {#get} + +```http +GET /api/v1/notifications HTTP/1.1 +``` + +关于用户的通知。此 API 返回包含指向下一页/上一页的链接的 Link 标头。但是，也可以使用查询参数和 `id` 值嘟文构造链接。 + +要过滤的类型包括： +- `mention` = 有人在他们的嘟文中提到了你 +- `status` = 你启用了发嘟通知的账户发布了一条嘟文 +- `reblog` = 有人转发了你的一条嘟文 +- `follow` = 有人关注了你 +- `follow_request` = 有人请求关注你 +- `favourite` = 有人喜欢了你的一条嘟文 +- `poll` = 你已投票或创建的投票已结束 +- `update` = 你转发的嘟文已被编辑 +- `admin.sign_up` = 有人注册了 (可以根据具体配置发送给管理员) +- `admin.report` = 已提交新的举报 + +**返回：** [Notification]({{< relref "entities/Notification" >}}) 数组\ +**OAuth：** 用户令牌 + `read:notifications`\ +**版本历史：**\ +0.0.0 - 添加\ +2.6.0 - 添加 `min_id`\ +2.9.0 - 添加 `account_id`\ +3.1.0 - 添加 `follow_request` 类型\ +3.3.0 - 添加 `status` 类型；现在可以同时使用 `min_id` 和 `max_id`\ +3.5.0 - 添加 `types`；添加 `update` 和 `admin.sign_up` 类型\ +4.0.0 - 添加 `admin.report` 类型\ +4.1.0 - 通知限制从15 （最大30）更改为40 （最大80）\ +4.3.0 - 添加 `include_filtered` 参数 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 来获得对本 API 方法的访问授权。 + +##### 查询参数 + +max_id +: 字符串。返回的所有结果将小于此 ID。事实上设置了结果的上限。 + +since_id +: 字符串。返回的所有结果将大于此 ID。事实上设置了结果的下限。 + +min_id +: 字符串。返回与此 ID 相邻且更新的结果。事实上在此 ID 处设置一个游标并向前分页。 + +limit +: 整数。要返回的最大结果数。默认为 40 个通知。最多 80 个通知。 + +types[] +: 字符串数组。要包含在结果中的类型。 + +exclude_types[] +: 字符串数组。要从结果中排除的类型。 + +account_id +: 字符串。仅返回从指定帐户收到的通知。 + +include_filtered +: 布尔值。是否包括被用户的 [NotificationPolicy]({{< relref "entities/NotificationPolicy" >}}) 筛选的通知。默认为 false。 + +#### 响应 + +使用 limit=2 的示例调用。 + +```http +GET https://mastodon.social/api/v1/notifications?limit=2 HTTP/1.1 +Authorization: Bearer +``` + +##### 200: OK + +响应体包含一页通知。你可以使用 HTTP Link 标头进行进一步分页。 + +```http +Link: ; rel="next", ; +``` + +```json +[ + { + "id": "34975861", + "type": "mention", + "created_at": "2019-11-23T07:49:02.064Z", + "account": { + "id": "971724", + "username": "zsc", + "acct": "zsc", + // ... + }, + "status": { + "id": "103186126728896492", + "created_at": "2019-11-23T07:49:01.940Z", + "in_reply_to_id": "103186038209478945", + "in_reply_to_account_id": "14715", + // ... + "content": "

@trwnh sup!

", + // ... + "account": { + "id": "971724", + "username": "zsc", + "acct": "zsc", + // ... + }, + // ... + "mentions": [ + { + "id": "14715", + "username": "trwnh", + "url": "https://mastodon.social/@trwnh", + "acct": "trwnh" + } + ], + // ... + } + }, + { + "id": "34975535", + "type": "favourite", + "created_at": "2019-11-23T07:29:18.903Z", + "account": { + "id": "297420", + "username": "haskal", + "acct": "haskal@cybre.space", + // ... + }, + "status": { + "id": "103186046267791694", + "created_at": "2019-11-23T07:28:34.210Z", + "in_reply_to_id": "103186044372624124", + "in_reply_to_account_id": "297420", + // ... + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + // ... + } + } + } +] +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 获取单个通知 {#get-one} + +```http +GET /api/v1/notifications/:id HTTP/1.1 +``` + +查看有关具有给定 ID 的通知的信息。 + +**返回：** [Notification]({{< relref "entities/Notification" >}})\ +**OAuth：** 用户令牌 + `read:notifications`\ +**版本历史：**\ +0.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中通知的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 来获得对本 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +单个通知 + +```json +{ + "id": "34975861", + "type": "mention", + "created_at": "2019-11-23T07:49:02.064Z", + "account": { + "id": "971724", + "username": "zsc", + "acct": "zsc", + // ... + }, + "status": { + "id": "103186126728896492", + "created_at": "2019-11-23T07:49:01.940Z", + "in_reply_to_id": "103186038209478945", + "in_reply_to_account_id": "14715", + // ... + "content": "

@trwnh sup!

", + // ... + "account": { + "id": "971724", + "username": "zsc", + "acct": "zsc", + // ... + }, + // ... + "mentions": [ + { + "id": "14715", + "username": "trwnh", + "url": "https://mastodon.social/@trwnh", + "acct": "trwnh" + } + ], + // ... + } +} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 忽略所有通知 {#clear} + +```http +POST /api/v1/notifications/clear HTTP/1.1 +``` + +从实例清除所有通知。 + +**返回：** 空\ +**OAuth：** 用户令牌 + `write:notifications`\ +**版本历史：**\ +0.0.0 - 添加 + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 来获得对本 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +通知已成功清除。 + +```json +{} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 忽略单个通知 {#dismiss} + +```http +POST /api/v1/notifications/:id/dismiss HTTP/1.1 +``` + +从实例忽略单个通知。 + +**返回：** 空\ +**OAuth：** 用户令牌 + `write:notifications`\ +**版本历史：**\ +1.3.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中通知的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 来获得对本 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +成功忽略具有给定 ID 的通知 + +```json +{} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 忽略单个通知 {{%removed%}} {#dismiss-deprecated} + +```http +POST /api/v1/notifications/dismiss HTTP/1.1 +``` + +从实例忽略单个通知。 + +**返回：** 空\ +**OAuth：** 用户令牌 + `write:notifications`\ +**版本历史：**\ +0.0.0 - 可用\ +1.3.0 - 弃用，推荐使用 [notifications/:id/dismiss](#dismiss) +3.0.0 - 移除 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 来获得对本 API 方法的访问授权。 + +##### 表单数据参数 +id +: {{}} 字符串。数据库中通知的 ID。 + +#### 响应 + +##### 200: OK + +成功忽略具有给定 ID 的通知 + +```json +{} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 获取未读通知的数量 {#unread-count} + +```http +GET /api/v1/notifications/unread_count HTTP/1.1 +``` + +获取当前用户的未读通知的（上限）数量。 +若通知比 [通知已读标记]({{< relref "methods/markers" >}}) 更新，则认为该通知未读。 +由于计数取决于参数，因此每次都会计算，因此这是一个相对较慢的操作（尽管比获取完整的相应通知更快），因此返回的通知数量受到限制。 + +**返回：** 具有单个 `count` 键的哈希\ +**OAuth：** 用户令牌 + `read:notifications`\ +**版本历史：**\ +4.3.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 来获得对本 API 方法的访问授权。 + +##### 查询参数 + +limit +: 整数。要返回的最大结果数。默认为 100 个通知。最多 1000 个通知。 + +types[] +: 字符串数组。应计入未读通知的通知类型。 + +exclude_types[] +: 字符串数组。不应计入未读通知的通知类型。 + +account_id +: 字符串。仅计算从指定帐户收到的未读通知。 + +#### 响应 + +##### 200: OK + +响应体包含未读通知的上限计数。 + +```json +{ + "count": 42, +} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 获取通知的筛选策略 {#get-policy} + +```http +GET /api/v2/notifications/policy HTTP/1.1 +``` + +用户的通知筛选策略。 + +**返回：** [NotificationPolicy]({{< relref "entities/NotificationPolicy" >}})\ +**OAuth：** 用户令牌 + `read:notifications`\ +**版本历史：**\ +4.3.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 来获得对本 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +响应体包含用户当前的通知筛选策略。 + +```json +{ + "for_not_following": "accept", + "for_not_followers": "accept", + "for_new_accounts": "accept", + "for_private_mentions": "drop", + "for_limited_accounts": "filter", + "summary": { + "pending_requests_count": 0, + "pending_notifications_count": 0 + } +} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +## 更新通知的筛选策略 + +```http +PATCH /api/v2/notifications/policy HTTP/1.1 +``` + +更新用户的通知筛选策略。 + +**返回：** [NotificationPolicy]({{< relref "entities/NotificationPolicy" >}})\ +**OAuth：** 用户令牌 + `write:notifications`\ +**版本历史：**\ +4.3.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 来获得对本 API 方法的访问授权。 + +#### 表单数据参数 + +for_not_following +: 字符串。是 `accept`，`filter` 还是 `drop` 来自用户未关注的帐户的通知。`drop` 将完全阻止通知对象的创建（但不阻止底层活动），`filter` 将导致通知被标记为已过滤，而 `accept` 不会影响其处理。 + +for_not_followers +: 字符串。是 `accept`，`filter` 还是 `drop` 来自未关注用户的帐户的通知。`drop` 将完全阻止通知对象的创建（但不阻止底层活动），`filter` 将导致通知被标记为已过滤，而 `accept` 不会影响其处理。 + +for_new_accounts +: 字符串。是 `accept`，`filter` 还是 `drop` 来自过去 30 天内创建的帐户的通知。`drop` 将完全阻止通知对象的创建（但不阻止底层活动），`filter` 将导致通知被标记为已过滤，而 `accept` 不会影响其处理。 + +for_private_mentions +: 字符串。是 `accept`，`filter` 还是 `drop` 来自私有提及的通知。`drop` 将完全阻止通知对象的创建（但不阻止底层活动），`filter` 将导致通知被标记为已过滤，而 `accept` 不会影响其处理。始终允许回复用户发起的私人提及以及用户关注的帐户，无论此值如何。 + +for_limited_accounts +: 字符串。是 `accept`，`filter` 还是 `drop` 来自被审核员限制的帐户的通知。`drop` 将完全阻止通知对象的创建（但不阻止底层活动），`filter` 将导致通知被标记为已过滤，而 `accept` 不会影响其处理。 + + +#### 响应 + +##### 200: OK + +响应体包含用户更新后的通知筛选策略。 + +```json +{ + "filter_not_following": false, + "filter_not_followers": false, + "filter_new_accounts": false, + "filter_private_mentions": true, + "summary": { + "pending_requests_count": 0, + "pending_notifications_count": 0 + } +} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 获取所有通知请求 {#get-requests} + +```http +GET /api/v1/notifications/requests HTTP/1.1 +``` + +被用户的策略过滤的通知的通知请求。此 API 返回包含指向下一页/上一页的链接的 Link 标头。 + +**返回：** [NotificationRequest]({{< relref "entities/NotificationRequest" >}}) 数组\ +**OAuth：** 用户令牌 + `read:notifications`\ +**版本历史：**\ +4.3.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 来获得对本 API 方法的访问授权。 + +##### 查询参数 + +max_id +: 字符串。返回的所有结果将小于此 ID。事实上设置了结果的上限。 + +since_id +: 字符串。返回的所有结果将大于此 ID。事实上设置了结果的下限。 + +min_id +: 字符串。返回与此 ID 相邻且更新的结果。事实上在此 ID 处设置一个游标并向前分页。 + +limit +: 整数。要返回的最大结果数。默认为 40 个通知请求。最多 80 个通知请求。 + +#### 响应 + +##### 200: OK + +响应体包含一页通知请求。你可以使用 HTTP Link 标头进行进一步分页。 + +```http +Link: ; rel="next", ; rel="prev" +``` + +```json +[ + { + "id": "112456967201894256", + "created_at": "2024-05-17T14:45:41.171Z", + "updated_at": "2024-05-17T14:45:41.171Z", + "notifications_count": "1", + "account": { + "id": "971724", + "username": "zsc", + "acct": "zsc", + // ... + }, + "last_status": { + "id": "103186126728896492", + "created_at": "2019-11-23T07:49:01.940Z", + "in_reply_to_id": "103186038209478945", + "in_reply_to_account_id": "14715", + // ... + "content": "

@trwnh sup!

", + // ... + "account": { + "id": "971724", + "username": "zsc", + "acct": "zsc", + // ... + }, + // ... + "mentions": [ + { + "id": "14715", + "username": "trwnh", + "url": "https://mastodon.social/@trwnh", + "acct": "trwnh" + } + ], + // ... + } + } +] +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 获取单个通知请求 {#get-one-request} + +```http +GET /api/v1/notifications/requests/:id HTTP/1.1 +``` + +查看有关具有给定 ID 的通知请求的信息。 + +**返回：** [NotificationRequest]({{< relref "entities/NotificationRequest" >}})\ +**OAuth：** 用户令牌 + `read:notifications`\ +**版本历史：**\ +4.3.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中通知的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 来获得对本 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +单个通知请求。 + +```json + { + "id": "112456967201894256", + "created_at": "2024-05-17T14:45:41.171Z", + "updated_at": "2024-05-17T14:45:41.171Z", + "notifications_count": "1", + "account": { + "id": "971724", + "username": "zsc", + "acct": "zsc", + // ... + }, + "last_status": { + "id": "103186126728896492", + "created_at": "2019-11-23T07:49:01.940Z", + "in_reply_to_id": "103186038209478945", + "in_reply_to_account_id": "14715", + // ... + "content": "

@trwnh sup!

", + // ... + "account": { + "id": "971724", + "username": "zsc", + "acct": "zsc", + // ... + }, + // ... + "mentions": [ + { + "id": "14715", + "username": "trwnh", + "url": "https://mastodon.social/@trwnh", + "acct": "trwnh" + } + ], + // ... + } + } +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 接受单个通知请求 {#accept-request} + +```http +POST /api/v1/notifications/requests/:id/accept HTTP/1.1 +``` + +接受通知请求，这将把来自该用户的已过滤通知合并回主通知，并接受来自他们的所有未来通知。 + +**返回：** 空\ +**OAuth：** 用户令牌 + `write:notifications`\ +**版本历史：**\ +4.3.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中通知的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 来获得对本 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +成功的调用将返回一个空对象。 + +```json +{} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 忽略单个通知请求 {#dismiss-request} + +```http +POST /api/v1/notifications/requests/:id/dismiss HTTP/1.1 +``` + +忽略通知请求，这将隐藏对应的通知并不再将其计入待处理通知计数。 + +**返回：** 空\ +**OAuth：** 用户令牌 + `write:notifications`\ +**版本历史：**\ +4.3.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中通知的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 来获得对本 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +成功调用将返回一个空对象。 + +```json +{} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 接受多个通知请求 {#accept-multiple-requests} + +```http +POST /api/v1/notifications/requests/accept HTTP/1.1 +``` + +接受多个通知请求，这将把来自这些用户的已过滤通知合并回主通知，并接受来自他们的所有未来通知。 + +**返回：** 空\ +**OAuth：** 用户令牌 + `write:notifications`\ +**版本历史：**\ +4.3.0 - 添加 + +#### 请求 + +##### 表单数据参数 + +":id[] +: {{}} 字符串数组。数据库中通知请求的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 来获得对本 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +成功的调用将返回一个空对象。 + +```json +{} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 忽略多个通知请求 {#dismiss-multiple-requests} + +```http +POST /api/v1/notifications/requests/dismiss HTTP/1.1 +``` + +忽略多个通知请求，这将隐藏对应的通知并不再将其计入待处理通知计数。 + +**返回：** 空\ +**OAuth：** 用户令牌 + `write:notifications`\ +**版本历史：**\ +4.3.0 - 添加 + +#### 请求 + +##### 表单数据参数 + +:id[] +: {{}} 字符串数组。数据库中通知请求的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 来获得对本 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +成功调用将返回一个空对象。 + +```json +{} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 检查接受的通知请求是否已合并 {#requests-merged} + +```http +GET /api/v1/notifications/requests/merged +``` + +检查接受的通知请求是否已合并。 +接受通知请求后系统将安排一个后台作业，将已过滤的通知合并回正常的通知列表。该过程完成后，客户端应尽快刷新通知列表。这是通过 `notifications_merged` 流事件传达的，但也可以使用此端点进行轮询。 + +***返回：** 具有单个布尔属性 `merged` 的哈希\ +**OAuth：** 用户令牌 + `read:notifications`\ +**版本历史：**\ +4.3.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 来获得对本 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +成功的调用将返回是否已合并通知并准备好加载。 + +```json +{ + "merged": false +} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 另请参考 + +{{< page-relref ref="methods/push" caption="push API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/notifications_controller.rb" caption="app/controllers/api/v1/notifications_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="notifications API methods" raw_link="/methods/notifications/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/notifications_alpha.md b/content/zh-cn/methods/notifications_alpha.md new file mode 100644 index 0000000..7b9b9f1 --- /dev/null +++ b/content/zh-cn/methods/notifications_alpha.md @@ -0,0 +1,635 @@ +--- +title: notifications API 方法 (Alpha) +description: 接收关于你的帐户或嘟文活动的通知。 +--- + + + +{{< hint style="warning" >}} +此页面记录了实验性的 API 端点，仅供历史参考。若你想在客户端中实现分组通知功能，请参阅[最终版本]({{< relref "methods/grouped_notifications" >}})。 +{{}} + +本页介绍分组通知，我们已在服务端实现该功能，以便： +- 使跨客户端分组保持一致 +- 客户端不会遇到浏览整个页面却没有产生任何新组的问题；相反，通知已经在服务端进行了去重 + +API 的结构与非分组通知略有不同，因为大型通知组通常涉及相同的帐户，将帐户移动到根键可以避免大量重复，从而减少服务端的工作量和网络负载。 + +## 获取所有分组通知 {#get-grouped} + +```http +GET /api/v2_alpha/notifications HTTP/1.1 +``` + +返回与用户相关的分组通知。此 API 返回包含指向下一页/上一页链接的 Link 标头。但是，链接也可以使用查询参数和 `id` 值嘟文构建。 + +在相似的时间段内，类型和目标相同，且类型为 `favourite` 或 `reblog` 的通知会被实例赋予相同的 `group_key`，查询此端点将返回聚合的通知，每个 `group_key` 只有一个对象。其他通知类型（如 `follow`）将来可能会被分组。 + +要筛选的类型包括： +- `mention` = 有人在其嘟文中提到了你 +- `status` = 你启用了通知的人发布了嘟文 +- `reblog` = 有人转发了你的某条嘟文 +- `follow` = 有人关注了你 +- `follow_request` = 有人请求关注你 +- `favourite` = 有人喜欢了你的某条嘟文 +- `poll` = 你投票或创建的投票已结束 +- `update` = 你转发的嘟文已被编辑 +- `admin.sign_up` = 有人注册了（可根据具体配置发送给管理员） +- `admin.report` = 已提交新的举报 + +**返回：** [GroupedNotificationsResults](#GroupedNotificationsResults)\ +**OAuth：** 用户令牌 + `read:notifications`\ +**版本历史：**\ +4.3.0-beta.1 - 添加\ +4.3.0-beta.2 - 弃用 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: 字符串。返回的所有结果都将是关于严格早于此通知 ID 的通知。事实上设置结果的上限。 + +since_id +: 字符串。返回的所有结果都将是关于严格晚于此通知 ID 的通知。事实上设置结果的下限。 + +min_id +: 字符串。返回关于紧邻在此通知 ID 之后的新通知的结果。事实上在此 ID 处设置一个游标并向前分页。 + +limit +: 整数。要返回的最大结果数。默认为 40 个通知。最多 80 个通知组。 + +types[] +: 字符串数组。要包含在结果中的类型。 + +exclude_types[] +: 字符串数组。要从结果中排除的类型。 + +account_id +: 字符串。仅返回从指定帐户收到的通知。 + +expand_accounts +: 字符串。`full`（默认）或 `partial_avatars` 之一。设置为 `partial_avatars` 时，某些帐户将不会在返回的 `accounts` 列表中完整呈现，而是以精简形式在 `partial_accounts` 列表中返回。通知组中最新的帐户始终在 `accounts` 属性中完整呈现。 + +grouped_types[] +: 字符串数组。限制可以分组的通知类型。若你的客户端不支持某些通知类型分组，请使用此选项。若省略，实例将对它支持的所有类型的通知（目前，`favourite` 和 `reblog`）进行分组。若你不希望进行任何通知分组，请改用 [GET `/api/v1/notifications`]({{< relref "methods/notifications#get" >}})。 + +#### 响应 + +使用 limit=2 的示例调用。 + +```http +GET https://mastodon.social/api/v2_alpha/notifications?limit=2 HTTP/1.1 +Authorization: Bearer xxx +``` + +##### 200: OK + +响应体包含一页分组通知。你可以使用 HTTP Link 标头进行进一步的分页。 + +```http +Link: ; rel="next", ; rel="prev"; +``` + +```json +{ + "accounts": [ + { + "id": "16", + "username": "eve", + "acct": "eve", + // … + }, + { + "id": "3547", + "username": "alice", + "acct": "alice", + // … + }, + { + "id": "31460", + "username": "bob", + "acct": "bob", + // … + }, + { + "id": "36509", + "username": "mallory", + "acct": "mallory", + // … + } + ], + "statuses": [ + { + "id": "113010503322889311", + "created_at": "2024-08-23T08:57:12.057Z", + "account": { + "id": "55911", + "username": "user", + "acct": "user", + // … + }, + // … + }, + { + "id": "113006771938929950", + "created_at": "2024-08-22T17:08:15.654Z", + "account": { + "id": "55911", + "username": "user", + "acct": "user", + // … + }, + // … + } + ], + "notification_groups": [ + { + "group_key": "favourite-113010503322889311-479000", + "notifications_count": 2, + "type": "favourite", + "most_recent_notification_id": 196014, + "page_min_id": "196013", + "page_max_id": "196014", + "latest_page_notification_at": "2024-08-23T08:59:56.743Z", + "sample_account_ids": [ + "16", + "3547" + ], + "status_id": "113010503322889311" + }, + { + "group_key": "favourite-113006771938929950-478999", + "notifications_count": 2, + "type": "favourite", + "most_recent_notification_id": 196012, + "page_min_id": "196012", + "page_max_id": "196012", + "latest_page_notification_at": "2024-08-23T08:16:32.112Z", + "sample_account_ids": [ + "31460", + "36509" + ], + "status_id": "113006771938929950" + } + ] +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 获取单个通知组 {#get-notification-group} + +```http +GET /api/v2_alpha/notifications/:group_key HTTP/1.1 +``` + +查看有关具有给定分组键的特定通知组的信息。 + +**返回：** [GroupedNotificationsResults](#GroupedNotificationsResults) +**OAuth：** 用户令牌 + `read:notifications` +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### 请求 + +##### 路径参数 + +:group_key +: {{}} 字符串。通知组的分组键。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +成功时，返回一个带有单个通知组的 [GroupedNotificationsResults](#GroupedNotificationsResults)。 + +```json +{ + "accounts": [ + { + "id": "16", + "username": "eve", + "acct": "eve", + // … + }, + { + "id": "3547", + "username": "alice", + "acct": "alice", + // … + } + ], + "statuses": [ + { + "id": "113010503322889311", + "created_at": "2024-08-23T08:57:12.057Z", + "account": { + "id": "55911", + "username": "user", + "acct": "user", + // … + }, + // … + } + ], + "notification_groups": [ + { + "group_key": "favourite-113010503322889311-479000", + "notifications_count": 2, + "type": "favourite", + "most_recent_notification_id": 196014, + "sample_account_ids": [ + "16", + "3547" + ], + "status_id": "113010503322889311" + } + ] +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 忽略单个通知组 {#dismiss-group} + +```http +POST /api/v2_alpha/notifications/:group_key/dismiss HTTP/1.1 +``` + +忽略单个通知组。 + +**返回：** 空 +**OAuth：** 用户令牌 + `write:notifications` +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### 请求 + +##### 路径参数 + +:group_key +: {{}} 字符串。要丢弃的通知的分组键。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +成功请求后，具有给定分组键的通知将被成功忽略。 + +```json +{} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 获取未读通知的数量 {#unread-group-count} + +```http +GET /api/v2_alpha/notifications/unread_count HTTP/1.1 +``` + +获取当前用户的（上限）未读通知组的数量。 +若通知比[通知读取标记]({{< relref "methods/markers" >}})更新，则认为该通知未读。 +由于计数取决于具体参数，因此每次请求都会重新计算，因此这是一个相对较慢的操作（尽管比获取完整的相应通知更快），因此返回的通知数量受到限制。 + +**返回：** 具有单个 `count` 键的哈希 +**OAuth：** 用户令牌 + `read:notifications` +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +limit +: 整数。要返回的最大结果数。默认为 100 个通知。最多 1000 个通知。 + +types[] +: 字符串数组。应计入未读通知的通知类型。 + +exclude_types[] +: 字符串数组。不应计入未读通知的通知类型。 + +account_id +: 字符串。仅计算从指定帐户收到的未读通知。 + +grouped_types[] +: 字符串数组。限制可以分组的通知类型。若你的客户端不支持某些通知类型分组，请使用此选项。若省略，实例将对它支持的所有类型的通知（目前支持 `favourite` 和 `reblog`）进行分组。若你不希望进行任何通知分组，请改用 [GET `/api/v1/notifications/unread_count`]({{< relref "methods/notifications#unread-count" >}})。 + +#### 响应 + +##### 200: OK + +响应体包含未读通知的上限计数。 + +```json +{ + "count": 42, +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## `GroupedNotificationsResults` 实体 {#GroupedNotificationsResults} + +### 属性 + +#### `accounts` + +**描述：** 分组通知引用的帐户。 +**类型：** [Account]({{< relref "entities/Account" >}}) 数组 +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `partial_accounts` {{%optional%}} + +**描述：** 分组通知引用的部分帐户。仅在请求带有 `expand_accounts=partial_avatars` 的分组通知时返回。 +**类型：** [PartialAccountWithAvatar](#PartialAccountWithAvatar) 数组 +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `statuses` + +**描述：** 分组通知引用的嘟文。 +**类型：** [Status]({{< relref "entities/Status" >}}) 数组 +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `notification_groups` + +**描述：** 分组通知本身。 +**类型：** [NotificationGroup](#NotificationGroup) +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +### 示例 + +TODO + +--- + +## `PartialAccountWithAvatar` 实体 {#PartialAccountWithAvatar} + +这些是 [Account]({{< relref "entities/Account" >}}) 的精简版本，仅包含显示头像列表以及其他一些有用的属性所需的内容。构造此实体旨在减少昂贵的服务端序列化，并减小通知组的网络负载大小。 + +### 属性 + +#### `id` + +**描述：** 帐户 ID。 +**类型：** 字符串（从整数转换而来，但不保证是数字） +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `acct` + +**描述：** Webfinger 帐户 URI。对于本站用户，等于 `username`，对于外站用户，等于 `username@domain`。 +**类型：** 字符串 +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `url` + +**描述：** 用户个人资料页面的位置。 +**类型：** 字符串 (URL) +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `avatar` + +**描述：** 显示在嘟文旁边和个人资料中的图像图标。 +**类型：** 字符串 (URL) +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `avatar_static` + +**描述：** 头像的静态版本。若其值为静态图像，则等于 `avatar`；若 `avatar` 是动画 GIF，则不同。 +**类型：** 字符串 (URL) +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `locked` + +**描述：** 该帐户是否手动批准关注请求。 +**类型：** 布尔值 +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `bot` + +**描述：** 指示该帐户可能执行自动化操作，可能未被监控，或标识为机器人。 +**类型：** 布尔值 +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +### 示例 + +TODO + +-- + +## `NotificationGroup` 实体 {#NotificationGroup} + +### 属性 + +#### `group_key` + +**描述：** 标识分组通知的分组键。应将其视为不透明值。 +**类型：** 字符串 +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `notifications_count` + +**描述：** 作为此通知组一部分的个人通知总数。 +**类型：** 整数 +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `type` + +**描述：** 导致此通知组中通知的事件类型。 +**类型：** 字符串 (可枚举 oneOf) +`mention` = 有人在其嘟文中提到了你 +`status` = 你启用了通知的人发布了嘟文 +`reblog` = 有人转发了你的某条嘟文 +`follow` = 有人关注了你 +`follow_request` = 有人请求关注你 +`favourite` = 有人喜欢了你的某条嘟文 +`poll` = 你投票或创建的投票已结束 +`update` = 你与之交互的嘟文已被编辑 +`admin.sign_up` = 有人注册了（可根据具体配置发送给管理员） +`admin.report` = 已提交新的举报 +`severed_relationships` = 由于管理或屏蔽事件，你的一些关注关系已被切断 +`moderation_warning` = 审核员已对你的帐户采取行动或向你发送了警告 +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `most_recent_notification_id` + +**描述：** 通知组中最新通知的 ID。 +**类型：** 字符串 +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `page_min_id` {{%optional%}} + +**描述：** 当前页面中表示的此通知组中最旧通知的 ID。这仅在分页浏览通知组时返回。在轮询新通知时很有用。 +**类型：** 字符串 +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `page_max_id` {{%optional%}} + +**描述：** 当前页面中表示的此通知组中最新通知的 ID。这仅在分页浏览通知组时返回。在轮询新通知时很有用。 +**类型：** 字符串 +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `latest_page_notification_at` {{%optional%}} + +**描述：** 在当前页面中，此通知组中最新通知的创建日期。这仅在分页浏览通知组时返回。 +**类型：** ([Datetime](/api/datetime-format#datetime)) 字符串 +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `sample_account_ids` + +**描述：** 最近触发此通知组中通知的某些帐户的 ID。 +**类型：** 字符串数组 +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `status_id` {{%optional%}} + +**描述：** 作为通知对象的 [Status]({{< relref "entities/Status" >}}) 的 ID。当通知的 `type` 为 `favourite`、`reblog`、`status`、`mention`、`poll` 或 `update` 时附加。 +**类型：** 字符串 +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `report` {{%optional%}} + +**描述：** 作为通知对象的举报。当通知的 `type` 为 `admin.report` 时附加。 +**类型：** [Report]({{< relref "entities/Report" >}}) +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `event` {{%optional%}} + +**描述：** 导致关注关系断开的事件摘要。当通知的 `type` 为 `severed_relationships` 时附加。 +**类型：** [RelationshipSeveranceEvent]({{< relref "entities/RelationshipSeveranceEvent" >}}) +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +#### `moderation_warning` {{%optional%}} + +**描述：** 导致通知的管理警告。当通知的 `type` 为 `moderation_warning` 时附加。 +**类型：** [AccountWarning]({{< relref "entities/AccountWarning" >}}) +**版本历史：** +4.3.0-beta.1 - 添加 +4.3.0-beta.2 - 弃用 + +### 示例 + +TODO + +--- + +## 另请参考 + +{{< page-relref ref="methods/grouped_notifications" caption="分组通知 API 方法的最终版本" >}} + +{{< page-relref ref="methods/notifications" caption="单个通知 API 方法" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v2_alpha/notifications_controller.rb" caption="app/controllers/api/v2_alpha/notifications_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="notifications API alpha methods" raw_link="/methods/notifications_alpha/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/oauth.md b/content/zh-cn/methods/oauth.md new file mode 100644 index 0000000..e3809f8 --- /dev/null +++ b/content/zh-cn/methods/oauth.md @@ -0,0 +1,346 @@ +--- +title: OAuth API 方法 +description: 生成和管理 OAuth 令牌。 +menu: + docs: + weight: 10 + name: oauth + parent: methods-apps + identifier: methods-oauth +aliases: ["/methods/oauth", "/api/methods/oauth", "/methods/apps/oauth"] +--- + + + +## 授权用户 {#authorize} + +```http +GET /oauth/authorize HTTP/1.1 +``` + +向用户显示授权表单。若获得批准，将创建并返回授权码，然后重定向到所需的 `redirect_uri`，或者若请求了 `urn:ietf:wg:oauth:2.0:oob`，则显示授权码。授权码可以在请求令牌并获得对用户级方法的访问权限时使用。 + +**返回:** 字符串（URL）或 HTML 响应\ +**OAuth:** 公开\ +**版本历史记录:**\ +0.1.0 - 添加\ +2.6.0 - 添加 `force_login`\ +3.5.0 - 添加 `lang` +4.3.0 - 添加 PKCE 参数支持 + +#### 请求 + +##### 查询参数 + +response_type +: {{}} 字符串。应设置为等于 `code`。 + +client_id +: {{}} 字符串。客户端 ID，在应用注册期间获得。 + +redirect_uri +: {{}} 字符串。设置一个 URI 以将用户重定向到该 URI。若此参数设置为 `urn:ietf:wg:oauth:2.0:oob`，则将显示授权码。必须与应用注册期间声明的 `redirect_uris` 之一匹配。 + +scope +: 字符串。请求的 [OAuth 作用域]({{< relref "api/oauth-scopes" >}})列表，由空格分隔（若使用查询参数，则由加号分隔）。必须是应用注册期间声明的 `scopes` 的子集。若未提供，则默认为 `read`。 + +state +: 字符串。任意值，用于在用户授权或拒绝授权请求时传递到你的服务。 + +code_challenge +: 字符串。授权请求的 [PKCE 代码质询]({{< relref "spec/oauth#pkce" >}})。 + +code_challenge_method +: 字符串。必须是 `S256`，因为这是 Mastodon 支持的唯一代码质询方法，用于 PKCE。 + +force_login +: 布尔值。强制用户重新登录，这对于从同一实例使用多个帐户进行授权是必要的。 + +lang +: 字符串。用于呈现授权表单的 ISO 639-1 双字符语言代码。 + +#### 响应 + +##### 200: OK + +授权码将作为名为 `code` 的查询参数返回。 + +{{< hint style="warning" >}} +将 `code` 查询参数视为密码，你应确保它未记录在请求日志中。 +{{< /hint >}} + +```http +redirect_uri?code=qDFUEaYrRK5c-HNmTCJbAzazwLRInJ7VHFat0wcMgCU +``` + +若使用了 state 参数，那么当客户端被重定向时，它也将出现在 URI 中。 + +```http +redirect_uri?code=qDFUEaYrRK5c-HNmTCJbAzazwLRInJ7VHFat0wcMgCU&state=example +``` + +##### 400: Client error + +若授权码不正确或已被使用，则请求将失败。 + +```json +{ + "error": "invalid_grant", + "error_description": "提供的授权许可无效、已过期、已撤销、与授权请求中使用的重定向 URI 不匹配，或者已颁发给另一个客户端。" +} +``` + +--- + +## 获取令牌 {#token} + +```http +POST /oauth/token HTTP/1.1 +``` + +获取访问令牌，用于非公开 API 调用。 + +**返回:** [令牌]({{< relref "entities/token" >}})\ +**OAuth:** 公开\ +**版本历史记录:**\ +0.1.0 - 添加 +4.3.0 - 添加 PKCE 参数支持 + +#### 请求 + +##### 表单数据参数 + +grant_type +: {{}} 字符串。若提供了 `code` 以获得用户级访问权限，则设置为等于 `authorization_code`。否则，设置为等于 `client_credentials` 以仅获得应用级别访问权限。 + +code +: {{}} 字符串。用户授权码，从 [授权请求](#authorize) 获得批准后的重定向中获得。若 `redirect_uri` 为 `urn:ietf:wg:oauth:2.0:oob`，则也可以选择向用户显示。 + +client_id +: {{}} 字符串。客户端 ID，在应用注册期间获得。 + +client_secret +: {{}} 字符串。客户端密钥，在应用注册期间获得。 + +redirect_uri +: {{}} 字符串。必须与 [授权请求](#authorize) 期间使用的 `redirect_uri` 匹配。 + +code_verifier +: 字符串。若在授权请求期间使用了 [PKCE]({{< relref "spec/oauth#pkce" >}})，则为必填项。这是用于使用授权请求的 `code_challenge_method` 创建 `code_challenge` 的代码验证器。 + +scope +: 字符串。当 `grant_type` 设置为 `client_credentials` 时，为请求的 OAuth 作用域列表，以空格分隔（若使用查询参数，则用加号分隔）。必须是在创建应用时请求的作用域的子集。若省略，则默认为 `read`。当 `grant_type` 为 `authorization_code` 时，无效。 + +#### 响应 + +##### 200: OK + +存储此 `access_token` 以供以后与需要身份验证的方法一起使用。令牌应作为 HTTP `Authorization` 标头传递，值为 `Bearer `。 + +{{< hint style="warning" >}} +将 `access_token` 视为密码。我们建议你在将其存储在缓存中时对其进行加密，以防止凭据泄露。\ +\ +此外，你应确保不记录 `code` 参数。 +{{< /hint >}} + +```json +{ + "access_token": "ZA-Yj3aBD8U8Cm7lKUp-lm9O9BmDgdhHzDeqsY8tlL0", + "token_type": "Bearer", + "scope": "read write follow push", + "created_at": 1573979017 +} +``` + +##### 400: Client error + +若你尝试请求注册应用时未包含的作用域，则请求将失败。 + +```json +{ + "error": "invalid_scope", + "error_description": "请求的作用域无效、未知或格式不正确。" +} +``` + +##### 401: Unauthorized + +若 client_id 和 client_secret 不匹配或无效，则请求将失败。 + +```json +{ + "error": "invalid_grant", + "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client." +} +``` + +--- + +## 撤销令牌 {#revoke} + +```http +POST /oauth/revoke HTTP/1.1 +``` + +撤销访问令牌，使其不再有效。 + +**返回:** 空\ +**OAuth:** 公开\ +**版本历史记录:**\ +0.1.0 - 添加 + +#### 请求 + +##### 表单数据参数 + +client_id +: {{}} 字符串。客户端 ID，在应用注册期间获得。 + +client_secret +: {{}} 字符串。客户端密钥，在应用注册期间获得。 + +token +: {{}} 字符串。先前获得的令牌，将被设置为无效。 + +#### 响应 + +##### 200: OK + +若你拥有提供的令牌，则 API 调用将提供一个空响应。此操作是幂等的，因此多次调用此 API 仍将返回 OK。 + +```json +{} +``` + +##### 403: Forbidden + +若你提供了一个你并未拥有的令牌，或者根本没有提供任何令牌，则 API 调用将返回 403 错误。 + +```json +{ + "error": "unauthorized_client", + "error_description": "You are not authorized to revoke this token" +} +``` + +--- + +## 发现 OAuth 实例配置 {#authorization-server-metadata} + +```http +GET /.well-known/oauth-authorization-server HTTP/1.1 +``` + +返回 Mastodon 实例的 OAuth 2 授权实例元数据，按 [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414#section-3.2) 规范要求定义。 + +我们包括了 `app_registration_endpoint` 的附加非标准属性，该属性是指 [POST /api/v1/apps]({{% relref ref="methods/apps#create" %}}) 端点，因为我们目前不支持用于 [动态客户端注册](https://oauth.net/2/dynamic-client-registration/) 的标准 `registration_endpoint` 端点。 + +此端点公开的属性可以帮助你更好地与 Mastodon API 集成，例如允许协商不同 Mastodon 版本中的 `scopes`。 + +{{< hint style="info" >}} +**示例:** 你希望使用 `profile` 作用域，但也想支持没有该作用域且需要 `read:accounts` 的旧版 Mastodon 实例。你可以通过向此端点发出请求来发现实例是否支持该作用域。 +{{< /hint >}} + +**返回:** 如上所述的 JSON\ +**OAuth:** 公开\ +**版本历史记录:**\ +4.3.0 - 添加 + +#### 响应 + +##### 200: OK + +```json +{ + "issuer": "https://social.example/", + "service_documentation": "https://docs.joinmastodon.org/", + "authorization_endpoint": "https://social.example/oauth/authorize", + "token_endpoint": "https://social.example/oauth/token", + "app_registration_endpoint": "https://social.example/api/v1/apps", + "revocation_endpoint": "https://social.example/oauth/revoke", + "scopes_supported": [ + "read", + "write", + "write:accounts", + "write:blocks", + "write:bookmarks", + "write:conversations", + "write:favourites", + "write:filters", + "write:follows", + "write:lists", + "write:media", + "write:mutes", + "write:notifications", + "write:reports", + "write:statuses", + "read:accounts", + "read:blocks", + "read:bookmarks", + "read:favourites", + "read:filters", + "read:follows", + "read:lists", + "read:mutes", + "read:notifications", + "read:search", + "read:statuses", + "follow", + "push", + "profile", + "admin:read", + "admin:read:accounts", + "admin:read:reports", + "admin:read:domain_allows", + "admin:read:domain_blocks", + "admin:read:ip_blocks", + "admin:read:email_domain_blocks", + "admin:read:canonical_email_blocks", + "admin:write", + "admin:write:accounts", + "admin:write:reports", + "admin:write:domain_allows", + "admin:write:domain_blocks", + "admin:write:ip_blocks", + "admin:write:email_domain_blocks", + "admin:write:canonical_email_blocks" + ], + "response_types_supported": ["code"], + "response_modes_supported": ["query", "fragment", "form_post"], + "code_challenge_methods_supported": [ + "S256" + ], + "grant_types_supported": [ + "authorization_code", + "client_credentials" + ], + "token_endpoint_auth_methods_supported": [ + "client_secret_basic", + "client_secret_post" + ] +} +``` + +##### 较旧的 Mastodon 版本 – 404: 未找到 + +在 4.3.0 之前的 Mastodon 版本上，请求此端点将导致 `404 Not Found` 错误。 + +此时，你需要“猜测”该实例支持的内容，而不是动态发现支持的 OAuth 2 端点、授权流程和作用域。 + +你可能希望回退到 [实例元数据端点]({{% relref ref="methods/instance#v2" %}})，尝试通过解析 `version` 字作用域来发现实例正在运行的 Mastodon 版本；但是，这提供的保证非常脆弱，不建议使用。 + +--- + +## 另请参考 + +{{< page-relref ref="methods/apps#create" caption="POST /api/v1/apps" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/oauth/authorizations_controller.rb" caption="app/controllers/oauth/authorizations_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/oauth/authorized_applications_controller.rb" caption="app/controllers/oauth/authorized_applications_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/oauth/tokens_controller.rb" caption="app/controllers/oauth/tokens_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="OAuth API methods" raw_link="/methods/oauth/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/oembed.md b/content/zh-cn/methods/oembed.md new file mode 100644 index 0000000..02eae42 --- /dev/null +++ b/content/zh-cn/methods/oembed.md @@ -0,0 +1,80 @@ +--- +title: oembed API 方法 +description: 用于生成 OEmbed 预览。 +menu: + docs: + weight: 110 + name: oembed + parent: methods + identifier: methods-oembed +aliases: [ + "/methods/oembed", + "/api/methods/oembed", +] +--- + + + +## 以 JSON 格式获取 OEmbed 信息 {#get} + +```http +GET /api/oembed HTTP/1.1 +``` + +**返回：** OEmbed 元数据\ +**OAuth：** 公开\ +**版本历史：**\ +1.0.0 - 添加 + +#### 请求 +##### 查询参数 + +url +: {{}} 字符串。嘟文的 URL。 + +maxwidth +: 数字。iframe 的宽度。默认为 400 + +maxheight +: 数字。iframe 的高度。默认为 null + +#### 响应 +##### 200: OK + +表示 OEmbed “富媒体 (rich)” 预览，带有相关的 iframe 和元数据。 + +```json +{ + "type": "rich", + "version": "1.0", + "title": "trwnh 的新嘟文", + "author_name": "infinite love ⴳ", + "author_url": "https://mastodon.social/@trwnh", + "provider_name": "mastodon.social", + "provider_url": "https://mastodon.social/", + "cache_age": 86400, + "html": "", + "width": 400, + "height": null +} +``` + +##### 404: Not found + +对于给定的 URL，未找到嘟文 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/oembed_controller.rb" caption="app/controllers/api/oembed_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="oembed API methods" raw_link="/methods/oembed/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/polls.md b/content/zh-cn/methods/polls.md new file mode 100644 index 0000000..bfac922 --- /dev/null +++ b/content/zh-cn/methods/polls.md @@ -0,0 +1,233 @@ +--- +title: polls API 方法 +description: >- + 查看和投票给附加到嘟文的投票。要发现投票 ID，你需要首先 GET 一个嘟文，然后检查 `poll` 属性。 +menu: + docs: + weight: 20 + name: polls + parent: methods-statuses + identifier: methods-polls +aliases: [ + "/methods/polls", + "/api/methods/polls", + "/methods/statuses/polls", +] +--- + + + +## 查看投票 {#get} + +```http +GET /api/v1/polls/:id HTTP/1.1 +``` + +查看附加到嘟文的投票。 + +**返回：** [Poll]({{< relref "entities/poll" >}})\ +**OAuth:** 若上级嘟文是公开的，则为公开。若上级嘟文是私有的，则为用户令牌 + `read:statuses`。\ +**版本历史：**\ +2.8.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中投票的 ID。 + +##### 标头 + +Authorization +: 提供此标头，并使用 `Bearer ` 以获得对该 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{ + "id": "34830", + "expires_at": "2019-12-05T04:05:08.302Z", + "expired": true, + "multiple": false, + "votes_count": 10, + "voters_count": null, + "voted": true, + "own_votes": [ + 1 + ], + "options": [ + { + "title": "accept", + "votes_count": 6 + }, + { + "title": "deny", + "votes_count": 4 + } + ], + "emojis": [] +} +``` + +##### 404: Not found + +投票不存在，或投票的上级嘟文是私有的 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 投票 {#vote} + +```http +POST /api/v1/polls/:id/votes HTTP/1.1 +``` + +投票给附加到嘟文的投票。 + +**返回：** [Poll]({{< relref "entities/poll" >}})\ +**OAuth:** 用户令牌 + `write:statuses`\ +**版本历史：**\ +2.8.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中投票的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，并使用 `Bearer ` 以获得对该 API 方法的访问授权。 + +##### 表单数据参数 + +choices[] +: {{}} 整数数组。将你自己的投票作为每个选项的索引提供（从 0 开始）。 + +#### 响应 +##### 200: OK + +已成功进行投票 + +```json +{ + "id": "34873", + "expires_at": "2019-12-05T11:16:17.426Z", + "expired": false, + "multiple": true, + "votes_count": 5, + "voters_count": null, + "voted": true, + "own_votes": [ + 0, + 2, + 4, + 9, + 6 + ], + "options": [ + { + "title": "option 0", + "votes_count": 1 + }, + { + "title": "option 1", + "votes_count": 0 + }, + { + "title": "option 2", + "votes_count": 1 + }, + { + "title": "option 3", + "votes_count": 0 + }, + { + "title": "option 4", + "votes_count": 1 + }, + { + "title": "option 5", + "votes_count": 0 + }, + { + "title": "option 6", + "votes_count": 1 + }, + { + "title": "option 7", + "votes_count": 0 + }, + { + "title": "option 8", + "votes_count": 0 + }, + { + "title": "option 9", + "votes_count": 1 + } + ], + "emojis": [] +} +``` + +##### 401: Unauthorized + +无效或缺少授权标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +投票不存在，或投票的上级嘟文是私有的 + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +投票已过期 + +```json +{ + "error": "Validation failed: The poll has already ended" +} +``` + +或者，你已经进行过投票 + +```json +{ + "error": "Validation failed: You have already voted on this poll" +} +``` + +--- + +## 另请参考 + +{{< page-relref ref="methods/statuses#create" caption="POST /api/v1/statuses (`poll` parameter)" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/polls_controller.rb" caption="app/controllers/api/v1/polls_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/polls/votes_controller.rb" caption="app/controllers/api/v1/polls/votes_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="polls API methods" raw_link="/methods/polls/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/preferences.md b/content/zh-cn/methods/preferences.md new file mode 100644 index 0000000..045724e --- /dev/null +++ b/content/zh-cn/methods/preferences.md @@ -0,0 +1,71 @@ +--- +title: preferences API 方法 +description: 客户端间共享的通用默认行为。 +menu: + docs: + weight: 110 + name: preferences + parent: methods-accounts + identifier: methods-preferences +aliases: [ + "/methods/preferences", + "/api/methods/preferences", + "/methods/accounts/preferences", +] +--- + + + +## 查看用户偏好设置 {#get} + +```http +GET /api/v1/preferences HTTP/1.1 +``` + +用户在其帐户设置中定义的偏好设置。 + +**返回：** 按键和值返回偏好设置\ +**OAuth：** 用户令牌 + `read:accounts`\ +**版本历史：**\ +2.8.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，并使用 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +```json +{ + "posting:default:visibility": "public", + "posting:default:sensitive": false, + "posting:default:language": null, + "reading:expand:media": "default", + "reading:expand:spoilers": false +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "访问令牌无效" +} +``` + +--- + +## 另请参阅 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/preferences_controller.rb" caption="app/controllers/api/v1/preferences_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="preferences API methods" raw_link="/methods/preferences/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/profile.md b/content/zh-cn/methods/profile.md new file mode 100644 index 0000000..b10a58b --- /dev/null +++ b/content/zh-cn/methods/profile.md @@ -0,0 +1,180 @@ +--- +title: profile API 方法 +description: 关于用户账户的方法。 +menu: + docs: + weight: 20 + name: profile + parent: methods + identifier: methods-profile +--- + + + +## 删除账户头像 + +```http +DELETE /api/v1/profile/avatar HTTP/1.1 +``` + +**返回:** [CredentialAccount]({{< relref "entities/Account#CredentialAccount">}})\ +**OAuth:** 用户令牌 + `write:accounts`\ +**版本历史:**\ +4.2.0 - 添加 + +删除与账户关联的头像。 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，并附带 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 路径参数 + +#### 响应 + +##### 200: OK + +已成功从账户中删除头像。若该账户未关联任何头像，响应仍将提示成功删除。 + +```json +{ + "id": "110357222516183152", + "username": "rob", + "acct": "rob", + "display_name": "", + "locked": false, + "bot": false, + "discoverable": false, + "group": false, + "created_at": "2023-05-12T00:00:00.000Z", + "note": "", + "url": "http://localhost:3000/@rob", + "uri": "http://localhost:3000/users/rob", + "avatar": "http://localhost:3000/avatars/original/missing.png", + "avatar_static": "http://localhost:3000/avatars/original/missing.png", + "header": "http://localhost:3000/system/accounts/headers/110/357/222/516/183/152/original/0cd99648c23005ed.png", + "header_static": "http://localhost:3000/system/accounts/headers/110/357/222/516/183/152/original/0cd99648c23005ed.png", + "followers_count": 14, + "following_count": 2, + "statuses_count": 10, + "last_status_at": "2023-06-26", + "noindex": false, + "source": { + "privacy": "public", + "sensitive": false, + "language": null, + "note": "", + "fields": [], + "follow_requests_count": 0 + }, + "emojis": [], + "roles": [], + "fields": [], + "role": { + "id": "-99", + "name": "", + "permissions": "65536", + "color": "", + "highlighted": false + } +} +``` + +### 401: 未授权 + +Authorization 标头无效或缺失。 + +```json +{ + "error": "The access token is invalid" +} +``` + +## 删除账户横幅图片 + +```http +DELETE /api/v1/profile/header HTTP/1.1 +``` + +**返回:** [CredentialAccount]({{< relref "entities/Account#CredentialAccount">}})\ +**OAuth:** 用户令牌 + `write:accounts`\ +**版本历史:**\ +4.2.0 - 添加 + +删除与账户关联的横幅图片。 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，并附带 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 路径参数 + +#### 响应 + +##### 200: OK + +已成功从账户中删除横幅图片。若该账户未关联任何横幅图片，响应仍将提示成功删除。 + +```json +{ + "id": "110357222516183152", + "username": "rob", + "acct": "rob", + "display_name": "", + "locked": false, + "bot": false, + "discoverable": false, + "group": false, + "created_at": "2023-05-12T00:00:00.000Z", + "note": "", + "url": "http://localhost:3000/@rob", + "uri": "http://localhost:3000/users/rob", + "avatar": "http://localhost:3000/avatars/original/missing.png", + "avatar_static": "http://localhost:3000/avatars/original/missing.png", + "header": "http://localhost:3000/headers/original/missing.png", + "header_static": "http://localhost:3000/headers/original/missing.png", + "followers_count": 14, + "following_count": 2, + "statuses_count": 10, + "last_status_at": "2023-06-26", + "noindex": false, + "source": { + "privacy": "public", + "sensitive": false, + "language": null, + "note": "", + "fields": [], + "follow_requests_count": 0 + }, + "emojis": [], + "roles": [], + "fields": [], + "role": { + "id": "-99", + "name": "", + "permissions": "65536", + "color": "", + "highlighted": false + } +} +``` + +### 401: 未授权 + +Authorization 标头无效或缺失。 + +```json +{ + "error": "The access token is invalid" +} +``` + +{{< translation-status-zh-cn raw_title="profile API methods" raw_link="/methods/profile/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/proofs.md b/content/zh-cn/methods/proofs.md new file mode 100644 index 0000000..a2ec90d --- /dev/null +++ b/content/zh-cn/methods/proofs.md @@ -0,0 +1,79 @@ +--- +title: proofs API 方法 +description: 供身份提供者使用。 +menu: + docs: + weight: 100 + name: proofs + parent: methods + identifier: methods-proofs +aliases: [ + "/methods/proofs", + "/api/methods/proofs", + "/methods/accounts/proofs", +] +--- + + + +{{< hint style="danger" >}} +**已弃用**\ +身份证明已在 3.5.0 及更高版本中弃用。 以前，唯一的证明提供者是 Keybase，但自从被 Zoom 收购以来，Keybase 的开发已经完全停滞。 +{{< /hint >}} + +## 查看身份证明{{%removed%}} {#get} + +```http +GET /api/proofs HTTP/1.1 +``` + +**返回：** 由提供者定义的自定义响应\ +**OAuth：** 公开\ +**版本历史：**\ +2.8.0 - 添加 + +#### 请求 +##### 查询参数 + +provider +: 字符串。要查找的身份提供者。目前仅支持 `keybase`（区分大小写）。 + +username +: 字符串。所选身份提供者上的用户名。 + +#### 响应 +##### 200: OK + +通过“keybase”`provider` 查找 `username` “gargron” + +```json +{ + "avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg", + "signatures": [ + { + "sig_hash": "5cfc20c7018f2beefb42a68836da59a792e55daa4d118498c9b1898de7e845690f", + "kb_username": "gargron" + } + ] +} +``` + +##### 404: Not found + +未找到 `provider` 上 `username` 的身份证明 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/pull/17045" caption="删除 Keybase 集成 (#17045)" >}} + +{{< translation-status-zh-cn raw_title="proofs API methods" raw_link="/methods/proofs/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/push.md b/content/zh-cn/methods/push.md new file mode 100644 index 0000000..441f1cf --- /dev/null +++ b/content/zh-cn/methods/push.md @@ -0,0 +1,346 @@ +--- +title: push API 方法 +description: >- + 通过 Web Push API 订阅并接收服务端通知。 +menu: + docs: + weight: 10 + name: push + parent: methods-notifications + identifier: methods-push +aliases: [ + "/methods/push", + "/api/methods/push", + "/methods/notifications/push", +] +--- + + + +## 关于 Web Push API {#about} + +Mastodon 原生支持 [Web Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API)。你可以为你的原生应用使用相同的机制。Mastodon 不直接连接到 Android 和 Apple 的专有通知网关，所以若你希望使用这些网关，你可以配置一个代理实例，在 WebPush 标准和这些网关之间进行转换。这可以以一种代理实例无法访问通知内容的方式来实现。例如，可以参考 [Mozilla 的 web push 参考实例](https://github.com/mozilla-services/autopush)，或者 Mastodon 社区专门为此目的开发的几个中继之一： + +* [toot-relay](https://github.com/DagAgren/toot-relay) +* [PushToFCM](https://github.com/tateisu/PushToFCM) +* [metatext-apns](https://github.com/metabolist/metatext-apns) + +--- + +## 订阅推送通知 {#create} + +```http +POST /api/v1/push/subscription HTTP/1.1 +``` + +添加 Web Push API 订阅以接收通知。每个访问令牌可以拥有一个推送订阅。若你创建一个新的订阅，旧的订阅将被删除。 + +**返回：** [WebPushSubscription]({{< relref "entities/WebPushSubscription" >}})\ +**OAuth：** 用户令牌 + `push`\ +**版本历史：**\ +2.4.0 - 添加\ +3.3.0 - 添加 `data[alerts][status]`\ +3.4.0 - 添加 `data[policy]`\ +3.5.0 - 添加 `data[alerts][update]` 和 `data[alerts][admin.sign_up]`\ +4.0.0 - 添加 `data[alerts][admin.report]`\ +4.3.0 - 添加了更严格的请求参数验证，无效的端点 URL 和订阅密钥现在将导致错误，在此之前这种行为将被接受，但会静默失败。\ +4.4.0 - 添加 `subscription[standard]` + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +subscription[endpoint] +: {{}} 字符串。发生通知事件时调用的端点 URL。 + +subscription[keys][p256dh] +: {{}} 字符串。用户代理公钥。使用 `prime256v1` 曲线的 ECDH 密钥对中的公钥的 Base64 编码字符串。 + +subscription[keys][auth] +: {{}} 字符串。身份验证密钥。16 字节随机数据的 Base64 编码字符串。 + +subscription[standard] +: 布尔值。是否遵循标准的 WebPush (RFC8030+RFC8291+RFC8292) 规范？若为否，则遵循传统的 WebPush（未发布的版本，RFC8291 的第 4 版草案和 RFC8292 的第 1 版草案）。默认为 false。 + +data[alerts][mention] +: 布尔值。是否接收提及通知？默认为 false。 + +data[alerts][status] +: 布尔值。是否接收新的已订阅帐户通知？默认为 false。 + +data[alerts][reblog] +: 布尔值。是否接收转嘟通知？默认为 false。 + +data[alerts][follow] +: 布尔值。是否接收关注通知？默认为 false。 + +data[alerts][follow_request] +: 布尔值。是否接收关注请求通知？默认为 false。 + +data[alerts][favourite] +: 布尔值。是否接收喜欢通知？默认为 false。 + +data[alerts][poll] +: 布尔值。是否接收投票通知？默认为 false。 + +data[alerts][update] +: 布尔值。是否接收嘟文编辑通知？默认为 false。 + +data[alerts][admin.sign_up] +: 布尔值。是否接收新用户注册通知？默认为 false。必须具有具有适当权限的用户组。 + +data[alerts][admin.report] +: 布尔值。是否接收新举报通知？默认为 false。必须具有具有适当权限的用户组。 + +data[policy] +: 字符串。指定是否接收来自 `all`（所有用户）、`followed`（关注的用户）、`follower`（关注者）或 `none`（无）用户的推送通知。 + +#### 响应 +##### 200: OK + +已生成新的 PushSubscription，它会将请求的提醒发送到你的端点。 + +```json +{ + "id": 328183, + "endpoint": "https://yourdomain.example/listener", + "standard": true, + "alerts": { + "follow": true, + "favourite": true, + "reblog": true, + "mention": true, + "poll": true + }, + "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 获取当前订阅 {#get} + +```http +GET /api/v1/push/subscription HTTP/1.1 +``` + +查看当前与此访问令牌关联的 PushSubscription。 + +**返回：** [WebPushSubscription]({{< relref "entities/WebPushSubscription" >}})\ +**OAuth：** 用户令牌 + `push`\ +**版本历史：**\ +2.4.0 - 添加 + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{ + "id": 328183, + "endpoint": "https://yourdomain.example/listener", + "standard": true, + "alerts": { + "follow": true, + "favourite": true, + "reblog": true, + "mention": true, + "poll": true + }, + "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +此令牌不存在 PushSubscription。 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 更改通知类型 {#update} + +```http +PUT /api/v1/push/subscription HTTP/1.1 +``` + +更新当前的推送订阅。只能更新数据部分。要更改基本信息，必须创建一个新的订阅。 + +**返回：** [WebPushSubscription]({{< relref "entities/WebPushSubscription" >}})\ +**OAuth：** 用户令牌 + `push`\ +**版本历史：**\ +2.4.0 - 添加\ +3.3.0 - 添加 `data[alerts][status]`\ +3.4.0 - 添加 `policy`\ +3.5.0 - 添加 `data[alerts][update]` 和 `data[alerts][admin.sign_up]`\ +4.0.0 - 添加 `data[alerts][admin.report]` + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +data[alerts][mention] +: 布尔值。是否接收提及通知？默认为 false。 + +data[alerts][status] +: 布尔值。是否接收新的已订阅帐户通知？默认为 false。 + +data[alerts][reblog] +: 布尔值。是否接收转嘟通知？默认为 false。 + +data[alerts][follow] +: 布尔值。是否接收关注通知？默认为 false。 + +data[alerts][follow_request] +: 布尔值。是否接收关注请求通知？默认为 false。 + +data[alerts][favourite] +: 布尔值。是否接收喜欢通知？默认为 false。 + +data[alerts][poll] +: 布尔值。是否接收投票通知？默认为 false。 + +data[alerts][update] +: 布尔值。是否接收嘟文编辑通知？默认为 false。 + +data[alerts][admin.sign_up] +: 布尔值。是否接收新用户注册通知？默认为 false。必须具有具有适当权限的用户组。 + +data[alerts][admin.report] +: 布尔值。是否接收新举报通知？默认为 false。必须具有具有适当权限的用户组。 + +policy +: 字符串。指定是否接收来自 `all`（所有用户）、`followed`（关注的用户）、`follower`（关注者）或 `none`（无）用户的推送通知。 + +#### 响应 +##### 200: OK + +更新 PushSubscription 以仅接收提及提醒 + +```json +{ + "id": 328183, + "endpoint": "https://yourdomain.example/listener", + "standard": true, + "alerts": { + "follow": false, + "favourite": false, + "reblog": false, + "mention": true, + "poll": false + }, + "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +此令牌不存在 PushSubscription + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 删除当前订阅 {#delete} + +```http +DELETE /api/v1/push/subscription HTTP/1.1 +``` + +删除当前的 Web Push API 订阅。 + +**返回：** 空\ +**OAuth：** 用户令牌 + `push`\ +**版本历史：**\ +2.4.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，使用 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 + +##### 200: OK + +PushSubscription 已成功删除或之前不存在 + +```json +{} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/push/subscriptions_controller.rb" caption="app/controllers/api/v1/push/subscriptions_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="push API methods" raw_link="/methods/push/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/reports.md b/content/zh-cn/methods/reports.md new file mode 100644 index 0000000..ff5e543 --- /dev/null +++ b/content/zh-cn/methods/reports.md @@ -0,0 +1,158 @@ +--- +title: reports API 方法 +description: 向你的管理员举报有问题的用户。 +menu: + docs: + weight: 70 + name: reports + parent: methods-accounts + identifier: methods-reports +aliases: [ + "/methods/reports", + "/api/methods/reports", + "/methods/accounts/reports", +] +--- + + + +## 提交举报 {#post} + +```http +POST /api/v1/reports HTTP/1.1 +``` + +**返回:** [Report]({{< relref "entities/report" >}})\ +**OAuth:** 用户令牌 + `write:reports`\ +**版本历史:**\ +1.1 - 添加\ +2.3.0 - 添加 `forward` 参数\ +3.5.0 - 添加 `category` 和 `rule_ids` 参数\ +4.0.0 - 若提供了 `rule_ids`，则 `category` 现在是可选的\ +4.2.0 - 添加 `legal` 类别 + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供带有 `Bearer ` 的标头，以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +account_id +: {{}} 字符串。要举报的帐户的 ID。 + +status_ids[] +: 字符串数组。你可以将嘟文附加到举报以提供其他上下文。 + +comment +: 字符串。举报的原因。默认最大长度为 1000 个字符。 + +forward +: 布尔值。若帐户是外站账户，是否应将举报转发给外站管理员？默认为 false。 + +category +: 字符串。指定举报是否由于 `spam` （骚扰信息）、`legal` （非法内容）、 `violation` （违反特定的实例规则） 或某些 `other` （其它）原因。默认为 `other`。若提供了 `rule_ids[]`，则将设置为 `violation`（无论你实际提供了何种类别）。 + +rule_ids[] +: 字符串数组。对于 `violation` 类别举报，指定所违反的确切规则的 ID。规则及其 ID 可通过 [GET /api/v1/instance/rules]({{< relref "methods/instance#rules" >}}) 和 [GET /api/v1/instance]({{< relref "methods/instance#get" >}}) 获得。有关更多信息，请参见 [处理和排序 ID]({{< relref "api/guidelines/#id" >}})。 + +#### 响应 +##### 200: OK + +提供了一个嘟文 ID 和一个类别为 `spam`，并带有评论的示例调用 + +```json +{ + "id": "48914", + "action_taken": false, + "action_taken_at": null, + "category": "spam", + "comment": "Spam account", + "forwarded": false, + "created_at": "2022-08-25T09:56:16.763Z", + "status_ids": [ + "108882889550545820" + ], + "rule_ids": null, + "target_account": { + "id": "108366849347798387", + "username": "Baluke", + "acct": "Baluke", + "display_name": "Baluke Dental Studios", + "locked": false, + "bot": false, + "discoverable": false, + "group": false, + "created_at": "2022-05-26T00:00:00.000Z", + "note": "

Baluke Dental Studios is a full service dental lab offering fabrication, staining, and digital services. Advanced technologies and a meticulous process ensure reduced chair time, lower costs, and better patient outcomes with beautiful smiles. Talk to a representative today.

https://baluke.com/

", + "url": "https://mastodon.social/@Baluke", + "avatar": "https://files.mastodon.social/accounts/avatars/108/366/849/347/798/387/original/dbcfe99ed5def0f4.png", + "avatar_static": "https://files.mastodon.social/accounts/avatars/108/366/849/347/798/387/original/dbcfe99ed5def0f4.png", + "header": "https://static-cdn.mastodon.social/headers/original/missing.png", + "header_static": "https://static-cdn.mastodon.social/headers/original/missing.png", + "followers_count": 0, + "following_count": 0, + "statuses_count": 38, + "last_status_at": "2022-08-25", + "emojis": [], + "fields": [] + } +} +``` + +##### 401: Unauthorized + +无效或缺失的授权标头 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +举报未提交。 + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +令牌没有授权用户 + +```json +{ + "error": "This method requires an authenticated user" +} +``` + +或者，`category` 设置为 `violation`，但提供了无效或缺失的 `rule_ids` + +```json +{ + "error": "Validation failed: Rule ids does not reference valid rules" +} +``` + +或者（Mastodon 3.5），`category` 设置为 `violation` 之外的其他内容，但提供了一些 `rule_ids` + +```json +{ + "error": "Validation failed: Rule ids must be blank" +} +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/reports_controller.rb" caption="app/controllers/api/v1/reports_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="reports API methods" raw_link="/methods/reports/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/scheduled_statuses.md b/content/zh-cn/methods/scheduled_statuses.md new file mode 100644 index 0000000..582046a --- /dev/null +++ b/content/zh-cn/methods/scheduled_statuses.md @@ -0,0 +1,298 @@ +--- +title: scheduled_statuses API 方法 +description: 管理计划在未来日期发布的嘟文。 +menu: + docs: + weight: 30 + name: scheduled_statuses + parent: methods-statuses + identifier: methods-scheduled_statuses +aliases: [ + "/methods/scheduled_statuses", + "/api/methods/scheduled_statuses", + "/methods/statuses/scheduled_statuses", +] +--- + + + +## 查看定时嘟文 {#get} + +```http +GET /api/v1/scheduled_statuses HTTP/1.1 +``` + +**返回：** [ScheduledStatus]({{< relref "entities/scheduledstatus" >}}) 数组\ +**OAuth：** 用户令牌 + `read:statuses`\ +**版本历史：**\ +2.7.0 - 添加\ +3.3.0 - 现在可以同时使用 `min_id` 和 `max_id` + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，并附带 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: 字符串。返回的所有结果都将小于此 ID。 事实上设置了结果的上限。 + +since_id +: 字符串。返回的所有结果都将大于此 ID。 事实上设置了结果的下限。 + +min_id +: 字符串。返回与此 ID 相邻且更新的结果。事实上在此 ID 处设置一个游标并向前分页。 + +limit +: 整数。要返回的最大结果数。默认为 20 个嘟文。最多允许 40 个嘟文。 + +#### 响应 +##### 200: OK + +```json +[ + { + "id": "3221", + "scheduled_at": "2019-12-05T12:33:01.000Z", + "params": { + "poll": null, + "text": "test content", + "media_ids": null, + "sensitive": null, + "visibility": null, + "idempotency": null, + "scheduled_at": null, + "spoiler_text": null, + "application_id": 596551, + "in_reply_to_id": null + }, + "media_attachments": [] + } +] +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 查看单条定时嘟文 {#get-one} + +```http +GET /api/v1/scheduled_statuses/:id HTTP/1.1 +``` + +**返回：** [ScheduledStatus]({{< relref "entities/scheduledstatus" >}})\ +**OAuth：** 用户令牌 + `read:statuses`\ +**版本历史：**\ +2.7.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 ScheduledStatus 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，并附带 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{ + "id": "3221", + "scheduled_at": "2019-12-05T12:33:01.000Z", + "params": { + "poll": null, + "text": "test content", + "media_ids": null, + "sensitive": null, + "visibility": null, + "idempotency": null, + "scheduled_at": null, + "spoiler_text": null, + "application_id": 596551, + "in_reply_to_id": null + }, + "media_attachments": [] +} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +该 ScheduledStatus 不属于你或不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 更新定时嘟文的发布时间 {#update} + +```http +PUT /api/v1/scheduled_statuses/:id HTTP/1.1 +``` + +**返回：** [ScheduledStatus]({{< relref "entities/scheduledstatus" >}})\ +**OAuth：** 用户令牌 + `write:statuses`\ +**版本历史：**\ +2.7.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 ScheduledStatus 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，并附带 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +scheduled_at +: 字符串。嘟文将要发布的 [DateTime](/api/datetime-format#datetime)。必须至少在未来 5 分钟之后。 + +#### 响应 +##### 200: OK + +```json +{ + "id": "3221", + "scheduled_at": "2019-12-05T13:33:01.000Z", + "params": { + "poll": null, + "text": "test content", + "media_ids": null, + "sensitive": null, + "visibility": null, + "idempotency": null, + "scheduled_at": null, + "spoiler_text": null, + "application_id": 596551, + "in_reply_to_id": null + }, + "media_attachments": [] +} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +ScheduledStatus 不属于你或不存在 + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +```json +{ + "error": "Validation failed: Scheduled at The scheduled date must be in the future" +} +``` + +--- + +## 撤销定时嘟文 {#cancel} + +```http +DELETE /api/v1/scheduled_statuses/:id HTTP/1.1 +``` + +**返回：** 空\ +**OAuth：** 用户令牌 + `write:statuses`\ +**版本历史：**\ +2.7.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中 ScheduledStatus 的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，并附带 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +该 ScheduledStatus 不属于你或不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 另请参阅 + +{{< page-relref ref="methods/statuses#create" caption="POST /api/v1/statuses (`scheduled_at` 参数)" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/scheduled_statuses_controller.rb" caption="app/controllers/api/v1/scheduled_statuses_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="scheduled_statuses API methods" raw_link="/methods/scheduled_statuses/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/search.md b/content/zh-cn/methods/search.md new file mode 100644 index 0000000..bcafcad --- /dev/null +++ b/content/zh-cn/methods/search.md @@ -0,0 +1,236 @@ +--- +title: search API 方法 +description: 在帐户、嘟文和话题标签中搜索内容。 +menu: + docs: + weight: 60 + name: search + parent: methods + identifier: methods-search +aliases: [ + "/methods/search", + "/api/methods/search", +] +--- + + + +## 执行搜索 {#v2} + +```http +GET /api/v2/search HTTP/1.1 +``` + +**返回：** [Search]({{< relref "entities/Search" >}})\ +**OAuth：** 公开（不带 `resolve` 或 `offset`），或用户令牌 + `read:search`\ +**版本历史：**\ +2.4.1 - 添加，`limit` 硬编码为 5\ +2.8.0 - 添加 `type`、`limit`、`offset`、`min_id`、`max_id`、`account_id`\ +3.0.0 - 添加 `exclude_unreviewed` 参数\ +3.3.0 - `min_id` 和 `max_id` 可以一起使用\ +4.0.0 - 不再需要用户令牌。若没有有效的用户令牌，则无法使用 `resolve` 或 `offset` 参数。 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，并在其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +q +: {{}} 字符串。搜索关键词。 + +type +: 字符串。指定是否仅搜索 `accounts`、`hashtags`、`statuses`。 + +resolve +: 布尔值。仅当 `type` 包含 `accounts` 时相关。若为 `true` 且 (a) 搜索关键词是针对外站帐户（例如，`someaccount@someother.server`），并且 (b) 本站实例不知晓该帐户，则使用 [WebFinger](/spec/webfinger) 尝试在 `someother.server` 解析该帐户。这在较高延迟下提供最佳搜素成功率。若为 `false`，则仅返回实例知晓的帐户。 + +following +: 布尔值。是否仅包括用户正在关注的帐户？默认为 false。 + +account_id +: 字符串。若提供，则仅返回此帐户撰写的嘟文。 + +exclude_unreviewed +: 布尔值。是否过滤掉未经审核的话题标签？默认为 false。在尝试查找热门话题标签时使用 true。 + +max_id +: 字符串。返回的所有结果都将小于此 ID。事实上设置了结果的上限。 + +min_id +: 字符串。返回与此 ID 相邻且更新的结果。事实上在此 ID 处设置一个游标并向前分页。 + +limit +: 整数。每个类型要返回的最大结果数。默认为每个类别 20 个结果。每个类别最多 40 个结果。 + +offset +: 整数。跳过前 n 个结果。 + +#### 响应 +##### 200: OK + +对 "cats" 进行的示例搜索的结果（已截断），limit=2。 + +```json +{ + "accounts": [ + { + "id": "180744", + "username": "catstar", + "acct": "catstar@catgram.jp", + "display_name": "catstar", + // ... + }, + { + "id": "214293", + "username": "catsareweird", + "acct": "catsareweird", + "display_name": "Cats Are Weird", + // ... + } + ], + "statuses": [ + { + "id": "103085519055545958", + "created_at": "2019-11-05T13:23:09.000Z", + // ... + "content": "

cats
cats never change

", + // ... + }, + { + "id": "101068121469614510", + "created_at": "2018-11-14T06:31:48.000Z", + // ... + "spoiler_text": "Cats", + // ... + "content": "

Cats are inherently good at self-care.

#cats

", + // ... + ], + "hashtags": [ + { + "name": "cats", + "url": "https://mastodon.social/tags/cats", + "history": [ + { + "day": "1574553600", + "uses": "10", + "accounts": "9" + }, + // ... + ] + }, + { + "name": "catsofmastodon", + "url": "https://mastodon.social/tags/catsofmastodon", + "history": [ + { + "day": "1574553600", + "uses": "6", + "accounts": "5" + }, + // ... + ] + } + ] +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 执行搜索 (v1) {{%removed%}} {#v1} + +```http +GET /api/v1/search HTTP/1.1 +``` + +**返回：** [Search]({{< relref "entities/Search" >}})，但 `hashtags` 是一个字符串数组，而不是 Tag 数组。\ +**OAuth：** 用户令牌 + `read:search`\ +**版本历史：**\ +1.1 - 添加，`limit` 硬编码为 5\ +1.5.0 - 现在需要身份验证\ +2.4.1 - 弃用，建议使用 [v2 搜索](#v2)\ +2.8.0 - 添加 `limit`、分页和帐户选项\ +3.0.0 - 移除；请改用 [v2 搜索](#v2) + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，并在其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +q +: {{}} 字符串。搜索关键词。 + +type +: 字符串。指定是否仅搜索 `accounts`、`hashtags`、`statuses`。 + +resolve +: 布尔值。是否尝试 WebFinger 查找？默认为 false。 + +account_id +: 字符串。若提供，则仅返回此帐户撰写的嘟文。 + +max_id +: 字符串。返回的所有结果都将小于此 ID。事实上设置了结果的上限。 + +min_id +: 字符串。返回与此 ID 相邻且更新的结果。事实上在此 ID 处设置一个游标并向前分页。 + +limit +: 整数。每个类型要返回的最大结果数。默认为每个类别 20 个结果。每个类别最多 40 个结果。 + +offset +: 整数。搜索结果中的偏移量，用于分页。默认为 0。 + +#### 响应 +##### 200: OK + +v1 搜索已被弃用，因为话题标签作为字符串而不是 Tag 实体返回。 + +```json +{ + "accounts": [...], + "statuses": [...], + "hashtags": ["cats","catsofmastodon"] +} +``` + +##### 401: Unauthorized + +无效或缺失的 Authorization 标头。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 另请参考 + +{{< page-relref ref="methods/accounts#search" caption="GET /api/v1/accounts/search" >}} + +{{< page-relref ref="methods/accounts#lookup" caption="GET /api/v1/accounts/lookup" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v2/search_controller.rb" caption="app/controllers/api/v2/search_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="search API methods" raw_link="/methods/search/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/statuses.md b/content/zh-cn/methods/statuses.md new file mode 100644 index 0000000..70e862e --- /dev/null +++ b/content/zh-cn/methods/statuses.md @@ -0,0 +1,2006 @@ +--- +title: statuses API 方法 +description: 发布、互动和查看有关嘟文的信息。 +menu: + docs: + weight: 30 + name: statuses + parent: methods + identifier: methods-statuses +aliases: [ + "/methods/statuses", + "/api/methods/statuses", +] +--- + + + +## 发布新嘟文 {#create} + +```http +POST /api/v1/statuses HTTP/1.1 +``` + +使用给定的参数发布嘟文。 + +**返回：** [Status]({{}})。当存在 `scheduled_at` 时，返回 [ScheduledStatus]({{}}) 。\ +**OAuth:** 用户 + `write:statuses`\ +**版本历史：**\ +0.0.0 - 添加\ +2.7.0 - 添加 `scheduled_at`\ +2.8.0 - 添加 `poll` + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +Idempotency-Key +: 提供此标头，其中包含任何任意字符串，以防止重复提交相同的嘟文。考虑使用客户端生成的哈希或 UUID。幂等性密钥最多存储 1 小时。 + +##### 表单数据参数 + +status +: {{}} 字符串。嘟文的文本内容。若提供了 `media_ids`，则此参数变为可选。若提供了 `status`，则 `poll` 是可选的。 + +media_ids[] +: {{}} 字符串数组。包含要附加为媒体的附件 ID。若提供了此参数，则 `status` 变为可选，并且不能使用 `poll`。 + +poll[options][] +: {{}} 字符串数组。投票的可能选项。若提供了此参数，则不能使用 `media_ids`，并且必须提供 `poll[expires_in]`。 + +poll[expires_in] +: {{}} 整数。投票应保持开放的持续时间，以秒为单位。若提供了此参数，则不能使用 `media_ids`，并且必须提供 `poll[options]`。 + +poll[multiple] +: 布尔值。是否允许多选？默认为 false。 + +poll[hide_totals] +: 布尔值。是否在投票结束前隐藏投票数？默认为 false。 + +in_reply_to_id +: 字符串。若嘟文为回复，则为被回复嘟文的 ID。 + +sensitive +: 布尔值。是否将嘟文和附加的媒体标记为敏感内容？默认为 false。 + +spoiler_text +: 字符串。在实际内容之前显示的警告或主题文本。嘟文通常被折叠于此字段之后。 + +visibility +: 字符串。将发布的嘟文的可见性设置为 `public`、`unlisted`、`private`、`direct`。 + +language +: 字符串。此嘟文的 ISO 639 语言代码。 + +scheduled_at +: 字符串。嘟文计划发布的 [DateTime]({{}})。提供此参数将导致返回 ScheduledStatus 而不是 Status。必须至少在未来 5 分钟。 + +#### 响应 +##### 200: OK + +嘟文将使用选择的参数发布： + +```json +{ + "id": "103254962155278888", + "created_at": "2019-12-05T11:34:47.196Z", + // ... + "content": "

test content

", + // ... + "application": { + "name": "test app", + "website": null + }, + // ... +} +``` + +若提供 scheduled_at ，则返回 ScheduledStatus： + +```json +{ + "id": "3221", + "scheduled_at": "2019-12-05T12:33:01.000Z", + "params": { + "text": "test content", + "media_ids": null, + "sensitive": null, + "spoiler_text": null, + "visibility": null, + "scheduled_at": null, + "poll": null, + "idempotency": null, + "in_reply_to_id": null, + "application_id": 596551 + }, + "media_attachments": [] +} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +```json +{ + "error": "Validation failed: Text can't be blank" +} +``` + +--- + +## 查看单个嘟文 {#get} + +```http +GET /api/v1/statuses/:id HTTP/1.1 +``` + +获取有关嘟文的信息。 + +**返回：** [Status]({{< relref "entities/status" >}})\ +**OAuth:** 公开嘟文为Public，私有嘟文为用户令牌 + `read:statuses`\ +**版本历史：**\ +0.0.0 - 添加\ +2.7.0 - 公开嘟文不再需要令牌 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的 ID。 + +##### 标头 + +Authorization +: 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{ + "id": "1", + "created_at": "2016-03-16T14:44:31.580Z", + "in_reply_to_id": null, + "in_reply_to_account_id": null, + "sensitive": false, + "spoiler_text": "", + "visibility": "public", + "language": "en", + "uri": "https://mastodon.social/users/Gargron/statuses/1", + "url": "https://mastodon.social/@Gargron/1", + "replies_count": 7, + "reblogs_count": 98, + "favourites_count": 112, + "favourited": false, + "reblogged": false, + "muted": false, + "bookmarked": false, + "content": "

Hello world

", + "reblog": null, + "application": null, + "account": { + "id": "1", + "username": "Gargron", + "acct": "Gargron", + "display_name": "Eugen", + "locked": false, + "bot": false, + "created_at": "2016-03-16T14:34:26.392Z", + "note": "

Developer of Mastodon and administrator of mastodon.social. I post service announcements, development updates, and personal stuff.

", + "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": 320472, + "following_count": 453, + "statuses_count": 61163, + "last_status_at": "2019-12-05T03:03:02.595Z", + "emojis": [], + "fields": [ + { + "name": "Patreon", + "value": "https://www.patreon.com/mastodon", + "verified_at": null + }, + { + "name": "Homepage", + "value": "https://zeonfederated.com", + "verified_at": "2019-07-15T18:29:57.191+00:00" + } + ] + }, + "media_attachments": [], + "mentions": [], + "tags": [], + "emojis": [], + "card": null, + "poll": null +} +``` + +##### 401: Unauthorized + +实例处于 authorized-fetch 模式。 + +```json +{ + "error": "This API requires an authenticated user" +} +``` + +##### 404: Not found + +嘟文不存在或为私有嘟文。 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 查看多个嘟文 {#index} + +```http +GET /api/v1/statuses HTTP/1.1 +``` + +获取有关多条嘟文的信息。 + +**返回：** [Status]({{< relref "entities/status" >}}) 数组\ +**OAuth:** 公开嘟文为公开，私有嘟文为用户令牌 + `read:statuses`\ +**版本历史：**\ +4.3.0 - 添加 + +#### 请求 + +##### 查询参数 + +id[] +: 字符串数组。数据库中嘟文的 ID。 + +##### 标头 + +Authorization +: 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +将返回请求嘟文的 [Status]({{< relref "entities/status" >}}) 记录。若请求的嘟文不存在或无法使用当前凭据访问，则记录数可能少于请求数。 +当不存在 `id=2` 的嘟文时，使用 `id[]=1&id[]=2` 的示例调用返回： + +```json +[ + { + "id": "1", + "created_at": "2016-03-16T14:44:31.580Z", + "in_reply_to_id": null, + "in_reply_to_account_id": null, + "sensitive": false, + "spoiler_text": "", + "visibility": "public", + "language": "en", + "uri": "https://mastodon.social/users/Gargron/statuses/1", + "url": "https://mastodon.social/@Gargron/1", + "replies_count": 7, + "reblogs_count": 98, + "favourites_count": 112, + "favourited": false, + "reblogged": false, + "muted": false, + "bookmarked": false, + "content": "

Hello world

", + "reblog": null, + "application": null, + "account": { + "id": "1", + "username": "Gargron", + "acct": "Gargron", + "display_name": "Eugen", + "locked": false, + "bot": false, + "created_at": "2016-03-16T14:34:26.392Z", + "note": "

Developer of Mastodon and administrator of mastodon.social. I post service announcements, development updates, and personal stuff.

", + "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": 320472, + "following_count": 453, + "statuses_count": 61163, + "last_status_at": "2019-12-05T03:03:02.595Z", + "emojis": [], + "fields": [ + { + "name": "Patreon", + "value": "https://www.patreon.com/mastodon", + "verified_at": null + }, + { + "name": "Homepage", + "value": "https://zeonfederated.com", + "verified_at": "2019-07-15T18:29:57.191+00:00" + } + ] + }, + "media_attachments": [], + "mentions": [], + "tags": [], + "emojis": [], + "card": null, + "poll": null + } +] +``` + +##### 401: Unauthorized + +实例处于 authorized-fetch 模式。 + +```json +{ + "error": "This API requires an authenticated user" +} +``` + +--- + +## 删除嘟文 {#delete} + +```http +DELETE /api/v1/statuses/:id HTTP/1.1 +``` + +删除你自己的某条嘟文。 + +**返回：** 具有源文本 `text` 以及 `poll` 或 `media_attachments` 的 [Status]({{< relref "entities/status" >}})\ +**OAuth:** 用户令牌 + `write:statuses`\ +**版本历史：**\ +0.0.0 - 添加\ +2.9.0 - 返回源属性，用于删除和重新编辑\ +4.4.0 ( `mastodon` [API 版本]({{< relref "entities/Instance#api-versions" >}}) 4) - 添加 `delete_media` 可选参数 + +#### 请求 + +##### 查询参数 + +delete_media +: 布尔值。是否立即删除嘟文的媒体附件。若省略或为 `false`，则媒体附件可能会保留大约 24 小时，以便可以在新嘟文中重复使用。 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +注意特殊属性 `text` 和 `poll` 或 `media_attachments`，它们可用于重新发布嘟文，例如，在删除和重新编辑功能的情况下。使用 [POST /api/v1/statuses](#create)，并使用 `text` 作为 `status` 参数的值， `media_attachments[n]["id"]` 作为 `media_ids` 数组参数，以及具有相应参数的 `poll` 属性（例如 `poll[multiple]` 和 `poll[options]`，每个用户输入都有一个新的 `poll[expires_in]` 和 `poll[hide_totals]`）。 + +删除带媒体附件的嘟文的示例： + +```json +{ + "id": "103254193998341330", + "created_at": "2019-12-05T08:19:26.052Z", + "in_reply_to_id": null, + "in_reply_to_account_id": null, + "sensitive": false, + "spoiler_text": "", + "visibility": "public", + "language": "en", + "uri": "https://mastodon.social/users/trwnh/statuses/103254193998341330", + "url": "https://mastodon.social/@trwnh/103254193998341330", + "replies_count": 0, + "reblogs_count": 0, + "favourites_count": 0, + "favourited": false, + "reblogged": false, + "muted": false, + "bookmarked": false, + "pinned": false, + "text": "test", + "reblog": null, + "application": { + "name": "Web", + "website": null + }, + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + // ... + }, + "media_attachments": [ + { + "id": "22345792", + "type": "image", + "url": "https://files.mastodon.social/media_attachments/files/022/345/792/original/57859aede991da25.jpeg", + "preview_url": "https://files.mastodon.social/media_attachments/files/022/345/792/small/57859aede991da25.jpeg", + "remote_url": null, + "text_url": "https://mastodon.social/media/2N4uvkuUtPVrkZGysms", + "meta": { + "original": { + "width": 640, + "height": 480, + "size": "640x480", + "aspect": 1.3333333333333333 + }, + "small": { + "width": 461, + "height": 346, + "size": "461x346", + "aspect": 1.3323699421965318 + }, + "focus": { + "x": -0.27, + "y": 0.51 + } + }, + "description": "test media description", + "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}" + } + ], + "mentions": [], + "tags": [], + "emojis": [], + "card": null, + "poll": null +} +``` + +删除投票的示例： + +```json +{ + "id": "103254222827484720", + "created_at": "2019-12-05T08:26:45.958Z", + "in_reply_to_id": null, + "in_reply_to_account_id": null, + "sensitive": false, + "spoiler_text": "", + "visibility": "public", + "language": "en", + "uri": "https://mastodon.social/users/trwnh/statuses/103254222827484720", + "url": "https://mastodon.social/@trwnh/103254222827484720", + "replies_count": 0, + "reblogs_count": 0, + "favourites_count": 0, + "favourited": false, + "reblogged": false, + "muted": false, + "bookmarked": false, + "pinned": false, + "text": "test", + "reblog": null, + "application": { + "name": "Web", + "website": null + }, + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + // ... + }, + "media_attachments": [], + "mentions": [], + "tags": [], + "emojis": [], + "card": null, + "poll": { + "id": "34858", + "expires_at": "2019-12-06T08:26:45.945Z", + "expired": false, + "multiple": false, + "votes_count": 1, + "voters_count": 1, + "voted": true, + "own_votes": [], + "options": [ + { + "title": "test 1", + "votes_count": 1 + }, + { + "title": "test 2", + "votes_count": 0 + } + ], + "emojis": [] + } +} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +该嘟文不属于你或不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 获取上下文中上级嘟文和子嘟文 {#context} + +```http +GET /api/v1/statuses/:id/context HTTP/1.1 +``` + +查看此嘟文在嘟文串中的上下嘟文。 + +**返回：** [Context]({{< relref "entities/context" >}})\ +**OAuth:** 对于公开嘟文，限制为 40 个祖先和 60 个后代，最大深度为 20。对于用户令牌 + `read:statuses`，最多遍历 4,096 个祖先、4,096 个后代、无限深度和私有嘟文。\ +**版本历史：**\ +0.0.0 - 添加 +4.0.0 - 限制未经身份验证的请求 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的 ID。 + +##### 标头 + +Authorization +: 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{ + "ancestors": [ + { + "id": "103188938570975982", + "created_at": "2019-11-23T19:44:00.124Z", + "in_reply_to_id": null, + "in_reply_to_account_id": null, + // ... + }, + { + "id": "103188971072973252", + "created_at": "2019-11-23T19:52:23.398Z", + "in_reply_to_id": "103188938570975982", + "in_reply_to_account_id": "634458", + // ... + }, + { + "id": "103188982235527758", + "created_at": "2019-11-23T19:55:08.208Z", + "in_reply_to_id": "103188971072973252", + "in_reply_to_account_id": "14715", + // ... + } + ], + "descendants": [ + { + "id": "103189026958574542", + "created_at": "2019-11-23T20:06:36.011Z", + "in_reply_to_id": "103189005915505698", + "in_reply_to_account_id": "634458", + // ... + } + ] +} +``` + +##### 404: Not found + +嘟文是私有的或不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 翻译嘟文 {#translate} + +```http +POST /api/v1/statuses/:id/translate HTTP/1.1 +``` + +将嘟文内容翻译成某种语言。 + +**返回：** [Translation]({{< relref "entities/translation" >}})\ +**OAuth:** 应用令牌 + `read:statuses`\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的 ID。 + +##### 表单数据参数 + +lang +: 字符串（ISO 639 语言代码）。嘟文内容将被翻译成此语言。默认为用户的当前语言设置。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +将西班牙语的具有内容警告和媒体的嘟文翻译成英语 + +```json +{ + "content": "

Hello world

", + "spoiler_text": "Greatings ahead", + "media_attachments": [ + { + "id": 22345792, + "description": "Status author waving at the camera" + } + ], + "poll": null, + "detected_source_language": "es", + "provider": "DeepL.com" +} +``` + +将带有投票的嘟文翻译成英语 + +```json +{ + "content": "

Should I stay or should I go?

", + "spoiler_text": null, + "media_attachments": [], + "poll": [ + { + "id": 34858, + "options": [ + { + "title": "Stay" + }, + { + "title": "Go" + } + ] + } + ], + "detected_source_language": "ja", + "provider": "DeepL.com" +} +``` + +##### 404: Not found + +嘟文是私有的或不存在 + +```json +{ + "error": "Record not found" +} +``` + +##### 503: 服务不可用 + +翻译请求失败 + +```json +{ + "error": "Service Unavailable" +} +``` + +--- + +## 查看谁转发了嘟文 {#reblogged_by} + +```http +GET /api/v1/statuses/:id/reblogged_by HTTP/1.1 +``` + +查看谁转发了给定的嘟文。 + +**返回：** [Account]({{< relref "entities/account" >}}) 数组\ +**OAuth:** 可以公开查询公开嘟文。私有嘟文为用户令牌 + `read:statuses`。 +**版本历史：**\ +0.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的 ID。 + +##### 标头 + +Authorization +: 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +since_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +limit +: 整数。要返回的最大结果数。默认为 40 个帐户。最多 80 个帐户。 + +#### 响应 +##### 200: OK + +转发嘟文的帐户列表 + +```json +[ + { + "id": "711345", + "username": "Norman_Doors", + "acct": "Norman_Doors@witches.live", + // ... + }, + // ... +] +``` + +由于通常无法提前知道转发嘟文 ID，因此你必须解析 HTTP `Link` 标头才能加载较旧或较新的结果。有关更多信息，请参见[通过 API 响应进行分页]({{}})。 + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 404: Not found + +嘟文不存在或为私有嘟文 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 查看谁喜欢了嘟文 {#favourited_by} + +```http +GET /api/v1/statuses/:id/favourited_by HTTP/1.1 +``` + +查看谁喜欢了给定的嘟文。 + +**返回：** [Account]({{< relref "entities/account" >}}) 数组\ +**OAuth:** 可以公开查询公开嘟文。对私有嘟文为用户令牌 + `read:statuses`。\ +**版本历史：**\ +0.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的 ID。 + +##### 标头 + +Authorization +: 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +since_id +: **内部参数。** 使用 HTTP `Link` 标头进行分页。 + +limit +: 整数。要返回的最大结果数。默认为 40 个帐户。最多 80 个帐户。 + +#### 响应 +##### 200: OK + +喜欢嘟文的帐户列表 + +```json +[ + { + "id": "828600", + "username": "fructose_dealer", + "acct": "fructose_dealer@radical.town", + // ... + }, + // ... +] +``` + +由于喜欢 ID 通常不会通过任何 API 响应公开，因此你必须解析 HTTP `Link` 标头才能加载较旧或较新的结果。有关更多信息，请参见[通过 API 响应进行分页]({{}})。 + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 404: Not found + +嘟文不存在或为私有嘟文 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 喜欢嘟文 {#favourite} + +```http +POST /api/v1/statuses/:id/favourite HTTP/1.1 +``` + +将嘟文添加到你的喜欢列表。 + +**返回：** [Status]({{< relref "entities/status" >}})\ +**OAuth:** 用户令牌 + `write:favourites`\ +**版本历史：**\ +0.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，其中包含 `Bearer `，以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +已成功发送喜欢或嘟文已被你喜欢 + +```json +{ + "id": "99734435964706331", + "created_at": "2018-03-23T17:38:40.700Z", + // ... + "favourited": true, + "reblogged": false, + "muted": false, + "bookmarked": false, + "pinned": false, + // ... +} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not Found + +嘟文不存在或为私密嘟文 + +```json +{ + "error": "记录未找到" +} +``` + +--- + +## 取消喜欢一条嘟文 {#unfavourite} + +```http +POST /api/v1/statuses/:id/unfavourite HTTP/1.1 +``` + +从喜欢列表中移除一条嘟文。 + +**返回值：** [Staus]({{< relref "entities/status" >}})\ +**OAuth:** 用户令牌 + `write:favourites`\ +**版本历史：**\ +0.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的ID。 + +##### 标头 + +Authorization +: {{}} 使用 `Bearer ` 提供此标头以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +已取消喜欢嘟文或嘟文已不在喜欢列表中 + +```json +{ + "id": "99734435964706331", + "created_at": "2018-03-23T17:38:40.700Z", + // ... + "favourited": false, + "reblogged": false, + "muted": false, + "bookmarked": false, + "pinned": false, + // ... +} +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "访问令牌无效" +} +``` + +##### 404: Not Found + +嘟文不存在或为私密嘟文 + +```json +{ + "error": "记录未找到" +} +``` + +--- + +## 转发一条嘟文 {#boost} + +```http +POST /api/v1/statuses/:id/reblog HTTP/1.1 +``` + +在你的账户上分享一条嘟文。 + +**返回值：** [Staus]({{< relref "entities/status" >}})\ +**OAuth:** 用户令牌 + `write:statuses`\ +**版本历史：**\ +0.0.0 - 添加\ +2.8.0 - 新增 `visibility` 参数 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的ID。 + +##### 标头 + +Authorization +: {{}} 使用 `Bearer ` 提供此标头以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +visibility +: 字符串。嘟文的可见性，除 `limited` 或 `direct` 之外均可（即 `public`、`unlisted`、`private`）。默认值为 public。目前在 UI 中未使用。 + +#### 响应 +##### 200: OK + +嘟文已被转发。请注意，顶层 ID 已更改。被转发嘟文的 ID 现在在 `reblog` 属性中。顶层 ID 是转嘟本身的 ID。还要注意，转发的嘟文不能被置顶。 + +```json +{ + "id": "103254401326800919", + "created_at": "2019-12-05T09:12:09.625Z", + // ... + "favourited": false, + "reblogged": true, + "muted": false, + "bookmarked": false, + // ... + "reblog": { + "id": "99734435964706331", + "created_at": "2018-03-23T17:38:40.700Z", + // ... + "favourited": false, + "reblogged": true, + "muted": false, + "bookmarked": false, + "pinned": false, + // ... + }, + // ... +} +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "访问令牌无效" +} +``` + +##### 404: Not Found + +嘟文不存在或为私密嘟文 + +```json +{ + "error": "记录未找到" +} +``` + +--- + +## 取消转发一条嘟文 {#unreblog} + +```http +POST /api/v1/statuses/:id/unreblog HTTP/1.1 +``` + +取消重新分享一条嘟文。 + +**返回值：** [Staus]({{< relref "entities/status" >}})\ +**OAuth:** 用户令牌 + `write:statuses`\ +**版本历史：**\ +0.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的ID。 + +##### 标头 + +Authorization +: {{}} 使用 `Bearer ` 提供此标头以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +嘟文已取消转发或本就未被转发 + +```json +{ + "id": "99734435964706331", + "created_at": "2018-03-23T17:38:40.700Z", + // ... + "favourited": false, + "reblogged": false, + "muted": false, + "bookmarked": false, + "pinned": false, + // ... +} +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "访问令牌无效" +} +``` + +##### 404: Not Found + +嘟文不存在或为私密嘟文 + +```json +{ + "error": "记录未找到" +} +``` + +--- + +## 将嘟文添加到书签 {#bookmark} + +```http +POST /api/v1/statuses/:id/bookmark HTTP/1.1 +``` + +私密地喜欢一条嘟文。 + +**返回值：** [Staus]({{< relref "entities/status" >}})\ +**OAuth:** 用户令牌 + `write:bookmarks`\ +**版本历史：**\ +3.1.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的ID。 + +##### 标头 + +Authorization +: {{}} 使用 `Bearer ` 提供此标头以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +嘟文已被添加到书签或本就已被添加到书签 + +```json +{ + "id": "99734435964706331", + "created_at": "2018-03-23T17:38:40.700Z", + // ... + "favourited": false, + "reblogged": false, + "muted": false, + "bookmarked": true, + "pinned": false, + // ... +} +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "访问令牌无效" +} +``` + +--- + +## 从书签中移除嘟文 {#unbookmark} + +```http +POST /api/v1/statuses/:id/unbookmark HTTP/1.1 +``` + +从书签中移除一条嘟文。 + +**返回值：** [Staus]({{< relref "entities/status" >}})\ +**OAuth:** 用户令牌 + `write:bookmarks`\ +**版本历史：**\ +3.1.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的ID。 + +##### 标头 + +Authorization +: {{}} 使用 `Bearer ` 提供此标头以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +嘟文已从书签中移除或本就未在书签中 + +```json +{ + "id": "99734435964706331", + "created_at": "2018-03-23T17:38:40.700Z", + // ... + "favourited": false, + "reblogged": false, + "muted": false, + "bookmarked": false, + "pinned": false, + // ... +} +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "访问令牌无效" +} +``` + +##### 404: Not Found + +嘟文不存在或为私密嘟文。 + +```json +{ + "error": "记录未找到" +} +``` + +--- + +## 隐藏一个会话的通知 {#mute} + +```http +POST /api/v1/statuses/:id/mute HTTP/1.1 +``` + +不接收此嘟文所属的嘟文串的通知。目标嘟文串必须是你参与讨论的嘟文串。 + +**返回值：** [Staus]({{< relref "entities/status" >}})\ +**OAuth:** 用户令牌 + `write:mutes`\ +**版本历史：**\ +1.4.2 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的ID。 + +##### 标头 + +Authorization +: {{}} 使用 `Bearer ` 提供此标头以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +以隐藏对应会话的通知，或该对话的通知本就已被隐藏 + +```json +{ + "id": "99734435964706331", + "created_at": "2018-03-23T17:38:40.700Z", + // ... + "favourited": false, + "reblogged": false, + "muted": true, + "bookmarked": false, + "pinned": false, + // ... +} +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "访问令牌无效" +} +``` + +##### 404: Not Found + +嘟文不存在或为私密嘟文。 + +```json +{ + "error": "记录未找到" +} +``` + +--- + +## 取消隐藏会话通知 {#unmute} + +```http +POST /api/v1/statuses/:id/unmute HTTP/1.1 +``` + +重新开始接收此嘟文所属的嘟文串的通知。 + +**返回值：** [Staus]({{< relref "entities/status" >}})\ +**OAuth:** 用户令牌 + `write:mutes`\ +**版本历史：**\ +1.4.2 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的ID。 + +##### 标头 + +Authorization +: {{}} 使用 `Bearer ` 提供此标头以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +已取消隐藏对应会话的通知，或该对话的通知本就未被隐藏 + +```json +{ + "id": "99734435964706331", + "created_at": "2018-03-23T17:38:40.700Z", + // ... + "favourited": false, + "reblogged": false, + "muted": false, + "bookmarked": false, + "pinned": false, + // ... +} +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "访问令牌无效" +} +``` + +##### 404: Not Found + +嘟文不存在或为私密嘟文。 + +```json +{ + "error": "记录未找到" +} +``` + +--- + +## 将嘟文在账户页置顶 {#pin} + +```http +POST /api/v1/statuses/:id/pin HTTP/1.1 +``` + +将你的一条公开嘟文在账户页置顶。 + +**返回值：** [Staus]({{< relref "entities/status" >}})\ +**OAuth:** 用户令牌 + `write:accounts`\ +**版本历史：**\ +1.6.0 - 添加\ +3.5.0 - 现在可以置顶私密嘟文 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的本地ID。嘟文应由授权账户所撰写。 + +##### 标头 + +Authorization +: {{}} 使用 `Bearer ` 提供此标头以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +嘟文已置顶。注意，该嘟文不是转发，并且其作者账户是你自己的。 + +```json +{ + "id": "99734435964706331", + "created_at": "2018-03-23T17:38:40.700Z", + // ... + "favourited": false, + "reblogged": false, + "muted": false, + "bookmarked": false, + "pinned": true, + // ... + "reblog": null, + // ... + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + // ... + }, + // ... +} +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not Found + +嘟文不存在或为私密嘟文。 + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +嘟文不属于你： + +```json +{ + "error": "Validation failed: Someone else's post cannot be pinned" +} +``` + +在3.5.0之前，你不能置顶私密嘟文，因为私密嘟文无法从远程网站获取，且必须被递送。（3.5.0增加了一种机制，可以代表账户获取嘟文。） + +```json +{ + "error": "Validation failed: Non-public toot cannot be pinned" +} +``` + +--- + +## 从账户页取消置顶嘟文 {#unpin} + +```http +POST /api/v1/statuses/:id/unpin HTTP/1.1 +``` + +将某个嘟文从你的账户页取消置顶。 + +**返回值：** [Staus]({{< relref "entities/status" >}})\ +**OAuth:** 用户令牌 + `write:accounts`\ +**版本历史：**\ +1.6.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的本地ID。 + +##### 标头 + +Authorization +: {{}} 使用 `Bearer ` 提供此标头以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +嘟文已被取消置顶或本就未被置顶 + +```json +{ + "id": "99734435964706331", + "created_at": "2018-03-23T17:38:40.700Z", + // ... + "favourited": false, + "reblogged": false, + "muted": false, + "bookmarked": false, + "pinned": false, + // ... + "reblog": null, + // ... + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + // ... + }, + // ... +} +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "访问令牌无效" +} +``` + +##### 404: Not Found + +嘟文不存在或为私密嘟文。 + +```json +{ + "error": "记录未找到" +} +``` + +--- + +## 编辑一条嘟文 {#edit} + +```http +PUT /api/v1/statuses/:id HTTP/1.1 +``` + +编辑给定的嘟文以更改其文本、敏感性、媒体附件或投票。请注意，编辑投票选项会重置投票。 + +**返回值：** [Staus]({{< relref "entities/status" >}})\ +**OAuth:** 用户令牌 + `write:statuses`\ +**版本历史：**\ +3.5.0 - 添加\ +4.0.0 - 新增 `language` + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的ID。 + +##### 标头 + +Authorization +: {{}} 使用 `Bearer ` 提供此标头以获得对此 API 方法的访问授权。 + +##### 表单数据参数 + +status +: 字符串。嘟文的纯文本内容。 + +spoiler_text +: 字符串。嘟文的主题或内容警告的纯文本。 + +sensitive +: 布尔值。嘟文是否应标记为敏感。 + +language +: 字符串。嘟文的 ISO 639 语言代码。 + +media_ids[] +: 字符串数组。包含要作为媒体附加的附件 ID。若提供，`status` 变为可选，`poll` 则不能使用。 + +media_attributes[][] +: 字符串数组。每个数组包括 id、description 和 focus。 + +poll[options][] +: 字符串数组。投票的可能选项。若提供，则不能使用 `media_ids`，并且必须提供 `poll[expires_in]`。 + +poll[expires_in] +: 整数。投票开放的时长，以秒为单位。若提供，则不能使用 `media_ids`，并且必须提供 `poll[options]`。 + +poll[multiple] +: 布尔值。允许多选？默认为 false。 + +poll[hide_totals] +: 布尔值。是否在投票结束前隐藏票数？默认为 false。 + +#### 响应 +##### 200: OK + +嘟文已成功编辑。 + +```json +{ + "id": "108942703571991143", + "created_at": "2022-09-04T23:22:13.704Z", + "in_reply_to_id": null, + "in_reply_to_account_id": null, + "sensitive": false, + "spoiler_text": "", + "visibility": "public", + "language": "en", + "uri": "https://mastodon.social/users/trwnh/statuses/108942703571991143", + "url": "https://mastodon.social/@trwnh/108942703571991143", + "replies_count": 3, + "reblogs_count": 1, + "favourites_count": 6, + "edited_at": "2022-09-05T00:33:20.309Z", + "favourited": false, + "reblogged": false, + "muted": false, + "bookmarked": false, + "pinned": false, + "content": "

this is a status that has been edited multiple times to change the text, add a poll, and change poll options.

", + "filtered": [], + "reblog": null, + "application": { + "name": "SubwayTooter", + "website": null + }, + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + // ... + }, + "media_attachments": [], + "mentions": [], + "tags": [], + "emojis": [], + "card": null, + "poll": null +} +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not Found + +嘟文不存在、私密或不属于你。 + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +```json +{ + "error": "Validation failed: Text can't be blank" +} +``` + +--- + +## 查看嘟文的编辑历史 {#history} + +```http +GET /api/v1/statuses/:id/history HTTP/1.1 +``` + +获取一条嘟文的所有已知版本，包括初始版本和当前嘟文。 + +**返回值：** [StatusEdit]({{< relref "entities/statusedit" >}}) 数组\ +**OAuth:** 可公开查询公开嘟文，对私密嘟文则要求用户令牌 + `read:statuses`\ +**版本历史：**\ +3.5.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的本地ID。 + +##### 标头 + +Authorization +: 使用 `Bearer ` 提供此标头以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +[ + { + "content": "

this is a status that will be edited

", + "spoiler_text": "", + "sensitive": false, + "created_at": "2022-09-04T23:22:13.704Z", + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + // ... + }, + "media_attachments": [], + "emojis": [] + }, + { + "content": "

this is a status that has been edited

", + "spoiler_text": "", + "sensitive": false, + "created_at": "2022-09-04T23:22:42.555Z", + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + // ... + }, + "media_attachments": [], + "emojis": [] + }, + { + "content": "

this is a status that has been edited twice

", + "spoiler_text": "", + "sensitive": false, + "created_at": "2022-09-04T23:22:55.956Z", + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + // ... + }, + "media_attachments": [], + "emojis": [] + }, + { + "content": "

this is a status that has been edited three times. this time a poll has been added.

", + "spoiler_text": "", + "sensitive": false, + "created_at": "2022-09-05T00:01:48.160Z", + "poll": { + "options": [ + { + "title": "cool" + }, + { + "title": "uncool" + }, + { + "title": "spiderman" + } + ] + }, + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + // ... + }, + "media_attachments": [], + "emojis": [] + }, + { + "content": "

this is a status that has been edited three times. this time a poll has been added.

", + "spoiler_text": "", + "sensitive": false, + "created_at": "2022-09-05T00:03:32.480Z", + "poll": { + "options": [ + { + "title": "cool" + }, + { + "title": "uncool" + }, + { + "title": "spiderman (this option has been changed)" + } + ] + }, + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + // ... + }, + "media_attachments": [], + "emojis": [] + } +] +``` + +##### 404: Not Found + +嘟文不存在或为私密嘟文。 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 查看嘟文源文本 {#source} + +```http +GET /api/v1/statuses/:id/source HTTP/1.1 +``` + +获取嘟文的源属性以便编辑。 + +**返回值：** [StatusSource]({{< relref "entities/statussource" >}})\ +**OAuth:** 应用程序令牌 + `read:statuses`\ +**版本历史：**\ +3.5.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的本地ID。 + +##### 标头 + +Authorization +: 使用 `Bearer ` 提供此标头以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{ + "id": "108942703571991143", + "text": "this is a status that will be edited", + "spoiler_text": "" +} +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not Found + +嘟文不存在或为私密嘟文。 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 获取预览卡片 {{%deprecated%}} {#card} + +```http +GET /api/v1/statuses/:id/card HTTP/1.1 +``` + +**返回值：** [PreviewCard]({{< relref "entities/PreviewCard" >}})\ +**OAuth:** 可公开查询公开嘟文，对私密嘟文则要求用户令牌 + `read:statuses`\ +**版本历史：**\ +0.0.0 - 添加\ +2.6.0 - 弃用，推荐使用嘟文实体中的 card 属性\ +3.0.0 - 移除 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。数据库中嘟文的本地ID。 + +##### 标头 + +Authorization +: 使用 `Bearer ` 提供此标头以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{ + "url": "https://www.youtube.com/watch?v=OMv_EPMED8Y", + "title": "♪ Brand New Friend (Christmas Song!)", + "description": "", + "type": "video", + "author_name": "YOGSCAST Lewis & Simon", + "author_url": "https://www.youtube.com/user/BlueXephos", + "provider_name": "YouTube", + "provider_url": "https://www.youtube.com/", + "html": "", + "width": 480, + "height": 270, + "image": "https://files.mastodon.social/preview_cards/images/014/179/145/original/9cf4b7cf5567b569.jpeg", + "embed_url": "" +} +``` + +##### 404: Not Found + +嘟文不存在或为私密嘟文。 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 另请参阅 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses_controller.rb" caption="app/controllers/api/v1/statuses_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/bookmarks_controller.rb" caption="app/controllers/api/v1/statuses/bookmarks_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/favourited_by_accounts_controller.rb" caption="app/controllers/api/v1/statuses/favourited_by_accounts_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/favourites_controller.rb" caption="app/controllers/api/v1/statuses/favourites_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/histories_controller.rb" caption="app/controllers/api/v1/statuses/histories_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/mutes_controller.rb" caption="app/controllers/api/v1/statuses/mutes_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/pins_controller.rb" caption="app/controllers/api/v1/statuses/pins_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/reblogged_by_accounts_controller.rb" caption="app/controllers/api/v1/statuses/reblogged_by_accounts_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/reblogs_controller.rb" caption="app/controllers/api/v1/statuses/reblogs_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/sources_controller.rb" caption="app/controllers/api/v1/statuses/sources_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="statuses API methods" raw_link="/methods/statuses/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/streaming.md b/content/zh-cn/methods/streaming.md new file mode 100644 index 0000000..c30150e --- /dev/null +++ b/content/zh-cn/methods/streaming.md @@ -0,0 +1,733 @@ +--- +title: streaming API 方法 +description: >- + 通过 HTTP 长连接或 WebSocket 订阅实例发送的事件，以获取实时更新。 +menu: + docs: + weight: 40 + name: streaming + parent: methods-timelines + identifier: methods-streaming +aliases: [ + "/methods/streaming", + "/api/methods/streaming", + "/methods/timelines/streaming", +] +--- + + + +## 事件类型和有效载荷 {#events} + +`update` +: 出现了一条新的嘟文。有效载荷包含一个被转换为字符串的 [Status]({{< relref "entities/Status" >}})。自 v1.0.0 起可用。 + +`delete` +: 嘟文已被删除。有效载荷包含已删除嘟文的字符串 ID。自 v1.0.0 起可用。 + +`notification` +: 出现了一条新的通知。有效载荷包含一个被转换为字符串的 [Notification]({{< relref "entities/Notification" >}})。自 v1.4.2 起可用。 + +`filters_changed` +: 关键词过滤规则已更改。要么不包含有效载荷（对于 WebSocket 连接），要么包含未定义的有效载荷（对于 HTTP 连接）。自 v2.4.3 起可用。 + +`conversation` +: 私信已更新。有效载荷包含一个被转换为字符串的 [Conversation]({{< relref "entities/Conversation" >}})。自 v2.6.0 起可用。 + +`announcement` +: 已发布公告。有效载荷包含一个被转换为字符串的 [Announcement]({{< relref "entities/Announcement" >}})。自 v3.1.0 起可用。 + +`announcement.reaction` +: 公告已收到表情回应。有效载荷包含一个哈希值（带有 `name`、`count` 和 `announcement_id`），并转换为字符串。自 v3.1.0 起可用。 + +`announcement.delete` +: 公告已被删除。有效载荷包含已删除公告的字符串 ID。自 v3.1.0 起可用。 + +`status.update` +: 嘟文已被编辑。有效载荷包含一个被转换为字符串的 [Status]({{< relref "entities/Status" >}})。自 v3.5.0 起可用。 + +`encrypted_message` +: 已收到加密消息。在 v3.2.0 中实现，但当前未使用。 + +`notifications_merged` +: 接受的通知请求已完成合并，应刷新通知列表。可以忽略有效载荷。自 v4.3.0 起可用。 + +## Streaming 时间线/类别 {#streams} + +`public` +: 实例已知的所有公开嘟文。类似于跨站时间线。自 v1.0.0 起可用。 + +`public:media` +: 实例已知的所有公开嘟文，已筛选出带媒体附件的嘟文。类似于启用了“仅媒体”的跨站时间线。自 v2.4.0 起可用。 + +`public:local` +: 来自此实例的所有公开嘟文。类似于本站时间线。自 v1.1 起可用。 + +`public:local:media` +: 来自此实例的所有公开嘟文，已筛选出带媒体附件的嘟文。类似于启用了“仅媒体”的本站时间线。自 v2.4.0 起可用。 + +`public:remote` +: 来自其他实例的所有公开嘟文。自 v3.1.4 起可用。 + +`public:remote:media` +: 来自其他实例的所有公开嘟文，已筛选出带媒体附件的嘟文。自 v3.1.4 起可用。 + +`hashtag` +: 所有使用特定话题标签的公开嘟文。自 v1.0.0 起可用。 + +`hashtag:local` +: 所有使用特定话题标签的公开嘟文，来自此实例。自 v1.1 起可用。 + +`user` +: 与当前用户相关的事件，例如主页嘟文更新和通知。自 v1.0.0 起可用。 + +`user:notification` +: 当前用户的通知。自 v1.4.2 起可用。 + +`list` +: 特定列表的更新。自 v2.1.0 起可用。 + +`direct` +: 私信的更新。自 v2.4.0 起可用。 + +--- + +## 关于 HTTP 实例发送事件 {#http} + +你的应用可以使用 [服务端发送事件](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) 端点来接收实时更新。服务端发送事件是一种极其简单的传输方法，完全依赖于分块编码传输；换句话说，HTTP 连接保持打开状态并定期接收新数据。 + +数据流流将包含事件以及心跳注释。解析器可以忽略以冒号 (`:`) 开头的行。例如，可以使用心跳注释来保持连接处于活动状态： + +```text +:thump +``` + +通常，事件具有以下结构： + +```text +event: +data: +``` + +--- + +## 检查服务端是否在线 {#health} + +```http +GET /api/v1/streaming/health HTTP/1.1 +``` + +在连接到流服务之前，验证它是否在线。 + +**返回：** 字符串\ +**OAuth：** 公开\ +**版本历史：**\ +2.5.0 - 新增 + +#### 响应 +##### 200: OK + +流式服务端在线 + +```text +OK +``` + +--- + +## 监测你的主页时间线和通知 {#user} + +```http +GET /api/v1/streaming/user HTTP/1.1 +``` + +返回与授权用户相关的事件，即主页时间线和通知 + +**返回：** `update`、`delete`、`notification`、`filters_changed`、`announcement`、`announcement.reaction`、`announcement.delete`、`status.update`\ +**OAuth：** 用户令牌 + `read:statuses` + `read:notifications`\ +**版本历史：**\ +1.0.0 - 新增\ +1.4.2 - 现在还会返回 `notification`\ +2.4.3 - 现在还会返回 `filters_changed`\ +3.1.0 - 现在还会返回 `announcement`、`announcement.reaction`、`announcement.delete`\ +3.5.0 - 现在还会返回 `status.update` + + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供带有 `Bearer ` 的标头，以获得对此 API 方法的访问授权。 + +#### 事件 + +主页时间线的更新示例： + +```text +event: update +data: {"id":"108914327388663283","created_at":"2022-08-30T23:05:46.839Z","in_reply_to_id":"108914298452377720","in_reply_to_account_id":"107946650784398271","sensitive":false,"spoiler_text":"","visibility":"unlisted","language":null,"uri":"https://letsalllovela.in/objects/e9cebb0c-7c75-414f-9608-20b5628e52d7","url":"https://letsalllovela.in/objects/e9cebb0c-7c75-414f-9608-20b5628e52d7","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"favourited":false,"reblogged":false,"muted":false,"bookmarked":false,"content":"@disarray glad i was able to help","filtered":[],"reblog":null,"account":{"id":"464472","username":"freon","acct":"freon@letsalllovela.in","display_name":"freon","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2018-08-18T00:00:00.000Z","note":"tech archaeologist, unix weenie
#nobot","url":"https://letsalllovela.in/users/freon","avatar":"https://files.mastodon.social/cache/accounts/avatars/000/464/472/original/bfc518d70cf6f13a.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/000/464/472/original/bfc518d70cf6f13a.png","header":"https://files.mastodon.social/cache/accounts/headers/000/464/472/original/2e94bd33745f86a6.gif","header_static":"https://files.mastodon.social/cache/accounts/headers/000/464/472/static/2e94bd33745f86a6.png","followers_count":37,"following_count":41,"statuses_count":18442,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"pronouns","value":"emacs/xemacs (or he/they)","verified_at":null},{"name":"age","value":"23.66667","verified_at":null}]},"media_attachments":[],"mentions":[{"id":"107946650784398271","username":"disarray","url":"https://pl.nulled.red/users/disarray","acct":"disarray@pl.nulled.red"}],"tags":[],"emojis":[],"card":null,"poll":null} +``` + +通知示例： + +```text +event: notification +data: {"id":"68739215","type":"mention","created_at":"2022-08-30T23:09:54.070Z","account":{"id":"108892712797543112","username":"a","acct":"a@pl.nulled.red","display_name":"a","locked":false,"bot":true,"discoverable":false,"group":false,"created_at":"2022-08-27T00:00:00.000Z","note":"a (pleroma edition)","url":"https://pl.nulled.red/users/a","avatar":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/5396d516ae170bb0.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/5396d516ae170bb0.png","header":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","header_static":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","followers_count":0,"following_count":0,"statuses_count":12,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"mastodon","value":"@trwnh@mastodon.social","verified_at":null}]},"status":{"id":"108914343542683797","created_at":"2022-08-30T23:09:52.359Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"unlisted","language":null,"uri":"https://pl.nulled.red/objects/64b196c6-3bc5-44d5-8ffb-f760235ee6ca","url":"https://pl.nulled.red/objects/64b196c6-3bc5-44d5-8ffb-f760235ee6ca","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"favourited":false,"reblogged":false,"muted":false,"bookmarked":false,"content":"@trwnh test","filtered":[],"reblog":null,"account":{"id":"108892712797543112","username":"a","acct":"a@pl.nulled.red","display_name":"a","locked":false,"bot":true,"discoverable":false,"group":false,"created_at":"2022-08-27T00:00:00.000Z","note":"a (pleroma edition)","url":"https://pl.nulled.red/users/a","avatar":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/5396d516ae170bb0.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/5396d516ae170bb0.png","header":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","header_static":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","followers_count":0,"following_count":0,"statuses_count":12,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"mastodon","value":"@trwnh@mastodon.social","verified_at":null}]},"media_attachments":[],"mentions":[{"id":"14715","username":"trwnh","url":"https://mastodon.social/@trwnh","acct":"trwnh"}],"tags":[],"emojis":[],"card":null,"poll":null}} +``` + +过滤规则修改的示例： + +```text +event: filters_changed +data: undefined +``` + +公告示例： + +```text +event: announcement +data: {"id":"1","content":"

test

","starts_at":null,"ends_at":null,"all_day":true,"published_at":"2022-11-15T15:55:22.452Z","updated_at":"2022-11-15T15:55:22.528Z","mentions":[],"statuses":[],"tags":[],"emojis":[],"reactions":[]} +``` + +公告回应示例： + +```text +event: announcement.reaction +data: {"name":"🤔","count":1,"announcement_id":"1"} +``` + +公告删除示例： + +```text +event: announcement.delete +data: 1 +``` + +嘟文被编辑的示例： + +```text +event: status.update +data: {"id":"109348677773283527","created_at":"2022-11-15T16:06:48.410Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"http://mastodon.local/users/admin/statuses/109348677773283527","url":"http://mastodon.local/@admin/109348677773283527","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":"2022-11-15T16:07:29.023Z","content":"

edited

","reblog":null,"application":{"name":"Web","website":null},"account":{"id":"109334860508022726","username":"admin","acct":"admin","display_name":"","locked":false,"bot":false,"discoverable":null,"group":false,"created_at":"2022-11-13T00:00:00.000Z","note":"","url":"http://mastodon.local/@admin","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":4,"last_status_at":"2022-11-15","noindex":false,"emojis":[],"fields":[]},"media_attachments":[],"mentions":[],"tags":[],"emojis":[],"card":null,"poll":null,"favourited":false,"reblogged":false,"muted":false,"bookmarked":false,"pinned":false,"filtered":[]} +``` + +--- + +## 监测你的通知 {#notification} + +```http +GET /api/v1/streaming/user/notification HTTP/1.1 +``` + +返回收到的通知的事件 + +**返回：** `notification`\ +**OAuth：** 用户令牌 + `read:statuses` + `read:notifications`\ +**版本历史：**\ +1.4.2 - 新增 + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供带有 `Bearer ` 的标头，以获得对此 API 方法的访问授权。 + +#### 事件 + +通知示例： + +```text +event: notification +data: {"id":"68739215","type":"mention","created_at":"2022-08-30T23:09:54.070Z","account":{"id":"108892712797543112","username":"a","acct":"a@pl.nulled.red","display_name":"a","locked":false,"bot":true,"discoverable":false,"group":false,"created_at":"2022-08-27T00:00:00.000Z","note":"a (pleroma edition)","url":"https://pl.nulled.red/users/a","avatar":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/5396d516ae170bb0.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/5396d516ae170bb0.png","header":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","header_static":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","followers_count":0,"following_count":0,"statuses_count":12,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"mastodon","value":"@trwnh@mastodon.social","verified_at":null}]},"status":{"id":"108914343542683797","created_at":"2022-08-30T23:09:52.359Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"unlisted","language":null,"uri":"https://pl.nulled.red/objects/64b196c6-3bc5-44d5-8ffb-f760235ee6ca","url":"https://pl.nulled.red/objects/64b196c6-3bc5-44d5-8ffb-f760235ee6ca","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"favourited":false,"reblogged":false,"muted":false,"bookmarked":false,"content":"@trwnh test","filtered":[],"reblog":null,"account":{"id":"108892712797543112","username":"a","acct":"a@pl.nulled.red","display_name":"a","locked":false,"bot":true,"discoverable":false,"group":false,"created_at":"2022-08-27T00:00:00.000Z","note":"a (pleroma edition)","url":"https://pl.nulled.red/users/a","avatar":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/5396d516ae170bb0.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/5396d516ae170bb0.png","header":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","header_static":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","followers_count":0,"following_count":0,"statuses_count":12,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"mastodon","value":"@trwnh@mastodon.social","verified_at":null}]},"media_attachments":[],"mentions":[{"id":"14715","username":"trwnh","url":"https://mastodon.social/@trwnh","acct":"trwnh"}],"tags":[],"emojis":[],"card":null,"poll":null}} +``` + +--- + +## 监测跨站时间线 {#public} + +```http +GET /api/v1/streaming/public HTTP/1.1 +``` + +返回所有公开嘟文 + +**返回：** `update`、`delete`、`status.update`\ +**OAuth：** 用户令牌 + `read:statuses`\ +**版本历史：**\ +1.0.0 - 新增\ +2.4.0 - 添加 `only_media` 参数\ +3.5.0 - 现在返回 `status.update` +4.2.0 - 已更改为需要用户令牌，移除公开和应用令牌访问 [#23989](https://github.com/mastodon/mastodon/pull/23989) + +#### 请求 +##### 标头 + +Authorization +: 提供带有 `Bearer ` 的标头，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +only_media +: 布尔值。若为 true，则仅返回带有媒体附件的嘟文。 + +#### 事件 + +跨站时间线的更新示例： + +```text +event: update +data: {"id":"108914354907984653","created_at":"2022-08-30T23:12:47.000Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://mstdn.jp/users/aiueohisama/statuses/108914354891945610","url":"https://mstdn.jp/@aiueohisama/108914354891945610","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"content":"

処女の子が「処女だからキモい絡み方しちゃうかもだけど許して🥺」なんて言ってるのわたしは見たことない、童貞の甘えだよそれは 嫌われたくないなら最低限のマナーくらい身につけた方がいい

","reblog":null,"account":{"id":"272619","username":"aiueohisama","acct":"aiueohisama@mstdn.jp","display_name":"💎🌻陽菜💙💛","locked":false,"bot":false,"discoverable":false,"group":false,"created_at":"2017-04-15T00:00:00.000Z","note":"

とっても素直で真面目なOLでし！

","url":"https://mstdn.jp/@aiueohisama","avatar":"https://files.mastodon.social/cache/accounts/avatars/000/272/619/original/573669a325c87b8b.jpeg","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/000/272/619/original/573669a325c87b8b.jpeg","header":"https://files.mastodon.social/cache/accounts/headers/000/272/619/original/5d5dad59a9fd1531.jpeg","header_static":"https://files.mastodon.social/cache/accounts/headers/000/272/619/original/5d5dad59a9fd1531.jpeg","followers_count":182,"following_count":20,"statuses_count":1128,"last_status_at":"2022-08-30","emojis":[],"fields":[]},"media_attachments":[],"mentions":[],"tags":[],"emojis":[],"card":null,"poll":null,"filter_results":[]} +``` + +删除示例： + +```text +event: delete +data: 107214471804101576 +``` + +嘟文被编辑的示例： + +```text +event: status.update +data: {"id":"109348684737626801","created_at":"2022-11-15T16:08:30.000Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://ruby.social/users/chrismo/statuses/109348684454557541","url":"https://ruby.social/@chrismo/109348684454557541","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":"2022-11-15T16:10:43.000Z","content":"

#musicTuesday

Here's a solo #piano track of mine called Gravity Assist

#neoclassical (#jazz ish)

https://cstudios.bandcamp.com/track/celestia-gravity-assist-no-19-var-2

","reblog":null,"account":{"id":"795442","username":"chrismo","acct":"chrismo@ruby.social","display_name":"chrismo","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2019-04-25T00:00:00.000Z","note":"

i mash keys

","url":"https://ruby.social/@chrismo","avatar":"https://files.mastodon.social/cache/accounts/avatars/000/795/442/original/12084217a7eb7513.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/000/795/442/original/12084217a7eb7513.png","header":"https://static-cdn.mastodon.social/headers/original/missing.png","header_static":"https://static-cdn.mastodon.social/headers/original/missing.png","followers_count":40,"following_count":62,"statuses_count":42,"last_status_at":"2022-11-15","emojis":[],"fields":[{"name":"web","value":"clabs.org","verified_at":null},{"name":"github","value":"github.com/chrismo","verified_at":null},{"name":"twitter","value":"twitter.com/the_chrismo","verified_at":null},{"name":"bandcamp","value":"cstudios.bandcamp.com","verified_at":null}]},"media_attachments":[],"mentions":[],"tags":[{"name":"MUSICTUESDAY","url":"https://mastodon.social/tags/MUSICTUESDAY"},{"name":"piano","url":"https://mastodon.social/tags/piano"},{"name":"neoclassical","url":"https://mastodon.social/tags/neoclassical"},{"name":"jazz","url":"https://mastodon.social/tags/jazz"}],"emojis":[],"card":null,"poll":null} +``` + +--- + +## 监测本站时间线 {#public-local} + +```http +GET /api/v1/streaming/public/local HTTP/1.1 +``` + +返回所有本站公开嘟文 + +**返回：** `update`、`delete`、`status.update`\ +**OAuth：** 用户令牌 + `read:statuses`\ +**版本历史：**\ +1.1.0 - 新增\ +2.4.0 - 添加 `only_media` 参数\ +3.5.0 - 现在返回 `status.update` +4.2.0 - 已更改为需要用户令牌，移除公开和应用令牌访问 [#23989](https://github.com/mastodon/mastodon/pull/23989) + +#### 请求 +##### 标头 + +Authorization +: 提供带有 `Bearer ` 的标头，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +only_media +: 布尔值。若为 true，则仅返回带有媒体附件的嘟文。 + +#### 事件 + +本站时间线的一个更新示例如下： + +```text +event: update +data: {"id":"108914398911648589","created_at":"2022-08-30T23:23:58.863Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://mastodon.social/users/trwnh/statuses/108914398911648589","url":"https://mastodon.social/@trwnh/108914398911648589","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"content":"

test

","reblog":null,"application":{"name":"Web","website":null},"account":{"id":"14715","username":"trwnh","acct":"trwnh","display_name":"infinite love ⴳ","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2016-11-24T00:00:00.000Z","note":"

i have approximate knowledge of many things. perpetual student. (nb/ace/they)

xmpp/email: a@trwnh.com
https://trwnh.com
help me live: https://liberapay.com/trwnh or paypal

- my triggers are moths and glitter
- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise
- dm me if i did something wrong, so i can improve
- purest person on fedi, do not lewd in my presence

","url":"https://mastodon.social/@trwnh","avatar":"https://files.mastodon.social/accounts/avatars/000/014/715/original/e430cc93d56f5ac2.png","avatar_static":"https://files.mastodon.social/accounts/avatars/000/014/715/original/e430cc93d56f5ac2.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":2520,"following_count":266,"statuses_count":59817,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"Website","value":"https://trwnh.com","verified_at":"2019-08-29T04:14:55.571+00:00"},{"name":"Portfolio","value":"https://abdullahtarawneh.com","verified_at":"2021-02-11T20:34:13.574+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":"What to expect:","value":"talking about various things i find interesting, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people! and to spill my thoughts.","verified_at":null}]},"media_attachments":[],"mentions":[],"tags":[],"emojis":[],"card":null,"poll":null} +``` + +一个删除的示例如下： + +```text +event: delete +data: 108914398911648589 +``` + +一个嘟文编辑事件的示例如下： + +``` +event: status.update +data: {"id":"109348699525106378","created_at":"2022-11-15T16:12:20.310Z","in_reply_to_id":"109348674754176227","in_reply_to_account_id":"30437","sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://mastodon.social/users/gregpak/statuses/109348699525106378","url":"https://mastodon.social/@gregpak/109348699525106378","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":"2022-11-15T16:12:41.694Z","content":"

By default, in Feedly it just shows a thumbnail of the images in a post, though. And NetNewsWire doesn't show any image, boo! Gotta find an RSS reader that'll show a full sized image automatically without requiring a clickthrough... any suggestions would be very welcome, thanks!

","reblog":null,"account":{"id":"30437","username":"gregpak","acct":"gregpak","display_name":"Greg Pak","locked":false,"bot":false,"discoverable":false,"group":false,"created_at":"2017-04-02T00:00:00.000Z","note":"

Comic book writer & filmmaker. Mech Cadet Yu, Planet Hulk, Darth Vader, Ronin Island, Princess Who Saved. Get vaxxed, get out the vote. He/Him.
#Comics #ComicBooks #writing #AmWriting #photography #BelieveInFilm

","url":"https://mastodon.social/@gregpak","avatar":"https://files.mastodon.social/accounts/avatars/000/030/437/original/9a71f06d6e285f32.jpg","avatar_static":"https://files.mastodon.social/accounts/avatars/000/030/437/original/9a71f06d6e285f32.jpg","header":"https://files.mastodon.social/accounts/headers/000/030/437/original/1f589d01e13340bc.jpg","header_static":"https://files.mastodon.social/accounts/headers/000/030/437/original/1f589d01e13340bc.jpg","followers_count":2307,"following_count":279,"statuses_count":818,"last_status_at":"2022-11-15","noindex":false,"emojis":[],"fields":[{"name":"Website/Blog","value":"https://gregpak.com/","verified_at":"2022-11-04T19:59:52.817+00:00"},{"name":"Newsletter","value":"https://gregpak.com/newsletter","verified_at":"2022-11-04T19:59:58.287+00:00"},{"name":"Shop","value":"https://gregpakshop.com/pages/about-us","verified_at":"2022-11-07T05:50:02.310+00:00"}]},"media_attachments":[],"mentions":[],"tags":[],"emojis":[],"card":null,"poll":null} +``` + +--- + +## 监测外站嘟文 {#public-remote} + +```http +GET /api/v1/streaming/public/remote HTTP/1.1 +``` + +返回来自外站实例的所有公开嘟文。 + +**返回：** `update`、`delete`、`status.update`\ +**OAuth：** 用户令牌 + `read:statuses`\ +**版本历史：**\ +3.1.4 - 已添加\ +3.5.0 - 现在返回 `status.update` +4.2.0 - 更改为需要用户令牌，移除了公开和应用令牌访问 [#23989](https://github.com/mastodon/mastodon/pull/23989) + +#### 请求 +##### 标头 + +Authorization +: 提供此标头以及 `Bearer `，以获得对此 API 方法的授权访问。 + +##### 查询参数 + +only_media +: 布尔值。如果为true，则只返回包含媒体附件的嘟文。 + +#### 事件 + +一个更新的示例如下： + +```text +event: update +data: {"id":"108914354907984653","created_at":"2022-08-30T23:12:47.000Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://mstdn.jp/users/aiueohisama/statuses/108914354891945610","url":"https://mstdn.jp/@aiueohisama/108914354891945610","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"content":"

処女の子が「処女だからキモい絡み方しちゃうかもだけど許して🥺」なんて言ってるのわたしは見たことない、童貞の甘えだよそれは 嫌われたくないなら最低限のマナーくらい身につけた方がいい

","reblog":null,"account":{"id":"272619","username":"aiueohisama","acct":"aiueohisama@mstdn.jp","display_name":"💎🌻陽菜💙💛","locked":false,"bot":false,"discoverable":false,"group":false,"created_at":"2017-04-15T00:00:00.000Z","note":"

とっても素直で真面目なOLでし！

","url":"https://mstdn.jp/@aiueohisama","avatar":"https://files.mastodon.social/cache/accounts/avatars/000/272/619/original/573669a325c87b8b.jpeg","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/000/272/619/original/573669a325c87b8b.jpeg","header":"https://files.mastodon.social/cache/accounts/headers/000/272/619/original/5d5dad59a9fd1531.jpeg","header_static":"https://files.mastodon.social/cache/accounts/headers/000/272/619/original/5d5dad59a9fd1531.jpeg","followers_count":182,"following_count":20,"statuses_count":1128,"last_status_at":"2022-08-30","emojis":[],"fields":[]},"media_attachments":[],"mentions":[],"tags":[],"emojis":[],"card":null,"poll":null,"filter_results":[]} +``` + +一个删除的示例如下： + +```text +event: delete +data: 107214471804101576 +``` + +一个嘟文编辑事件的示例如下： + +```text +event: status.update +data: {"id":"109348684737626801","created_at":"2022-11-15T16:08:30.000Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://ruby.social/users/chrismo/statuses/109348684454557541","url":"https://ruby.social/@chrismo/109348684454557541","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":"2022-11-15T16:10:43.000Z","content":"

#musicTuesday

Here's a solo #piano track of mine called Gravity Assist

#neoclassical (#jazz ish)

https://cstudios.bandcamp.com/track/celestia-gravity-assist-no-19-var-2

","reblog":null,"account":{"id":"795442","username":"chrismo","acct":"chrismo@ruby.social","display_name":"chrismo","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2019-04-25T00:00:00.000Z","note":"

i mash keys

","url":"https://ruby.social/@chrismo","avatar":"https://files.mastodon.social/cache/accounts/avatars/000/795/442/original/12084217a7eb7513.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/000/795/442/original/12084217a7eb7513.png","header":"https://static-cdn.mastodon.social/headers/original/missing.png","header_static":"https://static-cdn.mastodon.social/headers/original/missing.png","followers_count":40,"following_count":62,"statuses_count":42,"last_status_at":"2022-11-15","emojis":[],"fields":[{"name":"web","value":"clabs.org","verified_at":null},{"name":"github","value":"github.com/chrismo","verified_at":null},{"name":"twitter","value":"twitter.com/the_chrismo","verified_at":null},{"name":"bandcamp","value":"cstudios.bandcamp.com","verified_at":null}]},"media_attachments":[],"mentions":[],"tags":[{"name":"MUSICTUESDAY","url":"https://mastodon.social/tags/MUSICTUESDAY"},{"name":"piano","url":"https://mastodon.social/tags/piano"},{"name":"neoclassical","url":"https://mastodon.social/tags/neoclassical"},{"name":"jazz","url":"https://mastodon.social/tags/jazz"}],"emojis":[],"card":null,"poll":null} +``` + +--- + +## 监测特定话题标签的公共时间线 {#hashtag} + +```http +GET /api/v1/streaming/hashtag HTTP/1.1 +``` + +返回特定话题标签的所有公开嘟文。 + +**返回：** `update`、`delete`、`status.update`\ +**OAuth：** 用户令牌 + `read:statuses`\ +**版本历史：**\ +1.0.0 - 已添加\ +3.5.0 - 现在返回 `status.update` +4.2.0 - 更改为需要用户令牌，移除了公开和应用令牌访问 [#23989](https://github.com/mastodon/mastodon/pull/23989) + +#### 请求 +##### 标头 + +Authorization +: 提供此标头以及 `Bearer `，以获得对此 API 方法的授权访问。 + +##### 查询参数 + +tag +: {{}} 字符串。要监测的话题标签的名称。 + +#### 事件 + +话题标签时间线的一个更新示例如下： + +```text +event: update +data: {"id":"108914430312582020","created_at":"2022-08-30T23:31:58.006Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://mastodon.social/users/trwnh/statuses/108914430312582020","url":"https://mastodon.social/@trwnh/108914430312582020","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"content":"

#test

","reblog":null,"application":{"name":"Web","website":null},"account":{"id":"14715","username":"trwnh","acct":"trwnh","display_name":"infinite love ⴳ","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2016-11-24T00:00:00.000Z","note":"

i have approximate knowledge of many things. perpetual student. (nb/ace/they)

xmpp/email: a@trwnh.com
https://trwnh.com
help me live: https://liberapay.com/trwnh or paypal

- my triggers are moths and glitter
- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise
- dm me if i did something wrong, so i can improve
- purest person on fedi, do not lewd in my presence

","url":"https://mastodon.social/@trwnh","avatar":"https://files.mastodon.social/accounts/avatars/000/014/715/original/e430cc93d56f5ac2.png","avatar_static":"https://files.mastodon.social/accounts/avatars/000/014/715/original/e430cc93d56f5ac2.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":2520,"following_count":266,"statuses_count":59817,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"Website","value":"https://trwnh.com","verified_at":"2019-08-29T04:14:55.571+00:00"},{"name":"Portfolio","value":"https://abdullahtarawneh.com","verified_at":"2021-02-11T20:34:13.574+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":"What to expect:","value":"talking about various things i find interesting, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people! and to spill my thoughts.","verified_at":null}]},"media_attachments":[],"mentions":[],"tags":[{"name":"test","url":"https://mastodon.social/tags/test"}],"emojis":[],"card":null,"poll":null} +``` + +一个删除的示例如下： + +```text +event: delete +data: 108914430312582020 +``` + +一个嘟文编辑事件的示例如下： + +```text +event: status.update +data: {"id":"109348684737626801","created_at":"2022-11-15T16:08:30.000Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://ruby.social/users/chrismo/statuses/109348684454557541","url":"https://ruby.social/@chrismo/109348684454557541","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":"2022-11-15T16:10:43.000Z","content":"

#musicTuesday

Here's a solo #piano track of mine called Gravity Assist

#neoclassical (#jazz ish)

https://cstudios.bandcamp.com/track/celestia-gravity-assist-no-19-var-2

","reblog":null,"account":{"id":"795442","username":"chrismo","acct":"chrismo@ruby.social","display_name":"chrismo","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2019-04-25T00:00:00.000Z","note":"

i mash keys

","url":"https://ruby.social/@chrismo","avatar":"https://files.mastodon.social/cache/accounts/avatars/000/795/442/original/12084217a7eb7513.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/000/795/442/original/12084217a7eb7513.png","header":"https://static-cdn.mastodon.social/headers/original/missing.png","header_static":"https://static-cdn.mastodon.social/headers/original/missing.png","followers_count":40,"following_count":62,"statuses_count":42,"last_status_at":"2022-11-15","emojis":[],"fields":[{"name":"web","value":"clabs.org","verified_at":null},{"name":"github","value":"github.com/chrismo","verified_at":null},{"name":"twitter","value":"twitter.com/the_chrismo","verified_at":null},{"name":"bandcamp","value":"cstudios.bandcamp.com","verified_at":null}]},"media_attachments":[],"mentions":[],"tags":[{"name":"MUSICTUESDAY","url":"https://mastodon.social/tags/MUSICTUESDAY"},{"name":"piano","url":"https://mastodon.social/tags/piano"},{"name":"neoclassical","url":"https://mastodon.social/tags/neoclassical"},{"name":"jazz","url":"https://mastodon.social/tags/jazz"}],"emojis":[],"card":null,"poll":null} +``` + +--- + +## 监测本站时间线中特定的话题标签 {#hashtag-local} + +```http +GET /api/v1/streaming/hashtag/local HTTP/1.1 +``` + +返回特定话题标签的所有本站公开嘟文。 + +**返回：** `update`、`delete`、`status.update`\ +**OAuth：** 用户令牌 + `read:statuses`\ +**版本历史：**\ +1.1.0 - 已添加\ +3.5.0 - 现在返回 `status.update` +4.2.0 - 更改为需要用户令牌，移除了公开和应用令牌访问 [#23989](https://github.com/mastodon/mastodon/pull/23989) + +#### 请求 +##### 标头 + +Authorization +: 提供此标头以及 `Bearer `，以获得对此 API 方法的授权访问。 + +##### 查询参数 + +tag +: {{}} 字符串。要监测的话题标签的名称。 + +#### 事件 + +本站话题标签时间线的一个更新示例如下： + +```text +event: update +data: {"id":"108914430312582020","created_at":"2022-08-30T23:31:58.006Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://mastodon.social/users/trwnh/statuses/108914430312582020","url":"https://mastodon.social/@trwnh/108914430312582020","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"content":"

#test

","reblog":null,"application":{"name":"Web","website":null},"account":{"id":"14715","username":"trwnh","acct":"trwnh","display_name":"infinite love ⴳ","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2016-11-24T00:00:00.000Z","note":"

i have approximate knowledge of many things. perpetual student. (nb/ace/they)

xmpp/email: a@trwnh.com
https://trwnh.com
help me live: https://liberapay.com/trwnh or paypal

- my triggers are moths and glitter
- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise
- dm me if i did something wrong, so i can improve
- purest person on fedi, do not lewd in my presence

","url":"https://mastodon.social/@trwnh","avatar":"https://files.mastodon.social/accounts/avatars/000/014/715/original/e430cc93d56f5ac2.png","avatar_static":"https://files.mastodon.social/accounts/avatars/000/014/715/original/e430cc93d56f5ac2.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":2520,"following_count":266,"statuses_count":59817,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"Website","value":"https://trwnh.com","verified_at":"2019-08-29T04:14:55.571+00:00"},{"name":"Portfolio","value":"https://abdullahtarawneh.com","verified_at":"2021-02-11T20:34:13.574+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":"What to expect:","value":"talking about various things i find interesting, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people! and to spill my thoughts.","verified_at":null}]},"media_attachments":[],"mentions":[],"tags":[{"name":"test","url":"https://mastodon.social/tags/test"}],"emojis":[],"card":null,"poll":null} +``` + +一个删除事件的示例： + +```text +event: delete +data: 108914430312582020 +``` + +一个嘟文编辑事件的示例： + +```text +event: status.update +data: {"id":"108914430312582020","created_at":"2022-08-30T23:32:12.006Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://mastodon.social/users/trwnh/statuses/108914430312582020","url":"https://mastodon.social/@trwnh/108914430312582020","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"content":"

#test but edited

","reblog":null,"application":{"name":"Web","website":null},"account":{"id":"14715","username":"trwnh","acct":"trwnh","display_name":"infinite love ⴳ","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2016-11-24T00:00:00.000Z","note":"

i have approximate knowledge of many things. perpetual student. (nb/ace/they)

xmpp/email: a@trwnh.com
https://trwnh.com
help me live: https://liberapay.com/trwnh or paypal

- my triggers are moths and glitter
- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise
- dm me if i did something wrong, so i can improve
- purest person on fedi, do not lewd in my presence

","url":"https://mastodon.social/@trwnh","avatar":"https://files.mastodon.social/accounts/avatars/000/014/715/original/e430cc93d56f5ac2.png","avatar_static":"https://files.mastodon.social/accounts/avatars/000/014/715/original/e430cc93d56f5ac2.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":2520,"following_count":266,"statuses_count":59817,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"Website","value":"https://trwnh.com","verified_at":"2019-08-29T04:14:55.571+00:00"},{"name":"Portfolio","value":"https://abdullahtarawneh.com","verified_at":"2021-02-11T20:34:13.574+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":"What to expect:","value":"talking about various things i find interesting, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people! and to spill my thoughts.","verified_at":null}]},"media_attachments":[],"mentions":[],"tags":[{"name":"test","url":"https://mastodon.social/tags/test"}],"emojis":[],"card":null,"poll":null} +``` + +--- + +## 监测列表更新 {#list} + +```http +GET /api/v1/streaming/list HTTP/1.1 +``` + +返回列表的嘟文更新 + +**返回：**`update`，`delete`，`status.update`\ +**OAuth：**用户令牌 + `read:statuses`\ +**版本历史：**\ +2.1.0 - 添加\ +3.5.0 - 现在返回 `status.update` +4.2.0 - 更改为需要用户令牌，移除公开和应用程序令牌访问 [#23989](https://github.com/mastodon/mastodon/pull/23989) + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供带有 `Bearer ` 的标头，以获得对此 API 方法的授权访问权限。 + +##### 查询参数 + +list +: {{}} 字符串。 要监测的列表的 ID。 + +#### 事件 + +列表时间线的更新示例： + +```text +event: update +data: {"id":"108914327388663283","created_at":"2022-08-30T23:05:46.839Z","in_reply_to_id":"108914298452377720","in_reply_to_account_id":"107946650784398271","sensitive":false,"spoiler_text":"","visibility":"unlisted","language":null,"uri":"https://letsalllovela.in/objects/e9cebb0c-7c75-414f-9608-20b5628e52d7","url":"https://letsalllovela.in/objects/e9cebb0c-7c75-414f-9608-20b5628e52d7","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"favourited":false,"reblogged":false,"muted":false,"bookmarked":false,"content":"@disarray glad i was able to help","filtered":[],"reblog":null,"account":{"id":"464472","username":"freon","acct":"freon@letsalllovela.in","display_name":"freon","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2018-08-18T00:00:00.000Z","note":"tech archaeologist, unix weenie
#nobot","url":"https://letsalllovela.in/users/freon","avatar":"https://files.mastodon.social/cache/accounts/avatars/000/464/472/original/bfc518d70cf6f13a.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/000/464/472/original/bfc518d70cf6f13a.png","header":"https://files.mastodon.social/cache/accounts/headers/000/464/472/original/2e94bd33745f86a6.gif","header_static":"https://files.mastodon.social/cache/accounts/headers/000/464/472/static/2e94bd33745f86a6.png","followers_count":37,"following_count":41,"statuses_count":18442,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"pronouns","value":"emacs/xemacs (or he/they)","verified_at":null},{"name":"age","value":"23.66667","verified_at":null}]},"media_attachments":[],"mentions":[{"id":"107946650784398271","username":"disarray","url":"https://pl.nulled.red/users/disarray","acct":"disarray@pl.nulled.red"}],"tags":[],"emojis":[],"card":null,"poll":null} +``` + +一个删除事件的示例： + +```text +event: delete +data: 108914398911648589 +``` + +一个嘟文编辑事件的示例： + +```text +event: status.update +data: {"id":"108914327388663283","created_at":"2022-08-30T23:05:53.839Z","in_reply_to_id":"108914298452377720","in_reply_to_account_id":"107946650784398271","sensitive":false,"spoiler_text":"","visibility":"unlisted","language":null,"uri":"https://letsalllovela.in/objects/e9cebb0c-7c75-414f-9608-20b5628e52d7","url":"https://letsalllovela.in/objects/e9cebb0c-7c75-414f-9608-20b5628e52d7","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"favourited":false,"reblogged":false,"muted":false,"bookmarked":false,"content":"@disarray glad i was able to help","filtered":[],"reblog":null,"account":{"id":"464472","username":"freon","acct":"freon@letsalllovela.in","display_name":"freon","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2018-08-18T00:00:00.000Z","note":"tech archaeologist, unix weenie
#nobot","url":"https://letsalllovela.in/users/freon","avatar":"https://files.mastodon.social/cache/accounts/avatars/000/464/472/original/bfc518d70cf6f13a.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/000/464/472/original/bfc518d70cf6f13a.png","header":"https://files.mastodon.social/cache/accounts/headers/000/464/472/original/2e94bd33745f86a6.gif","header_static":"https://files.mastodon.social/cache/accounts/headers/000/464/472/static/2e94bd33745f86a6.png","followers_count":37,"following_count":41,"statuses_count":18442,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"pronouns","value":"emacs/xemacs (or he/they)","verified_at":null},{"name":"age","value":"23.66667","verified_at":null}]},"media_attachments":[],"mentions":[{"id":"107946650784398271","username":"disarray","url":"https://pl.nulled.red/users/disarray","acct":"disarray@pl.nulled.red"}],"tags":[],"emojis":[],"card":null,"poll":null} +``` + +--- + +## 监测私信 {#direct} + +```http +GET /api/v1/streaming/direct HTTP/1.1 +``` + +返回接收到的私信的事件。 + +**返回：** `conversation`\ +**OAuth：**用户令牌 + `read:statuses`\ +**版本历史：**\ +2.4.0 - 添加\ +2.6.0 - 现在返回 `conversation` 而不是 `update` + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供带有 `Bearer ` 的标头，以获得对此 API 方法的授权访问权限。 + +#### 事件 + +#### 事件 + +会话更新的示例： + +```text +event: conversation +data: {"id":"819516","unread":true,"accounts":[{"id":"108892712797543112","username":"a","acct":"a@pl.nulled.red","display_name":"a","locked":false,"bot":true,"discoverable":false,"group":false,"created_at":"2022-08-27T00:00:00.000Z","note":"a (pleroma edition)","url":"https://pl.nulled.red/users/a","avatar":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/975674b2caa61034.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/975674b2caa61034.png","header":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","header_static":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","followers_count":0,"following_count":0,"statuses_count":362,"last_status_at":"2022-11-13","emojis":[],"fields":[]}],"last_status":{"id":"109346889330629417","created_at":"2022-11-15T08:31:57.476Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"direct","language":null,"uri":"https://pl.nulled.red/objects/c869c5be-c184-4706-a45d-3459d9aa711c","url":"https://pl.nulled.red/objects/c869c5be-c184-4706-a45d-3459d9aa711c","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"favourited":false,"reblogged":false,"muted":false,"bookmarked":false,"content":"test @trwnh","filtered":[],"reblog":null,"account":{"id":"108892712797543112","username":"a","acct":"a@pl.nulled.red","display_name":"a","locked":false,"bot":true,"discoverable":false,"group":false,"created_at":"2022-08-27T00:00:00.000Z","note":"a (pleroma edition)","url":"https://pl.nulled.red/users/a","avatar":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/975674b2caa61034.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/975674b2caa61034.png","header":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","header_static":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","followers_count":0,"following_count":0,"statuses_count":362,"last_status_at":"2022-11-13","emojis":[],"fields":[]},"media_attachments":[],"mentions":[{"id":"14715","username":"trwnh","url":"https://mastodon.social/@trwnh","acct":"trwnh"}],"tags":[],"emojis":[],"card":null,"poll":null}} +``` + +--- + +## 建立 WebSocket 连接 {#websocket} + +```http +wss://mastodon.example/api/v1/streaming +``` + +**返回：** [Events](#events)流\ +**OAuth：** 用户令牌 + `read`（或 `read:statuses` 和/或 `read:notifications`）\ +**版本历史：**\ +3.3.0 - 添加 +4.2.0 - 更改为需要用户令牌，移除公开和应用程序令牌访问 [#23989](https://github.com/mastodon/mastodon/pull/23989) + +打开一个多路复用的 WebSocket 连接来接收事件。 + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供带有 `Bearer ` 的标头，以获得对此 API 方法的授权访问权限。 + +##### 参数 + +{{< hint style="info" >}} +建议对单用途连接使用查询参数，但也可以通过 WebSocket 连接发送带有 `type` 参数的 JSON 编码有效负载来提供参数。 + +订阅包含话题标签 `#foo` 的本站嘟文的示例： + +```json +{ "type": "subscribe", "stream": "hashtag:local", "tag": "foo" } +``` + +取消订阅用户更新的示例： + +```json +{ "type": "unsubscribe", "stream": "user" } +``` +{{}} + +access_token +: {{}} 字符串。 用户授权的 OAuth 令牌。 替代 `Authorization` 标头。 + +stream +: {{}} 字符串。 要监测事件的流。 有关可能的值，请参阅 [流](#streams)。 + +list +: 字符串。 当 `stream` 设置为 `list` 时，使用此参数指定列表 ID。 + +tag +: 字符串。 当 `stream` 设置为 `hashtag` 或 `hashtag:local` 时，使用此参数指定标签名称。 + +type +: 字符串。 对于发送到实例的 JSON 编码的有效负载，指定 `subscribe` 或 `unsubscribe` 以管理你希望接收的事件。 + +##### 事件 + +事件采用 JSON 编码。 如果提供了无效的访问令牌，连接将立即关闭。 如果你的实例启用了有限联合模式或授权获取模式，则必须提供访问令牌才能接收事件。 + +公开时间线的更新示例： + +```json +{ + "stream": [ + "public" + ], + "event": "update", + "payload": "{\"id\":\"108913983692647032\",\"created_at\":\"2022-08-30T21:38:22.000Z\",\"in_reply_to_id\":\"108913981098896721\",\"in_reply_to_account_id\":\"1081104\",\"sensitive\":false,\"spoiler_text\":\"\",\"visibility\":\"public\",\"language\":\"en\",\"uri\":\"https://fosstodon.org/users/tobtobxx/statuses/108913983628474640\",\"url\":\"https://fosstodon.org/@tobtobxx/108913983628474640\",\"replies_count\":0,\"reblogs_count\":0,\"favourites_count\":0,\"edited_at\":null,\"content\":\"

And now I can't exit the inner nvim because I mapped escape to the parent vim instance 😂

\",\"reblog\":null,\"account\":{\"id\":\"1081104\",\"username\":\"tobtobxx\",\"acct\":\"tobtobxx@fosstodon.org\",\"display_name\":\"TobTobXX\",\"locked\":false,\"bot\":false,\"discoverable\":true,\"group\":false,\"created_at\":\"2020-01-10T00:00:00.000Z\",\"note\":\"

Young tech enthusiast. Likes software (and also general, just not work-) minimalsim. Constantly trying to escape big-tech software.
Other hobbies include making music, stargazing, math and recently chess, but there's a lot that piques my interest and a lot left to learn out there.

„Of course, every house is constructed by someone, but the one who constructed all things is God.“ (Hebrews 3:4 [nwt18])

\",\"url\":\"https://fosstodon.org/@tobtobxx\",\"avatar\":\"https://files.mastodon.social/cache/accounts/avatars/001/081/104/original/230a8d0fb54e249b.png\",\"avatar_static\":\"https://files.mastodon.social/cache/accounts/avatars/001/081/104/original/230a8d0fb54e249b.png\",\"header\":\"https://static-cdn.mastodon.social/headers/original/missing.png\",\"header_static\":\"https://static-cdn.mastodon.social/headers/original/missing.png\",\"followers_count\":150,\"following_count\":216,\"statuses_count\":2447,\"last_status_at\":\"2022-08-30\",\"emojis\":[],\"fields\":[{\"name\":\"📍 Lives in:\",\"value\":\"Switzerland (CET: UTC+1 or CEST: UTC+2)\",\"verified_at\":null},{\"name\":\"🔑 GPG key:\",\"value\":\"EA23 42C5 3EBF 2A2D 985C 416A 12AC 3D47 52E2 FA2E\",\"verified_at\":null}]},\"media_attachments\":[],\"mentions\":[],\"tags\":[],\"emojis\":[],\"card\":null,\"poll\":null}" +} +``` + +{{< hint style="warning" >}} +请注意，虽然事件是 JSON 编码的，但 `payload` 是按字符串编码和转义的，因此必须从该字符串解析并按 JSON 格式加载。 但是，对于 `delete` 和 `announcements.delete` 事件，有效负载是一个字符串，表示标识符，而不是 JSON 值。 +{{}} + +公共时间线的删除事件示例： + +```json +{ + "stream": [ + "public" + ], + "event": "delete", + "payload": "106692867363994015" +} +``` + +用户更改过滤规则的示例： + +```json +{ + "stream": [ + "user" + ], + "event": "filters_changed" +} +``` + +{{< hint style="warning" >}} +请注意，`filters_changed` 事件不存在 `payload` 属性。 对于 `delete` 和 `announcements.delete`，有效负载是一个字符串，而不是对象。 +{{}} + +## 另请参阅 + +### 流式服务端 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/streaming/index.js" caption="streaming/index.js" >}} + +### 后端事件发布 + +流式时间线在 Redis 中维护，并通过 `redis.publish()` 发布到 Redis。 + +#### 嘟文事件 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/services/fan_out_on_write_service.rb" caption="app/services/fan_out_on_write_service.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/services/remove_status_service.rb" caption="app/services/remove_status_service.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/services/batched_remove_status_service.rb" caption="app/services/batched_remove_status_service.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/push_conversation_worker.rb" caption="app/workers/push_conversation_worker.rb" >}} + +#### 用户事件 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/feed_manager.rb" caption="app/lib/feed_manager.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/push_update_worker.rb" caption="app/workers/push_update_worker.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/services/notify_service.rb" caption="app/services/notify_service.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/custom_filter.rb" caption="app/models/custom_filter.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/publish_scheduled_announcement_worker.rb" caption="app/workers/publish_scheduled_announcement_worker.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/publish_announcement_reaction_worker.rb" caption="app/workers/publish_announcement_reaction_worker.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/unpublish_announcement_worker.rb" caption="app/workers/unpublish_announcement_worker.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/push_encrypted_message_worker.rb" caption="app/workers/push_encrypted_message_worker.rb" >}} + +### 流式客户端 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/javascript/mastodon/stream.js" caption="app/javascript/mastodon/stream.js" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/javascript/mastodon/actions/streaming.js" caption="app/javascript/mastodon/actions/streaming.js" >}} + +{{< translation-status-zh-cn raw_title="streaming API methods" raw_link="/methods/streaming/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} + diff --git a/content/zh-cn/methods/suggestions.md b/content/zh-cn/methods/suggestions.md new file mode 100644 index 0000000..4b442b1 --- /dev/null +++ b/content/zh-cn/methods/suggestions.md @@ -0,0 +1,201 @@ +--- +title: suggestions API 方法 +description: >- + 实例根据之前积极的互动关系生成的关注建议。 +menu: + docs: + weight: 120 + name: suggestions + parent: methods-accounts + identifier: methods-suggestions +aliases: [ + "/methods/suggestions", + "/api/methods/suggestions", + "/methods/accounts/suggestions", +] +--- + + + +## 查看关注建议 (v2) {#v2} + +```http +GET /api/v2/suggestions HTTP/1.1 +``` + +由站点工作人员推荐的，或者用户之前与之有过积极互动但尚未关注的帐户。 + +**返回：**[Suggestion]({{< relref "entities/Suggestion" >}}) 数组\ +**OAuth：**用户令牌 + `read`\ +**版本历史：**\ +3.4.0 - 添加 + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供此标头，并带有 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 查询参数 + +limit +: 整数。要返回的最大结果数。默认为 40 个帐户。最多 80 个帐户。 + +#### 响应 +##### 200: OK + +```json +[ + { + "source": "past_interactions", + "account": { + "id": "784058", + "username": "katie", + "acct": "katie@pleroma.voidlurker.net", + // ... + }, + // ... + { + "source": "global", + "account": { + "id": "108194863260762493", + "username": "thunderbird", + "acct": "thunderbird@mastodon.online", + // ... + } +] +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 移除建议 {#remove} + +```http +DELETE /api/v1/suggestions/:account_id HTTP/1.1 +``` + +从关注建议中移除一个帐户。 + +**返回：**空\ +**OAuth：**用户令牌 + `read`\ +**版本历史：**\ +2.4.3 - 添加 + +#### 请求 + +##### 路径参数 + +:account_id +: {{}} 字符串。数据库中帐户的 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头，并带有 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +成功调用将返回一个空对象。请注意，即使提供的帐户 ID 无效或并非建议的帐户，调用也会成功。 + +```json +{} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 查看关注建议 (v1) {{%deprecated%}} {#v1} + +```http +GET /api/v1/suggestions HTTP/1.1 +``` + +用户过去与之有过积极互动但尚未关注的帐户。 + +**返回：**[Account]({{< relref "entities/Account" >}}) 数组\ +**OAuth：**用户令牌 + `read`\ +**版本历史：**\ +2.4.3 - 添加\ +3.4.0 - 弃用 + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供此标头，并带有 `Bearer ` 以获得对此 API 方法的访问授权。 + +##### 查询参数 + +limit +: 整数。要返回的最大结果数。默认为 40 个帐户。最多 80 个帐户。 + +#### 响应 +##### 200: OK + +```json +[ + { + "id": "332766", + "username": "kaniini", + "acct": "kaniini@pleroma.site", + // ... + }, + { + "id": "689455", + "username": "interneteh", + "acct": "interneteh@sunbeam.city", + // ... + }, + { + "id": "764276", + "username": "Dee", + "acct": "Dee@fedi.underscore.world", + // ... + }, + // ... +] +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 另请参考 + +{{< page-relref ref="methods/accounts#follow" caption="POST /api/v1/accounts/:id/follow" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v2/suggestions_controller.rb" caption="app/controllers/api/v2/suggestions_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/suggestions_controller.rb" caption="app/controllers/api/v1/suggestions_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="suggestions API methods" raw_link="/methods/suggestions/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/tags.md b/content/zh-cn/methods/tags.md new file mode 100644 index 0000000..90c7f8a --- /dev/null +++ b/content/zh-cn/methods/tags.md @@ -0,0 +1,286 @@ +--- +title: tags API 方法 +description: 查看关于话题标签的信息或关注/取消关注话题标签。 +menu: + docs: + weight: 120 + name: tags + parent: methods-accounts + identifier: methods-tags +aliases: [ + "/methods/tags", + "/api/methods/tags", +] +--- + + + +## 查看单个话题标签的信息 {#get} + +```http +GET /api/v1/tags/:id HTTP/1.1 +``` + +显示一个话题标签及其相关信息 + +**返回：** [Tag]({{< relref "entities/Tag" >}})\ +**OAuth：** 公开访问，或要求用户令牌\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。话题标签的名称。 + +##### 标头 + +Authorization +: 提供此标头并附带 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +```json +{ + "name": "Test", + "url": "http://mastodon.example/tags/test", + "history": [ + { + "day": "1668556800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668470400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668384000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668297600", + "accounts": "1", + "uses": "1" + }, + { + "day": "1668211200", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668124800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668038400", + "accounts": "0", + "uses": "0" + } + ], + "following": false +} +``` + +--- + +## 关注一个话题标签 {#follow} + +```http +POST /api/v1/tags/:id/follow HTTP/1.1 +``` + +关注一个话题标签。包含已关注话题标签的嘟文将被插入到你的主页时间线中。 + +**返回：** [Tag]({{< relref "entities/Tag" >}})\ +**OAuth：** 用户令牌 + `write:follows`\ +**版本历史：**\ +4.0.0 - 添加\ +4.1.0 - 此操作现在是幂等的 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。话题标签的名称。 + +##### 标头 + +Authorization +: {{}} 提供此标头并附带 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +已成功关注该话题标签 + +```json +{ + "name": "Test", + "url": "http://mastodon.example/tags/test", + "history": [ + { + "day": "1668556800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668470400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668384000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668297600", + "accounts": "1", + "uses": "1" + }, + { + "day": "1668211200", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668124800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668038400", + "accounts": "0", + "uses": "0" + } + ], + "following": true +} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +在 4.1.0 之前：该话题标签已被关注 + +```json +{ + "error": "Duplicate record" +} +``` + +--- + +## 取消关注一个话题标签 {#unfollow} + +```http +POST /api/v1/tags/:id/unfollow HTTP/1.1 +``` + +取消关注一个话题标签。包含此话题标签的嘟文将不再被插入到你的主页时间线中。 + +**返回：** [Tag]({{< relref "entities/Tag" >}})\ +**OAuth：** 用户令牌 + `write:follows`\ +**版本历史：**\ +4.0.0 - 添加 + +#### 请求 + +##### 路径参数 + +:id +: {{}} 字符串。话题标签的名称。 + +##### 标头 + +Authorization +: {{}} 提供此标头并附带 `Bearer ` 以获得对此 API 方法的访问授权。 + +#### 响应 +##### 200: OK + +已成功取消关注该话题标签，或原本就未关注该话题标签 + +```json +{ + "name": "Test", + "url": "http://mastodon.example/tags/test", + "history": [ + { + "day": "1668556800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668470400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668384000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668297600", + "accounts": "1", + "uses": "1" + }, + { + "day": "1668211200", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668124800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668038400", + "accounts": "0", + "uses": "0" + } + ], + "following": false +} +``` + +##### 401: Unauthorized + +Authorization 标头缺失或无效。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 另请参考 + +{{< page-relref ref="methods/followed_tags#get" caption="GET /api/v1/followed_tags" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/tags_controller.rb" caption="app/controllers/api/v1/tags_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="tags API methods" raw_link="/methods/tags/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/timelines.md b/content/zh-cn/methods/timelines.md new file mode 100644 index 0000000..78b481b --- /dev/null +++ b/content/zh-cn/methods/timelines.md @@ -0,0 +1,508 @@ +--- +title: timelines API方法 +description: 读取和查看嘟文的时间线。 +menu: + docs: + weight: 40 + name: timelines + parent: methods + identifier: methods-timelines +aliases: [ + "/methods/timelines", + "/api/methods/timelines", +] +--- + + + +## 查看公共时间线 {#public} + +```http +GET /api/v1/timelines/public HTTP/1.1 +``` + +查看公开嘟文。 + +**返回：** [Status]({{}}) 数组\ +**OAuth：** 允许公开调用。 若实例已禁用公共预览，则需要应用令牌 + `read:statuses`。\ +**版本历史：**\ +0.0.0 - 添加\ +2.3.0 - 添加 `only_media`\ +2.6.0 - 添加 `min_id`\ +3.0.0 - 若公共预览已禁用，则需要身份验证\ +3.1.4 - 添加 `remote`\ +3.3.0 - 现在可以同时使用 `min_id` 和 `max_id` + +#### 请求 + +##### 标头 + +Authorization +: 提供此标头以及 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +local +: 布尔值。 是否仅显示本站嘟文？ 默认为 false。 + +remote +: 布尔值。 是否仅显示外站嘟文？ 默认为 false。 + +only_media +: 布尔值。 是否仅显示附有媒体的嘟文？ 默认为 false。 + +max_id +: 字符串。 返回的所有结果将小于此 ID。 事实上设置了结果的上限。 + +since_id +: 字符串。 返回的所有结果将大于此 ID。 事实上设置了结果的下限。 + +min_id +: 字符串。 返回与此 ID 相邻且更新的结果。 事实上在此 ID 处设置游标并向前分页。 + +limit +: 整数。 要返回的最大结果数。 默认为 20 个嘟文。 最多 40 个嘟文。 + +#### 响应 +##### 200: OK + +带有 limit=2 的示例 API 调用 + +```json +[ + { + "id": "103206804533200177", + "created_at": "2019-11-26T23:27:31.000Z", + // ... + "visibility": "public", + // ... + }, + { + "id": "103206804086086361", + "created_at": "2019-11-26T23:27:32.000Z", + // ... + "visibility": "public", + // ... + } +] +``` + +--- + +## 查看话题标签时间线 {#tag} + +```http +GET /api/v1/timelines/tag/:hashtag HTTP/1.1 +``` + +查看包含给定话题标签的公开嘟文。 + +**返回：** [Status]({{}}) 数组\ +**OAuth：** 允许公开调用。 若实例已禁用公共预览，则需要应用令牌 + `read:statuses`。\ +**版本历史：**\ +0.0.0 - 添加\ +2.3.0 - 添加 `only_media`\ +2.6.0 - 添加 `min_id`\ +2.7.0 - 为其他标签添加 `any[]`、`all[]`、`none[]`\ +3.0.0 - 若公共预览已禁用，则需要身份验证\ +3.3.0 - 现在可以同时使用 `min_id` 和 `max_id`。 添加 `remote` + +#### 请求 + +##### 路径参数 + +:hashtag +: {{}} 字符串。 话题标签的名称（不包括#符号）。 + +##### 标头 + +Authorization +: 提供此标头以及 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +any[] +: 字符串数组。 返回包含其中**任何一个**话题标签的嘟文。 + +all[] +: 字符串数组。 返回同时包含**所有**话题标签的嘟文。 + +none[] +: 字符串数组。 返回不包含其中**任何一个**话题标签的嘟文。 + +local +: 布尔值。 是否仅返回本站嘟文？ 默认为 false。 + +remote +: 布尔值。 是否仅返回外站嘟文？ 默认为 false。 + +only_media +: 布尔值。 是否仅返回附有媒体的嘟文？ 默认为 false。 + +max_id +: 字符串。 返回的所有结果将小于此 ID。 事实上设置了结果的上限。 + +since_id +: 字符串。 返回的所有结果将大于此 ID。 事实上设置了结果的下限。 + +min_id +: 字符串。 返回与此 ID 相邻且更新的结果。 事实上在此 ID 处设置游标并向前分页。 + +limit +: 整数。 要返回的最大结果数。 默认为 20 个嘟文。 最多 40 个嘟文。 + +#### 响应 +##### 200: OK + +话题标签 #cats 的时间线示例，limit=2 + +```json +[ + { + "id": "103206185588894565", + "created_at": "2019-11-26T20:50:15.866Z", + // ... + "visibility": "public", + // ... + "content": "

#cats

", + // ... + "tags": [ + { + "name": "cats", + "url": "https://mastodon.social/tags/cats" + } + ], + // ... + }, + { + "id": "103203659567597966", + "created_at": "2019-11-26T10:07:49.000Z", + // ... + "visibility": "public", + // ... + "content": "

Caught on the hop. 😺

#Qualitätskatzen #cats #mastocats #catsofmastodon #Greece #Agistri
(photo: @kernpanik | license: CC BY-NC-SA 4.0)

", + // ... + "tags": [ + { + "name": "qualitätskatzen", + "url": "https://mastodon.social/tags/qualit%C3%A4tskatzen" + }, + { + "name": "cats", + "url": "https://mastodon.social/tags/cats" + }, + { + "name": "mastocats", + "url": "https://mastodon.social/tags/mastocats" + }, + { + "name": "catsofmastodon", + "url": "https://mastodon.social/tags/catsofmastodon" + }, + { + "name": "greece", + "url": "https://mastodon.social/tags/greece" + }, + { + "name": "agistri", + "url": "https://mastodon.social/tags/agistri" + } + ], + // ... + } +] +``` + +##### 404: Not found + +话题标签不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 查看主页时间线 {#home} + +```http +GET /api/v1/timelines/home HTTP/1.1 +``` + +查看来自关注的用户和话题标签的嘟文。 + +**返回：** [Status]({{}}) 数组\ +**OAuth：** 用户 + `read:statuses`\ +**版本历史：**\ +0.0.0 - 添加\ +2.6.0 - 添加 `min_id`\ +3.3.0 - 现在可以同时使用 `min_id` 和 `max_id` +4.0.0 - 由于用户现在可以关注话题标签，因此来自未关注用户的嘟文可能会出现在时间线中 + +#### 请求 + +##### 标头 + +Authorization +: {{}} 提供此标头以及 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: 字符串。 返回的所有结果将小于此 ID。 事实上设置了结果的上限。 + +since_id +: 字符串。 返回的所有结果将大于此 ID。 事实上设置了结果的下限。 + +min_id +: 字符串。 返回与此 ID 相邻且更新的结果。 事实上在此 ID 处设置游标并向前分页。 + +limit +: 整数。 要返回的最大结果数。 默认为 20 个嘟文。 最多 40 个嘟文。 + +#### 响应 +##### 200: OK + +将返回主页时间线中的嘟文 + +```json +[ + { + "id": "103206791453397862", + "created_at": "2019-11-26T23:24:13.113Z", + // ... + }, + // ... +] +``` + +##### 206: Partial content + +正在重新生成主页信息流 + +```text +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 查看链接时间线 {#link} + +```http +GET /api/v1/timelines/link?url=:url HTTP/1.1 +``` + +查看包含指向指定的当前热门文章的链接的公开嘟文。 这仅列出来自选择加入发现功能的用户的嘟文。 + +**返回：** [Status]({{}}) 数组\ +**OAuth：** 允许公开调用。 若实例已禁用公共预览，则需要应用令牌 + `read:statuses`。\ +**版本历史：**\ +4.3.0 - 添加 + +#### 请求 + +##### 标头 + +Authorization +: 提供此标头以及 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +url +: {{}} 字符串。热门文章的 URL。 + +max_id +: 字符串。 返回的所有结果将小于此 ID。 事实上设置了结果的上限。 + +since_id +: 字符串。 返回的所有结果将大于此 ID。 事实上设置了结果的下限。 + +min_id +: 字符串。 返回与此 ID 相邻且更新的结果。 事实上在此 ID 处设置游标并向前分页。 + +limit +: 整数。 要返回的最大结果数。 默认为 20 个嘟文。 最多 40 个嘟文。 + +#### 响应 +##### 200: OK + +##### 404: Not found + +提供的 URL 当前不是热门文章链接。 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 查看列表时间线 {#list} + +```http +GET /api/v1/timelines/list/:list_id HTTP/1.1 +``` + +查看给定列表时间线中的嘟文。 + +**返回：** [Status]({{}}) 数组\ +**OAuth：** 用户令牌 + `read:lists`\ +**版本历史：**\ +2.1.0 - 添加\ +2.6.0 - 添加 `min_id`\ +3.3.0 - 现在可以同时使用 `min_id` 和 `max_id` + +#### 请求 + +##### 路径参数 + +:list_id +: {{}} 字符串。 数据库中列表的本站 ID。 + +##### 标头 + +Authorization +: {{}} 提供此标头以及 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: 字符串。 返回的所有结果将小于此 ID。 事实上设置了结果的上限。 + +since_id +: 字符串。 返回的所有结果将大于此 ID。 事实上设置了结果的下限。 + +min_id +: 字符串。 返回与此 ID 相邻且更新的结果。 事实上在此 ID 处设置游标并向前分页。 + +limit +: 整数。 要返回的最大结果数。 默认为 20 个嘟文。 最多 40 个嘟文。 + +#### 响应 +##### 200: OK + +将返回此列表中的嘟文。 + +```json +[ + { + "id": "103206791453397862", + "created_at": "2019-11-26T23:24:13.113Z", + // ... + }, + // ... +] +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +你并未拥有该列表或该列表不存在 + +```json +{ + "error": "Record not found" +} +``` + +--- + +## 查看私信时间线 {{%deprecated%}} {#direct} + +```http +GET /api/v1/timelines/direct HTTP/1.1 +``` + +查看你的帐户或通知中可见性设置为 "direct" 的嘟文。 + +**返回：** [Status]({{}}) 数组\ +**OAuth：** 用户令牌 + `read:statuses`\ +**版本历史：**\ +x.x.x - 添加\ +2.6.0 - 添加 `min_id`。 已弃用，推荐使用 [Conversations API]({{}})\ +3.0.0 - 移除 + +#### 请求 +##### 标头 + +Authorization +: {{}} 提供此标头以及 `Bearer `，以获得对此 API 方法的访问授权。 + +##### 查询参数 + +max_id +: 字符串。 返回的所有结果将小于此 ID。 事实上设置了结果的上限。 + +since_id +: 字符串。 返回的所有结果将大于此 ID。 事实上设置了结果的下限。 + +min_id +: 字符串。 返回与此 ID 相邻且更新的结果。 事实上在此 ID 处设置游标并向前分页。 + +limit +: 整数。 要返回的最大结果数。 默认为 20 个嘟文。 最多 40 个嘟文。 + +#### 响应 +##### 200: OK + +由你撰写或提及了你的带有 `direct` 可见性的嘟文。 嘟文不按对话分组，而是按时间顺序返回。 + +```json +[ + { + "id": "103206185588894565", + "created_at": "2019-11-26T20:50:15.866Z", + // ... + "visibility": "direct", + // ... + }, + // ... +] +``` + +##### 401: Unauthorized + +Authorization 标头无效或缺失。 + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## 另请参考 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/timelines/home_controller.rb" caption="app/controllers/api/v1/timelines/home_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/timelines/list_controller.rb" caption="app/controllers/api/v1/timelines/list_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/timelines/public_controller.rb" caption="app/controllers/api/v1/timelines/public_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/timelines/tag_controller.rb" caption="app/controllers/api/v1/timelines/tag_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="timelines API methods" raw_link="/methods/timelines/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/methods/trends.md b/content/zh-cn/methods/trends.md new file mode 100644 index 0000000..64ac01f --- /dev/null +++ b/content/zh-cn/methods/trends.md @@ -0,0 +1,229 @@ +--- +title: trends API 方法 +description: 查看当前使用频率高于平常的话题标签。 +menu: + docs: + weight: 10 + name: trends + parent: methods-instance + identifier: methods-trends +aliases: [ + "/methods/trends", + "/api/methods/trends", + "/methods/instance/trends", +] +--- + + + +## 查看热门话题标签 {#tags} + +```http +GET /api/v1/trends/tags HTTP/1.1 +``` + +过去一周内使用频率较高的话题标签。 + +**返回：** [Tag]({{< relref "entities/Tag" >}}) 数组\ +**OAuth：** 公开\ +**版本历史：**\ +3.0.0 - 新增\ +3.5.0 - 方法签名从 `GET /api/v1/trends` 更改为 `GET /api/v1/trends/tags`。 前者是一个已弃用的别名，将来可能会被删除。 + +#### 请求 + +##### 查询参数 + +limit +: 整数。返回的最大结果数。默认为 10 个标签。最多 20 个标签。 + +offset +: 整数。跳过前 n 个结果。 + +#### 响应 +##### 200: OK + +```json +[ + { + "name": "hola", + "url": "https://mastodon.social/tags/hola", + "history": [ + { + "day": "1574726400", + "uses": "13", + "accounts": "10" + }, + // ... + ] + }, + { + "name": "SaveDotOrg", + "url": "https://mastodon.social/tags/SaveDotOrg", + "history": [ + { + "day": "1574726400", + "uses": "9", + "accounts": "9" + }, + // ... + ] + }, + { + "name": "introduction", + "url": "https://mastodon.social/tags/introduction", + "history": [ + { + "day": "1574726400", + "uses": "15", + "accounts": "14" + }, + // ... + ] + }, + // ... +] +``` + +--- + +## 查看热门嘟文 {#statuses} + +```http +GET /api/v1/trends/statuses HTTP/1.1 +``` + +与其他嘟文相比，互动量更高的嘟文。 + +**返回：** [Status]({{< relref "entities/Status" >}}) 数组\ +**OAuth：** 公开\ +**版本历史：**\ +3.5.0 - 新增 + +#### 请求 +##### 查询参数 + +limit +: 整数。返回的最大结果数。默认为 20 个嘟文。最多 40 个嘟文。 + +offset +: 整数。跳过前 n 个结果。 + +#### 响应 +##### 200: OK + +```json +[ + { + "id": "108910940413327534", + "created_at": "2022-08-30T08:44:26.366Z", + "in_reply_to_id": null, + "in_reply_to_account_id": null, + "sensitive": false, + // ... + "content": "

In order to prevent such incidents from happening in the future, we are implementing a fixed set of internal guidelines which must be met before any media content can be shared on our social media platforms. The distribution of material which promotes a message of racism or sexism is unacceptable. We can do better and in the future we will do better.

We apologize again for this incident and can assure you that it will not happen again.

Your Tutanota Team

", + // ... + }, + // ... +] +``` + +--- + +## 查看热门链接 {#links} + +```http +GET /api/v1/trends/links HTTP/1.1 +``` + +与其他链接相比，被分享次数更多的链接。 + +**返回：** [Trends::Link]({{< relref "entities/PreviewCard#trends-link" >}}) 数组\ +**OAuth：** 公开\ +**版本历史：**\ +3.5.0 - 新增 + +#### 请求 +##### 查询参数 + +limit +: 整数。返回的最大结果数。默认为 10 个链接。最多 20 个链接。 + +offset +: 整数。跳过前 n 个结果。 + +#### 响应 +##### 200: OK + +```json +[ + { + "url": "https://www.nbcnews.com/specials/plan-your-vote-2022-elections/index.html", + "title": "Plan Your Vote: 2022 Elections", + "description": "Everything you need to know about the voting rules where you live, including registration, mail-in voting, changes since 2020, and more.", + "type": "link", + "author_name": "NBC News", + "author_url": "", + "provider_name": "NBC News", + "provider_url": "", + "html": "", + "width": 400, + "height": 225, + "image": "https://files.mastodon.social/cache/preview_cards/images/045/027/478/original/0783d5e91a14fd49.jpeg", + "embed_url": "", + "blurhash": "UcQmF#ay~qofj[WBj[j[~qof9Fayofofayay", + "history": [ + { + "day": "1661817600", + "accounts": "7", + "uses": "7" + }, + { + "day": "1661731200", + "accounts": "23", + "uses": "23" + }, + { + "day": "1661644800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1661558400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1661472000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1661385600", + "accounts": "0", + "uses": "0" + }, + { + "day": "1661299200", + "accounts": "0", + "uses": "0" + } + ] + }, + // ... +] +``` + +--- + +## 另请参阅 + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/trends/links_controller.rb" caption="app/controllers/api/v1/trends/links_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/trends/statuses_controller.rb" caption="app/controllers/api/v1/trends/statuses_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/trends/tags_controller.rb" caption="app/controllers/api/v1/trends/tags_controller.rb" >}} + +{{< translation-status-zh-cn raw_title="trends API methods" raw_link="/methods/trends/" last_translation_time="2025-04-06" raw_commit="5e2b739ee193896bea937addc2843146ea0bc870">}} diff --git a/content/zh-cn/spec/activitypub.md b/content/zh-cn/spec/activitypub.md new file mode 100644 index 0000000..f326b58 --- /dev/null +++ b/content/zh-cn/spec/activitypub.md @@ -0,0 +1,898 @@ +--- +title: ActivityPub +description: 基于 ActivityStreams 2.0 数据格式和 JSON-LD 的去中心化社交网络协议。 +menu: + docs: + weight: 10 + parent: spec +--- + +## 嘟文的联合 {#status} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/activitypub/activity.rb" caption="app/lib/activitypub/activity.rb" >}} + +### 嘟文支持的 Activity 类型 + +Create +: 转换为嘟文并保存到数据库中 + +Delete +: 从数据库中删除嘟文 + +Like +: 转换为嘟文的点赞 + +Announce +: 转换为嘟文的转发 + +Update +: 刷新投票计数（针对投票）。自 Mastodon 3.5.0 起：当存在 `updated` 时间戳时，编辑嘟文。 + +Undo +: 撤销之前的 Like 或 Announce。 + +Flag +: 转换为向审核团队的举报。更多信息请查看 [举报](#Flag) 扩展。 + +### 载荷 + +Mastodon 主要支持的对象类型为 `Note` 和 `Question`。 + +- Notes 会转换为常规嘟文。 +- Questions 会转换为投票嘟文。更多信息请查看 [投票](#Question) 扩展。 + +某些其他对象类型会尽可能地进行转换： + +- Article +- Page +- Image +- Audio +- Video +- Event + +转换器会使用 `content` 属性（如果可用），否则使用 `name` 属性来生成嘟文文本。 `url` 属性将会被追加到文本之后。 `summary` 属性将被用作内容警告 (CW) 文本。 `icon` 属性将被用作缩略图。 + +### HTML 清洗 {#sanitization} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/sanitize_ext/sanitize_config.rb" caption="lib/sanitize_ext/sanitize_config.rb" >}} + +Mastodon 会清洗接收到的 HTML，以避免破坏 API 客户端开发者的假设。受支持的元素将保持原样，不受支持的元素将被转换或移除。受支持的属性将被保留，所有其他属性将被剥离。以下是支持的元素和属性： + +- `

` +- `` (`class`) +- `
` +- `` (`href`, `rel`, `class`) +- 列表将会被转换为 `

`，并且列表项之间会用 `
` 分隔 + +自 Mastodon v4.2 起，支持以下元素和属性： + +- `

` +- `` (`class`) +- `
` +- `` (`href`, `rel`, `class`) +- `` +- `

`
+- ``
+- ``
+- ``
+- ``
+- ``
+- ``
+- `