# 搜索连接器概述
## 什么是搜索连接器
搜索连接器提供了一组RESTful API，帮助企业快速实现飞书之外的各类信息的搜索能力，在飞书内即可实现一站式的信息检索和获取，有效提升工作和协同效率。
开发者使用数据源API建立数据源，再通过数据API将数据推送到该数据源，就完成了飞书搜索能力的构建。企业员工可以在飞书搜索框中输入 "/" 进入该数据源的搜索，或者将该数据源的搜索自定义为飞书搜索的垂类（在**飞书搜索** - **更多** - **设置** 中进行拖动）。
![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/e1919b9b304269a752ca919573f597f0_nRD7xwWSVu.png?height=445&lazyload=true&width=763)

![image (1).png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/5074d3d426d5f474979e3d8a507e806f_jhuEsDUoxQ.png?height=2103&lazyload=true&width=3600)

## 名词解释
### Datasource（数据源）

数据源是逻辑上的数据容器，用来存储添加到“飞书搜索”中的外部数据记录。是在“飞书搜索”中创建数据索引的前提条件。

### Item（数据项）

数据项表示支持检索的资源对象，即一条数据记录。例如一个用户信息、一个审批单、一条数据库记录。

### schema（数据范式）

数据范式用来描述数据项中结构化字段（即 `structured_data` 中的数据）的字段类型、字段属性等。其决定了“飞书搜索”会以何种方式使用外部数据，并提供不同的搜索体验。用户必须在创建数据源时关联对应的数据范式。

### ACL
item 的 ACL 字段是指该条数据的访问权限设置。

## 关系描述
每个数据项必须归属于一个数据源。每个数据源必须绑定一个数据范式。数据项中的结构化数据需要符合其归属数据源绑定的数据范式的约束。关系可见下图：

![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/27b60c7614fc904bdcb6d6a81dd30e05_ICrvmY0Pvc.png?height=716&lazyload=true&width=1280)

如果有关系型数据库开发经验的用户，可以将“数据源”类比 “DB 表”；“数据项”类比“DB 记录”；“数据范式”类比“建表语句”来帮助理解。

## 如何创建一个搜索连接器
### 创建数据源（DataSource）
创建搜索连接器的第一步是创建一个数据源（DataSouce）。除此之外，开发者可以通过 DataSouce 的 open API 管理（创建，删除，更新）被飞书搜索索引的数据源。数据源可见性会与创建该数据源的应用可见性绑定。

调用接口可参考[创建数据源](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/search-v2/data_source/create)
### 索引数据项（item）
当数据源创建成功后，就可以将一条条数据索引给飞书搜索。数据 item 是对客户数据中一条数据的抽象描述，飞书搜索通过这种数据结构，可以理解该条具体数据的字段描述和访问权限。

调用接口可参考[索引数据项](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/search-v2/data_source-item/create)

#### 数据项（item）的举例说明

![card.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/0d3dbd3dcb076c505462f6eaa4cacc65_yHD9vkQY7O.png?height=215&lazyload=true&width=392)

根据[索引数据项](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/search-v2/data_source-item/create)文档中对请求 item 结构的描述，如果需要索引上述的卡片消息，请求的结构体如下：

```json
{
  ...
  "metadata": {
    "title": "输入补全功能开通灰度试用权限申请",
    "update_time": "2019-11-08 13:25",
    "source_url": "feishu.cn", // 点击该卡片后跳转的 url，在此场景会跳转到 feishu.cn
    ...
  },
  "structured_data": "{\"icon_url\":\"xxx.com/liumin.jpg\",\"footer\":\"来自 OA 审批\",\"summary\":\"刘敏 AI Search and Lark Lab PM\"}",
  ...
}
```

**注**：
- 上述举例中的 icon_url、source_url 为虚构的，仅为了说明。用户需要根据自己的场景进行填写；
- 上述举例仅列举了针对该卡片样式的必须字段，在 `structured_data` 中可以填入更多信息，但仅会用作搜索，不会用来在卡片上展示；

## 特别说明
- **该功能仅对飞书旗舰版开放**
- 单个租户最多创建10个数据源
- 单个数据源数据量应小于10GB
- 创建和索引数据时会有几秒到几分钟的延迟