Tablestore：文件管理

請求參數

程式碼範例

resp = client.upload_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {
            "filePath": "/home/user/docs/product_manual.pdf",
            "metadata": {"author": "張三", "category": "產品文檔"}
        },
        {
            "filePath": "/home/user/docs/faq.docx",
            "metadata": {"author": "李四", "category": "FAQ"}
        }
    ]
})

resp = client.add_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {
            "ossKey": "oss://example-bucket/docs/product_manual.pdf",
            "metadata": {"author": "張三"}
        }
    ]
})

resp = client.add_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {
            "ossKey": "oss://example-bucket/docs/",
            "inclusionFilters": ["*.pdf", "*.docx"],
            "exclusionFilters": ["*draft*"]
        }
    ]
})

響應說明

{
  "code": "SUCCESS",
  "data": {
    "documentDetails": [
      {"docId": "fc6ed97f-...", "status": "succeed", "ossKey": "oss://example-bucket/docs/product_manual.pdf"},
      {"docId": "940f2c5c-...", "status": "succeed", "ossKey": "oss://example-bucket/docs/faq.docx"}
    ]
  },
  "message": "succeed"
}

{
  "code": "SUCCESS",
  "data": {
    "documentDetails": [
      {"status": "failed", "failureReason": "Metadata field 'date' date string format is not supported", "ossKey": "oss://..."},
      {"status": "succeed", "ossKey": "oss://...", "docId": "940f2c5c-..."}
    ]
  },
  "message": "succeed"
}

注意事項

• HTTP 200 + code: SUCCESS 不代表所有文檔都處理成功。必須逐個檢查 documentDetails 中每個文檔的 status 欄位。

• status: "succeed" 表示上傳任務已接收，並非索引完成。必須等到文檔狀態變為 Completed 才能被檢索。

• 知識庫開啟 subspace 後必須傳 subspace 參數，否則報 INVALID_PARAMETER。

• metadata 日期格式需使用支援的格式（如 yyyy-MM-dd HH:mm:ss），不支援的格式會導致文檔 failed。

查詢索引狀態

文檔上傳後經過非同步處理才能被檢索。如需確認文檔是否索引完成，建議採用指數退避輪詢。

import time

def wait_for_document(client, kb_name, doc_id, max_interval=30):
    """指數退避輪詢文檔狀態，等待索引完成。"""
    interval = 3
    while True:
        resp = client.get_document({
            "knowledgeBaseName": kb_name,
            "docId": doc_id
        })
        status = resp["data"][0]["status"]
        if status == "completed":
            print(f"索引完成，切片數: {resp['data'][0].get('chunkNum', 'N/A')}")
            return resp
        elif status == "failed":
            raise Exception(f"索引失敗: {resp['data'][0].get('failedDetails')}")
        print(f"目前狀態: {status}，{interval}s 後重試...")
        time.sleep(interval)
        interval = min(interval * 2, max_interval)

文檔處理時間受檔案大小、類型和數量影響，小檔案通常幾秒完成，大檔案或大量匯入可能需要數分鐘。

請求參數

程式碼範例

resp = client.get_document({
    "knowledgeBaseName": "product_docs_kb",
    "docId": "fc6ed97f-..."
})

doc = resp["data"][0]
print(f"狀態: {doc['status']}, 切片數: {doc.get('chunkNum', 'N/A')}")

響應說明

注意事項

同一個 ossKey 經歷建立→刪除→建立後，get_document 可能返回多條記錄（包含記錄）。根據 status 欄位判斷有效文檔，取 Completed 狀態的記錄。

請求參數

程式碼範例

resp = client.list_documents({
    "knowledgeBaseName": "product_docs_kb",
    "maxResults": 20
})

for doc in resp["data"]["documentDetails"]:
    print(f"[{doc['status']}] {doc['ossKey']} (切片數: {doc.get('chunkNum', '-')})")

注意事項

subspace 參數支援多值列表，但最多 10 個，超過會報錯。

請求參數

程式碼範例

resp = client.update_document({
    "knowledgeBaseName": "product_docs_kb",
    "docId": "fc6ed97f-...",
    "metadata": {"author": "張三", "category": "技術文檔", "version": 2}
})

print(f"更新狀態: {resp['data']['updateStatus']}")  # UPDATED 或 NO_OP

響應說明

注意事項

• metadata 採用覆蓋式更新，傳入的值會全量替換原有 metadata。如果只想更新一個欄位，必須把所有欄位都帶上。

• 傳入 "metadata": null 會清空所有 metadata。

• 不傳 metadata 欄位則保留原值。

• 限制：metadata 總大小（key + value）最大 4KB，欄位數最多 200 個。

請求參數

程式碼範例

resp = client.delete_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {"docId": "fc6ed97f-..."},
        {"ossKey": "oss://example-bucket/docs/faq.docx"}
    ]
})

# 逐個檢查刪除結果
for detail in resp["data"]["documentDetails"]:
    print(f"{detail['ossKey']}: {detail['status']}")

注意事項

同 AddDocuments，刪除結果也需逐個檢查 documentDetails 中每個文檔的 status。