飞书开放平台 Server API 文档

主题

群公告概述 ​

本文档介绍飞书开放平台群组中的群公告能力相关的基本概念、使用限制、接入流程、方法列表等。

Tip: 本文档是针对新版群公告能力的说明。要了解新旧版本群公告能力的区别，参考新旧版本说明。

基础概念 ​

群公告 OpenAPI 中，两个基础概念为群公告和块。

群公告 ​

群公告是群组中的公告文档，采用飞书云文档承载，每个群组只有一个群公告，每篇群公告都有唯一的 chat_id作为标识。要获取群的 chat_id，参考以下任一方式。

群公告的基础元数据结构如下：

json
{
    "revision_id": int,    // 群公告当前版本号
    "create_time": int,    // 群公告生成的时间戳（秒）
    "update_time": int,    // 群公告更新的时间戳（秒）
    "owner_id": string,    // 群公告所有者 ID
    "owner_id_type": string,    // 群公告所有者的 ID 类型
    "modifier_id": string,    // 群公告最新修改者 ID
    "modifier_id_type": string,    // 群公告最新修改者 ID 类型
    "announcement_type": string    // 群公告类型，新版群公告为 docx，旧版群公告为 doc
}

块 ​

在一篇群公告中，有多个不同类型的段落，这些段落被定义为块（Block）。块是群公告中的最小构建单元，是内容的结构化组成元素，有着明确的含义。块有多种形态，可以是一段文字、一张电子表格、一张图片或一个多维表格等。每个块都有唯一的 block_id 作为标识。 每一篇群公告都有一个根块，即页面块（Page block）。页面块的 block_id 与其所在群公告的 chat_id 相同。在数据结构中，群公告的页面块与其它块形成父子关系，页面块为父块，称为 Parent，其它块为子块，称为 Children。其它块之间也可形成父子关系。

块的类别

从功能角度，块可以分为以下几种类别。了解块的具体类型，参考 BlockType 的枚举值。

功能类别典型块示例
文本类页面（Page）、文本（Text）、标题（Heading）、无序列表（Bullet）、有序列表（Ordered）、代码（Code）、待办事项（Todo）块等。
数据类多维表格（Bitable）、电子表格（Sheet）、思维笔记（Mindnote）块。
视觉类分割线（Divider）块。
媒体类图片（Image）、文件（File）、内嵌（Iframe）块等。
协作类会话卡片（ChatCard）块。
容器类表格单元格（TableCell）、分栏列（GridColumn）、高亮（Callout）、视图（View）、引用容器（QuoteContainer）块等。
垂直类流程图 & UML 图（Diagram）块。
辅助类表格（Table）、分栏（Grid）块等。
第三方块开放平台小组件（ISV）块。
未定义块/

块的父子关系规则

块与块之间可形成父子关系。在调用在群公告中创建块接口时，你需先了解以下规则，再指定父块和子块。

父块规则

只有具有容纳能力的块才可以作为父块，对其添加子块。这些块包括：

  • 文本功能类的块：页面（Page）、文本（Text）、标题（Heading）、无序列表（Bullet）、有序列表（Ordered）、任务（Task）、待办事项（Todo）块。
  • 容器功能类的块：表格单元格（TableCell）、分栏列（GridColumn）、高亮（Callout）、引用容器（QuoteContainer）块。

子块规则

以下块不可作为子块被添加至父块内：

块说明
页面（Page）一篇群公告有且只有一个页面块，在群公告创建时自动生成。
分栏列（GridColumn）只可通过批量更新群公告块的内容接口中的 InsertGridColumnRequest 操作添加，不可直接作为子块添加。
思维笔记（Mindnote）不支持。
单元格（TableCell）只可通过批量更新群公告块的内容接口中的 InsertTableRowRequest 或 InsertTableColumnRequest 操作添加，不可直接作为子块添加。
视图（View）在添加文件（File）块时，会自动生成默认的视图块。
未定义（Undefined）无效操作。
流程图 & UML（Diagram）不支持。

父子关系限制

其它的父子关系限制如下表所示：

块限制
单元格（Table Cell）不允许为单元格（TableCell）块添加如下块作为子块：• 表格（Table）• 电子表格（Sheet）• 多维表格（Bitable）• OKR
分栏列（Grid Column）不允许为分栏列（GridColumn）添加如下块作为子块：• 分栏（Grid）• 多维表格（Bitable）• OKR
高亮块（Callout）只允许为高亮块（Callout）添加如下块作为子块：• 文本（Text）• 标题（HeadingN）• 有序列表（Ordered）• 无序列表（Bullet）• 任务（Task）• 待办事项（Todo）• 引用（Quote）• 引用容器（QuoteContainer）

使用限制 ​

你可使用开放平台提供的一系列群公告开放接口对不同种类的块进行操作，包括创建、读取、以及编辑块的内容。针对不同块，群公告开放接口的支持情况不同，详情参考下表。 下表中，“/” 代表对应的操作无需支持或已在其他开放能力的场景中覆盖，具体情况如下：

  • 能力无需支持。例如，分割线（Divider）块不含内容，因此开放平台无需提供读取和编辑其内容的能力；
  • 能力已间接支持。例如，针对单元格（TableCell）块，你会在编辑表格（Table）块的内容时直接创建或删除单元格块，因此开放平台无需为单元格（TableCell）块单独提供创建能力；
  • 能力已在其他开放能力的场景中覆盖。针对多维表格（Bitable）块，你可在创建空的多维表格块后，根据返回的 Token 值使用多维表格的开放能力调用对应的读取和编辑接口。了解多维表格的开放能力，参考多维表格方法列表。
    块创建块读取内容编辑内容
    高亮块（Callout）支持支持支持
    表格（Table）支持支持支持
    文本（Text）支持支持支持
    分割线（Divider）支持//
    分栏（Grid）支持支持支持
    内嵌块（Iframe）支持支持不支持
    会话卡片（ChatCard）支持//
    图片（Image）支持//
    文件（File）支持//
    单元格（TableCell）/支持支持
    分栏列（GridColumn）/支持支持
    视图（View）/支持不支持
    三方块（ISV）支持//
    多维表格（Bitable）支持//
    电子表格（Sheet）支持//
    思维笔记（Mindnote）不支持//
    UML 图（Diagram）不支持不支持不支持
    引用容器（QuoteContainer）支持支持支持
    任务（Task）不支持//
    OKR支持支持/
    OKR 目标（OkrObjective）/支持/
    OKR 关键结果（OkrKeyResult）/支持/
    OKR 进展（OkrProgress）/支持/
    小组件（AddOns）支持支持/
    Jira 问题（JiraIssue）/支持/
    Wiki 子目录（WikiCatalog）支持//
    画板（Board）支持支持/
    未定义块（Undefined）///

接入流程 ​

接入群公告 OpenAPI 的流程如下图所示。了解更多，参考群组概述的 接入流程 一节。

方法列表 ​

以下为群公告和块的 OpenAPI 列表。

群公告 ​

方法 (API)权限要求（满足任一）访问凭证商店自建
``GET 获取群公告基本信息 [/open-apis/docx/v1/chats/:chat_id/announcement](https://open.larkoffice.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/chat-announcement/get)im:chat.announcement:read 查看群公告信息tenant_access_token user_access_token✓✓
``GET 获取群公告所有块 [/open-apis/docx/v1/chats/:chat_id/announcement/blocks](https://open.larkoffice.com/document/open-apis/docx/v1/chats/:chat_id/announcement/blocks)im:chat.announcement:read 查看群公告信息tenant_access_token user_access_token✓✓

块 ​

方法 (API)权限要求（满足任一）访问凭证商店自建
``POST 在群公告中创建块 [/open-apis/docx/v1/chats/:chat_id/announcement/blocks/:block_id/children](https://open.larkoffice.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/chat-announcement-block-children/create)im:chat.announcement:write_only 更新群公告内容tenant_access_token user_access_token✓✓
``PATCH 批量更新群公告块的内容 [/open-apis/docx/v1/chats/:chat_id/announcement/blocks/batch_update](https://open.larkoffice.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/chat-announcement-block/batch_update)im:chat.announcement:write_only 更新群公告内容tenant_access_token user_access_token✓✓
``GET 获取群公告块的内容[open-apis/docx/v1/chats/:chat_id/announcement/blocks/:block_id](https://open.larkoffice.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/chat-announcement-block/get)im:chat.announcement:read 查看群公告信息tenant_access_token user_access_token✓✓
``GET 获取所有子块[/open-apis/docx/v1/chats/:chat_id/announcement/blocks/:block_id/children](https://open.larkoffice.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/chat-announcement-block-children/get)im:chat.announcement:read 查看群公告信息tenant_access_token user_access_token✓✓
``DELETE 删除群公告中的块[/open-apis/docx/v1/chats/:chat_id/announcement/blocks/:block_id/children/batch_delete](https://open.larkoffice.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/chat-announcement-block-children/batch_delete)im:chat.announcement:write_only 更新群公告内容tenant_access_token user_access_token✓✓

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

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