接入指南

1.1. 整体介绍

开放搜索简介： 接入方通过飞书搜索提供的自定义配置能力，实现数据源在飞书内被搜索并展示。
开放搜索价值： 通过飞书搜索更好地满足用户“办公场景统一入口”的需求，为用户提供更便捷、更直接的使用入口。

1.2. 术语说明

数据源：抽象的数据容器，可联想成关系型数据库的表；
数据项：搜索结果中的单条记录，是搜索召回的最小数据单元，可联想成数据库表中的一条记录；
Search tab：Lark 搜索中的“综合”、“消息”、“Meego”等tab。点击“更多”可以看到所有 search tab。理论上一个数据源对应一个 search tab；
ACL：Access Control Lists，对资源是否能被搜索进行控制；

1.3. 说明

开放搜索的数据源必须绑定开放平台中的一个应用。应用的可见性（在租户管理后台配置）决定数据源对应的 search tab 对单个用户是否可见。
召回策略说明：
- 中文支持完整匹配、前缀匹配、分词匹配
- 英文支持完整匹配、前缀匹配、分词匹配
排序策略说明：默认根据底层 ES 的算分算法和item.id进行排序，也支持根据自定字段来排序
应用可见性设置

在版本管理与发布 - 应用发布时，可以选择应用的“可用性状态”，默认只有应用开发者可见。

租户管理后台入口（用户必须是租户管理员）：

“应用审核” 与 “应用可见性”配置的入口如下：

搜索数据权限 主要分为两部分，用户都有权限才能搜到数据：

Search tab 可见性：如果开放平台关联的应用对用户 A 不可见，则该 search tab 对 A 也不可见，即 A 对数据不可搜；在“飞书管理后台”-选择应用-“应用可见性”中编辑可见范围，可从员工或部门的维度进行增删。
数据项 ACL 控制：目前支持针对每个数据项来设置权限控制，支持以人(user) 的粒度来进行设置。如果没有设置，则默认全员不可搜。

2. 具体操作

2.1. 开放平台

在开放平台（open.feishu.cn）中申请应用；（或者复用已有应用）
- 如果复用已有应用，需要注意 search tab 的可见性是跟随已有应用的可见性的。例如已有应用（小程序或者 bot）的可见性为全员可见，那么绑定该应用的 search tab 也是全员可见；请注意不要这里做过多测试和长时间停留，可能会对搜索使用者尤其是kp造成困扰
- 建议新建开放平台应用来单独对 search tab 进行可见性控制；这样可以在测试和导入数据阶段自行控制灰度放量，如果后期想要复用已有应用，目前我们可以支持手动切换
- 如果不想等待企业管理员审批应用，推荐在测试租户创建应用进行测试，测试完成后线上直接使用上述a)方案，并尽快完成数据导入
在应用的“权限管理”中添加“查询、创建、修改和删除自定义搜索数据源、数据范式或数据项”和“查询自定义搜索数据源、数据范式或数据项”两个权限；
在应用的“应用发布”-“版本管理与发布”中，创建版本，并申请发布。发布申请会发送给租户管理员，经由租户管理员批准后方可上线；
在应用的“凭证与基础信息”中复制 App ID 和 App Secret。后续请求接口时需要使用到；

2.2. 开放搜索 OpenAPI

注意：curl 请求中的 ${xxx} 是需要用户手动替换的。

2.2.1. 请求接口获取 tenant access token

推荐使用 SDK ：服务端 SDK

参考链接：获取应用身份访问凭证 - 服务端文档 - 开发文档 - 飞书开放平台来请求接口

或者用以下的 curl 请求

bash

curl --location --request POST 'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal' \
--header 'Content-Type: application/json' \
--data-raw '{
    "app_id": "${App ID}", 
    "app_secret": "${App Secret}"
}'

获取到 tenant_access_token 字段（有效期2小时）

2.2.2. 请求创建数据范式

完整能力参考链接：创建数据范式 - 服务端文档 - 开发文档 - 飞书开放平台

请求体可以参考以下 curl 请求

bash

curl --location --request POST 'https://open.feishu.cn/open-apis/search/v2/schemas' \
--header 'Authorization:  Bearer ${Tenant Access Token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "display": {
        "card_key": "search_common_card",
        "fields_mapping": [
            {
                "data_field": "${expression}",
                "display_field": "${field}"
            },
            {
                "data_field": "${expression}",
                "display_field": "${field}"
            }
        ]
    },
    "properties": [
        {
            "is_returnable": true,
            "is_searchable": true,
            "is_sortable": false,
            "name": "${name}",
            "type": "text",
            "search_options": {
                "enable_semantic_match": true
            }
        },
        {
            "name": "${name}",
            "type": "int",
            "sort_options": {
                "order": "${order}",
                "priority": "${priority}"
            }
        },
        {
            "is_returnable": true,
            "name": "${name}",
            "type": "tag",
            "type_definitions": {
                "tag": [
                    {
                        "color": "${color}",
                        "name": "${name}",
                        "text": "${type}"
                    }
                ]
            }
        }
    ],
    "schema_id": "${schema_id}",
    "validate_only": false
}'

说明：

参数说明请参考接口文档创建数据范式 - 服务端文档 - 开发文档 - 飞书开放平台
card_key 指定数据范式对应的模版，目前支持search_common_card；模版信息如下：
- 红色框：icon_url
- 黄色框：title
- 绿色框：summary
- 蓝色框：footer
- 黑色框：从左到右依次为tag1,tag2,tag3
- 灰色框：PC端为source_url，移动端为source_url_mobile
fields_mapping 定义用户字段到模板字段的映射
- display_field字段为模板字段，目前支持的字段有summary，footer，icon_url，tag1，tag2，tag3；
- data_field支持模版语言且支持拼接, 如这是自定义的字段1: ${field1} 和字段2: ${field2}
具体如下：

json

  "display": {
        "card_key": "search_common_card",
        "fields_mapping": [
         {
                    "data_field": "${priority}",
                    "display_field": "tag1"
                },
                {
                    "data_field": "${status}",
                    "display_field": "tag2"
                },
                {
                    "data_field": "${type}",
                    "display_field": "tag3"
                },
                {
                    "data_field": "this is ${summary} and content is ${content}",
                    "display_field": "summary"
                },
                 {
                    "data_field": "${_create_time}",
                    "display_field": "footer"
                }
        ]
  }

映射有如下特殊规则：
- summary 和 footer 字段的映射支持文本类型和数值类型以及两者的拼接； tag1,tag2,tag3 只支持类型为tag的字段映射
- 对于footer字段，当 data_field 为 ${_create_time} 或 ${_update_time} 时，展示时会解析为 创建于 xxx 和 更新于 xxx 且支持i18n，无需另外配置；
properties为自定义字段处，字段内参数说明可参考上方接口文档
- 名称为_create_time，_update_time，_item_id，_title的字段为特殊字段；除此外，字段命名不能以_开头
- 以上字段对应着数据项的最基本的信息：_create_time，_update_time，_title，_item_id分别对应着metadata中的create_time，update_time，title以及请求体中的id字段；如下为创建item时请求体的metadata部分

json

{
	    "id":"id_1",
      "metadata": {
        "create_time": 0,
        "source_url": "",
        "source_url_mobile": "",
        "title": "",
        "update_time": 0
    }

创建schema时如果没有定义上述字段，系统会默认生成相应字段进行存储；如果无特殊需求，不建议手动配置

字段定义与字段搜索能力需要遵循一定的规范
- 字段的可搜索属性 is_searchable 与可排序属性 is_sortable 不能同时为true
- 只有数值类型字段的 is_sortable 可以为 true；只有文本类型字段的 is_searchable 可以为 true
- tag 类型的is_searchable和的is_sortable都不能为true

2.2.3. 请求创建数据源

参考链接：创建数据源 - 服务端文档 - 开发文档 - 飞书开放平台

或者使用以下 curl 请求

注：请求成功会返回相应的 datasource ID

bash

curl --location --request POST --max-time 10 'https://open.feishu.cn/open-apis/search/v2/data_sources' \
--header 'Authorization: Bearer ${Tenant Access Token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "${数据源名称}",
    "description": "${数据源描述：可选}",
    "icon_url": "${数据源对应 search tab 的图标}",
    "schema_id": "example_schema",
    "template": "search_common_card",
    "state": 1,
     "i18n_name": {
        "zh_cn": "${中文名}",
        "en_us": "${英文名}",
        "ja_jp": "${日文名}"
    },
    "i18n_description": {
        "zh_cn": "${中文描述}",
        "en_us": "${英文描述}",
        "ja_jp": "${日文描述}"
    }
}'

说明：

icon_url 指如下的图标：（支持 png、jpeg 格式图片，>= 200*200 像素）。需要使用公网可访问的图片链接。

i18n 目前支持：i18n_name、i18n_description两个字段，如果没有取到对应的 i18n 字段，则会显示默认字段。
由于需要新建集群索引，该请求的耗时较长（大约5s），请耐心等待。如果新建失败了，可以进行重试，重试再失败请提起反馈；
template，schema_id字段都是指定数据源绑定的模版
- template 目前仅支持 search_common_card，schema_id是创建好的数据范式对应的ID
- 如果设置了schema_id会优先绑定对应的数据范式，否则会根据template对应的模版来创建数据源，建议使用schema_id的方式来创建数据源。

2.2.4. 请求创建数据项

参考链接：索引数据项 - 服务端文档 - 开发文档 - 飞书开放平台

限频次数：1000次/秒；
可以参考使用以下 curl 请求；
metadata 中的 create_time 和 update_time 可省略。若输入，则输入形式为数字，且为 Unix Timestamp 时间。

bash

curl --location --request POST 'https://open.feishu.cn/open-apis/search/v2/data_sources/${Datasource ID}/items' \
--header 'Authorization: Bearer ${Tenant Access Token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "${Item ID}",
    "acl": [{
        "access": "allow",
        "type": "user",
        "value": "everyone"
    }],
    "metadata": {
        "create_time": ${Unix Timestamp},
        "source_url": "${App Link}",
        "title": "${Title}",
        "update_time": ${Unix Timestamp}
    },
    "structured_data": "{\"summary\":\"${Summary}\",\"icon_url\":\"${IconURL}\"}"
}'

说明：

以如下schema为例子

json

 "display": {
        "card_key": "search_common_card",
        "fields_mapping": [
         {
                    "data_field": "${priority}",
                    "display_field": "tag1"
                },
                {
                    "data_field": "${status}",
                    "display_field": "tag2"
                },
                {
                    "data_field": "${type}",
                    "display_field": "tag3"
                },
                {
                    "data_field": "${content}",
                    "display_field": "summary"
                },
                 {
                    "data_field": "${create_time}",
                    "display_field": "footer"
                }
        ]
    }

黄色框：metadata 中的 title 字段，该字段支持搜索
红色框：数据范式中field_mapping定义的映射到icon_url字段的信息；支持 png、jpeg 格式图片，>= 200*200 像素；icon_url为structured_data中字段

json

  {				   
    "structured_data":"{\icon_url\":"\www.feishu.com\"}"
   }

绿色框：field_mapping中定义的映射到summary字段的信息，content为structured_data中字段

json

  {				   
    "structured_data":"{\content\":"\测试摘要\"}"
   }

蓝色框：数据范式中field_mapping定义的映射到summary字段的信息；create_time为metadata中字段
黑色框：数据范式中field_mapping定义的映射到tag1``tag2``tag3字段的信息，为structured_data中字段

json

{				   
    "structured_data":"{\"type\":\"person\",\"status\":\"open\",\"priority\":\"nomal\"}"
   }

黑色框：metadata 中的 source_url 字段中指定的链接,为metadata中字段

特别说明：

目前仅支持根据 title 和 summary 字段来进行搜索。
请求体中的 structured_data 是一个 JSON 字符串。
- 上图数据完整的请求体为：

json

{
    "id": "item_1",
    "acl": [{
        "access": "allow",
        "type": "user",
        "value": "everyone"
    }],
    "metadata": {
        "create_time": 1627460490,
        "source_url": "www.baidu.com",
        "title": "title1",
        "update_time": 1627460490
    },
    "structured_data": "{\"content\":\"测试摘要\",\"icon_url\":\"https://sf3-ttcdn-tos.pstatp.com/obj/mosaic-legacy/6eed0002408143b46441\"，\"priority\":\"nomal\"，\"status\":\"open\"，\"type\":\"urgent\"}"
}

请求体中的 id 字段必须每个数据项唯一，否则会覆盖；
icon_url 仅支持 png、jpeg 格式图片。

3. 附录

3.1. ACL 说明（没有需求可跳过）

ACL 的配置结构如下：

json

[{
    "access": "allow", // 使用 allow 或者 deny
    "type": "user",   
    "value": "everyone"
},{
    "access": "deny", // 使用 allow 或者 deny
    "type": "user",   
    "value": "${ID}"
},
 // ...
]

规则说明

acl参数必须填写，如果配置为空数组，则默认不可见；如果配置了 acl，则数据项权限默认为全员不可搜，需要在 acl 中添加 access 为 allow 的配置，确保部分人可搜；
- 如果 type 为 user ，当 access 为 allow ，value 设置为 everyone 则全员可搜；
如果 type 为 user ，则 value 为用户的 employeeID。获取方式为租户的管理员在“飞书管理后台”中查看（可批量导出）。如下图红框中的“6c368g48”；

在优先级上，deny > allow。即如果 user1 既出现在 allow 列表中，又出现在 deny 列表中。则 user1 不可搜；
acl 长度限制：allow和deny分别限制为1000；

**🙋‍♂️举例说明**

json

{
    "id": "item_1",
    "acl": [],
    "metadata": {
        "create_time": 1632626242,
        "source_url": "https://www.feishu.cn",
        "title": "item01",
        "update_time": 1632626242
    },
    "structured_data": "{\"summary\":\"由北京发来贺电\",\"icon_url\":\"https://sf3-ttcdn-tos.pstatp.com/obj/mosaic-legacy/6eed0002408143b46441\"}"
}

根据规则1，因为没有配置 acl 字段，item_1 这个数据项全员不可见；

json

{
    "id": "item_2",
    "acl": [{
        "access": "allow",
        "type": "user",
        "value": "everyone"
    }],
    "metadata": {
        "create_time": 1632626242,
        "source_url": "https://www.feishu.cn",
        "title": "item02",
        "update_time": 1632626242
    },
    "structured_data": "{\"summary\":\"由北京发来贺电\",\"icon_url\":\"https://sf3-ttcdn-tos.pstatp.com/obj/mosaic-legacy/6eed0002408143b46441\"}"
}

根据规则 1 ，item_2 这个数据项全员可搜；

json

{
    "id": "item_3",
    "acl": [{
        "access": "allow",
        "type": "user",
        "value": "user1_employeeID"
    }, {
        "access": "allow",
        "type": "user",
        "value": "user2_employeeID"
    }],
    "metadata": {
        "create_time": 1632626242,
        "source_url": "https://www.feishu.cn",
        "title": "item03",
        "update_time": 1632626242
    },
    "structured_data": "{\"summary\":\"由北京发来贺电\",\"icon_url\":\"https://sf3-ttcdn-tos.pstatp.com/obj/mosaic-legacy/6eed0002408143b46441\"}"
}

因为 item_3 配置了 acl，该数据项仅 user1、user2用户可搜。

json

{
    "id": item_4",
    "acl": [{
        "access": "allow",
        "type": "user",
        "value": "everyone"
    }, {
        "access": "deny",
        "type": "user",
        "value": "user2"
    }],
    "metadata": {
        "create_time": 1632626242,
        "source_url": "https://www.feishu.cn",
        "title": "item04",
        "update_time": 1632626242
    },
    "structured_data": "{\"summary\":\"由北京发来贺电\",\"icon_url\":\"https://sf3-ttcdn-tos.pstatp.com/obj/mosaic-legacy/6eed0002408143b46441\"}"
}

item_4 数据项除user2用户外全员可搜；

数据源

数据源项

架构

接入指南

1.1. 整体介绍

1.2. 术语说明

1.3. 说明

2. 具体操作

2.1. 开放平台

2.2. 开放搜索 OpenAPI

2.2.1. 请求接口获取 tenant access token

2.2.2. 请求创建数据范式

2.2.3. 请求创建数据源

2.2.4. 请求创建数据项

3. 附录

3.1. ACL 说明（没有需求可跳过）

接入指南 ​

1.1. 整体介绍 ​

1.2. 术语说明 ​

1.3. 说明 ​

2. 具体操作 ​

2.1. 开放平台 ​

2.2. 开放搜索 OpenAPI ​

2.2.1. 请求接口获取 tenant access token ​

2.2.2. 请求创建数据范式 ​

2.2.3. 请求创建数据源 ​

2.2.4. 请求创建数据项 ​

3. 附录 ​

3.1. ACL 说明（没有需求可跳过） ​

接入指南

1.1. 整体介绍

1.2. 术语说明

1.3. 说明

2. 具体操作

2.1. 开放平台

2.2. 开放搜索 OpenAPI

2.2.1. 请求接口获取 tenant access token

2.2.2. 请求创建数据范式

2.2.3. 请求创建数据源

2.2.4. 请求创建数据项

3. 附录

3.1. ACL 说明（没有需求可跳过）