局部更新卡片实体
更新卡片实体局部内容，包括配置和组件。支持同时对多个组件进行增删改等不同操作。
使用限制
- 本接口仅支持卡片 JSON 2.0 结构。
- 调用该接口时，不支持将卡片设置为独享卡片模式。即不支持将卡片 JSON 数据中的
update_multi属性设置为false。 - 调用该接口的应用身份（tenant_access_token）需与创建目标卡片实体的应用身份一致。
请求
| 项目 | 值 |
|---|---|
| HTTP URL | https://open.feishu.cn/open-apis/cardkit/v1/cards/:card_id/batch_update |
| HTTP Method | POST |
| 接口频率限制 | 1000 次/分钟、50 次/秒 |
| 支持的应用类型 | custom,isv |
| 权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 | cardkit:card:write 创建与更新卡片 |
请求头
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| Authorization | string | 是 | tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token |
| Content-Type | string | 是 | 固定值："application/json; charset=utf-8" |
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
card_id | string | 卡片实体 ID。通过创建卡片实体获取。 示例值："7355439197428236291" 数据校验规则： - 长度范围： 1 ～ 20 字符 |
请求体
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
uuid | string | 否 | 幂等 ID，可通过传入唯一的 UUID 以保证相同批次的操作只进行一次。 示例值："a0d69e20-1dd1-458b-k525-dfeca4015204" 数据校验规则： - 长度范围： 1 ～ 64 字符 |
sequence | int | 是 | 操作卡片的序号。用于保证多次更新的时序性。 注意： 请确保在通过卡片 OpenAPI 操作同一张卡片时，sequence 的值相较于上一次操作严格递增。 数据校验规则：int32 范围（ 1~2147483647）内的正整数示例值：1 |
actions | string | 是 | 操作列表。参考示例更新配置或组件。支持的操作有： - partial_update_setting：更新卡片配置，支持更新卡片的 config 和 card_link 字段。参数结构可参考更新卡片配置； - add_elements：添加组件，支持 type、 target_element_id、elements 字段。参数结构可参考新增组件接口请求体； - delete_elements：删除组件，支持 element_ids 字段。参数值为组件 ID 数组。参数结构可参考删除组件； - partial_update_element：更新组件的属性，支持 element_id 和 partial_element 字段。参数结构可参考更新组件属性接口的路径参数 element_id 和请求体 partial_element 字段 ; - update_element：全量更新组件，支持 element_id 和 element 字段。参数结构可参考全量更新组件接口的路径参数 element_id 和请求体 element 字段示例值："[{"action":"partial_update_setting","params":{"settings": {\"config\":{\"streaming_mode\":true}}}},{"action":"add_elements","params":{\"type\":\"insert_before\",\"target_element_id\":\"markdown_1\",\"elements\":[{\"tag\":\"markdown\",\"element_id\":\"md_1\",\"content\":\"欢迎使用[飞书卡片搭建工具](https://open.feishu.cn/cardkit?from=open_docs)。\"}]}},{\"action\":\"delete_elements\",\"params\":{\"element_ids\":[\"text_1\",\"text_2\"]}},{"action":"partial_update_element","params":{\"element_id\":\"markdown_2\",\"partial_element\":{\"content\":\"详情参考飞书卡片相关文档。\"}}},{"action":"update_element","params":{"element_id":"markdown_3","element":{\"tag\":\"button\",\"text\":{\"tag\":\"plain_text\",\"content\":\"有帮助\"},"size":"medium","icon":{\"tag\":\"standard_icon\",\"token\":\"emoji_outlined\"}}}}]"数据校验规则： - 长度范围： 1 ～ 1000000 字符 |
请求体示例
json
{
"uuid": "a0d69e20-1dd1-458b-k525-dfeca4015204",
"sequence": 1,
"actions": "[{\"action\":\"partial_update_setting\",\"params\":{\"settings\":{\"config\":{\"streaming_mode\":true}}}},{\"action\":\"add_elements\",\"params\":{\"type\":\"insert_before\",\"target_element_id\":\"markdown_1\",\"elements\":[{\"tag\":\"markdown\",\"element_id\":\"md_1\",\"content\":\"欢迎使用[飞书卡片搭建工具](https://open.feishu.cn/cardkit?from=open_docs)。\"}]}},{\"action\":\"delete_elements\",\"params\":{\"element_ids\":[\"text_1\",\"text_2\"]}},{\"action\":\"partial_update_element\",\"params\":{\"element_id\":\"markdown_2\",\"partial_element\":{\"content\":\"详情参考飞书卡片相关文档。\"}}},{\"action\":\"update_element\",\"params\":{\"element_id\":\"markdown_3\",\"element\":{\"tag\":\"button\",\"text\":{\"tag\":\"plain_text\",\"content\":\"有帮助\"},\"size\":\"medium\",\"icon\":{\"tag\":\"standard_icon\",\"token\":\"emoji_outlined\"}}}}]"
}响应
响应体
| 名称 | 类型 | 描述 |
|---|---|---|
code | int | 错误码，非 0 表示失败 |
msg | string | 错误描述 |
data | \- | - |
响应体示例
json
{
"code": 0,
"msg": "success",
"data": {}
}错误码
| HTTP状态码 | 错误码 | 描述 | 排查建议 |
|---|---|---|---|
| 400 | 10002 | Your request contains an invalid request parameter. | 参数错误，请根据接口返回的错误信息并参考文档检查输入参数。 |
| 400 | 200740 | The card entity does not exist | 卡片实体不存在。请检查实体 ID 是否正确。 |
| 400 | 200750 | The card entity has expired | 卡片实体已过期。卡片实体的有效期为 14 天。即创建卡片实体超出 14 天后，你将无法调用相关接口操作卡片。请创建一个新的卡片实体。 |
| 400 | 200770 | UUID conflict | UUID 冲突。请传入唯一的 UUID 以保证相同批次的操作只进行一次。 |
| 400 | 200810 | The card is in an ongoing interaction and cannot be updated | 在用户点击卡片请求回调交互期间，卡片无法实现流式更新。请等待交互结束后再尝试更新卡片。 |
| 400 | 200860 | Card content exceeds limit. | 卡片体积超限。请将卡片大小控制在 30KB 以内。 |
| 400 | 300301 | Duplicate element_id in card component. | 卡片内部组件 ID （即 element_id）重复。 |
| 400 | 300302 | update_multi property is false | 卡片属性参数 update_multi 设置为了 false。在流式更新模式下，你需将卡片属性 update_multi 设置为 true。 |
| 400 | 300303 | Only schema 2.0 is supported | 该接口仅支持 Schema v2.0 结构。详情参考卡片 JSON 2.0 结构。 |
| 400 | 200220 | Failed to generate card content | 生成卡片内容失败。请检查卡片 JSON 格式是否有误。 |
| 400 | 300305 | The number of card components exceeds 200 | 超出卡片组件限制。卡片 JSON 2.0 结构中，一张卡片最多支持 200 个元素（如 tag 为 plain_text 的文本元素）或组件。请将组件和元素的数量之和控制在 200 个以内。 |
| 400 | 300307 | The card DSL is empty | 卡片 JSON 数据为空。请检查数据。 |
| 400 | 300311 | The current application does not have permission to update/use this card | 当前应用没有更新或使用该卡片的权限。仅支持创建卡片实体的应用调用相关 OpenAPI 发送、操作卡片。 |
| 400 | 300312 | Unable to update element tag | 更新卡片实体时，不能更新组件的标签（tag）属性。 |
| 400 | 300313 | Failed to update element properties | 更新组件属性失败。请根据接口返回的错误信息检查输入参数。 |
| 400 | 300314 | Failed to delete element | 删除组件失败。请根据接口返回的错误信息检查输入参数。 |
| 400 | 300315 | Failed to add element | 添加组件失败。请根据接口返回的错误信息检查输入参数。 |
| 400 | 300317 | The sequence number for operating on the card did not increment consecutively | 操作卡片的序号（sequence）未按顺序递增。请确保在通过卡片 OpenAPI 操作同一张卡片时，sequence 的值相较于上一次操作严格递增。 |
| 400 | 300121 | Failed to replace element | 替换组件失败。请根据接口返回的错误信息检查输入参数。 |
| 400 | 300122 | Failed to update card configuration | 更新卡片配置失败。请根据接口返回的错误信息检查输入参数。 |