Notion API 핵심 개념 완벽 정리

Notion API를 활용한 데이터베이스 조작, 페이지 생성, 블록 관리 등 핵심 개념을 실전 코드로 정리했습니다. 고급 개발자를 위한 Notion 자동화 완벽 가이드입니다.

---

---

들어가며

이 글에서는 Notion API 핵심 개념 완벽 정리에 대해 상세히 알아보겠습니다. 총 12가지 주요 개념을 다루며, 각각의 개념에 대한 설명과 실제 코드 예제를 함께 제공합니다.

목차

1. Notion_Client_초기화
2. 데이터베이스_조회
3. 필터링_쿼리
4. 정렬_쿼리
5. 페이지_생성
6. 페이지_속성_업데이트
7. 블록_콘텐츠_추가
8. 블록_목록_조회
9. 데이터베이스_생성
10. 페이지_검색
11. 리치_텍스트_포맷팅
12. 에러_핸들링_패턴

---

1. Notion Client 초기화

개요

Notion API를 사용하기 위한 클라이언트 초기화 방법입니다. API 키를 환경변수로 관리하여 안전하게 인증합니다.

코드 예제

const { Client } = require('@notionhq/client');

const notion = new Client({
  auth: process.env.NOTION_API_KEY
});

console.log('Notion client initialized');

설명

@notionhq/client 패키지를 사용해 Notion 클라이언트를 생성하고, 환경변수에서 API 키를 불러와 인증합니다.

---

2. 데이터베이스 조회

개요

Notion 데이터베이스의 모든 항목을 조회하는 방법입니다. 페이지네이션을 활용해 대량의 데이터도 처리할 수 있습니다.

코드 예제

const databaseId = 'your-database-id';

const response = await notion.databases.query({
  database_id: databaseId,
  page_size: 100
});

const pages = response.results;

설명

databases.query 메서드로 데이터베이스를 조회하며, page_size로 한 번에 가져올 항목 수를 지정합니다.

---

3. 필터링 쿼리

개요

특정 조건에 맞는 데이터만 필터링하여 조회합니다. 속성값을 기준으로 정확한 데이터를 가져올 수 있습니다.

코드 예제

const response = await notion.databases.query({
  database_id: databaseId,
  filter: {
    property: 'Status',
    select: { equals: 'In Progress' }
  }
});

설명

filter 객체를 사용해 Status 속성이 'In Progress'인 항목만 조회합니다. 다양한 속성 타입에 맞는 필터를 적용할 수 있습니다.

---

4. 정렬 쿼리

개요

데이터베이스 항목을 특정 속성 기준으로 정렬하여 조회합니다. 오름차순/내림차순 정렬이 가능합니다.

코드 예제

const response = await notion.databases.query({
  database_id: databaseId,
  sorts: [
    { property: 'Created', direction: 'descending' }
  ]
});

설명

sorts 배열에 정렬 기준을 지정합니다. Created 속성을 기준으로 최신 항목부터 조회합니다.

---

5. 페이지 생성

개요

Notion 데이터베이스에 새로운 페이지를 생성합니다. 속성값과 콘텐츠 블록을 함께 추가할 수 있습니다.

코드 예제

const newPage = await notion.pages.create({
  parent: { database_id: databaseId },
  properties: {
    Name: { title: [{ text: { content: 'New Task' } }] },
    Status: { select: { name: 'To Do' } }
  }
});

설명

pages.create로 새 페이지를 생성하며, properties 객체에 각 속성의 값을 지정합니다.

---

6. 페이지 속성 업데이트

개요

기존 페이지의 속성값을 수정합니다. 상태 변경, 날짜 업데이트 등 다양한 속성을 변경할 수 있습니다.

코드 예제

const pageId = 'your-page-id';

await notion.pages.update({
  page_id: pageId,
  properties: {
    Status: { select: { name: 'Done' } }
  }
});

설명

pages.update 메서드로 페이지 ID를 지정하고, 변경할 속성만 properties에 포함시켜 업데이트합니다.

---

7. 블록 콘텐츠 추가

개요

페이지에 텍스트, 헤딩, 리스트 등 다양한 블록을 추가합니다. 리치 콘텐츠를 프로그래밍 방식으로 생성할 수 있습니다.

코드 예제

await notion.blocks.children.append({
  block_id: pageId,
  children: [
    {
      paragraph: {
        rich_text: [{ text: { content: 'Hello Notion!' } }]
      }
    }
  ]
});

설명

blocks.children.append로 페이지에 블록을 추가합니다. paragraph 타입의 블록을 생성하여 텍스트 콘텐츠를 추가했습니다.

---

8. 블록 목록 조회

개요

페이지의 모든 하위 블록을 조회합니다. 페이지 콘텐츠를 프로그래밍 방식으로 읽을 수 있습니다.

코드 예제

const blockId = 'your-block-id';

const response = await notion.blocks.children.list({
  block_id: blockId,
  page_size: 50
});

const blocks = response.results;

설명

blocks.children.list로 특정 블록의 하위 블록들을 조회합니다. 페이지의 전체 콘텐츠 구조를 파악할 수 있습니다.

---

9. 데이터베이스 생성

개요

새로운 Notion 데이터베이스를 프로그래밍 방식으로 생성합니다. 속성 스키마를 정의하여 맞춤형 데이터베이스를 만들 수 있습니다.

코드 예제

await notion.databases.create({
  parent: { page_id: parentPageId },
  title: [{ text: { content: 'Tasks DB' } }],
  properties: {
    Name: { title: {} },
    Status: { select: { options: [{ name: 'To Do' }] } }
  }
});

설명

databases.create로 새 데이터베이스를 생성하며, properties에서 각 컬럼의 타입과 옵션을 정의합니다.

---

10. 페이지 검색

개요

Notion 워크스페이스 전체에서 특정 키워드로 페이지를 검색합니다. 통합된 검색 기능을 제공합니다.

코드 예제

const response = await notion.search({
  query: 'project',
  filter: { property: 'object', value: 'page' },
  sort: { direction: 'descending', timestamp: 'last_edited_time' }
});

설명

search 메서드로 'project' 키워드를 포함한 페이지를 검색하며, 최근 수정된 순서로 정렬합니다.

---

11. 리치 텍스트 포맷팅

개요

볼드, 이탤릭, 링크 등 다양한 텍스트 스타일을 적용합니다. Notion의 리치 텍스트 형식을 활용한 고급 포맷팅이 가능합니다.

코드 예제

const richText = {
  rich_text: [{
    text: { content: 'Bold text', link: { url: 'https://notion.so' } },
    annotations: { bold: true, color: 'blue' }
  }]
};

설명

rich_text 객체에서 text 내용과 annotations로 스타일을 지정합니다. 링크, 색상, 볼드 등을 적용할 수 있습니다.

---

12. 에러 핸들링 패턴

개요

Notion API 호출 시 발생할 수 있는 에러를 안전하게 처리합니다. 재시도 로직과 적절한 에러 메시지를 제공합니다.

코드 예제

try {
  const page = await notion.pages.retrieve({ page_id: pageId });
} catch (error) {
  if (error.code === 'object_not_found') {
    console.error('Page not found');
  }
  throw error;
}

설명

try-catch 블록으로 API 에러를 처리하며, error.code로 에러 유형을 구분하여 적절한 처리를 수행합니다.

---

마치며

이번 글에서는 Notion API 핵심 개념 완벽 정리에 대해 알아보았습니다. 총 12가지 개념을 다루었으며, 각각의 사용법과 예제를 살펴보았습니다.

관련 태그

#JavaScript #NotionAPI #Database #Automation #Integration