[SK 쉴더스 루키즈] Notion API 연동 실습

Notion Database

노션에는 데이터베이스가 있다. 데이터베이스에는 고유 ID가 있기 때문에, 파이썬 코드를 이용해 데이터베이스를 조작할 수 있다. 노션 애플리케이션에도 ID를 확인할 수 있지만, 웹을 통해 ID를 확인하는게 가장 정확한 것 같다.

 

실습에 사용한 것은 데이터베이스 ID, 데이터베이스 소스 ID를 사용했다.

 

URL로 알아보는 데이터베이스 고유 ID

 

실습에는 다음의 데이터베이스를 사용했다.

상품 재고 관리 DB

파란색 New 메뉴 바로 옆에 ID를 확인할 수 있는 버튼이 있으니 참고하길 바란다.

 

 

Notion API와 JSON

노션은 코드로 접속할 수 있도록 API 명세서를 docs로 적어 놓고 있다.

https://developers.notion.com/guides/get-started/overview

Overview - Notion Docs

 

이것이 데이터베이스에서 데이터를 조회하는 HTTP 명령 구조이다. 파이썬 코드를 이용해 다음과 같은 HTTP 패킷 구조를 만들고 전송하면 데이터베이스 값을 받아볼 수 있다.

 

 

Notion 데이터베이스 연동 실습

1️⃣ 원소 조회하기

 

원소 조회하기의 핵심은 다음과 같다.

1. .env 파일을 이용해 통신할 때 필요한 Token과 DB_ID를 안전하게 관리하기.

2. Notion API Docs에 나와 있는 대로 requests header를 미리 설계한다.

3. try - catch 구문을 이용해 오류를 잡아낸다.

4. response는 대부분 JSON이다. JSON은 기본적으로 Dict와 유사하므로 키값를 잘 판단해 원하는 값을 도출한다.

 

조회한 결과값

 

import os
import requests
from dotenv import load_dotenv

load_dotenv()

NOTION_TOKEN = os.getenv("NOTION_KEY")
DB_ID = os.getenv("DATABASE_ID")

if not NOTION_TOKEN or not DB_ID:
    raise ValueError("TOKEN 값 없음!")

url = f"https://api.notion.com/v1/databases/{DB_ID}/query"

header = {
    "Authorization": f"Bearer {NOTION_TOKEN}",
    "Notion-Version": "2022-06-28",
    "Content-Type": "application/json"
}

try:
    response = requests.post(url, headers=header, timeout=10)
    response.raise_for_status()

    data = response.json()
    page_list = data.get("results")

    for page in page_list:
        props = page.get("properties")
        price = props.get("금액", {}).get("number", 0)
        qty = props.get("재고 수량", {}).get("number", 0)
        total_price = props.get("총금액", {}).get("formula", {}).get("number", 0)
        
        title = props.get("상품명", {}).get("title", [])
        name = title[0].get("text", {}).get("content", "Error")

        print(price, qty, total_price, name)

except Exception as e:
    print(e)

curl -X POST https://api.notion.com/v1/data_sources/248104cd477e80afbc30000bd28de8f9/query \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2026-03-11" \
	--data '{
	  "filter": {
      "property": "Last ordered",
      "date": {
        "past_week": {}
      }
		}
	}'

 

 

2️⃣ 원소 생성하기

데이터베이스 내에 원소를 생성하기 위해선 parents 데이터와 properties 데이터가 필요하다. parents 데이터는 원소를 넣을 데이터베이스 ID다. properties는 데이터베이스 안에 집어 넣을 데이터의 형식이다.

 

공식 문서에서 나온 curl 요청 형식에 오류가 있었다. 공식 문서에서 지정하는 parent 형식으로 맞췄는데, parent JSON 안에 있는 "database_source_id" 키는 특수한 상황에서만 동작하는 키 형식이라 오류가 계속 났었다. 이 키 대신 "database_id" 키를 사용하니 문제 없이 JSON 파싱이 이루어졌다.

 

공식 문서대로 해도 안되는 경우가 있음을 배웠다. 최신 버전의 경우 제시한 방법이 안될 수도 있으니 유의하자.

 

원소 생성하기의 핵심은 다음과 같다.

1. 원소 조회하기와 코드 구조는 같다. 다만 생성하고자 하는 원소의 정보를 payload로 구현해야 한다.

2. payload를 구현할 때는 데이터베이스의 구조와 일치해야 한다.

 

생성한 결과값

 

import os
import requests
from dotenv import load_dotenv

load_dotenv()

NOTION_TOKEN = os.getenv("NOTION_KEY")
DB_ID = os.getenv("DATABASE_ID")
DB_SOURCE_ID = os.getenv("DATABASE_SOURCE_ID")

if not NOTION_TOKEN or not DB_ID:
    raise ValueError("TOKEN 값 없음!")

url = f"https://api.notion.com/v1/pages"

header = {
    "Authorization": f"Bearer {NOTION_TOKEN}",
    "Content-Type": "application/json",
    "Notion-Version": "2026-03-11"
}

payload = {
    "parent" : {
        "database_id" : DB_ID
    },
    "properties" : {
        "상품명" : {
            "type" : "title",
            "title" : [ {"type" : "text", "text" : {"content" : "BBQ 황금올리브치킨"}} ]
        },
        "재고 수량" : {
            "type" : "number",
            "number" : 23
        },
        "금액" : {
            "type" : "number",
            "number" : 23000
        }
    }
}

try:
    response = requests.post(url, headers=header, json=payload, timeout=10)
    data = response.json()
    print(data)
except Exception as e:
    print(e)

 

 

3️⃣ 원소 정렬 및 필터링 하기

Notion Query API를 이용해 데이터베이스 원소들의 관계를 변경하여 조회할 수 있다. 원소 생성하기 때 requests에 생성하고자 하는 데이터를 JSON으로 전달한 것과 마찬가지로, 보고자 하는 원소들의 관계를 payload로 생성해 전달한다.

 

쿼리 API이기 때문에 데이터베이스의 원본은 바뀌지 않고 정렬된 값만 조회 된다.

 

정렬한 데이터베이스 원소값

 

import os
import requests
from dotenv import load_dotenv

load_dotenv()

NOTION_TOKEN = os.getenv("NOTION_KEY")
DB_ID = os.getenv("DATABASE_ID")

if not NOTION_TOKEN or not DB_ID:
    raise ValueError("TOKEN 값 없음!")

url = f"https://api.notion.com/v1/databases/{DB_ID}/query"

header = {
    "Authorization": f"Bearer {NOTION_TOKEN}",
    "Notion-Version": "2022-06-28",
    "Content-Type": "application/json"
}

try:
    response = requests.post(url, headers=header, timeout=10)
    response.raise_for_status()

    data = response.json()
    page_list = data.get("results")

    for page in page_list:
        props = page.get("properties")
        price = props.get("금액", {}).get("number", 0)
        qty = props.get("재고 수량", {}).get("number", 0)
        total_price = props.get("총금액", {}).get("formula", {}).get("number", 0)
        
        title = props.get("상품명", {}).get("title", [])
        name = title[0].get("text", {}).get("content", "Error")

        print(price, qty, total_price, name)

except Exception as e:
    print(e)

 

소감

파이썬과 API를 이용해 다른 웹 애플리케이션의 데이터를 바꾸는 것이 흥미롭다. 이런 것들을 연습해서 생산성을 높이는 나만의 코딩 환경도 구축할 수 있을 것 같다.