ListThreads - - 阿里雲

列舉指定 DataAgent 下的會話，支援按狀態、會話 ID 過濾，並支援分頁返回。

介面說明

會話（Thread）是 DataAgent 的一次連續對話上下文，一個 DataAgent 下可以有多個會話。本介面用於查詢某個 DataAgent 名下的會話清單，可用來恢復歷史會話、繼續未完成的對話或清理不再需要的會話。返回的每個會話包含建立時間、更新時間、狀態與版本號等資訊，會話內容請透過 GetThreadData 取得。

調試

您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

調試

授權資訊

下表是API對應的授權資訊，可以在RAM權限原則語句的Action元素中使用，用來給RAM使用者或RAM角色授予調用此API的許可權。具體說明如下：

操作：是指具體的許可權點。
存取層級：是指每個操作的存取層級，取值為寫入（Write）、讀取（Read）或列出（List）。
資源類型：是指操作中支援授權的資源類型。具體說明如下：
- 對於必選的資源類型，用前面加 * 表示。
- 對於不支援資源級授權的操作，用全部資源表示。
條件關鍵字：是指雲產品自身定義的條件關鍵字。
關聯操作：是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權，操作才能成功。

操作

存取層級

資源類型

條件關鍵字

關聯操作

log:ListThreads

list

*DataAgent

acs:log:{#regionId}:{#accountId}:dataagent/{#name}/thread/*

無

請求文法

GET /dataagents/{name}/threads HTTP/1.1

路徑參數

名稱	類型	必填	描述	樣本值
name	string	否	DataAgent 的名稱，透過請求路徑傳入，用於指定要列舉哪個 DataAgent 下的會話。	order-analysis-agent

請求參數

名稱	類型	必填	描述	樣本值
nextToken	string	否	翻頁遊標。傳入上一次回應返回的 nextToken 可獲取下一頁；首次查詢無需傳入。	e81493d42a7d212810e0ac****
maxResults	integer	否	單頁返回的會話筆數，最大為 200。	20
status	string	否	按會話狀態過濾，取值與結果中的 status 一致，例如 active。	active
threadId	string	否	按會話 ID 過濾，用於只查詢某一個會話。	thread-tiirv9-irwdoal8t4rm
includeMission	boolean	否	是否包含由任務（Mission）自動建立的會話。	false

翻頁使用遊標 nextToken：將上一次回應返回的 nextToken 原樣傳入即可獲取下一頁；回應中不含 nextToken 時表示已返回全部結果。status 為精確匹配，不區分大小寫的取值請以實際返回為準。

返回參數

名稱	類型	描述	樣本值
	object	回應主體。返回符合條件的會話列表與分頁資訊。
maxResults	integer	本次查詢實際使用的單頁筆數，與請求中的 maxResults 一致。	20
nextToken	string	下一頁的翻頁遊標。沒有更多結果時不返回該欄位。	e81493d42a7d212810e0ac****
requestId	string	本次請求的 ID，用於問題排查時定位本次呼叫。	5B0A6B60BB6EE39764D458B5
threadId	string	相容保留欄位，通常不返回；會話列表請讀取 threads。	thread-tiirv9-irwdoal8t4rm
threads	array<object>	本次返回的會話清單，最多包含 maxResults 個會話。沒有符合條件的會話時返回空陣列。
	array<object>	一個會話的資訊。
attributes	object	會話的自訂屬性，鍵與值均為字串。
	string	屬性值，字串類型。	2026-08
createTime	string	會話的建立時間，採用帶時區的 ISO 8601 格式。	2026-08-14T10:00:03+08:00
status	string	會話狀態。常見取值：active（可繼續對話）、archived（已封存）、suspended（已暫停，等待補充輸入）、failed（執行失敗）、cancelled（已取消）。	active
threadId	string	會話 ID，用於發起對話或查詢、修改、刪除該會話。	thread-tiirv9-irwdoal8t4rm
title	string	會話標題，由服務根據對話內容產生，可透過 UpdateThread 修改。	Order Volume Anomaly Troubleshooting
updateTime	string	會話最近一次更新的時間，格式同 createTime。	2026-08-14T11:20:35+08:00
variables	object	會話的上下文變數。
project	string	會話關聯的日誌服務 Project 名稱。	etl-dev
workspace	string	會話關聯的工作空間（Workspace）名稱。	order-workspace
version	integer	會話的版本號，用於標識會話被修改的先後次序。	3
total	integer	符合過濾條件的會話總數。	12

本介面只返回會話的基本資訊，會話中的訊息內容需要按 threadId 呼叫 GetThreadData 獲取。

樣本

正常返回樣本

JSON格式

{
  "maxResults": 20,
  "nextToken": "e81493d42a7d212810e0ac****",
  "requestId": "5B0A6B60BB6EE39764D458B5",
  "threadId": "thread-tiirv9-irwdoal8t4rm",
  "threads": [
    {
      "attributes": {
        "key": "2026-08"
      },
      "createTime": "2026-08-14T10:00:03+08:00",
      "status": "active",
      "threadId": "thread-tiirv9-irwdoal8t4rm",
      "title": "Order volume anomaly troubleshooting",
      "updateTime": "2026-08-14T11:20:35+08:00",
      "variables": {
        "project": "etl-dev",
        "workspace": "order-workspace"
      },
      "version": 3
    }
  ],
  "total": 12
}

錯誤碼

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。