[Notion API] 리소스 업로더 만들어보기 - 1 (API 연결, Database Query)

나는 이렇게 처음 노션API를 접했다. 회사에 프론트엔드 엔지니어가 없어서, 데이터를 관리할 수 있는 툴이 없었다. 그렇다고 매번 리소스 변경할 때마다 앱 업데이트를 할 수도 없었기 때문에, 뭔가를 만들어야 했다. 몇 가지 방법이 있긴하다.

 

1. Winform

윈폼은 윈도우에서 제공하는 애플리케이션 생성 환경이다. 이걸로 리소스 업로더를 만들자니, 맥에서는 실행할 수 없고, 깔끔하게 만들기도 쉽지 않다. 윈폼 프로젝트 구성 자체도, 물론 내가 몰라서 그런거겠지만, 상당히 불편하고 관리하기 쉽지않게 만들어져있다.

2. 웹 제작

어차피 node.js를 사용할거라면, 웹을 제작하는 방법도 있다. 하지만 이것도 윈폼과 비슷한 문제가 있다. 웹을 만들기 위해 많은 공부를 해야하고, 결국 나밖에 할줄 모른다면, 프로젝트 운영 차원에서 마이너스 요인이라 생각한다.

3. Notion

회사의 다른 프로젝트에서 이미 사용한 적도 있고, 나 말고 다른 개발자 분도 다룰줄 알기 때문에 이 방법으로 통일하는게 운영적인 측면에서 좋다고 판단했다. 그래서 이 방법으로 리소스 업로더를 고도화하면 좋을 것 같다.

 

 

 

노션 페이지는 모두 API를 통해서 json object형태로 가져올 수 있다. 이걸 이용하면 노션 API로 정말 여러가지를 할 수 있다. 보통 리소스를 관리할 때는 테이블 형태로 관리하기가 편하기 때문에, Notion database를 활용하는 방법을 다뤄보겠다.

노션 Database에는 정말 많은 자료형이 있다. URL, 파일, 텍스트, 날짜, 등.. 이걸 이용하면 리소스 뿐만 아니라 운영 툴도 만들 수 있을 것 같다.

해당 글은 노션 공식 🔗API reference와 🔗스타트 가이드를 기반으로 작성했습니다. 노션 API를 활용할 수 있는 아이디어나, 구현하는데 더 좋은 방법이 있으시면 피드백 부탁드립니다 !

사용 언어 : JavaScript (node.js)

---

토큰 발급

먼저, 노션 개발자 페이지에 접속해서 API Token을 발급받아야 한다. 아래 페이지에 접속해서 로그인하고, 페이지 오른쪽 위 View my integration을 누른다.

Notion API

노션 개발자 페이지

그러면, Notion API를 사용할 워크스페이스를 선택하고, 필요한 정보를 입력 후 API 통합을 만든다.

노션 토큰 발급 절차

그러면, 토큰 키가 발급되는데, 나중에 사용할거니 복사해둔다. 그리고, 작업할 노션 페이지에 접속해서 아래 보이는 것처럼 아까 생성한 통합 이름으로 연결을 추가하면 된다.

노션 페이지 연결

그럼 이제 준비 끝이다.

 

---

노션 SDK 설치

npm install @notionhq/client

노션 클라이언트 준비

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

// initialize notion client
const notion = new Client({
    auth: process.env.NOTION_TOKEN,
})

토큰으로 노션 클라이언트를 인증해주자. 여기서 NOTION_TOKEN은 아까 개발자 페이지에서 발급받은 토큰이다.

 

---

Database Query

예시로 사용할 데이터베이스를 이렇게 만들어봤다. 일반적으로 데이터를 컨트롤할 때 자주 사용했던 걸 가져와봤다. 원리만 파악하면 다른 속성을 추가하는건 어렵지 않기 때문에, 이 정도만 작성했다.

노션 데이터베이스 예시

시작하기 전에, 데이터베이스의 id가 필요하다. 데이터베이스 오른쪽 위 ...을 눌러 보기 링크 복사하면 아래와 같이 해당 데이터베이스의 url이 나온다. 

https://www.notion.so/[데이터베이스 id]?v=…

노션 홈페이지 주소 바로 뒤에오는게 데이터베이스 id인데, 어디에 잘 적어두자.

 

데이터베이스 쿼리는 어렵지 않다. 아래 보이는 것처럼 API 자체는 직관적으로 만들어져있다. 여기서 database_id에 위에서 복사한 id를 넣어주면 된다.

const queryDatabase = async (database_id) => {
    const pages = await notion.databases.query({
        database_id: database_id,
    })

    console.log(`notionapis : loadDatabase - ${pages.results.length} database lines`)

    const {has_more, next_cursor, results } = pages;
    let resultList = [ ...results ];
    if(has_more)
    {
        await loadDatabaseWithCursor(database_id, next_cursor, resultList)
    }

    return resultList
}

 

이렇게 결과를 불러오면 엄청 많은 정보를 내려주는데, 그 중 우리가 필요한 값은 results.properties이다. 결과 값 안에는 아래 보이는 것처럼 많은 속성값이 있는데, 필요에 따라 래핑함수를 만들어서 사용하면 된다.

나는 이런 식으로 속성과 데이터베이스의 필드 이름을 파라미터로 받는 함수를 만들어서 사용하기 편하게 했다.

const getCheckbox=(properties, fieldName)=>{
    return properties[fieldName].checkbox
}

const getDateStart=(properties, fieldName)=>{
    return properties[fieldName].date?.start
}

const getDateEnd=(properties, fieldName)=>{
    return properties[fieldName].date?.end
}

const getFileName=(properties, fieldName)=>{
    return properties[fieldName].files[0]?.name
}

 

---

부가 기능

데이터베이스 query에는 filter와 sorts 기능이 있다. 말그대로 데이터를 필터해서 가져오는 기능과 정렬하는 기능이다.

 

나는 이렇게 래핑 함수를 만들고, 정렬 방향을 사전 정의해서 사용했다.

const queryDatabaseWithOrder = async (database_id, property, direction) => {
    const pages = await notion.databases.query({
        database_id: database_id,
        sorts:[{
            "property": property,
            "direction": direction
        }]  
    })

const SORT_DIRECTION = {
    ASCENDING: "ascending",
    DESCENDING: "descending"
}

 

두 가지 기능을 나눠서 테스트 해보자. 위에서 생성한 데이터베이스를 기준으로, select 속성을 가진 '선택'이라는 이름의 필드를 기준으로 내림차순 정렬을 시켰다.

const testOrder = async()=>{
    const database = await queryDatabase(databaseId);
    
    const databaseOrder = await queryDatabaseWithOrder(databaseId, '선택', SORT_DIRECTION.DESCENDING)
    
    console.log('############## database without order')
    database.forEach(x => {
        console.log(x.properties['선택'].select)
    })
    console.log('############## database with order')
    databaseOrder.forEach(x => {
        console.log(x.properties['선택'].select)
    })

    console.log('done loading databse!')
}

 

결과

notionapis : loadDatabase - 4 database lines
notionapis : loadDatabase - 4 database lines
############## database without order
{id: '61a3c32e-cefa-4b6a-8fae-24e0ac386cba', name: 'option 1', color: 'red'}
{id: 'de332ebe-7573-4a1f-987a-951a5a8e89e1', name: 'option 3', color: 'brown'}
{id: '65cda8d2-5c25-45a9-98a6-18f3b138ae32', name: 'option 2', color: 'green'}
{id: '61a3c32e-cefa-4b6a-8fae-24e0ac386cba', name: 'option 1', color: 'red'}
############## database with order
{id: 'de332ebe-7573-4a1f-987a-951a5a8e89e1', name: 'option 3', color: 'brown'}
{id: '65cda8d2-5c25-45a9-98a6-18f3b138ae32', name: 'option 2', color: 'green'}
{id: '61a3c32e-cefa-4b6a-8fae-24e0ac386cba', name: 'option 1', color: 'red'}
{id: '61a3c32e-cefa-4b6a-8fae-24e0ac386cba', name: 'option 1', color: 'red'}
done loading databse!

 

---

내용 검증

노션은 API 사용을 테스트하기 위한 포스트맨 서비스를 제공한다. Collections 탭에 들어가면 아래 사진에 보이는 것처럼 모든 API를 테스트 할 수 있다.

노션 API 포스트맨

Params탭에서 아까 복사한 데이터베이스 아이디와 Header에 노션 토큰을 집어넣고, 필요에 따라서 body에 filter 또는 sorts를 입력하면 같은 결과를 내려준다. 아까 node.js로 작성한 코드와 결과가 같은지 검증을 해보자.

노션 API 포스트맨 - Query Database

노션 API 포스트맨 - Query Database

 

---

후기

노션 API는 정말 유용하게 쓰는 것 중 하나이다. 이미 정리된 형태로 페이지를 보여주기 때문에 잘 활용하면 많은 걸 할 수 있겠다는 생각을 했다. 시간 컬럼도 있어서 이벤트 기간을 조절한다거나, 공지사항 같은 이미지 파일을 제어한다거나...

 

리소스 업로더나 컨텐츠 관리하는 용도로 사용하기 때문에 query 말고 다른 기능은 사실 사용할 일이 있나 모르겠다. 근데, 실제로 사용해보면 원리는 거의 다 비슷하다. 주의해야 할건, 당연하겠지만, 절대 라이브할 때 서비스에서 노션데이터를 직접적으로 읽지 않도록 해야한다. 노션 API는 빠르지도 않고, 안정성 측면에서도 검증되지 않았고, 여러가지 이유가 있겠지만, 웬만하면 데이터베이스를 가져와서 파일 서버에 올려서 사용하는 것이 좋다. 그리고, 로컬라이즈 테이블이나 외부로 공개해야할 데이터베이스, 또는 많은 양의 테이블이 필요한 경우에는 spreadsheet를 사용하는 것이 좋다. 아직 노션 테이블이 엑셀이나 Spreadsheet만큼 편한 수준은 아니다.

 

다음 글에서 작성한 스크립트를 어떻게 간편하게 실행하고, 파일관리를 어떻게 했는지 작성해보겠습니다~!

 

---

참고자료

GitHub - makenotion/notion-sdk-js: Official Notion JavaScript Client

Notion | Postman API Network

Database properties