飞书API 2-1：如何通过 API 创建文件夹？

本文探讨如何通过飞书的 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

思路相对比较简单，但实际操作比较繁琐。