在 Day 3，我們認識了 Notion API，知道它能夠存取 Pages、Databases 與 Blocks。今天，我們要進入實作 - 完成專案的基礎建置：準備好 Python / VS Code 環境、設定 GitHub 版控、建立 Notion Integration，最後用一個小測試確認 API 能正常運作。

Step 1. 確認 Python 與 Pip

在開始寫程式前，我們需要先把環境準備好，方便安裝後續需要的套件。
以下將用Macbook示範

# macOS 通常自帶 Python，但建議確認版本是否 ≥ 3.9：
python3 --version

# 同時確認 pip 是否可用：
pip3 --version

Step 2. 設定 VS Code (Visual Studio Code)

• 前往 Visual Studio Code 官網下載並安裝。
• 安裝必要擴充套件
  在 VS Code Extensions Marketplace 搜尋並安裝以下套件：
  • Python：必備，用來支援 Python 開發（Lint、Debugger、虛擬環境選擇）。
  • Pylance：強化 IntelliSense 與語法提示，讓 Python 編輯更順暢。
  • Git Graph
  • Github Copilot
    
    
    
    
• 建立專案資料夾：

  mkdir notion-llm-assistant
  cd notion-llm-assistant
  mkdir src
  touch README.md
  

• 建立虛擬環境 (venv)：

  python3 -m venv venv
  source venv/bin/activate   # 啟用虛擬環境
  

  成功後，Terminal 左邊會出現 (venv)。
• 安裝必要套件：

  pip install requests python-dotenv
  

• 匯出套件列表，建立 requirements.txt：

  pip freeze > requirements.txt
  

  
• 以上完成後，專案結構會長這樣：

notion-llm-assistant/
├── src/
├── .env
├── requirements.txt
└── README.md

Step 3. 設定 Notion API Token

在我們開始串接 API 之前，需要先拿到一組 Integration Token（也就是 API Key）。這組 Token 相當於是「Bot 身份證」，能代表你去存取 Notion 資料。

3.1 建立 Integration

1. 前往 Notion Integrations
2. 點選 + New Integration
   
3. 填寫基本資訊，完成後點選Save：
   • Name：給這個 Integration 取的名稱，可隨意命名，但需注意不可包含 “Notion“ 字串
   • Associated Workspace：選擇你要使用的 Notion 工作區
   • Type：選擇 Internal
     
4. 成功後會出現「Integration successfully created」視窗，點選下方「Configure integration settings」進入 Notion Integration 管理頁面
   

3.2 Integration 管理頁面設定

Configuration

• Integration Name：上一步的設定名稱。
• Internal Integration Secret：這是一組 API Token，相當於「金鑰」，讓外部應用程式（例如你 Python 寫的程式）能用這個身分去存取 Notion。
  ⚠️ 安全提醒：這組 Token 相當於「Bot 的身分證」，不能公開，請放在 .env。
  
• Capabilities：決定 Bot 能不能存取與修改 Notion 頁面與資料庫:
  • 依照本系列的需求勾選前三項，表示：
    • 這個 Integration 可以完整讀寫筆記（抓取舊的、新增新的、更新既有的）。
    • 也可以辨識使用者身分（例如誰建立、誰修改）。
    • 目前沒有啟用 Comment 功能，所以 Bot 不會管頁面留言。
      
  • 完整權限項目說明如下：

Access

設定 Integration 的存取範圍

• 點擊 + Select pages。
• 選擇你要讓這個 Integration 能夠存取的頁面。
• 通常會選擇一個「根 Page」（例如：Nikki’s Hub），然後這個 Page 底下的子頁面都會一併被授權。
• 選完後，在這裡會出現一個列表，顯示授權的頁面名稱。
• 之後你寫程式用 API 抓資料時，就只能存取這些頁面，其他未授權的 Page 會完全不可見。
  

Basic information

• Integration Name：同樣是 LLM_Assistant。
• Type：
  • Internal：僅限自己工作區，簡單安全。
  • Public：需要 Notion 官方審查，適合 SaaS 應用。
    

Webhooks

• Webhook 可以在 Notion 發生事件時（例如某頁被新增/更新）即時通知你。
• 適合用來做即時同步，不必定時輪詢 API。
  

3.3 建立 .env 檔

• 在專案根目錄新增 .env，並貼上API Token

NOTION_TOKEN=secret_xxxxxxx

• Python 讀取範例：

from dotenv import load_dotenv
import os

load_dotenv()
notion_token = os.getenv("NOTION_TOKEN")

Step 4. 加入 Git 與 GitHub 版控

一個好的專案除了程式碼要能執行，也需要良好的版控，方便追蹤變更、團隊協作，以及公開參賽用的程式碼展示。以下會示範如何把你 MacBook 上的專案資料夾推到 GitHub。

1. 初始化 Git 專案

• 在你的專案資料夾裡開啟 Terminal，執行：

  git init
  

  這樣就會在資料夾裡生成 .git 隱藏資料夾。
• 建立 Git 的使用者名稱與 Email

  git config user.name "Nikki Chen"
  git config user.email "your_github_email@example.com"
  

2. 建立 .gitignore

• 避免把虛擬環境、環境變數檔案推上去。新增一個 .gitignore 檔：

#Python venv
venv/
__pycache__/

#VSCode
.vscode/

#Environment files
.env

3. 連線到 GitHub

• 到 GitHub 建立一個新 repository，例如：notion-llm-assistant
• 加上 GitHub 的遠端連線（這裡把網址換成你 GitHub repo 產生的）

git remote add origin https://github.com/your-username/notion-llm-assistant.git

• 檢查 remote 是否連上：

git remote -v

會看到類似：

origin  https://github.com/your-username/notion-llm-assistant.git (fetch)
origin  https://github.com/your-username/notion-llm-assistant.git (push)

4. 加入並提交檔案

git add .
git commit -m "Initial commit: setup project structure"

5. 推送到 GitHub

git branch -M main
git push -u origin main

6. 驗證
到你的 GitHub repo 頁面，就可以看到剛剛推送的專案程式碼 🎉

Step 5. 測試 Notion API 連線

import requests, os
from dotenv import load_dotenv

load_dotenv()
token = os.getenv("NOTION_TOKEN")

url = "https://api.notion.com/v1/users/me"
headers = {
    "Authorization": f"Bearer {token}",
    "Notion-Version": "2022-06-28"
}

res = requests.get(url, headers=headers)
print(res.json())

• 程式碼說明

  • requests：Python 的 HTTP 請求套件，用來呼叫 Notion API。
  • os：存取系統環境變數，例如 .env 裡的 Token。
  • dotenv：讓 Python 可以讀取 .env 檔，把環境變數載入進程中。
  • load_dotenv()：讀取 .env 檔，裡面存放 NOTION_TOKEN=xxxxxx。
  • os.getenv("NOTION_TOKEN")：把 NOTION_TOKEN 這個值取出來，存在變數 token 裡。這樣可以避免把 Token 寫死在程式碼裡，提高安全性。
  • url：設定 API endpoint，/v1/users/me 是官方推薦的「測試 API」，用來檢查 Token 是否能正常存取 Notion。
  • headers：HTTP 請求標頭。
  • Authorization：帶上 Bearer <token>，告訴 Notion 這是合法的 Bot 身份。
  • Notion-Version：指定 API 版本，確保行為一致。
  • requests.get(...)：發送 GET 請求到 Notion API。
  • res.json()：把 API 回傳的 JSON 轉成 Python 字典，印出來。

• 如果一切正常，你會看到類似以下輸出：

{
  "object": "user",
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "bot",
  "bot": {
    "owner": {
      "type": "workspace",
      "workspace": true
    }
  },
  "name": "My Integration"
}

這段程式碼的目的就是測試 Token 是否有效。
如果成功，代表：

• .env 檔讀取成功
• Token 帶入 API 正確
• 你的 Integration 有至少「存取工作區」的基本權限

小結與下篇預告

今天，我們完成了專案的第一個「落地步驟」：

• 確認 Python 環境
• 設定 VS Code 與虛擬環境
• 建立並設定 Notion Integration
• 使用 Git/GitHub 建立版控
• 測試 API 連線

這些準備，確保我們的專案有 乾淨的環境、穩定的版控、安全的金鑰管理，能讓接下來的開發更順利。

在 Day 5，我們會進一步進行：
👉 實作抓取 Notion Page / Database 資料，把真實的筆記拉出來，並開始設計資料清洗策略，讓後續的 LLM 能更好地理解與檢索。