JavaScript 的 Notion SDK

一个简单易用的 Notion API 客户端

构建状态

安装

npm install @notionhq/client

使用方法

使用 Notion 的入门指南来设置使用 Notion API。

导入并使用集成令牌或 OAuth 访问令牌初始化客户端。

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

// 初始化客户端
const notion = new Client({
  auth: process.env.NOTION_TOKEN,
})

向任何 Notion API 端点发送请求。

在 API 参考中查看完整的端点列表。

;(async () => {
  const listUsersResponse = await notion.users.list({})
})()

每个方法都返回一个解析响应的 Promise。

console.log(listUsersResponse)

{
  results: [
    {
      object: 'user',
      id: 'd40e767c-d7af-4b18-a86d-55c61f1e39a4',
      type: 'person',
      person: {
        email: 'avo@example.org',
      },
      name: 'Avocado Lovelace',
      avatar_url: 'https://secure.notion-static.com/e6a352a8-8381-44d0-a1dc-9ed80e62b53d.jpg',
    },
    ...
  ]
}

端点参数被分组到一个单一对象中。你不需要记住哪些参数应该放在路径、查询或正文中。

const myPage = await notion.databases.query({
  database_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  filter: {
    property: "Landmark",
    rich_text: {
      contains: "Bridge",
    },
  },
})

错误处理

如果 API 返回一个不成功的响应，返回的 Promise 会以 APIResponseError 拒绝。

错误包含了响应的属性，其中最有用的是 code。你可以将 code 与 APIErrorCode 对象中的值进行比较，以避免拼写错误代码。

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

try {
  const notion = new Client({ auth: process.env.NOTION_TOKEN })
  const myPage = await notion.databases.query({
    database_id: databaseId,
    filter: {
      property: "Landmark",
      rich_text: {
        contains: "Bridge",
      },
    },
  })
} catch (error) {
  if (error.code === APIErrorCode.ObjectNotFound) {
    //
    // 例如：通过要求用户选择不同的数据库来处理
    //
  } else {
    // 其他错误处理代码
    console.error(error)
  }
}

日志记录

客户端会向日志记录器发送有用的信息。默认情况下，它只发送警告和错误。

如果你正在调试应用程序，并希望客户端记录响应体，请将 logLevel 选项设置为 LogLevel.DEBUG。

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

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  logLevel: LogLevel.DEBUG,
})

你还可以设置自定义 logger 来将日志发送到 stdout 以外的目的地。自定义日志记录器是一个接受 3 个参数的函数：logLevel、message 和 extraInfo。自定义日志记录器不应返回值。

客户端选项

Client 在初始化时支持以下选项。这些选项都是单个构造函数参数中的键。

选项	默认值	类型	描述
`auth`	`undefined`	`string`	用于身份验证的 Bearer 令牌。如果未定义，应在每个请求上设置 `auth` 参数。
`logLevel`	`LogLevel.WARN`	`LogLevel`	实例将产生的日志详细程度。默认情况下，日志写入 `stdout`。
`timeoutMs`	`60_000`	`number`	在发出 `RequestTimeoutError` 之前等待的毫秒数。
`baseUrl`	`"https://api.notion.com"`	`string`	发送 API 请求的根 URL。可以更改此值以使用模拟服务器进行测试。
`logger`	记录到控制台	`Logger`	自定义日志记录函数。仅当客户端发出的日志严重程度等于或大于 `logLevel` 时，才会调用此函数。
`agent`	默认 node 代理	`http.Agent`	用于控制 TCP 套接字的创建。常见用途是使用 `https-proxy-agent` 代理请求。

TypeScript

此包包含所有请求参数和响应的类型定义，以及这些实体中一些有用的子对象。由于TypeScript中的错误以any或unknown类型开始，您应该使用isNotionClientError类型守卫以类型安全的方式处理它们。每个NotionClientError类型都由其error.code唯一标识。APIErrorCode枚举中的代码由服务器返回。ClientErrorCode枚举中的代码在客户端产生。

try {
  const response = await notion.databases.query({
    /* ... */
  })
} catch (error: unknown) {
  if (isNotionClientError(error)) {
    // 错误现在被强类型化为NotionClientError
    switch (error.code) {
      case ClientErrorCode.RequestTimeout:
        // ...
        break
      case APIErrorCode.ObjectNotFound:
        // ...
        break
      case APIErrorCode.Unauthorized:
        // ...
        break
      // ...
      default:
        // 您甚至可以利用穷尽性检查
        assertNever(error.code)
    }
  }
}

类型守卫

提供了几个类型守卫来区分完整和部分API响应。

类型守卫函数	用途
`isFullPage`	确定对象是否为完整的`PageObjectResponse`
`isFullBlock`	确定对象是否为完整的`BlockObjectResponse`
`isFullDatabase`	确定对象是否为完整的`DatabaseObjectResponse`
`isFullPageOrDatabase`	确定对象是否为完整的`PageObjectResponse`或`DatabaseObjectResponse`
`isFullUser`	确定对象是否为完整的`UserObjectResponse`
`isFullComment`	确定对象是否为完整的`CommentObjectResponse`

以下是使用类型守卫的示例：

const fullOrPartialPages = await notion.databases.query({
  database_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
})
for (const page of fullOrPartialPages.results) {
  if (!isFullPageOrDatabase(page)) {
    continue
  }
  // page变量已从
  //      PageObjectResponse | PartialPageObjectResponse | DatabaseObjectResponse | PartialDatabaseObjectResponse
  // 缩小到
  //      PageObjectResponse | DatabaseObjectResponse。
  console.log("创建时间：", page.created_time)
}

实用函数

此包还导出了一些有助于处理任何分页API的实用函数。

`iteratePaginatedAPI(listFn, firstPageArgs)`

此实用函数将任何分页API转换为异步迭代器。

参数：

listFn：Notion客户端上代表分页API的任何函数（即接受start_cursor）。例如：notion.blocks.children.list。
firstPageArgs：在首次和后续API调用中应传递的参数，例如block_id。

返回：

API结果的异步迭代器。

示例：

for await (const block of iteratePaginatedAPI(notion.blocks.children.list, {
  block_id: parentBlockId,
})) {
  // 对block进行操作。
}

`collectPaginatedAPI(listFn, firstPageArgs)`

此实用函数接受与iteratePaginatedAPI相同的参数，但将结果收集到内存数组中。

在使用此实用函数之前，请检查您处理的数据是否足够小，能够放入内存。

参数：

listFn：Notion客户端上代表分页API的任何函数（即接受start_cursor）。例如：notion.blocks.children.list。
firstPageArgs：在首次和后续API调用中应传递的参数，例如block_id。

返回：

包含API结果的数组。

示例：

const blocks = await collectPaginatedAPI(notion.blocks.children.list, {
  block_id: parentBlockId,
})
// 对blocks进行操作。

要求

此包支持以下最低版本：

运行时：node >= 12
类型定义（可选）：typescript >= 4.5

较早的版本可能仍然有效，但我们鼓励构建新应用程序的开发者升级到当前的稳定版本。

获取帮助

如果您想为Notion的API提交功能请求，或在API平台上遇到任何问题，请发送电子邮件至developers@makenotion.com。

要报告SDK的问题，可以向此仓库提交issue。但是，我们不会密切监控这些问题。我们建议您直接联系我们，发送电子邮件至developers@makenotion.com。

notion-sdk-js