Python 接群益API 收不到事件?先檢查這 4 行的順序
登入回 0,成功。掛事件,沒有例外。訂閱函式,回傳正常。
然後——什麼都沒發生。
這個問題最難的地方,是它沒有給你任何線索:沒有錯誤碼、沒有例外、沒有一個可以拿去搜尋的字串。你手上只有「它不動」這件事。

目錄
群益API 收不到事件,但每個函式都回傳成功?
群益API 收不到事件的時候,你可能會依序懷疑這幾件事:
| 你會先懷疑 | 但是 |
|---|---|
| 是不是沒訂閱成功? | 訂閱函式回傳正常 |
| 是不是商品代碼寫錯? | 換一個確定存在的代碼,一樣沒反應 |
| 是不是盤後沒資料? | 盤中再試,還是沒有 |
| 是不是權限問題? | 登入回 0,事件也掛上去了 |
四個方向都排除之後,很容易回頭再讀一次自己的訂閱邏輯——而那段程式碼是對的。
問題不在你的訂閱邏輯,而在等待事件的那一段:用哪個函式抽送訊息,以及整個行程的 COM 執行緒模式。
為什麼 C# 的人不會遇到這個問題?
這是群益API 收不到事件會卡很久的原因之一:你搜尋不到這個問題。
網路上關於這套元件的範例以 C# 為主。而 C# 的視窗程式(WinForms、WPF)自帶訊息迴圈——它的 UI 執行緒本來就是一個正常運作的 STA,這件事由框架處理掉了,寫程式的人不需要知道它存在。
所以同一套元件,在 C# 下不會遇到這個狀況,自然也不會有人寫文章討論它。
如果你用 Python 卡在這裡,那不是你做錯了什麼,是你用的語言沒有幫你處理這一層。 這個認知本身就值得先講——它可以讓你停止懷疑自己的訂閱邏輯,把注意力移到對的地方。
STA 與 MTA:官方怎麼說
要理解群益API 收不到事件的檢查點,先看 COM 的執行緒模型。COM 把執行緒分成兩種 apartment 模式,微軟官方文件的對照如下:
| 模式 | CoInitializeEx 旗標 | 官方建議使用時機 |
|---|---|---|
| STA(單一執行緒 Apartment) | COINIT_APARTMENTTHREADED | 執行緒有訊息迴圈(例如 UI 執行緒),或所用的 COM 物件需要訊息幫浦 |
| MTA(多執行緒 Apartment) | COINIT_MULTITHREADED | 執行緒做背景工作、沒有訊息迴圈,且 COM 物件是執行緒安全或 agile 的 |
官方另有一段關於 STA 的重要提醒:STA 執行緒必須抽送訊息;如果 STA 執行緒在沒有抽送訊息的情況下阻塞等待,送進該 apartment 的 COM 呼叫就永遠不會被派送。
讀到這裡,很自然會想:原因是不是沒有抽送訊息?
要看你用哪個函式抽送。在我們的實測裡,用 comtypes 的 PumpEvents 抽送訊息,事件依然沒有進來;換成 pywin32 的 pythoncom.PumpWaitingMessages(),STA 下就收得到事件(實測條件見下一節)。
如果你用的是 PumpEvents,先換成 pythoncom.PumpWaitingMessages() 試試。
實測:哪些組合收得到群益API 的事件?
我們做過兩次實測,物件與版本都不同,分開列出:
| 項目 | 第一次(2026-07-18) | 第二次(2026-10-13) |
|---|---|---|
| SKCOM | 2.13.58 x64 | 2.13.59 x64 |
| Python | 3.12 | 3.12 |
| comtypes | 1.4.16 | 1.4.16(另裝 pywin32) |
| 實測物件與事件 | 海期報價 SKOSQuoteLib 的 OnConnect | 國內報價 SKQuoteLib 的 OnConnection |
第一次的結果:
- comtypes 預設走 STA,用
PumpEvents抽送訊息,事件完全收不到。 - 可以確認掛載是成功的——advise 沒有失敗,登入也回
0。 - 改成 MTA 之後,事件就正常進來了。
第二次換了物件與 SKCOM 版本,測了四種組合:
| 組合 | 結果 |
|---|---|
STA+PumpEvents | 30 秒內收不到 |
STA+pythoncom.PumpWaitingMessages() | 收得到 |
| MTA+只用 sleep 等待 | 收得到 |
MTA+pythoncom.PumpWaitingMessages() | 收得到 |
第二次的結果顯示,問題出在抽送訊息用的函式,不在 STA 或 MTA。第一次的環境(海期報價物件、2.13.58),我們沒有用 PumpWaitingMessages 重測。
至於為什麼 STA 搭配 PumpEvents 收不到、改用 PumpWaitingMessages 就收得到,我們沒有查明。 這裡只陳述觀察到的現象與有效的處理方式,不推測機制——因為推測出來的機制聽起來會很合理,而合理跟正確是兩件事。
這篇不會告訴你「Python 接群益API 一定要用 MTA」,也不會告訴你「一定要用 STA」。 有效的做法有兩條,下面分開講。
做法一:維持 STA,改用 PumpWaitingMessages 抽送訊息
維持 comtypes 預設的 STA,等待事件時改用 pywin32 的 pythoncom.PumpWaitingMessages():
import time
import pythoncom
# 維持 comtypes 預設的 STA,等待事件時用 pywin32 抽送訊息
def pump_until(cond, timeout):
end = time.time() + timeout
while not cond() and time.time() < end:
pythoncom.PumpWaitingMessages()
time.sleep(0.05)
return cond()- 需要先安裝 pywin32:
pip install pywin32。 0.05秒與逾時值都是示意值,依你的程式調整。
做法二:改成 MTA,這四行的順序決定它是否生效
如果你選擇 MTA 這條路,關鍵在下面這四行:
import sys
# 必須在 import comtypes 之前設定,否則不生效,而且不會報錯
sys.coinit_flags = 0x0 # 0x0 = COINIT_MULTITHREADED
import comtypes.client走 MTA 這條路,重點不在語法,在順序。
sys.coinit_flags 必須在 import comtypes 之前設定。comtypes 在匯入的當下就依這個值完成初始化——設晚了,它不會生效。
而最麻煩的是:設錯順序不會有任何錯誤訊息。 程式照跑、匯入成功、後面每一個函式也都回傳正常,然後你又回到文章開頭那個狀態——什麼都沒發生。
這是一個無聲失敗,套在另一個無聲失敗上面。 如果你已經知道要設 MTA、也寫了那一行,群益API 收不到事件的狀況卻還在,先檢查那行在不在 import comtypes 前面。
改成 MTA 之後,用輪詢等待事件就好
換成 MTA 就不需要訊息抽送迴圈了。等待事件的方式改成輪詢 sink 上的旗標,讓事件在背景被派送進來:
import time
# MTA 下不需要 PumpEvents,事件會在背景被派送進來
class QuoteSink:
def __init__(self):
self.received = False
# 官方簽名:OnConnect(int nCode, int nSocketCode)
def OnConnect(self, nCode, nSocketCode):
self.received = True # 回呼只做最輕量的標記
sink = QuoteSink()
connection = comtypes.client.GetEvents(quote_lib, sink) # quote_lib 為海期報價物件 SKOSQuoteLib
# 用輪詢等待,不要在這裡阻塞住
timeout = time.time() + 10
while not sink.received and time.time() < timeout:
time.sleep(0.1)注意回呼裡只做了一件事:把旗標設起來。這不是為了讓範例簡單,而是下一節的紀律。
本例的 quote_lib 是海期報價物件(SKOSQuoteLib),所以事件是 OnConnect。國內報價 SKQuoteLib 的連線事件是 OnConnection,參數順序也不同,差異見〈群益API 連線狀態碼怎麼解讀〉。
另外,登入之前必須先註冊 OnReplyMessage,否則 SKCenterLib_Login 會回 2017——這一條 C# 與 Python 一致,差別只在輸出參數的映射方式(Python 的 comtypes 以回傳值對應,寫 return -1)。這部分在〈群益API 是什麼〉講過,本篇不重述。
MTA 不取代回呼裡的那四條紀律
最後一件事,也是最容易被誤會的:不管走哪條路,解決的都只是事件進不進得來,不解決「回呼裡能做什麼」。
〈群益API 事件回呼跑在哪個執行緒〉那四條紀律照樣適用——不要在回呼裡更新畫面、不要呼叫耗時查詢、不要阻塞等待、不要重入元件。上面範例的回呼只設一個旗標,就是這個原因。
而且在 MTA 下還要更小心一件事:依 MTA 的定義,該 apartment 裡的物件可以被那個 apartment 的任何執行緒直接呼叫,也就是回呼可能跑在任意一條執行緒上。跨執行緒的資料保護要做得比 STA 下更嚴謹。
(這一點是從官方對 MTA 的定義推導出來的,不是我們量測的結果。)
常見問題
群益API 收不到事件,但登入和訂閱都成功,是哪裡寫錯了?
不一定是你寫錯。在 Python 端要檢查等待事件的方式。在我們的實測裡,預設的 STA 只靠 PumpEvents 收不到事件;改用 pythoncom.PumpWaitingMessages(),或改成 MTA,都收得到。
加上 PumpEvents 訊息迴圈就能收到事件嗎?
在我們兩次實測裡,STA 下加上 PumpEvents 都收不到。改用 pywin32 的 pythoncom.PumpWaitingMessages() 就收得到(第二次實測)。為什麼 PumpEvents 不行,原因我們沒有查明。
為什麼網路上查不到這個問題?
關於這套元件的範例以 C# 為主,而 C# 的視窗程式自帶訊息迴圈,UI 執行緒本來就是正常運作的 STA,不會遇到這個狀況。
sys.coinit_flags 我寫了,為什麼還是沒用?
檢查它在不在 import comtypes 前面。comtypes 在匯入的當下就依這個值初始化,設晚了不會生效,而且不會有任何錯誤訊息。
改成 MTA 之後,回呼裡就可以放心做事了嗎?
不行。MTA 解決的是事件進不進得來,回呼裡的四條紀律沒有改變;而且 MTA 下回呼可能跑在任意執行緒上,跨執行緒的資料保護要更小心。
風險揭露
期貨與選擇權屬高槓桿商品,價格波動可能造成超過原始保證金的損失,交易人須自負交易責任。本文為程式開發技術教學,說明 Python 端 COM 執行緒模式的設定與檢查方式,不構成投資建議,也不保證任何交易結果。程式化交易並不降低市場風險,反而可能因程式錯誤造成非預期的委託行為——本文描述的無聲失敗正是這類風險的來源之一。
投資人教育資源
| 機構 | 資源 |
|---|---|
| 臺灣期貨交易所(TAIFEX) | 期貨及選擇權數位學習網 |
| 證券暨期貨市場發展基金會 | 證券期貨市場教育推廣 |
| 金融智慧網 | 金管會金融知識平台 |
| 中華民國期貨業商業同業公會 | 期貨業法規與宣導 |
| 證券投資人及期貨交易人保護中心 | 投資人保護與申訴 |
延伸閱讀
- 〈群益API 事件回呼跑在哪個執行緒〉——回呼裡不能做的四件事;排除群益API 收不到事件之後,接著要守的就是那四條。
- 〈群益API 是什麼〉——COM、STA、Interop 組件與
OnReplyMessage的輸出參數映射都在那篇定義過。
參考資料
- Processes, Threads, and Apartments – Microsoft Learn(STA/MTA 的定義、
CoInitializeEx旗標、STA 需抽送訊息的說明) - pywin32 – PyPI(
pythoncom.PumpWaitingMessages()所屬套件) - 本篇核心現象為兩次實測,非官方文件記載:2026-07-18(SKCOM 2.13.58、海期報價物件:STA+
PumpEvents收不到、MTA 收得到);2026-10-13(SKCOM 2.13.59、國內報價物件:STA+PumpEvents收不到,STA+PumpWaitingMessages與 MTA 都收得到)。其機制未查明。 - 2026-10-15 更正:依第二次實測,補上 STA+
PumpWaitingMessages也收得到事件。 - 「MTA 下回呼可能跑在任意執行緒」為官方 MTA 定義的推導,非實測結果。
免責聲明
本文章僅作為群益API實作經驗分享,不構成投資建議,且策略及程式皆應自行撰寫。期貨及衍生性金融商品交易屬高風險投資,請謹慎評估自身風險承擔能力。







