# 更新组件属性
通过传入 `card_id`（卡片实体 ID）和 `element_id`（组件 ID），更新卡片实体中对应组件的属性。
## 使用限制
- 本接口不支持修改组件的标签（tag）属性。
- 调用该接口时，不支持将卡片设置为独享卡片模式。即不支持将卡片 JSON 数据中的 `update_multi` 属性设置为 `false`。
- 调用该接口的应用身份（tenant_access_token）需与创建目标卡片实体的应用身份一致。
## 请求
基本 |
---|---
HTTP URL | https://open.feishu.cn/open-apis/cardkit/v1/cards/:card_id/elements/:element_id
HTTP Method | PATCH
接口频率限制 | [1000 次/分钟、50 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 创建与更新卡片(cardkit:card:write)
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"
### 路径参数
名称 | 类型 | 描述
---|---|---
card_id | string | 卡片实体 ID。通过[创建卡片实体](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/cardkit-v1/card/create)获取
**示例值**："7355439197428236291"
**数据校验规则**：
- 长度范围：`1` ～ `20` 字符
element_id | string | 要更新的组件的 ID。对应 JSON 代码中的 `element_id` 属性，由开发者自定义。
**示例值**："markdown_1"
**数据校验规则**：
- 长度范围：`1` ～ `20` 字符
### 请求体
名称 | 类型 | 必填 | 描述
---|---|---|---
partial_element | string | 是 | 组件的新的配置项字段。传入 `element_id` 参数后，原组件的 ID 将更新。
**注意**：
- 不支持修改 `tag` 参数。
- 以下示例值未转义，使用时请注意将其转为 JSON 序列化后的字符串。
- 仅支持[卡片 JSON 2.0 结构](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-structure)。
**示例值**："{\"content\":\"更新后的组件文本\"}"
**数据校验规则**：
- 长度范围：`1` ～ `1000000` 字符
uuid | string | 否 | 幂等 ID，可通过传入唯一的 UUID 以保证相同批次的操作只进行一次。
**示例值**："a0d69e20-1dd1-458b-k525-dfeca4015204"
**数据校验规则**：
- 长度范围：`1` ～ `64` 字符
sequence | int | 是 | 操作卡片的序号。用于保证多次更新的时序性。
**注意**：
请确保在通过卡片 OpenAPI 操作同一张卡片时，sequence 的值相较于上一次操作严格递增。
**数据校验规则**：int32 范围（ `1`~`2147483647`）内的正整数。
**示例值**：1
### 请求体示例
```json
{
"partial_element": "{\"content\":\"更新后的组件文本\"}",
"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 | 在用户点击卡片[请求回调](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-callback-communication)交互期间，卡片无法实现流式更新。请等待交互结束后再尝试更新卡片。
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 结构](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-structure)。
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 | 300312 | Unable to update element tag | 更新卡片属性时，不能更新组件的标签（tag）属性。
400 | 300313 | Failed to update element properties | 更新组件属性失败。请根据接口返回的错误信息检查输入参数。
400 | 300317 | The sequence number for operating on the card did not increment consecutively | 操作卡片的序号（sequence）未按顺序递增。请确保在通过卡片 OpenAPI 操作同一张卡片时，sequence 的值相较于上一次操作严格递增。