노션 API를 공지사항에 적용해보면 어떨까?

💡 우연히 보게 된 화해 블로그의 Notion API 연동기.

잘 적용해보면 이리저리 쓰일 곳이 많을 것 같아서 백오피스 공지사항에 R&D 해보았다.

Notion API와 함께 정적 페이지로의 여정 – 화해 블로그 | 기술 블로그

---

관리자가 쓰기 쉬운 툴

우리 회사는 노션을 이미 사용 하고 있다. 스케쥴부터 공유 문서 등에서 모든 부서가 노션을 사용하고 있었으며, 그렇기에 노션 사용이 익숙할 것이라고 생각했다. 그렇지만 이미 백오피스에서 공지사항 입력 폼은 만들어 놓았었다.

그러나 아직 데이터베이스 공지사항에 셋팅 해놓지 않았고, 내용 입력에서는 아직 따로 텍스트 입력기 등의 라이브러리를 사용하지 않으므로 글자에 스타일 적용이 불가하다. 텍스트 입력기 라이브러리를 적용하면 되잖아? 싶지만 테이블 셋팅이 아직 안됐기에 노션 API를 적용해보기로 했다.

계획

저 위의 화해 블로그에 너무도 자세히 써져 있으므로 그대로 따라가기로 한다.

1. 노션 integration 추가
2. 원하는 페이지에 connection 추가
3. database 페이지 추가
4. properties 세팅
5. 데이터 추가
6. API를 통해 데이터 가져오기
7. 마크다운으로 변경
8. HTML 코드로 변경
9. 예쁘게 보여주기-💫

---

노션 API를 통해 데이터를 가져오기

@notionhq/client 를 사용한다.

const notion = new Client({ auth: token });

여기서 token은 integration 추가 시 받는 secret이다.

주의할 점

노션 API 호출은 서버 사이드에서만 가능하다.
클라이언트 사이드에서의 호출은 CORS ERROR를 일으킨다!

공지사항 리스트 가져오기

공지사항 리스트를 가져올 때는 필터해서 가져오는 기능이 필요했다.

1. 내가 보여줄 사이트에 관한 데이터
2. 공지사항 데이터
3. 노출 가능한 상태의 데이터
4. 노출일자에서 내림차순으로도 데이터를 가져올 수 있으면 좋겠다.

노션 리스트에서는 properties를 이용해서 쿼리를 할 수 있는데, 그 타입에 따라서 쿼리 하는 방법이 다르다.

// 단일 필터
filter: {
    property: '이름',
    [property type]: {
        [비교문]: '내용',
    },
}
// 다중 필터
filter: {
    and: [
        {
            property: '이름',
            [property type]: {
                [비교문]: '내용',
            }
        },
    ],
}

비교문은 property의 타입에 따라서 사용 방법이 다른 듯 하다.

노션 가이드에서는 찾질 못하였고, 코파일럿이나 ChatGPT에서 도움을 받는다면 쉽게 해결 할 수 있다.

sort하는 방법은 다음과 같다.

sorts: [
    {
        property: 'property 이름',
        direction: 'ascending or descending',
    },
],

limit를 지정 할 수 있다.

page_size: number | undefined

필요한 것들을 적용한 코드는 다음과 같다.

const response = await notion.databases.query({
  database_id: databaseId,
  page_size: !isNaN(Number(limit)) ? Number(limit) : undefined,
  filter: {
    and: [
      {
        property: '사이트',
        select: {
          equals: '백오피스',
        },
      },
      {
        property: '태그',
        select: {
          equals: '공지사항',
        },
      },
      {
        property: '상태',
        status: {
          equals: '노출',
        },
      },
      {
        property: '노출일자',
        date: {
          on_or_before: dayjs().format('YYYY-MM-DD'),
        },
      },
    ],
  },
  sorts: [
    {
      property: '노출일자',
      direction: 'descending',
    },
  ],
});

databaseId 는 해당 페이지의

https://www.notion.so/name/[databaseId]?.. 에서 확인 할 수 있다.

주의할 점

property의 이름이 달라지거나 타입이 달라지게 되면 쿼리에서 에러가 난다.
뭐 이렇게 쉽게 에러가 나지? 싶었지만, SQL에서 컬럼 이름이 변경되거나 타입이 변경되면 에러가 나는 것과 동일하다.

response를 콘솔에 찍어보면 다음과 같다.

// response
{
  object: 'list',
  results: [
    {
      object: 'page',
      id: 'page-id',
      created_time: '2024-05-23T02:30:00.000Z',
      last_edited_time: '2024-05-23T09:23:00.000Z',
      created_by: [Object],
      last_edited_by: [Object],
      cover: null,
      icon: null,
      parent: [Object],
      archived: false,
      in_trash: false,
      properties: [Object],
      url: 'https://www.notion.so/',
      public_url: null
    },
  ],
}

response만 찍어 봐서는 공지사항 리스트를 작성하기 위해 쓸만한 데이터가 하나도 없다.

여기서는 공지사항 세부 내용을 보기 위해 필요한 id만 건질 수 있다.

이외에 지정한 properties(컬럼들)를 보려면 properties를 보아야 한다.

타입 별로 구성되어 있는 데이터가 모두 다르니 꼭 찍어보기를 권한다.

공지사항 리스트를 구성하기 위한 데이터들을 얻었다!

const notices = response.results.map((result: any) => {
    return {
        id: result.id,
        title: result.properties['제목'].title[0].plain_text,
        category: result.properties['카테고리'].multi_select.map(
            (category: { name: string }) => category.name,
        ),
        displayedAt: result.properties['노출일자'].date.start,
    };
});

공지사항 세부 내용 가져오기

페이지 세부 내용을 가져와보면 끔찍한 JSON 데이터를 받아볼 수 있다.

const blocks = await notion.blocks.children.list({ block_id: pageId });

{
  object: 'list',
  results: [
    {
      object: 'block',
      id: '',
      parent: [Object],
      created_time: '2024-05-23T02:48:00.000Z',
      last_edited_time: '2024-05-23T10:51:00.000Z',
      created_by: [Object],
      last_edited_by: [Object],
      has_children: false,
      archived: false,
      in_trash: false,
      type: 'heading_2',
      heading_2: [Object]
    },
    {
      object: 'block',
      id: '',
      parent: [Object],
      created_time: '2024-05-23T02:48:00.000Z',
      last_edited_time: '2024-05-23T02:48:00.000Z',
      created_by: [Object],
      last_edited_by: [Object],
      has_children: false,
      archived: false,
      in_trash: false,
      type: 'heading_1',
      heading_1: [Object]
    },
    {
      object: 'block',
      id: '',
      parent: [Object],
      created_time: '2024-05-23T02:49:00.000Z',
      last_edited_time: '2024-05-23T02:49:00.000Z',
      created_by: [Object],
      last_edited_by: [Object],
      has_children: true,
      archived: false,
      in_trash: false,
      type: 'table',
      table: [Object]
    },
    {
      object: 'block',
      id: '',
      parent: [Object],
      created_time: '2024-05-23T02:48:00.000Z',
      last_edited_time: '2024-05-23T10:26:00.000Z',
      created_by: [Object],
      last_edited_by: [Object],
      has_children: false,
      archived: false,
      in_trash: false,
      type: 'code',
      code: [Object]
    },
    {
      object: 'block',
      id: '',
      parent: [Object],
      created_time: '2024-05-23T10:27:00.000Z',
      last_edited_time: '2024-05-23T10:27:00.000Z',
      created_by: [Object],
      last_edited_by: [Object],
      has_children: false,
      archived: false,
      in_trash: false,
      type: 'paragraph',
      paragraph: [Object]
    }
  ],
  next_cursor: null,
  has_more: false,
  type: 'block',
  block: {},
  request_id: ''
}

더 이상 알고싶지 않아졌다.

그 페이지에 어떤 내용이 쓰여질지 모르는데 paragraph, code, heading 등을 직접 정리해주고 싶지 않았다.

그래서 notion-to-md 를 사용한다.

우리는 저 데이터를 볼 필요가 없이 이게 마크다운으로 만들어 줄 것이다.

const mdBlocks = await n2m.pageToMarkdown(pageId);
const mdContent = n2m.toMarkdownString(mdBlocks).parent;

안타깝게도 제목 등 properties들은 리턴해주지 않는다.

그래서 다시 검색해준다.

const page = (await notion.pages.retrieve({ page_id: pageId })) as any;

예쁘게(?) 보여주기

마크다운을 그대로 보여줄 수 없으므로 HTML 코드로 만들어준다.

marked 를 사용하기로 했다.

const [content, setContent] = useState<string>('');

useEffect(() => {
    const convertMarkdownToHtml = async () => {
        const htmlString = await marked(notice.mdContent);

        setContent(htmlString);
    };

    convertMarkdownToHtml();
}, []);

return (
    <div dangerouslySetInnerHTML={{ __html: content }} />
);

tailwind를 사용하고 있어서 그런지 스타일이 적용되지 않아서 css 파일도 추가해주었다.

.markdown-body {
  font-family: Arial, sans-serif;
  line-height: 1.6;
  padding: 20px;
}

.markdown-body h1 {
  font-size: 2em;
  margin-bottom: 0.5em;
}

.markdown-body h2 {
  font-size: 1.75em;
  margin-bottom: 0.5em;
}

.markdown-body h3 {
  font-size: 1.5em;
  margin-bottom: 0.5em;
}

.markdown-body h4 {
  font-size: 1.25em;
  margin-bottom: 0.5em;
}

.markdown-body p {
  margin-bottom: 0.8em;
}

.markdown-body ul,
.markdown-body ol {
  margin: 0 0 1em 1.5em;
}

.markdown-body li {
  margin-bottom: 0.5em;
}

.markdown-body a {
  color: #0366d6;
  text-decoration: none;
}

.markdown-body a:hover {
  text-decoration: underline;
}

.markdown-body code {
  background-color: #f6f8fa;
  border-radius: 3px;
  font-size: 85%;
  padding: 0.2em 0.4em;
}

.markdown-body pre {
  background-color: #f6f8fa;
  border-radius: 3px;
  padding: 1em;
  overflow: auto;
}

.markdown-body blockquote {
  border-left: 0.25em solid #dfe2e5;
  padding: 0.5em 1em;
  color: #6a737d;
  background-color: #f6f8fa;
}

.markdown-body table {
  width: 100%;
  border-collapse: collapse;
  margin-bottom: 1em;
}

.markdown-body th,
.markdown-body td {
  border: 1px solid #dfe2e5;
  padding: 0.5em 1em;
}

.markdown-body th {
  background-color: #f6f8fa;
  font-weight: bold;
}

.markdown-body img {
  max-width: 100%;
  height: auto;
}

완성

사용 가능성

백오피스에 별다른 구현 없이 노션 페이지를 그대로 읽어 오는 것은 참 매력적인 방식인 것 같다. 속도 면에서도 아쉬운 부분은 없었고, 사용자가 익숙한 툴로 쉽게 입력 가능하다는게 제일 큰 장점으로 생각된다. 또한 쉬운 스타일 변경도 장점이다.

그러나 단점도 느껴졌다.

단점

• 사용자에게 조심성을 바라야 한다.
  • property가 바뀌면 바로 에러가 난다.
    • 데이터베이스 테이블이라고 생각하면 에러가 나는 것이 당연하지만, SQL처럼 어떠한 명령문을 쳐서 바뀌는게 아니기 때문에 너무 손쉽게 바뀔 수 있는 위험성이 있다.
    • property 변경은 꼭 개발부서에 확인 후 변경이 필요하다는 인지가 필요하다.
  • 수정 중인 글인지 확인 할 수 없다.
    • 찾아본 바로는 노션의 자동 저장 기능이 가장 대표적인 기능이기 때문에 그걸 끄는 방법은 제공하지 않는다고 한다.
    • Formula 함수를 이용 할 수는 있으나 완벽하게 원하는 함수를 구현 할 수 없다.
      • 예) if(now() > prop("노출일자") and prop("상태") == "노출", prop("Last edited time").dateAdd(1, "hours") > now(), false) : 수정 후 1시간 뒤 노출 등..
• 한 쿼리에 MAX LIMIT가 있다.
  • page_size에 undefined를 넣으면 100개까지의 리스트를 가져온다고 한다.
  • next_cursor등으로 페이지네이션을 구현 할 수 있으나, API 상에서 이전 페이지 데이터를 불러오기는 지원하지 않아 따로 구현이 필요하다.
    • 그러나 3페이지에서 5페이지로 이동이나 7페이지에서 4페이지의 이동 등은 구현하기 어렵다.
• 마크다운이나 HTML을 알아야 완벽히 원하는 페이지를 만들 수 있다.
  • 글자 색상 변경 등은 마크다운에서 지원하지 않으므로 HTML으로 작성해야 한다.
    • <span style="color:red;">글자</span> 등..
  • 다중 엔터 등..

위의 단점들을 이겨낼 수 있다면 사용 할 수 있을 것 같다.

많은 사람들이 사용할 예정인 공지사항보다는 일부 사람들만 사용하고 더 조심스럽게 다룰 내용같은 약관 등에 적합하다고 느꼈다.