botrun_keys_mgr

波特人 API 金鑰管理套件

概述

這是一個專門為波特人（botrun）用戶管理 API 金鑰申請和存取控制的 Python 套件。本套件提供 API 介面來查詢和驗證金鑰資訊，整合了 Google 表單進行申請，並使用 Google 試算表進行金鑰管理。

功能特色

• 提供 Python API 介面查詢金鑰資訊
• 透過 Google 表單管理 API 金鑰申請
• 金鑰驗證與確認
• 追蹤使用者電子郵件和金鑰啟用時間
• 整合 Google 試算表作為資料儲存

快速開始

安裝

pip install botrun-keys-mgr

可用功能

本套件提供以下主要功能：

1. 查詢金鑰資訊

from botrun_keys_mgr import KeyManager

# 初始化金鑰管理器
key_manager = KeyManager()

# 查詢金鑰資訊
key_data = key_manager.get_key_info("your-api-key")

if key_data:
    # 取得申請單位資訊
    print(f"申請單位：{key_data.department}")
    
    # 取得申請人資訊
    print(f"申請人：{key_data.applicant_name}")
    print(f"Email：{key_data.applicant_email}")
    print(f"申請事由：{key_data.purpose}")
    
    # 取得金鑰資訊
    print(f"處理 RD：{key_data.processor}")
    print(f"發放時間：{key_data.key_time}")
    print(f"申請時間：{key_data.timestamp}")
    
    # 取得備註（如果有的話）
    if key_data.note:
        print(f"備註：{key_data.note}")
else:
    print("找不到此金鑰資訊")

前置需求

Google Service Account 設定

1. 本套件需要一組具備 Google 試算表讀取權限的 Google Service Account
2. 請確保您有此 service account 的金鑰檔案（JSON 格式）
3. 設定環境變數：

export GOOGLE_APPLICATION_CREDENTIALS="./keys/google_service_account_key.json"

注意：請將金鑰檔案放在專案的 keys 目錄下，並命名為 google_service_account_key.json

申請流程

使用者可以透過以下流程申請 API 金鑰：

1. 透過內部 API 金鑰申請表單提交申請（表單連結請洽管理員）
2. 填寫必要資訊：
   • 申請單位
   • 申請事由
   • 申請人姓名
   • 申請人電子郵件
3. 管理員審核後會透過 Google 試算表記錄並管理金鑰資訊
4. 申請人可使用本套件的 API 介面查詢金鑰狀態

API 參考

KeyManager 類別

主要的金鑰管理類別，提供以下方法：

get_key_info(api_key: str) -> Optional[KeyData]

查詢指定 API 金鑰的資訊。

參數：

• api_key: 要查詢的 API 金鑰字串

回傳：

• 如果找到金鑰，回傳 KeyData 物件
• 如果找不到金鑰，回傳 None

KeyData 類別

金鑰資訊的資料類別，包含以下欄位：

from botrun_keys_mgr import KeyData

key_data = KeyData(
    timestamp="2024/1/22 上午 8:55:54",  # 申請時間戳記
    department="申請單位",               # 申請單位名稱
    purpose="申請事由",                 # 申請用途說明
    applicant_name="申請人姓名",        # 申請人姓名
    applicant_email="申請人Email",      # 申請人電子郵件
    processor="處理RD",                # 處理此申請的 RD
    key_time="2024/1/22",             # 金鑰發放時間
    api_key="sk-xxxxxxxxxxxxxxxx",     # API 金鑰
    note="備註（選填）"                 # 額外備註
)

資料儲存

系統使用 Google 試算表作為資料庫，追蹤和管理金鑰資訊：

• API 金鑰
• 關聯的電子郵件地址
• 金鑰啟用時間戳記

開發指南

開發環境安裝

1. 確保您已安裝 Python 3.11+ 和 Poetry
2. Clone 此專案：

git clone [repository_url]
cd botrun_keys_mgr

3. 使用 Poetry 安裝依賴：

poetry install

功能測試

本專案提供自動化測試來確保功能正常：

1. 金鑰查詢功能測試：
   • 測試有效金鑰查詢
   • 測試無效金鑰處理
   • 測試資料欄位解析

執行測試的方式：

使用 Poetry 執行測試：

poetry run python -m unittest discover -s tests

或者在 VS Code 中：

1. 開啟命令選擇（F1 或 Cmd+Shift+P）
2. 選擇 "Testing: Focus on Python Test Explorer"
3. 點擊測試檔案旁的執行按鈕

主程式測試

您可以執行主程式來測試金鑰查詢功能：

1. 確保已正確設置 service account 金鑰：

   • 建立 keys 目錄
   • 將金鑰檔案放入 keys/google_service_account_key.json

2. 使用 Poetry 執行：

poetry run python -m botrun_keys_mgr

主程式會：

• 連接到 Google Sheets API
• 測試查詢範例金鑰
• 顯示查詢結果

授權條款

[授權資訊待補充]