API

• 介绍
• 启用API支持
• 定义权限
• 授权传入请求
  • 由内置UI发起的请求

介绍

Jetstream 包含了对 Laravel Sanctum 内置集成。Laravel Sanctum 为单页应用程序、移动应用程序和简单基于 token 的 API 提供了轻量级身份验证系统。Sanctum 允许应用程序的每个用户为自己账户生成多个 API token。这些 token 可以被授予能力/权限，指定 token 允许执行的操作。

默认情况下，API token 创建面板可以使用右上角用户资料下拉菜单的 “API” 链接来访问。从这个界面上，用户可以创建具有不同权限的 Sanctum API token。

提示：Sanctum 文档
如需了解有关 Sanctum 的更多信息以及如何向 Sanctum 身份验证的 API 发出请求，请参阅官方的 Sanctum文档 。

启用API支持

如果你的应用程序将提供一个可以被第三方使用的 API，则必须启用 Jetstream 的 API 功能。要做到这一点，请取消注释你的应用程序配置文件中的 config/jetstream.php 的 features 配置选项的相关条目：

'features' => [
    Features::profilePhotos(),
    Features::api(),
    Features::teams(),
],

定义权限

API token 的可用权限是在你应用程序的 App\Providers/JetstreamServiceProvider 类中使用 Jetstream::permissions 方法定义的。权限被定义为简单的字符串。定义后，可以将其分配给 API token：

Jetstream::defaultApiTokenPermissions(['read']);

Jetstream::permissions([
    'post:create',
    'post:read',
    'post:update',
    'post:delete',
]);

上面的示例中的 defaultApiTokenPermissions 方法可用来指定创建新 API token 时应该默认选择哪些权限。当然，用户可以在创建 token 之前取消选中默认权限。

授权传入请求

每个发送到 Jetstream 应用程序的请求，甚至对routes/web.php文件中的身份验证路由，都将与一个 Sanctum token 对象关联。你可以使用 Laravel\Sanctum\HasApiTokens trait 提供的 tokenCan 方法确定关联的 token 是否具有给定的权限。

这个 HasApiTokens trait 在 Jetstream 的安装过程中自动应用到你应用程序的 App\Models\User 模型。通常，你会在你应用程序的控制器、Livewire组件或 授权策略 中调用 tokenCan 方法：

return $request->user()->id === $post->user_id &&
       $request->user()->tokenCan('post:update')

由内置UI发起的请求

当用户向你的routes/web.php文件中的一个路由发起请求时, 该请求通常会被 Sanctum 通过一个基于认证会话 cookie 的 守卫(guard)来验证。在大多数 Laravel 应用程序中, 这就是 web 守卫(guard).

当用户通过应用程序的内置 UI 发起请求时，tokenCan 方法将始终返回 true。请记住，这并不一定意味着应用程序必须让用户执行该操作。通常，你的策略将决定是否授予该 token 执行操作的权限，以及检查用户实例本身是否被允许执行该操作。

比如，在更新博客文章的情况下，这可能意味着检查 token 是否被授权更新文章，并且文章是否属于该用户。

return $request->user()->id === $post->user_id &&
       $request->user()->tokenCan('post:update')

一开始，允许tokenCan 方法被调用并始终返回true 给内置UI发起的请求可能看起来似乎很奇怪；但是，能够始终假设一个 API token 是可用的，并且可以通过tokenCan方法进行检查，这很方便。这意味着你可以在你应用程序的授权策略中总是调用tokenCan方法，而不必担心请求是由你应用程序的用户界面触发的还是由你的 API 的第三方消费者发起的。