使用富果行情 API 結合 LINE Messaging API 實現到價提醒服務

October 10, 2024 · 14 min read

Sr. Backend Engineer @Fugle

本文改寫自使用富果行情 API 結合 LINE Notify 實現到價提醒服務。根據 LINE Notify 結束服務公告，LINE Notify 服務將於 2025 年 4 月停止運作。為確保系統通知功能的持續運行，LINE 官方建議開發者改用 LINE Messaging API 取代 LINE Notify。本文將介紹如何申請與使用 LINE Messaging API，協助您實現與 LINE Notify 類似的功能，確保通知服務正常運作。

什麼是 LINE Messaging API？

LINE Messaging API 是由 LINE 提供的應用程式介面，讓開發者能與 LINE 用戶互動。透過此 API，開發者可以建立聊天機器人（Chatbot），自動在 LINE 平台上傳送與接收訊息，進行從單向通知到雙向溝通等多種操作。

其主要功能包括：

發送訊息：可以傳送文字、圖片、影片、貼圖等多種訊息格式給指定的 LINE 用戶。
接收訊息：支援用戶回覆訊息，系統可根據用戶回應進行處理或觸發特定動作。
多樣訊息格式：提供豐富的互動方式，支援彈性訊息（Flex Message）、按鈕選項等，提升用戶互動體驗。
Webhook 支援：當用戶與機器人互動時，API 可即時通知系統，讓開發者依據用戶操作進行回應。

每月可免費發送一定數量的訊息，免費額度取決於您的 LINE 官方帳號訂閱方案。

事前準備

在開始進行實作之前，我們必須先取得 富果行情 API 金鑰 以及申請使用 LINE Messaging API。

圖解：取得富果行情 API 金鑰

STEP 1：前往富果帳戶開發者網站首頁，點選「文件」→「行情」。

STEP 2：跳轉頁面後，點選「金鑰申請」。

STEP 3：「金鑰申請及管理」頁面下，即可新增行情 API 金鑰。

取得 API token 後，就可以使用富果即時行情 API。在開發者方案下，日內行情、行情快照與歷史行情 API 每分鐘可以請求 600 次；WebSocket API 可以訂閱 300 檔股票，並且可同時有 2 個連線數。基本上可以滿足一般用戶的需要。

圖解：申請使用 LINE Messaging API

STEP 1：前往 LINE Developers 平台，使用您的 LINE 帳號登入。如尚未擁有 LINE 帳號，請先註冊，並以該帳號登入 LINE Developers 平台。

STEP 2：登入後，點擊右上角的「Console」進入管理介面，從左側選單中選擇「Providers」，點擊「Create」，並輸入提供者名稱來建立新的 Provider。

STEP 3：完成 Provider 建立後，選擇「Create a Messaging API Channel」來建立 Messaging API Channel。

STEP 4：如果您尚未擁有 LINE 官方帳號，請前往 LINE Official Account Manager 申請官方帳號，並將此帳號連接至 Messaging API Channel。

STEP 5：按指示填寫 LINE 官方帳號的相關資訊。

STEP 6：確認輸入的所有資訊無誤後繼續。

STEP 7：申請完成後，點擊「前往 LINE Official Account Manager」進行後續設定。

圖10

STEP 8：進入 LINE Official Account Manager 時，您需同意 LINE 資料使用條款。請詳閱條款內容後點擊「同意」。

圖11

STEP 9：進入 LINE Official Account Manager 後，點擊右上角的「設定」，從左側選單中選擇「Messaging API」後，點選「啟用 Messaging API」。

圖12

STEP 10：在啟用 Messaging API 時，選擇您先前在 LINE Developers 建立的 Provider。

圖13

STEP 11：確認帳號名稱與對應的提供者名稱正確後，點擊「確定」。

圖14

STEP 12：返回 LINE Developers Console，進入您剛建立的 Provider 設定頁面。

圖15

STEP 13：在「Basic settings」頁籤下找到「Your user ID」，請記下此 ID，它將用於將訊息發送至您自己。

圖16

STEP 14：在「Messaging API」頁籤中，點擊「Issue」來生成一個長期有效的 Channel Access Token，此 Token 用於 API 請求的驗證。

圖17

實戰！到價提醒通知

以下我們以 Node.js 為例，手把手教您如何實作出一個基本的到價提醒功能。

安裝套件

為了方便存取 Fugle Realtime API 以及 LINE Notify，我們主要會使用到 @fugle/marketdata 以及 @line/bot-sdk 套件。請確認已經安裝 Node.js 開發環境，並在 Terminal 執行以下指令：

$ npm install --save @fugle/marketdata @line/bot-sdk dotenv js-yaml luxon numeral

主程式

我們將使用 Node.js 及一些相關的套件和模組來實現這個到價提醒功能。以下是程式碼的主要結構和流程：

'use strict'

// 引入所需的套件和模組
require('dotenv').config();
const fs = require('fs');
const yaml = require('js-yaml');
const MessagingApiClient = require('@line/bot-sdk').messagingApi.MessagingApiClient;
const numeral = require('numeral');
const { DateTime } = require('luxon');
const { WebSocketClient } = require('@fugle/marketdata');

// 獲取環境變數設定
const apiKey = process.env.FUGLE_MARKETDATA_API_KEY;
const channelAccessToken = process.env.LINE_CHANNEL_ACCESS_TOKEN;
const userId = process.env.LINE_USER_ID;

// 主要邏輯執行區塊
async function main() {
  try {
    // 讀取設定檔
    const config = yaml.load(fs.readFileSync('./config.yml', 'utf8'));
    const alerts = new Map(Object.entries(config.alerts));

    // 建立 Line Messaging API Client 和 Fugle Market Data API 的 WebSocket 連接
    const messagingApiClient = new MessagingApiClient({ channelAccessToken });
    const client = new WebSocketClient({ apiKey });
    const stock = client.stock;

    // 監聽行情資料變化
    if (alerts.size) {
      const symbols = Array.from(alerts.keys());
      await stock.connect();
      stock.subscribe({ channel: 'aggregates', symbols });

      stock.on('message', (message) => {
        const { event, data } = JSON.parse(message);
        if (event === 'data') checkMatches(data);
      });
    }

    // 檢查符合條件的行情資料
    function checkMatches(data) {
      // 擷取行情資料中的相關數據
      const { symbol, lastTrade, lastUpdated } = data;
      if (lastTrade?.time !== lastUpdated) return;

      // 檢查符合條件的監控股票
      const alert = alerts.get(symbol);
      if (!alert) return;

      // 根據監控條件進行判斷
      const compare = {
        '>': (value, target) => value > target,
        '>=': (value, target) => value >= target,
        '=': (value, target) => value === target,
        '<=': (value, target) => value <= target,
        '<': (value, target) => value < target,
      };

      // 符合條件時，發送通知
      if (alert.type === 'price' && compare[alert.comparator](lastTrade.price, alert.target)) {
        sendAlert(alert, data);
      }
    }

    // 發送通知
    function sendAlert(alert, data) {
      // 擷取相關數據
      const { symbol, name, lastPrice, change, changePercent, lastUpdated } = data;

      // 格式化時間
      const time = DateTime
        .fromMillis(Math.floor(lastUpdated / 1000))
        .toFormat('yyyy/MM/dd HH:mm:ss');

      // 建構通知內容
      const message = [].concat([
        `<<${alert.title}>>`,
        `${alert.message}`,
        `---`,
        `${name} (${symbol})`,
        `成交: ${numeral(lastPrice).format('0.00')}`,
        `漲跌: ${numeral(change).format('+0.00')} (${numeral(changePercent).format('+0.00')}%)`,
        `時間: ${time}`,
      ]).join('\n');

      // 發送 Line Message
      messagingApiClient.pushMessage({
        to: userId,
        messages: [{ type: 'text', text: message }],
      });

      // 從監控清單中刪除該股票
      alerts.delete(symbol);
    }
  } catch (e) {
    console.log(e)
  }
}

// 執行主要邏輯
main();

實作細節

讓我們逐一解釋這段程式碼的實作細節：

引入套件和模組

程式碼一開始使用 require 關鍵字引入所需的套件和模組。這些套件和模組包括 dotenv、fs、js-yaml、@line/bot-sdk、numeral、luxon 和 @fugle/marketdata。這些套件和模組提供了讀取環境變數、操作檔案、解析 YAML 格式、使用 LINE Messaging API、格式化數字、處理日期和時間以及連接富果行情 API 的能力。

獲取環境變數設定

這段程式碼使用 process.env 物件從環境變數中讀取富果行情 API 金鑰和 LINE Messaging API 的 Channel Access Token 及您的使用者 ID。環境變數的設定可以在專案目錄下新增 .env 檔案中設定：

FUGLE_MARKETDATA_API_KEY=your_fugle_api_key
LINE_MESSAGING_API_ACCESS_TOKEN=your_line_messaging_api_token
LINE_USER_ID=your_line_user_id

然後透過 dotenv 套件來讀取 .env 檔案並將其設定載入到程式中。

主要邏輯執行區塊

主要的邏輯執行區塊是 main 函式，它使用 async/await 來聲明為非同步函式。程式的進入點在 main() 的呼叫。

在 main() 函式中，首先從檔案系統中讀取設定檔 config.yml。這個設定檔設定了你所要監控股票的條件，可以包含一個或多個。例如：

---
alerts:
  2330:
    title: 到價提醒
    message: 台積電突破1000元
    type: price
    comparator: ">"
    target: 1000

設定檔 config.yml 透過使用 yaml.load() 方法將其解析為 JavaScript 物件。然後，建立一個 Map 物件來存儲從設定檔中獲取的股票價格監控條件。

接下來，建立 LINE Notify 服務的客戶端實體 notify 和富果行情 API 的 WebSocket 連接客戶端物件 client，並且從中取得表示台股市場資料的 stock 物件。

如果有監控條件，則進行 WebSocket 連接、訂閱股票市場資料、並監聽市場資料的變化。當收到市場資料變化的訊息時，解析訊息並檢查是否符合監控條件，如果符合則呼叫 checkMatches() 函式。

checkMatches() 函式用於檢查市場資料是否符合監控條件。它擷取市場資料中的相關數據，例如股票代號、最後交易價格和最後更新時間。接著，根據監控條件中的股票代號和監控股價的目標值，檢查最後交易價格是否符合條件。如果符合條件，則呼叫 sendAlert() 函式發送通知。

sendAlert() 函式用於發送 LINE Message。它從市場資料中獲取相關數據，並使用 luxon 函式庫將最後更新時間轉換為指定格式的時間字串。然後，建立通知的內容字串，包括標題、訊息和股票資訊等。最後，使用 LINE Messaging API Client 的 messagingApiClient.pushMessage() 方法發送通知，並在成功或失敗時輸出相關訊息。完成通知後，從監控清單中刪除該股票。

錯誤處理

程式碼使用 try/catch 塊來捕獲可能發生的錯誤，並輸出錯誤訊息。如果有錯誤發生，將錯誤訊息輸出到控制台。

執行主要邏輯

最後，在程式碼的最後，呼叫 main() 函式開始執行主要的邏輯。這將觸發程式的運行，連接富果行情 API 的 WebSocket 服務並開始監控股票價格的變化。如果符合監控條件，則會透過 LINE Messaging API 發送通知。

執行程式

完成程式撰寫後，我們可以在終端機執行以下指令啟動應用程式：

$ node app.js

如果盤中到達你所設定的警示條件，程式就會透過 LINE Messaging API 即時發送通知。

圖18

關於完整的程式碼，請參考我們的在 GitHub 上的範例程式儲存庫。

結語

在本文中，我們介紹了如何使用 Node.js 實作一個股價監控程式，並結合 LINE Messaging API 來實現通知推播的功能。本程式透過富果行情 API 提供的股票市場資料，利用 WebSocket 進行即時監控，當符合特定條件的股價變動時，即時通知將會透過 LINE Messaging API 發送給使用者。

隨著 LINE Notify 服務即將於 2025 年 4 月停止運作，開發者若希望繼續透過 LINE 推送通知，需考慮轉移到 LINE Messaging API。儘管 Messaging API 提供了更豐富的功能和彈性，允許客製化通知方式，但其進階功能可能涉及額外費用。因此，開發者在考量功能擴展的同時，需評估升級方案的成本，選擇最適合系統需求與預算的解決方案，確保系統的順利運作。

什麼是 LINE Messaging API？​

事前準備​

圖解：取得富果行情 API 金鑰​

圖解：申請使用 LINE Messaging API​

實戰！到價提醒通知​

安裝套件​

主程式​

實作細節​

執行程式​

結語​