Notion API 가이드 - 페이지 콘텐츠 작업.

2021. 6. 6. 14:17

Notion API Developer - Beta 한글 번역

0. 앞선 글

페이지는 사용자가 빠른 메모부터 공유문서, 랜딩페이지에 이르기까지 모든 것을 작성하는 곳입니다. 통합을 사용해 사용자는 콘텐츠를 조직하여 Notion을 단일 소스로 변경하거나 Notion내에서 콘텐츠를 수집, 연결, 시각화할 수 있습니다.

이 가이드에서는 페이지 콘텐츠의 구성요소가 API에 표시되는 방식과 이를 사용하여 수행할 수 있는 작업에 대해 알아보도록 하겠습니다. 이 가이드를 통해 사용자는 콘텐츠가 포함된 새 페이지를 만들고 다른 페이지의 콘텐츠를 읽어와 기존 페이지 블록에 추가할 수 있습니다.

1. 페이지 콘텐츠와 속성.

일반적으로 페이지 속성은 기한, 범주, 다른 페이지와의 관계 같은 구조화된 정보를 저장하는데 적합합니다. 페이지 콘텐츠는 좀 더 느슨한 구조나 자유 형식 콘텐츠를 저장하는데 적합합니다. 페이지 콘텐츠는 사용자의 생각을 작성하거나 이야기하는 곳입니다. 페이지 속성은 사용자가 데이터를 저장하고 시스템을 구축하는 곳입니다. 여러분의 통합은 여러분이 기대하는 대로 속성과 콘텐츠를 사용하는 것을 목표로 해야 합니다.

https://developers.notion.com/docs/working-with-page-content

2. 콘텐츠를 블록으로 모델링하기.

페이지 콘텐츠는 블록 객체 목록으로 표시됩니다. 이러한 블록을 페이지의 자식이라고도 합니다. 각 블록에는 단락, 제목, 이미지와 같은 타입이 있습니다. 토글 목록과 같은 일부 타입의 블록에는 자체 자식이 존재할 수 있습니다.

간단한 예제로 단락 블록을 확인해 보겠습니다.

{
  "object": "block",
  "id": "380c78c0-e0f5-4565-bdbd-c4ccb079050d",
  "type": "paragraph",
  "created_time": "",
  "last_edited_time": "",
  "has_children": false,

  "paragraph": {
    "text": [/* details omitted */]
  }
}

모든 단락 블록에는 object, type, created_time, last_edited_time, has_children의 공통된 속성을 포함합니다. 또한 단락 속성 내에 type-specific 정보가 포함되어 있습니다. 단락 블록에는 "text" 속성이 존재하며 블록 타입에 따라 type-specific 속성이 달라질 수 있습니다.

이제 블록에 자식 블록이 있는 예시를 살펴보도록 하겠습니다. "paragraph"에 들여 쓰기 된 "to_do" 블록을 확인해 보세요.

{
  "object": "block",
  "id": "380c78c0-e0f5-4565-bdbd-c4ccb079050d",
  "type": "paragraph",
  "created_time": "",
  "last_edited_time": "",
  "has_children": true,

  "paragraph": {
    "text": [/* details omitted */],
    "children": [
      {
        "object": "block",
        "id": "6d5b2463-a1c1-4e22-9b3b-49b3fe7ad384",
        "type": "to_do",
        "created_time": "",
        "last_edited_time": "",
        "has_children": false,
  
        "to_do": {
          "text": [/* details omitted */],
          "checked": false
        }
      }
    ]
  }
}

자식 블록은 type-specific 속성 내에 블록 목록으로 표시됩니다. 만약 블록에 자식이 있다면 "has_children" 속성은 true가 됩니다. 단락 블록과 같은 일부 블록 타입만 자식을 지원합니다.

* 지원하지 않는 블록 타입(Notion Version 2021-05-13 기준)

Notion API는 현자 텍스트와 유사한 블록만을 지원하며 곧 더 많은 블록을 지원할 예정입니다. 지원되지 않는 블록 타입은 페이지에 "unsupported" 타입으로 표시됩니다.

3. 서식이 있는 텍스트(Rich Text)

앞선 블록 예시에서 "text" 속성의 생략된 값은 서식이 있는 텍스트(Rich Text) 객체의 목록이었습니다. 서식이 있는 텍스트 객체는 단순한 문자열 이상을 표현할 수 있습니다. 이 객체에는 스타일 정보, 링크, 멘션 등이 포함될 수 있습니다.

"Grocery List"라는 단어만 포함된 간단한 예시를 살펴보도록 하겠습니다.

{
  "type": "text",
  "text": {
    "content": "Grocery List",
    "link": null
  },
  "annotations": {
    "bold": false,
    "italic": false,
    "strikethrough": false,
    "underline": false,
    "code": false,
    "color": "default"
  },
  "plain_text": "Grocery List",
  "href": null
}

서식이 있는 텍스트 객체는 type-specific 한 구성과 유사한 패턴을 따릅니다. 위의 서식이 있는 텍스트 객체에는 "text" 타입이 있으며 "text" 속성에 해당 타입과 관련된 추가 구성이 존재합니다. annotations, plain_text, href와 같은 타입에 의존하지 않는 기타 정보들은 서식이 있는 텍스트 객체의 최상위 수준에 위치하게 됩니다.

서식이 있는 텍스트는 페이지 콘텐츠와 내부 페이지 속성 값 모두에 사용될 수 있습니다.

4. 콘텐츠가 있는 페이지 만들기.

페이지 생성 엔드포인트를 사용하면 자식 블록을 통해 페이지를 만들 수 있습니다. 이 엔드포인트는 다름 페이지 내에서 페이지를 만들거나 데이터베이스 내에서 페이지 만들기를 지원합니다.

샘플 콘텐츠가 있는 다른 페이지 내에 페이지를 새로 만들어 보도록 하겠습니다. 이 엔트포인트에 대해 세 가지 파라미터를 사용하게 됩니다. "parnet" 파라미터는 부포 페이지가 됩니다. 기존의 페이지 ID를 사용할 수 있습니다.

{
  "type": "page_id",
  "page_id": "494c87d0-72c4-4cf6-960f-55f8427f7692"
}

"properites" 파라미터는 페이지 속성을 표현하는 객체입니다. 우선 이 예시에서는 "title" 속성만이 있는 간단한 페이지 속성을 구성하도록 하겠습니다.

{
  "Name": {
    "type": "title",
    "title": [{ "type": "text", "text": { "content": "A note from your pals at Notion" } }]
  }
}

"children" 파라미터는 페이지 콘텐츠를 표현하는 블록 객체 목록입니다. 몇 가지 샘플 콘텐츠를 사용하도록 하겠습니다.

[
  {
    "object": "block",
    "type": "paragraph",
    "paragraph": {
      "rich_text": [{ "type": "text", "text": { "content": "You made this page using the Notion API. Pretty cool, huh? We hope you enjoy building with us." } }]
    }
  }
]

이 세 가지 파라미터를 모두 사용해 엔드포인트에 요청을 전송하여 페이지를 생성해 보도록 하겠습니다.

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": { "database_id": "494c87d0-72c4-4cf6-960f-55f8427f7692" },
    "properties": {
        "title": {
      "title": [{ "type": "text", "text": { "content": "A note from your pals at Notion" } }]
        }
    },
    "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "text": [{ "type": "text", "text": { "content": "You made this page using the Notion API. Pretty cool, huh? We hope you enjoy building with us." } }]
      }
    }
  ]
}'

* 토큰과 ID 정보는 적절히 수정되어야 합니다.

* API 요청에는 크기 제한이 존재합니다. 자세한 내용은 Size Limit를 확인해 주세요.

페이지가 추가되면 새 페이지 객체가 포함된 응답을 받게 됩니다. Notion을 살펴보고 새 페이지를 확인해 보세요.

5. 페이지에서 블록 읽어오기.

페이지 콘텐츠는 자식 블록 검색 엔드포인트를 이용해 읽어올 수 있습니다. 이 엔드포인트는 모든 자식 목록을 반환합니다. 페이지는 블록 자식을 읽어오기 위한 일반적인 시작 방법이지만 다른 종류의 블록에 대한 자식들도 검색할 수 있습니다.

"block_id" 파라미터는 블록의 ID를 의미합니다. 예시에 따른다면 응답에 페이지 ID가 포함되어 있을 것입니다. 해당 페이지의 ID를 "block_id"로 사용해 페이지에서 샘플 콘텐츠를 읽어오도록 하겠습니다.

이제 "block_id"를 사용해 엔드포인트에 요청을 보내고 하위의 블록을 검색합니다.

curl https://api.notion.com/v1/blocks/16d8004e-5f6a-42a6-9811-51c22ddada12/children?page_size=100 \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Notion-Version: 2021-05-13"

* block_id 및 토큰 정보는 적절히 수정되어야 합니다.

블록 객체 목록이 포함된 응답을 받게 됩니다.

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

페이징 된 응답을 받을 수 있습니다. 페이징 된 응답은 Notion API 전반에서 사용됩니다. 페이징 된 응답의 최대 결과 개수는 100개입니다. "start_cursor"과 "page_size" 파라미터를 통해 100개가 넘는 결과를 얻어올 수도 있습니다.

이 응답에서 요청한 자식 블록은 "results" 배열 내부에 존재하게 됩니다.

6. 중첩된 블록 읽어오기.

결과 자체에 자식이 포함된 블록이 있는 경우 어떤 일이 일어날까요? 이 경우 응답에 중첩된 블록이 포함되지는 않지만 "has_children"의 값은 true가 됩니다. 통합에 페이지 콘텐츠 혹은 모든 블록의 완전한 표현이 필요하다면 "has_children"이 true인 블록에 대해 결과를 검색하고 엔드포인트를 재귀적으로 호출해야 합니다.

큰 페이지를 읽는데 다소 시간이 걸릴 수 있습니다. 아키텍처에서 작업 대기열과 같은 비동기 작업을 사용하는 것이 좋습니다. 또한 요청 제한에 도달할 수 있으므로 새 요청을 전송하는 속도를 적절히 늦춰야 할 수도 있습니다.

7. 페이지에 블록 추가하기.

통합은 블록 자식 추가 엔드포인트를 사용해 더 많은 콘텐츠를 추가할 수도 있습니다. 예시에서 만든 페이지에 다른 블록을 추가해 보도록 하겠습니다. 이 엔드포인트에는 "block_id"와 "children"의 두 개의 파라미터가 필요합니다

"block_id"는 기존 블록의 ID입니다. 블록 ID에 앞선 예시에서 사용한 페이지 ID를 동일하게 사용하도록 합니다.

"children" 파라미터는 추가할 내용을 설명할 블록 객체 목록입니다. 더 만든 샘플 콘텐츠를 사용해 보도록 하겠습니다.

[
  {
    "object": "block",
    "type": "paragraph",
    "paragraph": {
      "text": [{ "type": "text", "text": { "content": "– Notion API Team", "link": { "type": "url", "url": "https://twitter.com/NotionAPI" } } }]
    }
  }
]

두 파라미터를 이용해 엔드포인트에 요청을 전송하여 블록을 추가합니다.

curl -X PATCH https://api.notion.com/v1/blocks/16d8004e-5f6a-42a6-9811-51c22ddada12/children \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2021-05-13" \
  --data '{
    "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "text": [{ "type": "text", "text": { "content": "– Notion API Team", "link": { "type": "url", "url": "https://twitter.com/NotionAPI" } } }]
      }
    }
  ]
}'

* 블록 ID와 토큰을 적절히 수정하는 것을 잊지 마세요.

업데이트된 블록이 포함된 응답을 받게 됩니다. 응답에 하위 블록이 포함되어 있지는 않지만 "has_children"의 값이 true로 설정된 것을 확인할 수 있습니다.

8. 맺는 글.

사용자가 Notion에서 보는 것의 거의 모든 것이 블록으로 표시됩니다. 이제 통합으로 블록이 있는 페이즈를 만들었고 블록을 읽어올 수 있으며 페이지에 블록을 추가하는 방법을 이해했습니다. 이제 Notion에서 노출된 대부분의 영역을 다를 수 있게 되었습니다.

* 현재 블록을 삭제하거나 업데이트하는 것은 불가능합니다.

(NotionVersion 2021-05-13) 이러한 작업은 파괴적이므로 API를 통해 이 작업을 노출하는 가장 좋은 방법을 신중히 조사하고 있습니다. 향후 기능에 대한 업데이트를 위해 계속 지켜봐 주시기 바랍니다.

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

Working with page content

Overview Pages are where users write everything from quick notes, to shared documents, to curated landing pages in Notion. Integrations can help users turn Notion into the single source of truth by syndicating content or help users gather, connect, and vis

developers.notion.com

저작자표시

'Trunk' 카테고리의 다른 글

NuPhy Air60 구매 및 사용 후기 (2)	2022.05.04
씽크웨이 토체티 BW D&T 콜라보 K320w 구매 후기 (0)	2021.07.12
Notion API 가이드 - Notion API 시작하기. (0)	2021.06.06
Notion API 가이드 - 데이터베이스 작업. (0)	2021.06.06
쿠키런 킹덤 쿠폰 모음 (0)	2021.02.14

Simple is Beautiful.