更新卡片配置
更新指定卡片实体的配置，支持卡片配置 config 字段和卡片跳转链接 card_link 字段。
使用限制
- 调用该接口时，不支持将卡片设置为独享卡片模式。即不支持将卡片 JSON 数据中的
update_multi属性设置为false。 - 调用该接口的应用身份（tenant_access_token）需与创建目标卡片实体的应用身份一致。
请求
| 项目 | 值 |
|---|---|
| HTTP URL | https://open.feishu.cn/open-apis/cardkit/v1/cards/:card_id/settings |
| HTTP Method | PATCH |
| 接口频率限制 | 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。通过创建卡片实体获取 示例值："7355372766134157313" 数据校验规则： - 长度范围： 1 ～ 20 字符 |
请求体
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
settings | string | 是 | 卡片配置相关字段转义后的字符串，包括 config 和 card_link 字段。注意： - 以下示例值未转义，使用时请注意将其转为 JSON 序列化后的字符串。 - 本字段仅支持卡片 JSON 2.0 结构中的对应字段。 示例值："{"config":{"streaming_mode":true,"streaming_config": {\"print_frequency_ms\":{\"default\":70,\"android\":70,\"ios\":70,\"pc\":70},"print_step":{\"default\":1,\"android\":1,\"ios\":1,\"pc\":1},\"print_strategy\":\"fast\"}}}"数据校验规则： - 长度范围： 1 ～ 100000 字符 |
uuid | string | 否 | 幂等 ID，可通过传入唯一的 UUID 以保证相同批次的操作只进行一次。 示例值："a0d69e20-1dd1-458b-k525-dfeca4015204" 数据校验规则： - 长度范围： 1 ～ 64 字符 |
sequence | int | 是 | 操作卡片的序号。用于保证多次更新的时序性。 注意： 请确保在通过卡片 OpenAPI 操作同一张卡片时，sequence 的值相较于上一次操作严格递增。 数据校验规则：int32 范围（ 1~2147483647）内的正整数示例值：1 |
请求体示例
json
{
"settings": "{\"config\":{\"streaming_mode\":true,\"streaming_config\":{\"print_frequency_ms\":{\"default\":70,\"android\":70,\"ios\":70,\"pc\":70},\"print_step\":{\"default\":1,\"android\":1,\"ios\":1,\"pc\":1},\"print_strategy\":\"fast\"}}}",
"uuid": "a0d69e20-1dd1-458b-k525-dfeca4015204",
"sequence": 1
}响应
响应体
| 名称 | 类型 | 描述 |
|---|---|---|
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 | 300302 | update_multi property is false | 卡片全局属性 update_multi 设置为了 false。在流式更新模式下，卡片全局属性 update_multi 需设置为 true。 |
| 400 | 200220 | Failed to generate card content | 生成卡片内容失败。请检查卡片 JSON 格式是否有误。 |
| 400 | 300307 | The card DSL is empty | 卡片 JSON 数据为空。 |
| 400 | 300311 | The current application does not have permission to update/use this card | 当前应用没有更新或使用该卡片的权限。仅支持创建卡片实体的应用调用相关 OpenAPI 发送、操作卡片。 |
| 400 | 300317 | The sequence number for operating on the card did not increment consecutively | 操作卡片的序号（sequence）未按顺序递增。请确保在通过卡片 OpenAPI 操作同一张卡片时，sequence 的值相较于上一次操作严格递增。 |
| 400 | 300122 | Failed to update card configuration | 更新卡片配置失败。请根据接口返回的错误信息检查输入参数。 |