更新文档元数据值

更新指定文档上的元数据值，通过文档 ID 定位文档、字段名定位字段。增量合并：只改传入的字段，没传的不动；字段值传空字符串 "" = 清除该字段的值。一次最多更新 50 个文档。

请求方式

PUT

调用地址

https://api-${endpoint}.gptbots.ai/v1/bot/doc/metadata/update

调用验证

详情参见 API 概述的鉴权方式说明。

请求

请求示例

curl -X PUT 'https://api-${endpoint}.gptbots.ai/v1/bot/doc/metadata/update' \ -H 'Authorization: Bearer ${API Key}' \ -H 'Content-Type: application/json' \ -d '{ "documents": [ { "doc_id": "doc_001", "metadata": { "category": "技术", "priority": "P1" } }, { "doc_id": "doc_002", "metadata": { "category": "产品", "priority": "" } } ] }'

                      
                      curl -X PUT 'https://api-${endpoint}.gptbots.ai/v1/bot/doc/metadata/update' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "documents": [
        {
            "doc_id": "doc_001",
            "metadata": { "category": "技术", "priority": "P1" }
        },
        {
            "doc_id": "doc_002",
            "metadata": { "category": "产品", "priority": "" }
        }
    ]
}'

此代码块在浮窗中显示

请求头

字段	类型	描述
Authorization	Bearer ${API Key}	使用 Authorization: Bearer ${API Key}进行调用验证，请在 API 密钥页面获取密钥作为 API Key。
Content-Type	application/json	数据类型，设置为 `application/json`。

请求参数

字段	类型	必填	说明
documents	Array<Object>	是	要更新的文档列表，一次最多 50 个。
doc_id	String	是	文档 ID。
metadata	Object	否	「字段名 → 值」。空字符串清除该字段值，未传的字段保持不变。字段名须为该文档作用范围内已定义的字段。

注意： LIST 类型字段只能传入字段 options 中已定义的值，否则该文档项更新失败并返回 field 'x' contains value not in options。同一请求中，相同 doc_id 下的同一个 metadata key 只会更新第一次传入的值；后续包含该重复 key 的文档项整体更新失败，并返回 duplicate metadata key 'x' for doc_id 'y'; only the first value is applied。doc_id 必须属于当前 API Key 对应的 Agent，否则返回 doc not found。

响应

响应示例

{ "success_count": 1, "failure_count": 2, "results": [ { "doc_id": "doc_001", "success": true }, { "doc_id": "doc_002", "success": false, "error_message": "field 'priority2' is not defined" }, { "doc_id": "doc_003", "success": false, "error_message": "doc not found" } ] }

                      
                      {
    "success_count": 1,
    "failure_count": 2,
    "results": [
        {
            "doc_id": "doc_001",
            "success": true
        },
        {
            "doc_id": "doc_002",
            "success": false,
            "error_message": "field 'priority2' is not defined"
        },
        {
            "doc_id": "doc_003",
            "success": false,
            "error_message": "doc not found"
        }
    ]
}

此代码块在浮窗中显示

成功响应

字段	类型	说明
success_count	Integer	更新成功的文档数。
failure_count	Integer	更新失败的文档数。
results	Array<Object>	逐文档结果。
doc_id	String	文档 ID。
success	Boolean	是否更新成功。
error_message	String	失败原因，例如：`doc not found`（文档不存在或不属于当前 Agent）、`field 'x' is not defined`（字段名未定义）、`field 'x' contains value not in options`（LIST 值不在可选项中）、`duplicate metadata key 'x' for doc_id 'y'; only the first value is applied`（请求中字段重复，首次传入的值生效）。

失败响应

字段	类型	描述
code	Integer	错误码。
message	String	错误详情。