Notion API 가이드 - 데이터베이스 작업.

2021. 6. 6. 14:00

Notion API Developer - Beta 한글 번역

0. 앞선 글.

데이터베이스 스키마, 쿼리 등에 대해 알아봅시다.

데이터베이스를 통해 사용자는 Notion에서 구조화된 데이터를 만들고 다룰 수 있습니다. 통합을 사용해 사용자는 데이터베이스를 외부 시스템과 동기화하거나 Notion 데이터베이스를 중심으로 워크플로우를 구축할 수 있습니다.

이 가이드에서는 데이터베이스가 API에서 어떻게 표현되는지부터 데이터베이스에 아이템을 추가하는 방법, 아이템을 찾는 방법뿐 아니라 페이지의 속성(properties)을 업데이트하는 방법도 배울 것입니다.

1. 데이터베이스의 구조.

데이터베이스 객체는 사용자가 데이터베이스를 열 때 Notion에서 보는 것을 표현합니다. 가장 중요한 부분은 속성(properties) 컬렉션에 정의된 데이터베이스의 스키마입니다.

{
  "object": "database",
  "id": "2f26ee68-df30-4251-aad4-8ddc420cba3d",
  "created_time": "2020-03-17T19:10:04.968Z",
  "last_edited_time": "2020-03-17T21:49:37.913Z",
  "title": [/* details omitted */],
  "properties": {/* a collection of property objects */},
}

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

여러분이 보고 있는 데이터베이스가 표라고 가정해 보도록 합시다. 속성 객체는 열에 있는 모든 값들의 타입을 포함하며 열에 대한 설명을 저장합니다. 텍스트, 숫자, 날짜, 사람 등의 일반적인 타입을 사용할 수 있으며 각 타입에 대한 추가 구성 또한 사용할 수 있습니다. 다음 데이터베이스 객체 예시를 통해 속성 섹션에 대해 알아보도록 하겠습니다.

{
  "object": "database",
  "properties": {
    "Grocery item": {
      "id": "fy:{",
      "type": "title",
      "title": {}
    },
    "Price": {
      "id": "dia[",
      "type": "number",
      "number": {
        "format": "dollar"
      }
    },
    "Last ordered": {
      "id": "]\\R[",
      "type": "date",
      "date": {}
    },
  }
  // remaining details omitted
}

이 데이터베이스 객체에는 세 가지 속성이 정의되어 있습니다. 각각의 키는 속성의 이름이며 그 값은 속성 객체입니다. 몇 가지 핵심 사항에 대해 알아보겠습니다.

* "title"은 특별한 타입입니다. 모든 데이터베이스에는 "title" 타입을 가진 딱 하나의 속성이 존재합니다. 이 타입의 속성은 데이터베이스에서 각각의 아이템에 대한 페이지 제목을 참조하게 됩니다. 이 예시에서는 "Grocery item" 속성에 이 "title" 타입이 있습니다.

* "type"의 값은 속성 객체의 또 다른 키에 해당됩니다. 각 속성 객체에는 "type"의 값과 동일한 이름의 속성이 존재합니다. 예를 들어 "Last ordered"에는 "type"에 "date"라는 값이 존재하고 "date" 속성도 존재합니다. 이 패턴은 Notion API 전체에서 사용되며 type-specific 데이터라고 합니다.

* 특정 속성 객체에는 추가 구성이 있습니다. "number" 속성 내부에는 추가 구성이 있는 것을 확인할 수 있습니다. 이 예시에서 포맷 설정은 이 열이 보이는 방식을 제어하며 "dollar"로 설정되었습니다.

3. 데이터베이스에 페이지 추가하기.

페이지는 데이터베이스 내부의 아이템으로 사용되며 각 페이지의 속성은 부모 데이터베이스의 스키마를 따라야 합니다. 데이터베이스를 표라고 가정하면 페이지의 속성들은 한 행의 모든 값을 정의합니다.

페이지는 페이지 생성 API의 엔드포인트를 사용해 데이터베이스에 추가됩니다. 이 예시에서 데이터베이스에 새 페이지를 추가해 보도록 하겠습니다. 엔드포인트는 "parent"와 "properies"라는 두 가지 파라미터가 요구됩니다.

데이터베이스에 페이지를 추가할 때 "parent" 파라미터는 데이터베이스가 되어야 합니다.

{
  "type": "database_id",
  "database_id": "2f26ee68-df30-4251-aad4-8ddc420cba3d"
}

* 데이터베이스에 접근하기 위해 통합에 미리 권한을 부여해야 합니다.

"properties" 파라미터는 속성 이름이나 ID를 키로 사용하고 속성 값 객체를 값으로 사용하는 객체입니다. 이 파라미터를 올바르게 작성하기 위해 데이터베이스 스키마의 특성 객체를 참고하세요. 예시 데이터베이스에 대해서 다음 객체를 생성할 수 있습니다.

{
  "Grocery item": {
    "type": "title",
    "title": [{ "type": "text", "text": { "content": "Tomatoes" } }]
  },
  "Price": {
    "type": "number",
    "number": 1.49
  },
  "Last ordered": {
    "type": "date",
    "date": { "start": "2021-05-11" }
  }
}

이제 위의 "parent"와 "properties" 두 파라미터를 사용해 페이지를 생성하기 위해 엔드포인트에 HTTP 요청을 전송해 보겠습니다.

curl -X POST https://api.notion.com/v1/pages \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2021-05-13" \
  --data '{
      "parent": { "type": "database_id", "database_id": "2f26ee68-df30-4251-aad4-8ddc420cba3d" },
      "properties": {
      "Grocery item": {
        "type": "title",
        "title": [{ "type": "text", "text": { "content": "Tomatoes" } }]
      },
      "Price": {
        "type": "number",
        "number": 1.49
      },
      "Last ordered": {
        "type": "date",
        "date": { "start": "2021-05-11" }
      }
    }
  }'

* Authorization와 database_id를 적절히 바꾸는 것을 잊지 마세요

* 정상적으로 페이지가 추가되기 위해선 데이터베이스의 스키마가 알맞게 구성되어야 함을 잊지 마세요.

페이지가 추가된다면 새 페이지 객체가 포함된 응답을 받게 됩니다. 이 응답에서 중요한 속성은 페이지 ID입니다. Notion을 외부 시스템에 연결하여 사용하는 경우 이 페이지 ID를 알아두는 것이 좋습니다. 나중에 이 페이지의 속성을 업데이트할 때 업데이트 페이지 엔드포인트에서 이 ID를 사용합니다.

4. 데이터베이스에서 페이지 찾기.

데이터베이스 쿼리 엔드포인트를 사용해 데이터베이스에서 페이지를 읽어올 수 있습니다. 이 엔드포인트를 사용하려면 "Last ordered가 지난주부터"와 같은 기준에 따라 페이지를 찾을 수 있습니다. 일부 큰 데이터베이스에서는 이 엔드 포인트를 사용하면 특정 순서의 더 작은 결과를 얻어 낼 수 있습니다.

이렇게 페이지를 찾는 데 사용되는 조건을 필터라고 합니다. 필터는 "Tag에 긴급이 포함됨"과 같은 단순한 조건부터 "Tag에 긴급이 포함되어야 하고 Due date는 몇 주 이내여야 하며 Assignee는 Cassandra Vasquez여야 함"과 같은 복잡한 조건으로 설정할 수 있습니다. 이러한 복잡한 조건은 "and"나 "or"을 사용해 여러 개의 단순한 조건을 결합하여 사용하므로 복합필터라고 합니다.

이 가이드에서는 예시 데이터베이스에 단일 속성 조건을 사용하는 것을 중점으로 둡니다. 데이터베이스 스키마를 살펴보면 "Last ordered" 속성이 "date" 타입을 사용한다는 것을 알고 있습니다. 즉 "date" 타입에 대한 조건을 사용해 "Last ordered"에 대한 필터를 만들 수 있습니다.

{
  "property": "Last ordered",
  "date": {
    "past_week": {}
  }
}

이 필터를 사용해 예시 데이터베이스에서 조건에 맞는 페이지를 찾아와 보도록 합시다.

curl -X POST https://api.notion.com/v1/databases/2f26ee68df304251aad48ddc420cba3d/query \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"''
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2021-05-13" \
    --data '{
      "filter": {
      "property": "Last ordered",
      "date": {
        "past_week": {}
      }
        }
    }'

* Authorization과 URL의 databases 뒤에 데이터베이스 ID를 적절하게 바꿔야 함을 잊지 마세요.

필터에 일치하는 페이지 객체 목록이 포함된 응답을 받을 수 있습니다.

{
  "object": "list",
  "results": [
    {
      "object": "page",
      /* details omitted */
    }
  ],
  "has_more": false,
  "next_cursor": null
}

사실 이 응답은 페이징 된(paginated) 응답입니다. 페이징 된 응답은 큰 객체 목록을 반환하는 모든 Notion API의 응답에 사용됩니다. 페이징 된 응답의 최대 결과 개수는 100개입니다. 페이징 된 결과는 "start_cursor"과 "page_size" 파라 미터를 사용해 100개 이상의 결과를 얼어올 수도 있습니다.

이 예시에서 요청한 개별 페이지에 대한 정보는 "results"에 있습니다. 통합이나 사용자가 최근에 만들어진 페이지에 관심이 있다면 어떨까요? 가장 최근에 생성된 페이지가 첫 번째로 오도록 결과를 정렬할 수 있습니다. 특히 결과 페이지가 하나가 아닌 경우에 유용합니다.

"sort" 파라미터는 개별 속성 혹은 타임스탬프에 의해 결과를 정렬하는 데 사용됩니다. 이 파라미터는 정렬 객체의 배열에 할당될 수 있습니다.

페이지가 생성된 시간은 데이터베이스 스키마를 따르는 페이지 속성이 아닙니다. 이 속성은 모든 페이지에 존재는 두 종류의 타임스탬프 중 하나입니다. 이를 "created_time" 타임스탬프라고 합니다.

이제 가장 최근에 생성된 페이지가 먼저 표시되도록 결과를 정렬하는 정렬 객체를 만들어보도록 하겠습니다.

{
  "timestamp": "created_time",
  "direction": "descending"
}

마지막으로 이 정렬 객체를 사용해 페이지를 요청해 보도록 하겠습니다.

curl -X POST https://api.notion.com/v1/databases/2f26ee68df304251aad48ddc420cba3d/query \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"''
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2021-05-13" \
    --data '{
      "filter": {
      "property": "Last ordered",
      "date": {
        "past_week": {}
      }
        },
    "sorts": [{ "timestamp": "created_time", "direction": "descending" }]
    }'

* 데이터베이스 ID과 토큰 정보를 적절히 수정해야 함을 잊지 마세요.

5. 맺는 글.

데이터베이스 속성들에 의해 만들어진 데이터베이스 스키마를 이해하는 것은 Notion 데이터베이스 작업의 핵심입니다. 이를 통해 데이터베이스에 페이지를 추가하고 데이터베이스에서 아이템을 찾을 수 있습니다.

* 이 글은 Notion API Develpers - Beta: Working with database를 번역한 글입니다.

Working with databases

Learn about database schemas, querying databases, and more.

developers.notion.com

저작자표시

'Trunk' 카테고리의 다른 글

Notion API 가이드 - 페이지 콘텐츠 작업. (1)	2021.06.06
Notion API 가이드 - Notion API 시작하기. (0)	2021.06.06
쿠키런 킹덤 쿠폰 모음 (0)	2021.02.14
[Synology] Mac Finder에서 Synology 접속하기 (1)	2021.01.30
29.97fps? 30fps? 프레임 속도에 대한 초보자 가이드. (1)	2021.01.22

Simple is Beautiful.