文件
開啟 Studio

API 參考

finlab

本頁內容8

finlab 模組負責登入與憑證管理。在自己的電腦或 Colab 用瀏覽器登入一次,之後就會自動使用;伺服器、Docker、排程這類沒有瀏覽器的環境,改用環境變數憑證。

選哪個函式

你想做的事用這個
在自己的電腦登入一次,之後自動使用python -m finlab login
在 Python、Jupyter 或 Colab 裡登入finlab.login()
讓伺服器、Docker、排程不用瀏覽器也能使用python -m finlab token --env 產生的三個環境變數
查看登入狀態與方案python -m finlab status
在程式裡確認是否已登入、取得 tokenfinlab.get_token()
登出python -m finlab logout
從舊版 FINLAB_API_TOKEN 遷移python -m finlab migrate

程式在哪裡跑,就決定了怎麼登入。幫下面四台機器各選一種登入方式,看 FinLab 依序去哪裡找憑證:

互動關卡

登入方式配對:程式在哪裡跑,就用哪種登入

任務 1 / 3 點「自己的電腦」和「Google Colab」,各點一個對的登入方式

選對 0 / 4 台

「自己的電腦」要怎麼登入?

FinLab 依序找憑證

  1. 5 互動式登入 以上都沒有時,開瀏覽器登入

還沒有憑證,每次都要開瀏覽器登入。

四台機器的情境為示意;登入方式與找憑證的順序取自本頁。

在自己的電腦或 Colab 登入

本機電腦(推薦)

在終端機執行一次,之後同一台電腦的 Python 都會自動使用這份憑證:

python -m finlab login

或在 Python / Jupyter 中登入:

import finlab

# 1. 呼叫 login() 不帶參數
# 2. 瀏覽器會自動開啟 FinLab 登入頁面
finlab.login()

# 3. 登入成功後,憑證會儲存在 ~/.finlab/credentials.json
# 4. 之後使用不需要再次登入
  • 憑證儲存位置:~/.finlab/credentials.json
  • 有效期限:60 天(自動更新)

若瀏覽器登入失敗、被拒絕或逾時,finlab.login() 會拋出 finlab.exceptions.LoginError(RuntimeError 的子類別),不會再默默返回。

Google Colab

import finlab

finlab.login()  # 依畫面指示在瀏覽器完成登入

Colab 登入會使用 colab 這個名稱。第一次建立這筆登入紀錄時,會佔用一個 SDK 裝置名額;同一帳號已有同名紀錄時,再次登入會重用該紀錄。

函式

finlab.login

login(api_token) -> None

登錄量化平台。

不傳入參數時啟動瀏覽器登入,成功後憑證存於 ~/.finlab/credentials.json, 之後同一台機器會自動使用。Colab 同樣直接呼叫 finlab.login()。 無瀏覽器的環境(伺服器、排程)請在本機執行 python -m finlab token --env, 並設定 FINLAB_REFRESH_TOKEN、FINLAB_SESSION_ID、FINLAB_API_KEY。

參數

api_token str

已棄用的舊版 api_token,請改用瀏覽器登入。

可能的錯誤

LoginError

瀏覽器登入失敗、被拒絕或逾時。

查看 SDK 裝置名額

登入裝置管理頁,查看「已使用 X / Y 個裝置」與各筆登入紀錄:

  • X:目前已使用的 SDK 裝置名額。
  • Y:你的方案允許的 SDK 裝置上限。
  • 剩餘名額:Y 減 X。

請以這個頁面顯示的 Y 為準。使用條款中的「三台裝置或瀏覽器上線使用本網站」,不代表所有方案都有三個 SDK 裝置名額。

在伺服器、Docker、排程使用

沒有瀏覽器的環境不用呼叫 finlab.login()。先在已登入的本機匯出憑證:

python -m finlab token --env
# export FINLAB_REFRESH_TOKEN="..."
# export FINLAB_SESSION_ID="..."
# export FINLAB_API_KEY="..."

再把這三個值設成目標環境的環境變數(例如 docker-compose、GitHub Actions secrets、Cloud Functions 環境變數),程式中不需要呼叫 finlab.login():

from finlab import data

close = data.get('price:收盤價')  # 自動讀取 FINLAB_REFRESH_TOKEN 等環境變數

確認登入狀態與登出

在終端機查看狀態或登出:

python -m finlab status   # 顯示登入狀態與方案
python -m finlab logout   # 清除本機憑證並移除伺服器端 session

若曾設定環境變數憑證,登出時也請一併移除 FINLAB_REFRESH_TOKEN、FINLAB_SESSION_ID、FINLAB_API_KEY(以及舊版 FINLAB_API_TOKEN)。

在 Python 裡用 finlab.get_token() 確認是否已登入:

import finlab

try:
    token, token_type = finlab.get_token()
    print(f"✅ 已登入({token_type})")
except RuntimeError:
    print("❌ 未登入")
函式

finlab.get_token

get_token() -> tuple[str, str]

取得登錄會員的認證 token。

認證優先順序:

  1. ~/.finlab/credentials.json (新版 Firebase auth) → 返回 id_token
  2. FINLAB_ID_TOKEN 環境變數 (新版 Firebase auth) → 返回 id_token
  3. FINLAB_API_TOKEN 環境變數 (舊版) → 返回 api_token
  4. 互動式登入

回傳

tupletuple[str, str]

(token_string, token_type) where token_type is 'id_token' or 'api_token'

FinLab 怎麼找到你的憑證

方式優點缺點適用場景
瀏覽器登入(python -m finlab login / finlab.login())安全、方便、自動更新 Token需要瀏覽器本機開發、Jupyter、Colab
環境變數憑證(python -m finlab token --env)不需瀏覽器、不寫入程式碼需先在本機登入一次伺服器、Docker、排程、CI
FINLAB_API_TOKEN(已棄用)—已棄用,未來將移除請遷移

FinLab 會按照以下順序尋找認證資訊:

  1. FINLAB_REFRESH_TOKEN + FINLAB_SESSION_ID + FINLAB_API_KEY 環境變數(三個都設定時才生效)
  2. ~/.finlab/credentials.json:瀏覽器登入產生的憑證
  3. FINLAB_ID_TOKEN 環境變數:供瀏覽器 / Pyodide 執行環境使用
  4. FINLAB_API_TOKEN 環境變數:舊版 API Token(已棄用,會出現警告)
  5. 互動式登入:以上都沒有時啟動瀏覽器登入

常見問題

瀏覽器登入失敗怎麼辦?

finlab.login() 失敗時會拋出 LoginError 並附上處理方式。常見原因:

  1. 缺少 cryptography 套件

    pip install cryptography
  2. 無瀏覽器環境(如伺服器)

    • 在本機執行 python -m finlab login,再執行 python -m finlab token --env
    • 把輸出的 FINLAB_REFRESH_TOKEN、FINLAB_SESSION_ID、FINLAB_API_KEY 設為伺服器環境變數
  3. 登入逾時或防火牆阻擋

    • 重新執行 finlab.login(),並在時限內完成瀏覽器登入
    • 檢查網路設定
還在使用 FINLAB_API_TOKEN 怎麼辦?

執行 python -m finlab migrate 查看遷移步驟:本機改用 python -m finlab login,無瀏覽器環境改用 python -m finlab token --env 產生的三個環境變數,然後移除 FINLAB_API_TOKEN。

下一步

↑↓ 選擇 Enter 開啟 Esc 關閉