docs-mastodon/content/zh-cn/client/public.md

title	description	menu
使用公开数据	熟悉端点与实体。	docs weight parent 20 client

现在，你已经知道如何使用 cURL 或你喜欢的编程语言的 HTTP 实用程序或库来构造 HTTP 请求，那么现在是时候了解端点和响应了。

关于端点

所有 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。

获取公开时间线

让我们来了解 Mastodon 公开数据最基础的用例之一——公共时间线。

我们可以尝试请求 [GET /api/v1/timelines/public]({{< relref "methods/timelines" >}})，如下所示：

curl https://mastodon.example/api/v1/timelines/public

哇，响应中有很多文本！公共时间线默认返回 20 条嘟文。

{{< hint style="danger" >}} 一些 Mastodon 实例可能会通过管理设置禁用对其时间线的公开访问。如果你的实例进行了这样的配置，那么你将收到错误响应。 {{</ hint >}}

我们可以使用 limit 参数来请求更少的内容。让我们尝试请求相同的端点，但这次限制为 2：

curl https://mastodon.example/api/v1/timelines/public?limit=2

这次我们的响应应该更容易管理。我们可以使用我们选择的实用程序解析或美化这个 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）：

curl https://mastodon.example/api/v1/timelines/tag/cats?limit=2

我们应该再次看到，在 [Status]({{< relref "entities/status" >}}) 实体的 JSON 数组中返回了 2 条嘟文。我们可以按数组，然后按对象解析 JSON。如果我们使用的是 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 >}}

{{< hint style="info" >}} MastoVue 是一个应用示例，可让你浏览公开时间线。 {{</ hint >}}

获取公开帐户和嘟文

现在，我们熟悉了如何发出请求以及如何处理响应，你可以尝试更多公开数据。以下方法可能会引起你的兴趣：

• 一旦获取了帐户的 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 网站都会有所不同。

获取公开实例数据

你可以使用匿名请求做的最后一件事是查看有关 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，它允许你预览给定实例中的所有自定义表情符号。 {{</ hint >}}

{{< translation-status-zh-cn raw_title="Playing with public data" raw_link="/client/public/" last_translation_time="2025-04-21" raw_commit="6addd5cf525adec1859f48c52dafcfe1f96e558a">}}