CQE 佇列註冊指南
介紹如何將 CQE（Custom Query Engine）指令碼註冊為一台或多台邏輯伺服器（LSSN）上的執行排程，以及開始日期（startdate）的時區約定。
📋 概述
CQE 佇列註冊 用於從儲存庫中選擇指令碼（mssn），指定要執行它的邏輯伺服器（lssn），並將其註冊為執行排程（tMgmtScriptList）。儲存成功後會自動跳轉至 CQELSVR 執行清單 頁面。
🕒 開始日期（startdate）的時區約定 —— 請務必閱讀
| 項目 | 基準 |
|---|---|
| 介面輸入與顯示 | 您的瀏覽器本機時間（在台灣為 CST，在日本為 JST，依此類推） |
| 傳送與儲存 | UTC（ISO 8601）。介面會在傳送前自動轉換。 |
- 請直接依目前所用電腦上顯示的時間填寫，無需自行換算為 UTC。
- 在您按下儲存的那一刻，介面會把本機時間轉換為 UTC 後傳送。資料庫中記錄的是 UTC 值。
- 因此 CQELSVR 執行清單 中的
lastdate等欄位是以 UTC 為基準顯示的。與本機時間相差一個時區偏移是正常現象。
將開始日期設為未來時，在該時刻之前不會執行
開始日期的意義是「在此時刻之前不要執行」。若設定為未來的時間，代理程式在該時刻到來之前不會取走這筆排程。若想立即執行，請將開始日期保持為目前時間（或過去時間）。 開啟頁面時該欄位已預設填入目前的本機時間，若目的是立即執行，保持原樣即可。
⚠️ 先前介面會把本機時間字串未經 UTC 轉換直接傳送，導致以 UTC 運作的資料庫中儲存了比實際晚一個時區偏移的未來時間（giip #2537）。這類排程會在取用排序中被永久排到最後，完全不會執行。目前已修正為由介面承擔轉換責任。
🔍 畫面組成
1. 選擇指令碼（mssn）
- 輸入 mssn: 直接輸入要執行指令碼的唯一 ID。
- 選擇按鈕: 點擊後會彈出目前專案（csn）的指令碼儲存庫清單。可依關鍵字搜尋，並用 Prev / Next 翻頁；點擊某列的選擇會自動填入
mssn與script type。 - 這是必填項目，留空將無法儲存。
2. 選擇目標伺服器（LSSN 群組）
- 以核取方塊形式列出目前專案（csn）下已註冊的邏輯伺服器，顯示為
LSSN — 用途 @ 主機名稱。 - 可以同時選擇多台伺服器，系統會為每台所選伺服器各註冊一筆排程。
- 儲存前至少要選擇一台伺服器。
3. 執行選項
- csn: 專案編號，由登入工作階段自動填入。
- interval: 重複執行間隔（單位：分鐘）。
- active: 排程是否啟用。關閉時僅完成註冊，不會自動執行。
- script type: 指令碼類型（選擇指令碼時自動填入）。
- repeat: 是否重複執行。關閉則成為一次性排程。
- startdate: 開始日期時間（
YYYY-MM-DD HH:mm）。請參閱上方「時區約定」一節。 - auid: 執行要求者 ID，預設填入登入工作階段的使用者 ID。
4. 自訂值（custom_values）
當您希望不修改原始指令碼、只更換其中的值來執行時使用。此處輸入的內容會取代原始指令碼正文中標記為 {{customvalues}} 的位置。
5. 儲存 / 取消
- Save: 驗證輸入並註冊佇列項目，然後跳轉至 CQELSVR 執行清單 頁面。
- Cancel: 不註冊任何內容，返回執行清單頁面。
⚙️ 需求
- 需要登入工作階段（CSN）——沒有工作階段則無法載入伺服器清單與指令碼清單。
- 要註冊的指令碼（
mssn）與伺服器（lssn）都必須屬於目前專案。
疑難排解
| 症狀 | 原因 | 解決 |
|---|---|---|
| LSSN 群組清單為空 | 目前專案（csn）下沒有已註冊的邏輯伺服器，或工作階段已過期 | 確認已在頂部選擇正確的專案，必要時重新登入。 |
| 出現「mssn 為必填」錯誤 | 未選擇指令碼就按了儲存 | 使用選擇按鈕從儲存庫中挑選指令碼。 |
| 出現「請至少選擇一個 LSSN」錯誤 | 一台目標伺服器都未勾選 | 在 LSSN 群組中勾選至少一台伺服器。 |
| 出現「開始日期：使用 YYYY-MM-DD HH:mm 或 ISO 格式」錯誤 | 無法解析開始日期的格式 | 依 2026-09-15 14:30 的形式重新輸入，留空亦可。 |
註冊後執行清單中的 lastdate 與輸入的時間不一致 | lastdate 以 UTC 為基準顯示，而輸入的是本機時間 | 這是正常現象，相差一個時區偏移是正確的。 |
| 已註冊但過了幾分鐘代理程式仍未取走 | 開始日期被設為未來，或 active 處於關閉狀態 | 檢查開始日期，如需立即執行請以目前時間重新註冊，並確認 active 已開啟。 |
🔌 CQE API（自動化）
本畫面的操作對應以下 CQE API 動詞（byAK/bySk 分派器）。請求傳送 text（動詞+參數名）、jsondata（值）與 token。
- CQEQueuePut
mssn lssngroup csn interval active script_type custom_values repeat startdate auid— 為所選的各台伺服器（lssngroup，逗號分隔）註冊排程。startdate必須以 UTC ISO 8601 字串傳送（例如2026-09-15T05:30:00.000Z）。若直接傳送本機時間字串，資料庫中會儲存未來時間，排程將永遠不會執行。 - CQERepoList
csn <offset> [N'keyword']— 查詢指令碼選擇彈出視窗中顯示的儲存庫清單（每次 15 筆）。 - LSVRList
csn— 查詢該專案下註冊的邏輯伺服器清單（用於 LSSN 群組核取方塊）。
認證模型: 此頁面的 API 並非使用 giip-issue 技能的 x-api-key（SK）方式，而是使用登入工作階段的權杖方式，每次請求隨附 user_id + token。
相鄰功能的完整規格: CQELSVR 執行清單指南、CQE 儲存庫指令碼管理指南，以及 giipdb
docs/30_Specs/CQE_SPECIFICATION.md。
版本: 1.0
最後更新: 2026-09-15
來源檔案: giipv3/public/help/cqeQueuePut.zh-TW.md