飞书开发学习笔记(四)-飞书API的访问凭证获取

news2024/12/27 4:09:28

飞书开发学习笔记(四)-飞书API的访问凭证获取

一.了解飞书的访问凭证体系

飞书有一套完善的鉴权管理系统，在飞书API开发时，请求头中必须包含有相关的凭证信息。这个凭证信息是整个开发的安全所在，并且有对应的时效，所以了解飞书的这一套访问凭证体系是非常重要的。
获取访问凭证：获取访问凭证方法介绍
在这里插入图片描述
访问凭证分为三种：
tenant_access_token 租户授权凭证：应用代表租户（即企业或团队）执行对应操作，也就是说团队而非个人的场景。t-前缀。
user_access_token 用户授权凭证：代表用户执行的操作，比如云文档或日程。u-前缀。
app_access_token 应用授权凭证：应用使用自己的身份执行对应操作，不归属到具体的企业或用户。a-或t-前缀。

选择合适的访问凭证：
由于app_access_token的使用场景比较少，飞书开放平台正在逐步统一app_access_token和tenant_access_token两个凭证。

tenant_access_token
Tenant Access Token 代表使用应用的身份操作 OpenAPI，API 所能操作的数据资源范围受限于应用的身份所能操作的资源范围。

如果你的业务逻辑不需要操作用户的数据资源，仅需操作应用自己拥有的资源（比如在应用自己的文档目录空间下创建云文档），则推荐使用 Tenant Access Token，无需额外申请授权。

user_access_token
User Access Token 代表使用应用的使用者的身份操作 OpenAPI，API 所能操作的数据资源范围受限于用户的身份所能操作的资源范围。

如果你的业务逻辑需要操作用户的数据资源（例如需要在用户的文档目录空间下创建云文档），则推荐使用 User Access Token，无需额外申请授权。如果使用 Tenant Access Token，则需额外在资源层面为应用添加相应的授权。

以通讯录为例，如需使用 Tenant Access Token 调用通讯录，则需在开发者后台「权限管理」页面配置应用的通讯录权限范围；而使用 User Access Token 则无需单独配置通讯录权限范围，该范围遵循 User Access Token 所属的用户的通讯录权限范围。

二.获取相应的访问凭证

2.1凭证有效期

访问凭证存在有效期。
tenant_access_token和app_access_token的最大有效期是 2 小时。
user_access_token 的最大有效期是 6900 秒。
开发者需要在自己的服务端设置定时刷新凭证的业务逻辑，以防止过期。如在过期前 1.5 小时之内重新获取凭证，则会拿到与原值相同的值，但每次返回的剩余有效时间（expire）会发生变化，如下图所示。
在这里插入图片描述

2.2获取自建应用的 tenant_access_token

在基础信息 > 凭证与基础信息页面，获取应用凭证 App ID 和 App Secret。
这个在第一页是有说明的，用在API的headers里也能找到。
在这里插入图片描述
然后利用API获取 tenant_access_token

需要的参数: App ID 和 App Secret填入请求体，这两个参数是App创建完成之后固定不变的。

#API范例获取自建应用凭证tenant_access_token

app_id="cli_a3XXXXXX00e"
app_secret="kCp1XXXXXXXXXDu"
url = "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal"
payload = json.dumps({
	"app_id": app_id,
	"app_secret": app_secret
})

headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)
json_Data=json.loads(response.text)
# 打印返回体信息
print(json_Data)
tenant_access_token=json_Data['tenant_access_token']

这样，用这两个参数就获得了tenant_access_token
{‘code’: 0, ‘expire’: 3716, ‘msg’: ‘ok’, ‘tenant_access_token’: 't-xxxxxx}
返回体中有一个expire代表的是有效时间,3716代表还剩3716秒

说明： tenant_access_token 的最大有效期是 2 小时。如果在有效期小于 30 分钟的情况下，调用本接口，会返回一个新的 tenant_access_token，这会同时存在两个有效的 tenant_access_token。

2.3获取用户访问凭证 user_access_token

本章节以应用的网页应用功能为例介绍如何获取 user_access_token。如果你需要为应用的小程序能力获取user_access_token，则需要参考使用小程序提供的 code2session 接口。
获取 user_access_token 的方式同时适用于企业自建应用和商店应用。

登录开发者后台，选择指定应用。
在开发配置 > 安全设置页面，配置重定向 URL。
在这里插入图片描述
根据开发文档的介绍，需要应用中添加应用能力，比如小程序，网页或者移动应用登录等等，然后把
服务端URL进行重定向。这个过程比较复杂，就不进行展开了。

这里是网页应用免登以及二维码扫描登录的案例：
网页应用免登
https://open.feishu.cn/document/home/quickly-create-a-login-free-web-app/introduction
二维码扫描登录
https://open.feishu.cn/document/home/qr-code-scanning-login-for-web-app/introduction
在这里插入图片描述
飞书开放平台会校验应用发送过来的重定向 URL 的合法性，仅在重定向 URL 列表中的 URL 会通过校验。

这个API是https://open.feishu.cn/open-apis/authen/v1/access_token 方法为POST
需要的参数中请求头的Authorization需要app_access_token
而请求体中的code需要登录预授权码
都需要从其它方法中获得。
在这里插入图片描述

获取app_access_token

API https://open.feishu.cn/open-apis/auth/v3/app_access_token
方法为POST

只有1个app_ticket需要获取，其它都是有的，以下为app_ticket的获取方法。

根据以上说明，在配置请求地址以后，就可以通过接收消息获取最新的app_ticket，这样就得到了所有的参数可以执行app_access_token的查询和获得了。
获取登录预授权吗code
获取登录预授权码

API格式，方法为GET

需要配置的参数如下：

redirect_uri：重定向URL地址，在应用的“安全设置”中设置
app_id：应用id已经获得
state:用来维护请求和回调状态的附加字符串，在授权完成回调时会附加此参数，应用可以根据此字符串来判断上下文关系示例中为RANDOMSTATE
根据以上，飞书API访问凭证获取就了解完成了，实际上还有很多具体内容需要掌握，以后再慢慢结合应用开发进行练习。