wholetrans/docs-mastodon
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
docs-mastodon/content/zh-cn/client/authorized.md

8.5 KiB
Raw Blame History

title description menu
使用帐户登录 如何从用户处获取授权，并代表用户执行操作。
docs
weight parent
40 client

作用域说明

当我们注册应用及授权用户时，我们需要明确定义生成的令牌将具有哪些权限。这通过使用 [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 作用域" >}}

授权码流程示例

与之前的身份验证流程类似，但这次，我们还需要从用户处获取授权。

客户端 ID 与密钥

在开始操作之前，如果你尚未注册客户端应用，请查看上一页的 [创建我们的应用]({{< relref "client/token#creating-our-application" >}}) 或直接转到 [POST /api/v1/apps]({{< relref "methods/apps#create" >}}) 以获取该方法的完整文档。我们将需要应用的 client_id 和 client_secret。

获得用户授权

要获取用户授权，请在浏览器中请求 [GET /oauth/authorize]({{< relref "methods/oauth#authorize" >}}) 并使用以下查询参数：

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 >}}

获取令牌

获取授权 code 后，让我们获取一个访问令牌，该令牌将用于对授权用户的请求进行身份验证。为此，像以前一样使用 [POST /oauth/token]({{< relref "methods/oauth#token" >}})，但传递我们刚刚获得的授权码：

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 <access_token> 添加到任何需要 OAuth 的 API 调用（即，不是公开可访问的）。

让我们通过调用 [GET /api/v1/accounts/verify_credentials]({{< relref "methods/accounts#verify_credentials" >}}) 来验证我们获得的凭据是否有效：

curl \
	-H 'Authorization: Bearer <access_token>' \
	https://mastodon.example/api/v1/accounts/verify_credentials

如果我们正确地获得了令牌并设置了请求格式，我们应该看到我们的详细信息按 [帐户]({{< relref "entities/account" >}}) 实体的格式返回给我们，其中包含 source 参数。

以授权用户身份执行操作

有了授权用户的 OAuth 令牌后，我们现在可以以该用户的身份执行令牌作用域内的任何操作。

发布和删除嘟文

  • 有关如何创建嘟文的信息，请查看 [POST /api/v1/statuses]({{< relref "methods/statuses#create" >}})。
    • 有关创建媒体附件的信息，请查看 [/api/v1/media]({{< relref "methods/media" >}})。
    • 有关管理计划嘟文的信息，请查看 [/api/v1/scheduled_statuses]({{< relref "methods/scheduled_statuses" >}})。

与时间线交互

  • 有关访问时间线的信息，请查看 [/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" >}})。

与其他用户交互

  • 有关对其他用户执行操作的信息，请查看 [/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" >}})。

接收通知

  • 有关管理用户通知的信息，请查看 [/api/v1/notifications]({{< relref "methods/notifications" >}})。
  • 有关订阅推送通知的信息，请查看 [/api/v1/push]({{< relref "methods/push" >}})。

发现功能

  • 有关查询资源的信息，请查看 [/api/v2/search]({{< relref "methods/search#v2" >}})。
  • 有关推荐关注的账户的信息，请查看 [/api/v1/suggestions]({{< relref "methods/suggestions" >}})。

用户安全功能

  • 有关管理过滤关键词的信息，请查看 [/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" >}})。

管理帐户信息

  • 有关管理用户账户页中的特色帐户的信息，请查看 [/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-21" raw_commit="6addd5cf525adec1859f48c52dafcfe1f96e558a">}}