# 五、API 服務說明

## 5.1 商品查詢

* 當你需要取得商品資訊時，請使用 mdca_commodity_request 查詢。你可明確指出 “交易所” 和 ”商品根” 來指明你要查詢的商品，當然您也可以全代入 空字串(“”) 或 NULL，來表示全部包含。

---

## 5.2 即時行情訂閱

* 當你需要即時行情時，請使用 [mdca_quotation_subscribe](/3jSr3fihTyCjq2eTkUKUcw#9161-mdca_quotation_subscribe-%E6%96%B9%E6%B3%95) 訂閱行情，訂閱商品要有明確的 “交易所” 和 ”商品代碼” 來描述指定商品，當您首次訂閱成功後，會引發 [quotation_change](/3jSr3fihTyCjq2eTkUKUcw#9212-quotation_change-事件方法) 事件，請注意，首次引發的事件為初始行情快照，並非即時行情，接下來引發的事件，才是即時行情引發。

* MDC 支援指定交易所全商品訂閱，只要 “商品代碼” 為 “*” 即為全商品。

---

## 5.3 快照行情查詢

* 當你需要當下行情，而不需要即時資訊時，請使用[mdca_quotation_request](/3jSr3fihTyCjq2eTkUKUcw#9161-mdca_quotation_subscribe-%E6%96%B9%E6%B3%95) 查詢行情，查詢時您必須指定 “查詢識別ID”、“交易所” 和 “商品代碼”，查詢完成後，會引發 quotation_response 事件供您取得。

* MDC 支援指定交易所全商品查詢，只要 “商品代碼” 為 “*” 即為全商品。

---

## 5.4 歷史查詢

* 歷史查詢[mdca_history_request](/3jSr3fihTyCjq2eTkUKUcw#9171-mdca_history_request-%E6%96%B9%E6%B3%95)，參數為 [RequestArgument](/v-KO6tAmRqmK8ykncHtxSQ#89-QuotationBasic-%E8%A1%8C%E6%83%85%E9%9D%9C%E6%85%8B%E8%B3%87%E6%96%99%E7%B5%90%E6%A7%8B) 結構，必要欄位 RequestId 為非同步查詢唯一識別碼 (查詢中不可重覆)，ExchangeAbbr 交易所代碼，CommodityCode 商品代碼，DataType 資料類型 (Tick/Depth/分線/日線)，DockMode 歸線模式 (台灣/國際)，Realtime = 0 表示不包含即時處理 (單純歷史查詢)，DockValue 歸線參數 (目前版本不支援)，Condition 附加條件 (目前版本不支援)，指明日期 時間 範圍（StartDate、StartTime、EndDate、EndTime）。

* 若您查詢的歷史資料類型或長度超出您的權限，或是伺服器目前不支援此查詢，會在[history_response](/3jSr3fihTyCjq2eTkUKUcw#9213-history_response-%E4%BA%8B%E4%BB%B6%E6%96%B9%E6%B3%95) 事件取得 錯誤代碼 (error_code) 與錯誤說明 (error_message)，.RequestId 在此同時釋出，值可再次使用。

* 伺服器接受查詢並成功取得時，您會在 [history_response](/3jSr3fihTyCjq2eTkUKUcw#9213-history_response-%E4%BA%8B%E4%BB%B6%E6%96%B9%E6%B3%95) 事件取得資料，錯誤代碼 (error_code) 為 0，若 count 為0，表示指定時間範圍內並無資料，.RequestId 在此同時釋出，值可再次使用。

* [history_response](/3jSr3fihTyCjq2eTkUKUcw#9213-history_response-%E4%BA%8B%E4%BB%B6%E6%96%B9%E6%B3%95) 事件參數resp_data_type 描述了 pdata 對應的資料結構，[Mdcs_Tick](/v-KO6tAmRqmK8ykncHtxSQ#815-Tick-%E9%80%90%E7%AD%86%E6%88%90%E4%BA%A4) / [Mdcs_Depth](/v-KO6tAmRqmK8ykncHtxSQ#816-Depth-%E8%B2%B7%E8%B3%A320-%E6%AA%94) / [Mdcs_Candlestick](/v-KO6tAmRqmK8ykncHtxSQ#817-Candlestick-%E7%87%ADK-%E7%B7%9A)，這些結構都具有 .Status 屬性，這個屬性可以讓您知道，這筆資料的詳細狀態，以單純歷史查詢來看，.Status 的值永遠都是 Mdcs_RDS_History |Mdcs_RDS_Open | Mdcs_RDS_Close（歷史資料、創造資料列、收起資料列）。

---

## 5.5 即時歷史

* 即時歷史[mdca_history_request](/3jSr3fihTyCjq2eTkUKUcw#9171-mdca_history_request-%E6%96%B9%E6%B3%95)，參數為 [RequestArgument](/v-KO6tAmRqmK8ykncHtxSQ#89-QuotationBasic-%E8%A1%8C%E6%83%85%E9%9D%9C%E6%85%8B%E8%B3%87%E6%96%99%E7%B5%90%E6%A7%8B) 結構，必要欄位 RequestId 為非同步查詢兼訂閱的唯一識別碼，ExchangeAbbr 交易所代碼，CommodityCode 商品代碼，DataType 資料類型 (Tick/Depth/分線/日線)，DockMode 歸線模式 (台灣/國際)，Realtime = 1 表示包含即時行情處理，DockValue 歸線參數 (目前版本不支援)，Condition 附加條件 (目前版本不支援)，結束日期時間 (EndDate、EndTime) 必須為 0(因為包含即時行情，表示不用指定結束日期時間，而是用目前行情的最終時間)，至於開始日期時間 (StartDate、StartTime)，有二種模式，當值皆為0 時，表示從當下開始累積即時資料，若明確指出開始日期時間，便會從伺服端取出落差間的歷史資料。

* 若您查詢的歷史資料類型或長度超出您的權限，或是伺服器目前不支援此查詢，會在 [history_response](/3jSr3fihTyCjq2eTkUKUcw#9213-history_response-%E4%BA%8B%E4%BB%B6%E6%96%B9%E6%B3%95) 事件取得 錯誤代碼 (error_code) 與 錯誤說明 (error_message)，.RequestId 在此同時釋出，值可再次使用。

* 伺服器接受查詢並成功取得時，您會在 [history_response](/3jSr3fihTyCjq2eTkUKUcw#9213-history_response-%E4%BA%8B%E4%BB%B6%E6%96%B9%E6%B3%95) 事件取得資料，錯誤代碼 (error_code) 為 0，.RequestId 在此同時釋出，值可再次使用。

* history_response 事件參數resp_data_type 描述了 pdata 對應的資料構，Mdcs_Tick / Mdcs_Depth / Mdcs_Candlestick，這些結構都具有 .Status屬性，這個屬性可以讓您知道，這筆資料的詳細狀態。

* [mdca_history_unsubscribe](/3jSr3fihTyCjq2eTkUKUcw#9172-mdca_history_unsubscribe-%E6%96%B9%E6%B3%95) 可使用 RequestId 解訂閱即時歷史。

* 舉例 Mdcs_Tick 資料，而且有起始日期時間，說明：
* 歷史落差回應，.Status 的值是 Mdcs_RDS_History | Mdcs_RDS_Open| Mdcs_RDS_Close (歷史資料、創造資料列、收起資料列)。
* 即時行情推播，.Status 的值是 Mdcs_RDS_Realtime | Mdcs_RDS_Open | Mdcs_RDS_Close (即時資料、創造資料列、收起資料列)。

* 舉例 Mdcs_Candlestick 資料，而且有起始日期時間，說明：
* 歷史落差回應N 筆，(第1～第N-1) 的 .Status 值是Mdcs_RDS_History | Mdcs_RDS_Open | Mdcs_RDS_Close (歷史資料、創造資料列、收起資料列)，(第N) 的 .Status 值是Mdcs_RDS_History | Mdcs_RDS_Open (歷史資料、創造資料列)。
* 即時行情推播，.Status 的值是 Mdcs_RDS_Realtime | Mdcs_RDS_Update (即時資料、更新資料列)。
* 當即時行情跨越資料列時，會產生2 筆，.Status 分別為Mdcs_RDS_Realtime | Mdcs_RDS_Close (即時資料、收起資料列)，以及 Mdcs_RDS_Realtime | Mdcs_RDS_Open (即時資料、創造資料列)。

## 5.6 Log 機制

* MDC 是默認不寫 Log 的 Api 服務，但是為了方便確認開發問題，目前已支援 Log 機制，設定檔案位置如下：
* 位於工作目錄下存在 libMDCApi.conf 檔案時，依檔案設定做 Log
* 位於 C:\libMDCApi\libMDCApi.conf 檔案時 [Windows OS]
* 位於 /var/libMDCApi/libMDCApi.conf 檔案時 [Linux OS]

* libMDCApi.conf 為一個文字版的設定檔案，其中具有二個參數可設定
* [Log] Path = 為 Log 要寫到的指定路徑 (Default: ./ 即 .dll .so 所在位址)<br>[Log] Level = 為一個 Bit 模式開關的 Log 項目，可設定0~31(Default: 0 即什麼都不寫下)，其他bit 值功能如下：
* 1 = Function call / event log
* 2 = real-time (deal)
* 4 = real-time (depth)
* 8 = commodity response detail
* 16 = history response detail

* Log 檔案的格式 為 libMDCApi_{YYYYMMDD}_{HHMMSS}_{pid}.log
* YYYYMMDD 為被呼叫啟動的年月日
* HHMMSS 為被呼叫啟動的時分秒
* Pid 為 process id 於OS 編列
※同一個 Process 會存在同一個檔案，因此需要看 log handle 線號區分
* Log 新增 [mdca_log_file]() / [mdca_log_flag]() 的界面，供程式呼叫啟動功能。

---
###### tags: `行情API技術文件`