Skip to main content
2023-12-13 02:52 更新Version: latest

搜索功能

获取与文件相关的用户列表​

此接口用于 @ 功能用户补全。 在文件中输入 @ 时，展示下拉菜单，选择提及的用户，接入方可根据自己系统情况返回，例如：和当前用户最相关的用户列表、和当前文件最相关的用户列表、或返回空数组。

请求地址

GET /search/users/recent?fileId=file12345

HTTP Query Parameters

参数名值说明
fileIdfile12345表示当前查询来自接入方的某个文件 ID

HTTP Request Headers

Header 名值说明
X-Shimo-Token接入方提供的 Token用于接入方对本次请求鉴权

HTTP Response Body

字段名类型值示例说明
items[0].idstringuserid123接入方系统的用户的 ID
items[0].namestring张三接入方系统的用户名称
items[0].avatarstringhttp://fake.site/user-123.png接入方系统的用户头像地址
items[0].emailstringuser123@fake.site接入方系统的用户邮箱

Response Body Example

[
  {
    "id": "userid123",
    "name": "张三",
    "avatar": "http://fake.site/user-123.png",
    "email": "user123@fake.site"
  },
  {
    "id": "userid456",
    "name": "李四",
    "avatar": "http://fake.site/user-123.png",
    "email": "user456@fake.site"
  }
]

获取与文件相关的文件列表​

此接口用于 @ 功能文件补全。 在文件中输入 @ 时，展示下拉菜单，选择提及的文件，接入方可根据自己系统情况返回，例如：和当前用户最相关的文件列表、和当前文件最相关的文件列表、或返回空数组。

支持返回 @ 第三方文件​

说明

由于第三方文件无法进行协作，仅支持在 SDK 中插入 @ 时保留引用，因此需要达到点击后跳转至第三方页面，需要满足以下条件：

  1. file 信息 type 字段值为 file，参考如下 Response Body Example。

  2. file 信息增加 fullUrl 字段作为跳转至接入方系统的完整地址，参考如下 Response Body Example。

  3. 前端使用 shimo-js-sdk 时在调用 connect 需要实现 openLink 方法用于控制编辑器内点击链接时的跳转行为。

请求地址

GET /search/files/recent?fileId=file12345

HTTP Query Parameters

参数名值说明
fileIdfile12345表示当前查询来自接入方的某个文件 ID

HTTP Request Headers

Header 名值说明
X-Shimo-Token接入方提供的 Token用于接入方对本次请求鉴权

HTTP Response Body

字段名类型值示例说明
items[0].idstringba13551165cc5066接入方系统中的文档 ID
items[0].namestringfile title文档标题
items[0].typestringdocumentPro文档类型列表参考 创建文档，若为第三方存储的非石墨协作文件，则固定传 file
items[0].creatorIdstring1接入方文件的创建者用户 ID
items[0].createdAtstring2021-08-01T00:00:00Z接入方记录的文件创建时间，UTC 时间（0 时区）， 格式为 2022-01-01T09:00:01Z
items[0].updatedAtstring2021-08-02T00:00:00Z接入方记录的文件最后更新时间，UTC 时间（0 时区）， 格式为 2022-01-01T09:00:01Z
items[0].viewsnumber100接入方统计的文件阅读次数，用于在文档信息中展示阅读次数。若接入方未返回，则默认显示为 1
items[0].permissionsobject-请参考 文件权限说明
items[0].fullUrlstringhttps://customer-system.com/path/to/file访问文件的完整地址

Response Body Example

[
  {
    "id": "ba13551165cc5066",
    "name": "示例表格",
    "type": "spreadsheet",
    "permissions": {
      "commentable": true,
      "editable": false,
      "readable": true
    },
    "creatorId": "1",
    "createdAt": "2021-08-01T00:00:00Z", // UTC 时间，0 时区，在北京时间基础上减 8 小时
    "updatedAt": "2021-08-02T00:00:00Z", // UTC 时间，0 时区，在北京时间基础上减 8 小时
    "views": 100
   },
  {
    "id": "ba13551165cc5066",
    "name": "示例文档",
    "type": "document",
    "permissions": {
      "commentable": true,
      "editable": false,
      "readable": true
    },
    "creatorId": "1",
    "createdAt": "2021-08-01T00:00:00Z", // UTC 时间，0 时区，在北京时间基础上减 8 小时
    "updatedAt": "2021-08-02T00:00:00Z", // UTC 时间，0 时区，在北京时间基础上减 8 小时
    "views": 100
   },
  {
    "id": "ba13551165cc5066",
    "name": "接入方自己的文件.docx",
    "type": "file",
    "permissions": {
      "commentable": false,
      "editable": false,
      "readable": true
    },
    "creatorId": "1",
    "createdAt": "2021-08-01T00:00:00Z", // UTC 时间，0 时区，在北京时间基础上减 8 小时
    "updatedAt": "2021-08-02T00:00:00Z", // UTC 时间，0 时区，在北京时间基础上减 8 小时
    "views": 0,
    "fullUrl": "https://customer-system.com/path/to/file" // 仅在文件仅为接入方自身系统的文件而非协同文档时需要传递
   }
]

按关键字搜索文件和用户列表​

此接口用 @ 功能搜索，获取下拉菜单的结果使用。 输入 @ 时，如需要根据关键字搜索用户或文件，通过请求接入方系统返回对应的文件列表、用户列表；如不需要可将对应字段返回空数组。

支持返回 @ 第三方文件​

说明

由于第三方文件无法进行协作，仅支持在 SDK 中插入 @ 时保留引用，因此需要达到点击后跳转至第三方页面，需要满足以下条件：

  1. file 信息 type 字段值为 file，参考如下 Response Example

  2. file 信息增加 fullUrl 字段作为跳转至接入方系统的完整地址，参考如下 Response Example

  3. 前端使用 shimo-js-sdk 时在调用 connect 需要实现 openLink 方法用于控制编辑器内点击链接时的跳转行为。

请求地址

POST /search

HTTP Request Headers

Header 名值说明
X-Shimo-Token接入方提供的 Token用于接入方对本次请求鉴权

HTTP Request Body

字段名类型值示例说明
fileIdstringfileid1234接入方系统的文件 ID
keywordstringtest文件名或者用户名的关键字
pagenumber0搜索的结果第几页
pageSizenumber6搜索结果每页数量
typestringfile_name,recent_contact,collaborator,team_member,department指定搜索请求需要搜索的结果包括哪些类型，按照传入的类型按需返回不同的搜索结果。通过英文逗号 , 分割后根据命中的类型返回相应的结果。

type 字段说明​

说明
  • file_name 表示通过关键字搜索文件，对应 Response 中 files 结果。
  • recent_contact 表示通过关键字搜索比较相关用户，对应 Response 中 recentUsers 结果。
  • collaborator 表示通过关键字搜索协作者用户，对应 Response 中 collaborators 结果。
  • team_member 表示通过关键字搜索团队成员，对应 Response 中 teamMembers 结果。
  • department 表示通过关键字搜索部门，对应 Response 中 department 结果。

Request Body Example

{
  "fileId": "file1234",
  "keyword": "test",
  "page": 0,
  "pageSize": 6,
  "type": "file_name,recent_contact,collaborator,team_member,department"
}

HTTP Response Body

字段名类型值示例说明
files.countnumber3搜索到结果的总条数，包括所有分页结果的总和
files.pagenumber0当前为第几页，第如第一页的值为 0
files.pageSizenumber6每一页分页的结果的数量
files.pageCountnumber1分搜索结果的总条数按照分页大小计算后的总页数
files.results[0].idstringba13551165cc5066接入方系统中的文档 ID
files.results[0].namestringfile title文档标题
files.results[0].typestringdocumentPro文档类型列表参考 创建文档，若为第三方存储的非石墨协作文件，则固定传 file
files.results[0].creatorIdstring1接入方文件的创建者用户 ID
files.results[0].createdAtstring2021-08-01T00:00:00Z接入方记录的文件创建时间，UTC 时间（0 时区）， 格式为 2022-01-01T09:00:01Z
files.results[0].updatedAtstring2021-08-02T00:00:00Z接入方记录的文件最后更新时间，UTC 时间（0 时区）， 格式为 2022-01-01T09:00:01Z
files.results[0].viewsnumber100接入方统计的文件阅读次数，用于在文档信息中展示阅读次数。若接入方未返回，则默认显示为 1
files.results[0].permissionsobject请参考 文件权限说明
files.results[0].fullUrlstringhttps://customer-system.com/path/to/file访问文件的完整地址
recentUsers.countnumber3搜索到结果的总条数，包括所有分页结果的总和
recentUsers.pagenumber0当前为第几页，第如第一页的值为 0
recentUsers.pageSizenumber6每一页分页的结果的数量
recentUsers.pageCountnumber1分搜索结果的总条数按照分页大小计算后的总页数
recentUsers.results[0].idstringuserid123接入方系统的用户的 ID
recentUsers.results[0].namestring张三接入方系统的用户名称
recentUsers.results[0].avatarstringhttp://fake.site/user-123.png接入方系统的用户的头像地址
recentUsers.results[0].emailstringuser123@fake.site接入方系统的用户的邮箱
collaborators.countnumber3搜索到结果的总条数，包括所有分页结果的总和
collaborators.pagenumber0当前为第几页，第如第一页的值为 0
collaborators.pageSizenumber6每一页分页的结果的数量
collaborators.pageCountnumber1分搜索结果的总条数按照分页大小计算后的总页数
collaborators.results[0].idstringuserid123接入方系统的用户的 ID
collaborators.results[0].namestring张三接入方系统的用户名称
collaborators.results[0].avatarstringhttp://fake.site/user-123.png接入方系统的用户的头像地址
collaborators.results[0].emailstringuser123@fake.site接入方系统的用户的邮箱
teamMembers.countnumber3搜索到结果的总条数，包括所有分页结果的总和
teamMembers.pagenumber0当前为第几页，第如第一页的值为 0
teamMembers.pageSizenumber6每一页分页的结果的数量
teamMembers.pageCountnumber1分搜索结果的总条数按照分页大小计算后的总页数
teamMembers.results[0].idstringuserid123接入方系统的用户的 ID
teamMembers.results[0].namestring张三接入方系统的用户名称
teamMembers.results[0].avatarstringhttp://fake.site/user-123.png接入方系统的用户的头像地址
teamMembers.results[0].emailstringuser123@fake.site接入方系统的用户的邮箱
department.countnumber3搜索到结果的总条数，包括所有分页结果的总和
department.pagenumber0当前为第几页，第如第一页的值为 0
department.pageSizenumber6每一页分页的结果的数量
department.pageCountnumber1分搜索结果的总条数按照分页大小计算后的总页数
department.results[0].idstring123接入方系统的部门 ID
department.results[0].namestring张三接入方系统的部门名称
department.results[0].allMemberCountnumber10接入方系统的当前部门成员总数
department.results[0].parentDepartmentsArray接入方系统当前部门数据对应的所有父级部门，顺序 从高到底 ，不包括 团队 层级，从一级部门开始，若已是一级部门，则返回空数组。由于在 表格锁定 场景搜索部门时可能遇到同名部门，可以通过所有父级部门来帮助区分部门，若无需区分，可选择不返回父级部门列表。
department.results[0].parentDepartments[0].idstring接入方系统中当前部门父级部门的 ID
department.results[0].parentDepartments[0].namename接入方系统中当前部门父级部门的名称

Response Body Example

{
  "files": { // 按文件名搜索的文件
    "count": 3,
    "page": 0,
    "pageSize": 6,
    "pageCount": 3,
    "results": [
      {
        "id": "ba13551165cc5066",
        "name": "示例表格",
        "type": "spreadsheet",
        "permissions": {
          "commentable": true,
          "editable": false,
          "readable": true
        },
        "creatorId": "1",
        "createdAt": "2021-08-01T00:00:00Z", // UTC 时间，0 时区，在北京时间基础上减 8 小时
        "updatedAt": "2021-08-02T00:00:00Z", // UTC 时间，0 时区，在北京时间基础上减 8 小时
        "views": 100
       },
      {
        "id": "ba13551165cc5066",
        "name": "示例文档",
        "type": "document",
        "permissions": {
          "commentable": true,
          "editable": false,
          "readable": true
        },
        "creatorId": "1",
        "createdAt": "2021-08-01T00:00:00Z", // UTC 时间，0 时区，在北京时间基础上减 8 小时
        "updatedAt": "2021-08-02T00:00:00Z", // UTC 时间，0 时区，在北京时间基础上减 8 小时
        "views": 100
       },
      {
        "id": "ba13551165cc5066",
        "name": "接入方自己的文件.docx",
        "type": "file",
        "permissions": {
          "commentable": false,
          "editable": false,
          "readable": true
        },
        "creatorId": "1",
        "createdAt": "2021-08-01T00:00:00Z", // UTC 时间，0 时区，在北京时间基础上减 8 小时
        "updatedAt": "2021-08-02T00:00:00Z", // UTC 时间，0 时区，在北京时间基础上减 8 小时
        "views": 0,
        "fullUrl": "https://customer-system.com/path/to/file" // 仅在文件仅为接入方自身系统的文件而非协同文档时需要传递
       }
    ]
  },
  "recentUsers": { // 最近联系人等
    "count": 2,
    "page": 0,
    "pageSize": 6,
    "pageCount": 2,
    "results": [
      {
        "id": "userid123",
        "name": "张三",
        "avatar": "http://fake.site/user-123.png",
        "email": "user123@fake.site"
      },
      {
        "id": "userid456",
        "name": "李四",
        "avatar": "http://fake.site/user-123.png",
        "email": "userid456@fake.site"
      }
    ]
  },
  "collaborators": { // 协作者
    "count": 2,
    "page": 0,
    "pageSize": 6,
    "pageCount": 1,
    "results": [
      {
        "id": "userid123",
        "name": "张三",
        "avatar": "http://fake.site/user-123.png",
        "email": "user123@fake.site"
      },
      {
        "id": "userid456",
        "name": "李四",
        "avatar": "http://fake.site/user-123.png",
        "email": "userid456@fake.site"
      }
    ]
  },
  "teamMembers": { // 团队成员
    "count": 2,
    "page": 0,
    "pageSize": 6,
    "pageCount": 1,
    "results": [
      {
        "id": "userid123",
        "name": "张三",
        "avatar": "http://fake.site/user-123.png",
        "email": "user123@fake.site"
      },
      {
        "id": "userid456",
        "name": "李四",
        "avatar": "http://fake.site/user-123.png",
        "email": "userid456@fake.site"
      }
    ]
  },
  "department": {
    "count": 2,
    "page": 0,
    "pageSize": 6,
    "pageCount": 1,
    "results": [
      {
        "id": "2",
        "name": "后端组",
        "allMemberCount": 9,
        "parentDepartments": [
          {
            "id": "3",
            "name": "XXX 事业部" // 一级部门
          },
          {
            "id": "4",
            "name": "YYY 产品部"
          }
        ]
      },
      {
        "id": "userid456",
        "name": "基础服务后端组", // 已经是一级部门
        "allMemberCount": 20,
        "parentDepartments": []
      }
    ]
  }
}