飞书开放平台 Server API 文档

主题

创建数据知识 ​

在 Aily 中添加单个数据知识

Tip: - 仅支持开发环境

  • 开发者需要 Aily 平台的应用协作者角色，包括管理员、开发者、运维人员
  • 使用应用身份仅支持 Aily 平台渠道的应用身份

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/aily/v1/apps/:app_id/data_assets
HTTP MethodPOST
接口频率限制20 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用aily:data_asset:write 创建、更新、删除智能伙伴创建平台数据知识资产

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Typestring是固定值："application/json; charset=utf-8"

路径参数 ​

名称类型描述
app_idstringAily 平台的应用的APPID，可以直接从 Aily 应用的URL中获取。获取示例：/ai/{APPID}
示例值："spring_dfasdf__c"
数据校验规则：
- 长度范围：0 ～ 255 字符

查询参数 ​

名称类型必填描述
tenant_typestring否应用环境，枚举值： - online：线上环境（默认值） - dev：开发环境；目前只支持 dev
示例值：dev
数据校验规则：
- 长度范围：0 ～ 255 字符

请求体 ​

名称类型必填描述
connect_typestring是连接类型
示例值："direct"
可选值有：
- import: 导入模式 - direct: 直连模式
数据校验规则：
- 长度范围：0 ～ 255 字符
source_typestring是数据源类型
示例值："file"
可选值有：
- file: 文件，只支持导入模式 - lark_wiki_space: 飞书知识空间，只支持直连模式 - lark_doc: 飞书云文档，导入模式只支持docx - lark_helpdesk: 飞书服务台，只支持直连模式
数据校验规则：
- 长度范围：0 ～ 255 字符
import_knowledge_settingdata_asset_import_knowledge_setting否知识导入配置
  └ chunk_settingdata_asset_knowledge_chunk_setting否知识切片配置
    └ rule_typestring是切片规则
示例值："intelligent"
可选值有：
- separator: 按标识符 - intelligent: 智能切片
数据校验规则：
- 长度范围：0 ～ 255 字符
    └ separate_typestring否切片分割符类型
示例值："paragraph"
可选值有：
- paragraph: 段落分隔符："\n\n"、"\n"、空格 - title: 标题分割符：######
数据校验规则：
- 长度范围：0 ～ 255 字符
    └ sizeint否分段最大长度（字符），按标识符切片时必须填写
示例值：600
数据校验规则：
- 取值范围：200 ～ 1000
    └ overlapint否分段重叠字符数，按标识符切片时必须填写，不能超过size的数值
示例值：10
数据校验规则：
- 取值范围：0 ～ 200
  └ filedata_asset_import_knowledge_file否知识导入-文件
    └ titlestring否文件标题
示例值："文件标题"
数据校验规则：
- 长度范围：0 ～ 255 字符
    └ tokenstring否上传文件获取到的token。和content二选一，优先使用token。
示例值："bb690637b49440b08f39459a2fdcd2ca"
数据校验规则：
- 长度范围：0 ～ 255 字符
    └ contentstring否文件内容。和token二选一，优先使用token。有长度限制，大文件优先使用token方式。
示例值："这是文件内容"
数据校验规则：
- 长度范围：0 ～ 65536 字符
    └ mime_typestring否文件内容对应的 MIME 类型，必须填写 可选值： - text/plain (.txt) - application/pdf (.pdf) - application/vnd.openxmlformats-officedocument.presentationml.presentation (.pptx) - application/vnd.openxmlformats-officedocument.wordprocessingml.document (.docx)
示例值："application/pdf"
数据校验规则：
- 长度范围：0 ～ 255 字符
    └ urlstring否文件源的URL
示例值："https://document.com/1"
数据校验规则：
- 长度范围：0 ～ 65535 字符
  └ lark_docdata_asset_import_knowledge_lark_doc否知识导入-飞书云文档
    └ typestring是云文档类型
示例值："docx"
可选值有：
- doc: 飞书文档 - file: 飞书文件 - wiki: 飞书知识库 - docx: 飞书新版文档 - folder: 飞书文件夹
数据校验规则：
- 长度范围：0 ～ 255 字符
    └ tokenstring是云文档token，可以通过搜索云文档API获取
示例值："T8FAcuilgC1fdaxkt58vcp91xngh"
数据校验规则：
- 长度范围：0 ～ 255 字符
    └ with_sub_docsboolean否是否包含子文档，只有wiki类型的云文档支持
示例值：false
  └ lark_wiki_spacedata_asset_import_knowledge_wiki否知识导入-飞书知识空间
    └ space_idstring是飞书知识空间ID，可以通过搜索 WikiAPI获取
示例值："798546548961351"
数据校验规则：
- 长度范围：0 ～ 255 字符
    └ sub_docsdata_asset_import_knowledge_wiki_sub_doc\[\]否指定知识空间子节点时使用
      └ typestring是云文档类型，只支持wiki中的云文档
示例值："wiki"
可选值有：
- wiki: 飞书知识库
数据校验规则：
- 长度范围：0 ～ 255 字符
      └ tokenstring是云文档token，可以通过搜索云文档API获取
示例值："T8FAcuilgC1fdaxkt58vcp91xngh"
数据校验规则：
- 长度范围：0 ～ 255 字符
      └ urlstring否云文档链接
示例值："https://cdas.feishu.cn/wiki/fdisu1"
数据校验规则：
- 长度范围：0 ～ 65535 字符
    └ urlstring否知识空间URL
示例值："https://ai-tenant.feishu-boe.cn/wiki/space/7283525110814736404"
数据校验规则：
- 长度范围：0 ～ 65535 字符
  └ lark_helpdeskdata_asset_import_knowledge_helpdesk否知识导入-飞书服务台
    └ helpdesk_idstring是飞书服务台ID，可以通过服务台-接入指南 获取
示例值："123"
数据校验规则：
- 长度范围：0 ～ 255 字符
descriptionmap<string, string>否数据知识描述信息
示例值：{"zh_cn":"描述"}

请求体示例 ​

json
{
    "connect_type": "direct",
    "source_type": "file",
    "import_knowledge_setting": {
        "chunk_setting": {
            "rule_type": "intelligent",
            "separate_type": "paragraph",
            "size": 600,
            "overlap": 10
        },
        "file": {
            "title": "文件标题",
            "token": "bb690637b49440b08f39459a2fdcd2ca",
            "content": "这是文件内容",
            "mime_type": "application/pdf",
            "url": "https://document.com/1"
        },
        "lark_doc": {
            "type": "docx",
            "token": "T8FAcuilgC1fdaxkt58vcp91xngh",
            "with_sub_docs": false
        },
        "lark_wiki_space": {
            "space_id": "798546548961351",
            "sub_docs": [
                {
                    "type": "wiki",
                    "token": "T8FAcuilgC1fdaxkt58vcp91xngh",
                    "url": "https://cdas.feishu.cn/wiki/fdisu1"
                }
            ],
            "url": "https://ai-tenant.feishu-boe.cn/wiki/space/7283525110814736404"
        },
        "lark_helpdesk": {
            "helpdesk_id": "123"
        }
    },
    "description": {
        "zh_cn": "描述"
    }
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ data_assetdata_asset数据知识
    └ data_asset_idstring数据知识ID
    └ labelmap<string, string>数据知识标题
    └ descriptionmap<string, string>数据知识描述
    └ data_source_typestring数据资源类型
可选值有：
- excel: excel - pdf: pdf - pptx: pptx - txt: txt - docx: docx - mysql: mysql - postgresql: postgresql - larkbase: 飞书多维表格 - salesforce: salesforce - fenxiangxiaoke: 分享逍客 - qianchuan: 巨量千川 - clickhouse: clickhouse - databricks: databricks - servicedesk: 飞书服务台 - larkbiz_wiki: 飞书Wiki - larkbiz_doc: 旧版飞书云文档，目前已不支持 - larkbiz_docs: 飞书docs - larkbiz_docx: 新版飞书云文档，当前创建的飞书云文档均为此类型 - larkbiz_pdf: 云盘/wiki中的pdf文件pdf文件 - larkbiz_word: 云盘/wiki中的.docx（Word） - larkbiz_pptx: 云盘/wiki中的.pptx（Powerpoint） - larkbiz_sheets: 飞书电子表格 - larkbiz_base: 飞书多维表格 - larkbiz_personalfolder: 飞书个人文件夹 - larkbiz_sharedfolder: 飞书共享文件夹 - object: 数据表
    └ connect_statusstring数据连接状态
可选值有：
- awaiting: 等待连接 - syncing: 连接中 - successful: 连接成功 - continuously_syncing: 增量同步中 - partially_successful: 部分成功 - failed: 连接失败
    └ tagsdata_asset_tag\[\]数据知识分类列表
      └ data_asset_tag_idstring数据知识分类名称
      └ namestring数据知识分类ID
    └ itemsdata_asset_item\[\]数据知识项列表
      └ data_asset_item_idstring数据知识项ID
      └ api_namestring数据知识项标识
      └ labelmap<string, string>数据知识项标题
      └ descriptionmap<string, string>数据知识项描述
      └ resourcesdata_asset_resource\[\]数据知识资源
        └ resource_idstring数据知识资源ID
        └ resource_typestring数据知识资源类型
可选值有：
- dataset: 数据视图 - vector: 知识视图
    └ connect_failed_reasonstring连接状态失败信息
    └ connect_typestring数据连接类型
可选值有：
- import: 导入 - direct: 直连
    └ created_timestring创建时间，毫秒时间戳
    └ updated_timestring更新时间，毫秒时间戳

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "data_asset": {
            "data_asset_id": "asset_aadg3mcgvpybu",
            "label": {
                "zh_cn": "标题"
            },
            "description": {
                "zh_cn": "描述"
            },
            "data_source_type": "excel",
            "connect_status": "successful",
            "tags": [
                {
                    "data_asset_tag_id": "spring_5862e4fea8__c__asset_tag_aadg2b5ql4gbs",
                    "name": "电影"
                }
            ],
            "items": [
                {
                    "data_asset_item_id": "asset_item_aadg3mcgvpydu",
                    "api_name": "movie",
                    "label": {
                        "zh_cn": "标题"
                    },
                    "description": {
                        "zh_cn": "描述"
                    },
                    "resources": [
                        {
                            "resource_id": "spring_5862e4fea8__c__dataset_aadg3lxm4j6mg",
                            "resource_type": "dataset"
                        }
                    ]
                }
            ],
            "connect_failed_reason": "连接超时",
            "connect_type": "direct",
            "created_time": "1711975665710",
            "updated_time": "1711975665710"
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4002700001param is invalid参数错误，请结合说明文档排查
4032701004permission denied无权限，请检查是否有开发者或者运维权限
4002700026only support development environment仅支持开发环境操作
4002700027only supports uploading a single file仅支持上传单个文件
4002700028invalid chunk setting parameter无效的切片参数
4002700029the data source information is invalid数据源信息无效
4002700030data source not found未找到数据源
4032700031import cloud document permission check failed导入云文档权限检查失败，操作者需要有云文档的下载权限
4002700032unsupported data connection type不支持的数据连接类型，请结合文档排查
4002700033unsupported data source type不支持的数据源类型，请结合文档排查
4002700034unsupported file types不支持的文件类型
4002700460failed to get doc meta获取云文档元信息失败，请检查云文档参数是否正确以及操作者是否拥有相关文档的权限
4002700036cloud document-related resources only support user identity calls云文档相关资源仅支持用户身份调用
4002700472some param miss or invalid请求参数缺失或者不合法

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有