更新文件元資料值

更新指定文件上的元資料值，透過文件 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	錯誤詳情。