노션 API와 Python으로 데이터 자동 수정하기｜페이지 조회부터 일괄 업데이트까지

노션 데이터베이스를 사용하다 보면 몇 개 정도는 직접 수정해도 괜찮지만, 데이터가 수백 건으로 늘어나면 같은 작업을 반복하기가 상당히 번거롭습니다.

예를 들어 상품 관리 데이터베이스에 판매중, 판매 종료, 확인 필요 같은 상태가 있고 특정 조건에 해당하는 페이지를 한꺼번에 확인 필요로 변경해야 한다고 해보겠습니다.

이런 작업은 Python과 Notion API를 연결하면 반복 작업을 줄일 수 있습니다.

이번 글에서는 복잡한 자동화보다 데이터베이스에서 페이지를 조회하고 조건에 맞는 데이터의 속성을 수정하는 기본 흐름부터 살펴보겠습니다.

작업하기 전에 준비할 것

필요한 것은 크게 세 가지입니다.

Python 실행 환경 / Notion Integration / 수정할 데이터베이스

Notion Integration을 만든 뒤에는 해당 Integration이 작업할 페이지나 데이터베이스에 접근할 수 있도록 연결해줘야 합니다.

여기서 자주 생기는 실수가 있습니다.

API 토큰은 정상인데 요청하면 권한 관련 오류가 발생하는 경우입니다. 이때는 코드부터 고치기보다 Integration에 대상 페이지 접근 권한이 제대로 연결되어 있는지 먼저 확인하는 편이 좋습니다.

그리고 API 토큰은 블로그나 GitHub 등에 그대로 공개하면 안 됩니다.

Python에서 필요한 라이브러리 준비

이번 예제에서는 requests를 사용하겠습니다.

설치되어 있지 않다면 다음과 같이 설치합니다.

pip install requests

그다음 기본 설정을 만들어줍니다.

import requests

NOTION_TOKEN = "여기에_토큰을_직접_공개하지_마세요"
DATA_SOURCE_ID = "데이터_소스_ID"

headers = {
    "Authorization": f"Bearer {NOTION_TOKEN}",
    "Content-Type": "application/json",
    "Notion-Version": "현재 사용하는 API 버전"
}

실제로 운영할 때는 토큰을 코드에 직접 적기보다 환경변수로 관리하는 것이 안전합니다.

예를 들어 Windows나 서버 환경에 환경변수를 등록했다면 Python에서는 다음처럼 가져올 수 있습니다.

import os

NOTION_TOKEN = os.getenv("NOTION_TOKEN")

이렇게 해두면 소스코드를 공유하더라도 토큰이 그대로 노출되는 사고를 줄일 수 있습니다.

예제 데이터베이스는 이렇게 만들었습니다

이번에는 업무 데이터가 다음과 같이 있다고 가정하겠습니다.

업무명	상태	담당자
상세페이지 수정	진행중	김담당
상품정보 확인	대기	이담당
가격 업데이트	대기	박담당

목표는 간단합니다.

상태가 대기인 페이지를 찾아 확인 필요로 변경해보겠습니다.

이렇게 작은 예제로 먼저 테스트한 다음 실제 데이터베이스에 적용하는 것이 안전합니다.

데이터 조회하기

Notion API의 현재 데이터베이스·데이터 소스 구조는 API 버전에 따라 엔드포인트와 응답 구조가 달라질 수 있습니다.

따라서 아래 코드는 흐름을 이해하기 위한 예제로 보고, 실제 적용할 때는 사용 중인 Notion API 버전의 공식 문서에서 조회 엔드포인트를 확인해야 합니다.

url = f"https://api.notion.com/v1/data_sources/{DATA_SOURCE_ID}/query"

response = requests.post(
    url,
    headers=headers,
    json={}
)

response.raise_for_status()

data = response.json()

for page in data["results"]:
    print(page["id"])

여기까지 정상적으로 실행되면 조회된 페이지 ID가 출력됩니다.

페이지 ID는 이후 특정 페이지의 속성을 수정할 때 사용합니다.

상태가 ‘대기’인 데이터만 찾아보기

바로 업데이트하기 전에 어떤 데이터가 변경 대상인지 출력부터 해보는 것을 권합니다.

예를 들어 상태 속성이 status 타입이라면 다음처럼 확인할 수 있습니다.

for page in data["results"]:
    status = page["properties"]["상태"]["status"]

    if status and status["name"] == "대기":
        print("수정 대상:", page["id"])

여기서 출력되는 페이지가 실제로 수정하려던 데이터와 일치하는지 확인합니다.

저라면 이 단계를 생략하지 않습니다.

조건문을 잘못 작성한 상태에서 바로 업데이트 요청까지 실행하면 원하지 않는 페이지까지 대량으로 변경될 수 있기 때문입니다.

실제 상태를 업데이트해보기

대상이 정확한 것을 확인했다면 페이지 업데이트 요청을 보낼 수 있습니다.

def update_status(page_id):
    url = f"https://api.notion.com/v1/pages/{page_id}"

    payload = {
        "properties": {
            "상태": {
                "status": {
                    "name": "확인 필요"
                }
            }
        }
    }

    response = requests.patch(
        url,
        headers=headers,
        json=payload
    )

    response.raise_for_status()
    return response.json()

그리고 앞에서 확인한 조건과 연결합니다.

for page in data["results"]:
    status = page["properties"]["상태"]["status"]

    if status and status["name"] == "대기":
        update_status(page["id"])
        print("수정 완료:", page["id"])

정상적으로 처리되었다면 예제 데이터는 다음처럼 바뀌게 됩니다.

업무명	수정 전	수정 후
상세페이지 수정	진행중	진행중
상품정보 확인	대기	확인 필요
가격 업데이트	대기	확인 필요

모든 페이지를 수정하는 것이 아니라 조건에 맞는 두 건만 변경하는 것이 이번 예제의 핵심입니다.

코드가 실행되지 않을 때 확인할 부분

실제로 API를 연결하면 코드 자체보다 인증이나 데이터 구조 때문에 막히는 경우가 많습니다.

401 오류가 발생한다면 먼저 토큰을 확인합니다. 잘못된 토큰을 사용했거나 Authorization 헤더가 정상적으로 전달되지 않았을 가능성이 있습니다.

403 오류라면 Integration의 접근 권한을 살펴봅니다.

404 오류라고 해서 페이지가 무조건 삭제된 것은 아닙니다. ID가 잘못됐거나 Integration에서 해당 리소스에 접근하지 못하는 상황도 확인해야 합니다.

400 오류가 발생한다면 요청 JSON과 실제 노션 속성 타입이 맞는지 살펴보세요.

예를 들어 상태가 실제로는 select 속성인데 코드에서 status 형식으로 요청하면 정상적으로 처리되지 않습니다.

그래서 다른 데이터베이스에서 코드를 그대로 복사하기보다 현재 데이터베이스의 속성 이름과 타입을 먼저 확인하는 것이 중요합니다.

데이터가 많으면 한 번 조회로 끝나지 않습니다

테스트 데이터가 몇 건뿐이라면 위 코드로 개념을 이해할 수 있지만 실제 데이터베이스가 커지면 한 번의 요청으로 모든 페이지를 처리한다고 가정하면 안 됩니다.

Notion API 조회에는 페이지네이션이 적용될 수 있으므로 응답의 다음 페이지 정보를 확인하면서 추가 요청을 보내는 구조가 필요합니다.

또한 짧은 시간에 지나치게 많은 요청을 보내면 제한에 걸릴 수 있습니다.

대량 수정 작업이라면

조회 → 수정 대상 선별 → 소량 테스트 → 업데이트 → 결과 기록

순서로 처리하는 것이 안전합니다.

처음부터 500건을 수정하지 마세요

자동 수정에서 가장 조심해야 할 부분입니다.

코드가 정상적으로 실행된다는 것과 코드가 내가 원하는 데이터만 정확하게 수정한다는 것은 다른 문제입니다.

예를 들어 조건문 하나를 잘못 작성하면 10개를 수정하려다 수백 개를 변경할 수도 있습니다.

그래서 실제 데이터에 적용하기 전에는 테스트 데이터베이스를 만들거나 수정 대상을 몇 건으로 제한해 실행해보는 편이 좋습니다.

또 대량 변경 전에는 필요한 경우 원본 데이터를 백업해두는 것이 안전합니다.

제가 추천하는 자동 수정 구조

단순히 조회 → 바로 수정하는 것보다 다음 구조가 관리하기 좋습니다.

1. 데이터 조회

↓

2. 수정 조건 검사

↓

3. 수정 예정 데이터 출력

↓

4. 대상 확인

↓

5. API 업데이트

↓

6. 성공·실패 결과 기록

이렇게 하면 문제가 발생했을 때 어느 단계에서 잘못됐는지 찾기도 쉽습니다.

특히 자동화 작업에서는 성공한 데이터뿐 아니라 실패한 페이지 ID와 오류 메시지를 로그로 남겨두는 것이 중요합니다.

마무리

Notion API와 Python을 연결하는 목적은 단순히 코드를 사용하는 데 있지 않습니다.

매주 반복해서 상태를 변경하거나, 외부 시스템에서 받은 데이터를 정리하거나, 특정 조건에 맞는 페이지를 일괄 수정해야 할 때 특히 유용합니다.

처음에는 3~5개의 테스트 데이터로 조회 → 조건 확인 → 한 건 수정까지 성공시키는 것을 목표로 해보세요.

그다음 페이지네이션, 예외 처리, 실행 로그 등을 추가하는 방식으로 확장하는 것이 대량 데이터를 처음부터 한 번에 수정하는 것보다 안전합니다.