本文探讨如何通过飞书的 API 来创建文件夹。
通过 API 创建的文件夹，一般是放在共享空间，如果要放在个人空间，建议手动创建。
查看 API 文档
API 路径，可在飞书开放平台的服务端 API，依次查找云文档>云空间>文件夹>新建文件夹，或者直接点击新建文件夹API。
使用该 API 需要申请新的权限：创建云空间文件夹。
申请权限
到应用中心找到对应的应用，我的应用叫：飞书多维表数据传输，点击进入应用后台，进行权限申请。
在权限管理>API权限>搜索：文件夹>找到“创建云空间文件夹”，点击“开通权限”。
Tips：我开通不需要审核，所以开通即发布。不用审批的权限，其实可以不用到应用后台申请，可以直接在接口文档的右侧 API 调试窗口或者在 API 调试台直接勾选权限，然后点击批量开通。而在企业中，一般是需要审核的。如果需要审核，则就需要到应用后台操作：勾选申请开通的权限，然后创建一个新的版本发布，等待审核。
创建文件夹
有权限之后，发起调试便可成功创建文件夹。
响应体信息：
{
"code": 0,
"data": {
"token": "PFGpfPdFclWaEAdVUXFciHqKnxf",
"url": "https://xxx.feishu.cn/drive/folder/PFGpfPdFclWaEAdVUXFciHqKnxf"
},
"msg": "success"
}
发起请求代码参考如下：
import requests
import json
url = "https://open.feishu.cn/open-apis/drive/v1/files/create_folder"
payload = json.dumps({
"folder_token": "",
"name": "测试项目"
})
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer 【your_access_token】'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
文件夹创建好了，但是刷新我的云文档空间，看不到新建的文件夹？？？
通过响应体返回的链接进去看看，竟然还得申请权限！！文件夹归属应用所有，作为空间所有者，还需要向应用申请权限才能够查看？
应用不是一个实体的号，申请完谁来审批？试试看。
没有意外，在飞书客户端没有任何提醒，在应用后台也没有任何提醒。
添加协作者
直接申请权限时走不通，那应该会有添加协作者的 API。
在云文档的权限的常见问题中，找到了答案，可以通过调用增加协作者权限给个人 email 用户授予文档的访问权限。
不过这个是文档，文件夹呢？先看看增加协作者权限文档，发现这是一个大而全的接口，包含了文档、电子表格、云空间文件、知识库节点、多维表格、新版文档、文件夹、思维笔记、妙记、幻灯片等节点的权限开通。
使用该接口给自己的账号开权限，配置参考如下：
发起调试，执行成功。
刷新我的空间，发现在共享空间多了一个测试项目，没错就是刚刚应用创建的。
请求代码示例如下：
import requests
import json
url = "https://open.feishu.cn/open-apis/drive/v1/permissions/PFGpfPdFclWaEAdVUXFciHqKnxf/members?need_notification=true&type=folder"
payload = json.dumps({
"member_id": "your_openid",
"member_type": "openid",
"perm": "full_access",
"type": "user"
})
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer 【your_access_token】'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
如何获取openid？
找到“通过手机号或邮箱获取用户 ID”的 API，user_id_type 选择 openid，在“选择成员”界面勾选对应的用户可以复制成员 ID。
如果要通过调接口获取，需要申请对应的权限：通过手机号或邮箱获取用户 ID。
如果是创建之后直接给开发者开通管理权限，可以固定使用指定的开发人员的唯一标识（可以是openid、union_id、user_id），如果是需要传递一个名单进行开通，则需要调用该接口获取用户的唯一标识进行开通协作权限。
发起请求示例代码如下：
import requests
import json
url = "https://open.feishu.cn/open-apis/contact/v3/users/batch_get_id?user_id_type=open_id"
payload = json.dumps({
"include_resigned": false,
"mobiles": [
"your_mobile"
]
})
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer 【your_access_token】'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
流程总结
创建文件夹之后需要增加协作者，增加协作者需要协作者的唯一标识，所以需要通过手机号或邮箱获取用户的唯一标识，最终的结构如下：
将三个 API 的请求代码封装成一个函数，传递关键参数，然后返回需要值。
import requests
import json
def cre_folder(access_token,folder_name,folder_token=''):
url = "https://open.feishu.cn/open-apis/drive/v1/files/create_folder"
payload = json.dumps({
"folder_token": folder_token,
"name": folder_name
})
headers = {
'Content-Type': 'application/json',
'Authorization': f'Bearer {access_token}'
}
response = requests.request("POST", url, headers=headers, data=payload)
code = response.json()['code']
if code == 0:
token = response.json().get("data").get("token")
print(f"成功新建文件夹！文件夹 token 为：{token}。关联函数：cre_folder。")
return token
else:
msg = response.json().get("msg")
raise f"创建文件夹失败，失败信息：{msg}。关联函数：cre_folder。"
def get_userid(access_token,mobile):
"""
mobile 可以是单个手机号，或者一个手机号的列表，手机号必须是字符串，不带区号。
"""
url = "https://open.feishu.cn/open-apis/contact/v3/users/batch_get_id?user_id_type=open_id"
if isinstance(mobile, str):
mobile = [mobile]
payload = json.dumps({
"include_resigned": False,
"mobiles": mobile
})
headers = {
'Content-Type': 'application/json',
'Authorization': f'Bearer {access_token}'
}
response = requests.request("POST", url, headers=headers, data=payload)
code = response.json()['code']
if code == 0:
userid = response.json().get("data").get("user_list")
print(f"成功通过手机号获取用户的唯一标识：{userid}。关联函数：get_userid。")
return userid
else:
msg = response.json().get("msg")
raise f"创建文件夹失败，失败信息：{msg}。关联函数：get_userid。"
def add_folder_permission(access_token,folder_token,userid,permission_type='full_access'):
"""
permission_type:view（阅读）、edit（编辑）、full_access（管理）
"""
url = f"https://open.feishu.cn/open-apis/drive/v1/permissions/{folder_token}/members?need_notification=true&type=folder"
payload = json.dumps({
"member_id": userid,
"member_type": "openid",
"perm": "full_access",
"type": "user"
})
headers = {
'Content-Type': 'application/json',
'Authorization': f'Bearer {access_token}'
}
response = requests.request("POST", url, headers=headers, data=payload)
code = response.json()['code']
if code == 0:
print(f"成功为 {userid} 开通权限。关联函数：add_folder_permission。")
else:
msg = response.json().get("msg")
raise f"创建文件夹失败，失败信息：{msg}。关联函数：add_folder_permission。"
def get_tenant_access_token(app_id, app_secret):
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)
tenant_access_token = response.json()['tenant_access_token']
print(f'成功获取tenant_access_token：{tenant_access_token}。关联函数：get_table_params。')
return tenant_access_token
def main():
app_id = 'your_app_id'
app_secret = 'your_app_secret'
access_token = get_tenant_access_token(app_id, app_secret)
folder_token = ''
folder_name = '一个测试项目'
new_folder_token = cre_folder(access_token,folder_name,folder_token)
mobile = '157xxxxxxxx'
user_infos = get_userid(access_token,mobile)
for user_info in user_infos:
userid = user_info['user_id']
print(f"为用户：{user_info['mobile']}（{userid}）开权限。")
add_folder_permission(access_token,new_folder_token,userid,permission_type='full_access')
if __name__ == '__main__':
main()
小结
本文探讨了如何通过 API 创建文件夹并且给指定的用户开通协作权限。
具体操作如下：
- 申请权限：创建云空间文件夹、通过手机号或邮箱获取用户 ID
- 调用获取 access_token 的 API
- 调用创建文件夹的 API
- 调用获取用户 ID 的 API
- 调用添加协作者的 API
思路相对比较简单，但实际操作比较繁琐。
