Notion API 자료조사

Jay Kim·2022년 9월 15일

Notion 용어

데이터베이스 : 실제 데이터베이스와 같은 테이블 개념
페이지 : 데이터베이스 안에 있는 각각의 Object (각각의 행 “object : “page”)

→ 데이터베이스를 쿼리할 때 수신되는 것은 페이지 배열

Notion API 활용

→ 노션을 코드로 접근해서 CMS 혹은 데이터베이스로 활용 가능

Untitled

Notion API의 중요 기능 2가지
- Exchange information with other apps ( 다른 앱과 정보 교환)
  - 다른 앱에서 정보가 업데이트되면 Notion database에서도 업데이트가 자동으로 발생 반대로 Notion이 수정되면 Notion API가 다른 앱의 정보를 업데이트
  - ex) Notion의 연락처 데이터베이스와 Google 연락처와의 동기화 ,
```
    Notion의 이벤트 데이터베이스와 Google 캘린더와의 동기화
```
- Automate actions (작업을 자동화)
  - 본인 워크스페이스 내에서 작업을 자동화할 수 있다.
  - Notion API를 사용하여 반복 작업을 작업이 완료되면 다시 생성 및 다시 예약하는 등
  - ex) 매년 다음 생일을 자동 업데이트
What you can do with Notion API?
- 휴대폰으로 찍은 사진을 Notion 갤러리에 자동적으로 추가되도록 한다.
- Notion의 갤러리에 있는 이미지로 정적 미디어 사이트를 구축한다.
- 뉴스 크롤링한 정보를 노션에 표 데이터베이스 형식으로 업로드한다.
- VideoBlock을 이용하여 영상(유튜브) Embed를 자동으로 가져와 노션 페이지(표 or 리스트 or 갤러리 데이터베이스)에 표시한다.
- 콘텐츠를 소셜 미디어, 블로그 등 웹사이트에 자동적으로 게시하도록 한다. (+노션의 데이터를 구글 시트에 연동하여 쿼리, 차트 등 구글 시트의 기능으로 데이터를 다양하게 활용 가능)
- 은행, 온라인 쇼핑몰 및 금융 서비스의 거래를 집계한다.
- Notion의 To-do list를 정기적으로 확인하고, 새 Task가 등록될 경우 Slack과 같은 메시징 앱으로 알림을 보내도록 한다. (+ Google 캘린더와의 연결)
- Email과 Notion을 동기화
  - 새로운 이메일을 Notion 데이터베이스 항목에 추가/업데이트
  - Notion에서 완료된 체크리스트 항목에 대해 이메일 보내기 등

Notion API EndPoint

Endpoint란 API가 서버에서 자원(resource)에 접근할 수 있도록 하는 URL

각 endpoint에 대한 요청은 JavaScript SDK 및 cURL을 사용
- cURL? cURL(client URL)은 다양한 통신 프로토콜을 지원하는 무료 웹 개발 오픈소스. 서버와 통신할 수 있는 커맨드 명령어 툴로 사용한다.
현재 Notion API는 4가지의 대표적인 Endpoint를 제공 Database , Page, Block , User 로 Database 내부에 항목을 추가하거나 Page의 Block를 수정하는 등

JavaScript SDK 사용

cURL 사용

Notion API 작동 확인하기

노션에 입력된 데이터 조회하기
데이터베이스, 페이지를 추가하여 자동으로 데이터 입력하기
example
- 사용자가 제출할 수 있는 입력폼 웹어플리케이션을 만들고 받은 데이터를 노션 API로 보내기 노션 DB에 데이터가 업데이트
- 노션 API URL을 Auth 헤더와 함께 접근

Untitled

페이지 부모 설정(데이터베이스 아이디)

속성 = 데이터베이스 안에 있는 열의 이름

1. API용 유저 토큰 생성하기

Notion Developer용 https://www.notion.so/my-integrations 사이트에 접속하여 “새 통합 만들기”
로고 / 콘텐츠 기능 / 사용자 기능 설정
- 콘텐츠 기능 : 콘텐츠에 대한 접근 권한 설정
- 사용자 기능 : User API의 사용자 데이터 설정

Untitled

시크릿의 ‘프라이빗 API 통합 토큰’ 정보를 복사 후 저장하기 → 노션 API를 사용할 수 있는 중요한 KEY값

Untitled

2. 새로운 페이지 추가

“Hello Notion” 페이지 생성 후 /database 인라인 템플릿 사용

Untitled

데이터 입력 후 전체 페이지로 열기
페이지의 URL 중 notion.so/ 뒤 ?v= 구문 앞에 있는 내용이 데이터베이스의 고유 ID 값 → 토큰 값과 동일하게 복사 후 저장한다. (database_id)

Untitled

오른쪽 상단의 공유 > 생성한 통합 API (Test)를 초대하여 ”Hello Notion” 페이지에 접근 허용을 설정 ( 통합과 DB 공유)

Untitled

보안 이슈 때문에 브라우저에서 해당 API를 부를 수 없고 서버에서 부름 서버는 파이썬 자바 등 어떤 형태로 구현 가능하다.

3. Postman을 통해 노션 API가 정상적으로 동작하는지 조회

https://developers.notion.com/reference/retrieve-a-database 노션 API 문서를 통해 API 참조
데이터베이스 조회 (Retrieve a database)
- https://api.notion.com/v1/databases/{database_id} URL로 Get 요청
- Authorization
  - Type : Bearer Token 으로 Toekn 값으로 시크릿의 ‘프라이빗 API 통합 토큰’ 입력
  - What is Bearer Token?
```
        [토큰 기반 인증 방식](https://www.notion.so/c1f3fe4ee8134f93b7900e1f3d203944) 중 하나로 JWT 혹은 OAuth에 대한 토큰을 사용
        
```
- Header
  - 노션 버전에 대한 Key ,Value 입력
  - Key : Notion-Version / Value : 2022-06-28
  - Notion-Version 값은 아래 사진과 같이 노션 API 사이트를 통해 확인 가능하다. (혹은 https://developers.notion.com/changelog 참고)

Untitled

****Send 버튼을 눌러 API 요청을 보낸 후 데이터베이스가 정상적으로 조회가 되는지 확인 (200)

Untitled

DataBase 알아보기

Grocery Test 데이터베이스를 통해 아이템 추가해보기

Untitled

데이터베이스 구조

DB 객체 = 사용자가 데이터베이스를 열 때 Notion에서 보이는 것

가장 중요한 부분은 “properties”에 정의된 DB 스키마

{
  "object": "database",
  "id": "da3e736306e4495b99dcc51971274d3a", 
  "created_time": "2022-08-07T19:10:04.968Z",
  "last_edited_time": "2022-08-09T21:49:37.913Z",
  "title": [/* details omitted */],
  "properties": {/* a collection of property objects */},
}

2.데이터베이스 속성(Properties)

속성은 열에 있는 모든 값들의 타입을 포함하여 열에 대한 설명을 저장

→ 텍스트, 날짜 , URL 등 다양한 타입 사용 가능 (Key: 속성 이름, Value: 속성 객체)

Untitled

Grocery Test 데이터베이스 객체에는 총 3가지의 속성으로 정의된다. (title /number /date)

{
  "object": "database",
  "properties": {
    "Grocery item": {
      "id": "fy:{",
      "type": "title",
      "title": {}  ->  Title(제목) : DB에서 title 타입을 가진 단 하나의 속성
    },
    "Price": {
      "id": "dia[",
      "type": "number",
      "number": {
        "format": "dollar" -> number 특정 속성에 추가 구성 가능 
      }
    },
    "Last ordered": {
      "id": "]\\R[",
      "type": "date",
      "date": {}
    },
  }
  // remaining details omitted
}

DB에 페이지 추가하기

페이지 부모 설정(데이터베이스 아이디) -데이터베이스 각각의 아이템 = 자식 페이지 -부모를 데이터베이스로 설정함으로써 새 페이지를 생성해 DB 아이템 추가 → 새 아이템 추가하기 위해 페이지 생성 엔드포인트에 HTTP 요청을 보낸다. 엔드포인트는 “parent”, “properties” 파라미터 요구
- “parent”) 데이터베이스 접근 위해 통합에 권한 부여
- “properties”) 속성 이름을 key로 사용하고 속성 값 객체를 value로 사용하는 객체 ex) Grocery item , Price, Last ordered

curl -X POST https://api.notion.com/v1/pages \
  -H 'Authorization: secret_Jueo9fvwkT7EuuMpa5qwubYzI0vsBJM2taTIW7PpVoU' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2022-06-28" \
  --data '{
      "parent": { "type": "database_id", "database_id": "da3e736306e4495b99dcc51971274d3a"},
      "properties": {
      "Grocery item": {
        "type": "title",
        "title": [{ "type": "text", "text": { "content": "방울토마토" } }]
      },
      "Price": {
        "type": "number",
        "number": 1.49
      },
      "Last ordered": {
        "type": "date",
        "date": { "start": "2022-08-09" }
      }
    }
  }'

Untitled