如何获取 Notion 开放平台 API 密钥(分步指南)
Notion 开放平台 API 为开发者提供了访问 Notion 数据的强大功能。借助这个 API，开发者可以对 Notion 中的页面、数据库等内容进行操作、自动化流程和集成其他工具。通过 Notion API，您能够轻松访问和修改工作空间中的数据，并提供个性化的应用体验。本文将指导你如何获取Notion 开放平台API密钥，并进行初步的可用性测试，同时探讨在使用过程中需要考虑的其他关键因素。
1. 获取Notion 开放平台 API密钥步骤
获取Notion 开放平台 API密钥的过程相对简单，只需几个步骤即可完成：
1.访问官方集成页面 注册/登录：https://www.notion.so/login?redirectURL=%2Fprofile%2Fintegrations
2.按照第一步操作，登录成功就会自动跳转到集成页。点击 +号(新集成) 。
3.填写信息（注意： 类型这一栏可以选择 内部 或者 外部）案例选择的是内部。
4.创建以后就可以看到 内部集成密钥 ，将密钥保存下载用户API交互验证。
5.可以在下方选择哪些功能可以通过API来操作。
2. Notion 开放平台 API密钥可用性测试
在获取API密钥后，进行可用性测试是确保其正常工作的重要步骤。以下是使用curl进行测试的一个案例
以下接口为Notion 开放平台接口中 评论 里的检索评论接口
输入：
curl 'https://api.notion.com/v1/comments?block_id=5c6a28216bb14a7eb6e1c50111515c3d'\
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2022-06-28"输出：
结果以JSON格式返回，包含了指定页面中评论的详细信息，例如评论对象、该评论的创建时间、评论的最后编辑时间、评论的创建者、评论的内容等
{
"object": "list",
"results": [
{
"object": "comment",
"id": "94cc56ab-9f02-409d-9f99-1037e9fe502f",
"parent": {
"type": "page_id",
"page_id": "5c6a2821-6bb1-4a7e-b6e1-c50111515c3d"
},
"discussion_id": "f1407351-36f5-4c49-a13c-49f8ba11776d",
"created_time": "2022-07-15T16:52:00.000Z",
"last_edited_time": "2022-07-15T19:16:00.000Z",
"created_by": {
"object": "user",
"id": "9b15170a-9941-4297-8ee6-83fa7649a87a"
},
"rich_text": [
{
"type": "text",
"text": {
"content": "Single comment",
"link": null
},
"annotations": {
"bold": false,
"italic": false,
"strikethrough": false,
"underline": false,
"code": false,
"color": "default"
},
"plain_text": "Single comment",
"href": null
}
]
}
],
"next_cursor": null,
"has_more": false,
"type": "comment",
"comment": {}
}3. 使用Notion 开放平台 API搭建应用的其他关键考虑因素
在使用Notion 开放平台 API搭建应用时，除了获取和测试API密钥外，还需考虑以下因素：
速率限制
速率受限的请求将返回"rate_limited"错误代码（HTTP 响应状态 429）。每个集成传入请求的速率限制是平均每秒三个请求。允许一些超出平均速率的突发。
集成应通过处理 HTTP 429 响应并遵守 Retry-After 响应标头值（设置为整数秒数（十进制））来适应可变速率限制。等待最短时间后发出的请求不应再受到速率限制。
或者，可以通过降低（或减慢）未来请求的速度来适应速率限制。实现这一点的一种常见方法是使用一个或多个队列来处理待处理的请求，只要 Notion 不响应 HTTP 429，就可以通过发送请求来消耗这些队列。
大小限制
Notion 对某些参数的大小以及请求中子项的深度设有限制。超过这些限制的请求将返回 “validation_error” 错误代码（HTTP 响应状态 400），并在 “message” 属性中包含更具体的错误详情。
集成应主动避免发送超过这些限制的请求。建议在自己的测试套件中使用包含大参数的测试数据，以验证错误是否被适当处理。例如，如果集成从外部系统读取 URL 并将其放入 Notion 页面属性中，则集成应有一个处理超过 2000 字符长度限制的 URL 的方案。集成可能选择记录错误，或者通过电子邮件向设置集成的用户发送警报，或者采取其他措施。
请注意，除了以下的属性限制外，负载的最大大小为 1000 个区块元素和 500KB 总体大小。
属性值的限制：
| 属性值类型 | 内部属性 | 大小限制 |
|---|---|---|
| 富文本对象（Rich text object） | text.content | 2000 字符 |
| 富文本对象（Rich text object） | text.link.url | 2000 字符 |
| 富文本对象（Rich text object） | equation.expression | 1000 字符 |
| 任何类型的区块数组，包括富文本对象（Any array of all block types, including rich text objects） | 100 个元素 | |
| 任何 URL（Any URL） | 2000 字符 | |
| 任何电子邮件（Any email） | 200 字符 |
4. Notion 开放平台 API密钥申请和使用中的常见问题
在申请和使用 Notion 开放平台 API密钥过程中，你可能会遇到以下常见问题：
如果我的API密钥失效或被禁用，如何解决？
如果API密钥失效或被禁用，可以登录Schiphol开发者平台检查API密钥状态，并在需要时重新生成一个新的密钥。如果是由于频率限制或不当使用导致的禁用，请遵循平台的使用规则并减少请求频率。
如何保护我的API密钥？
为了确保安全，API密钥应避免暴露在公开的代码库中。可以使用环境变量或服务器端代码保护密钥，避免将其直接嵌入客户端代码中。此外，定期更新API密钥，并为密钥设置适当的权限和访问控制。
在请求Schiphol API时，如何处理密钥错误？
如果API请求返回密钥错误，请确认请求中包含的APP ID和APP KEY是否正确。如果你使用的是旧密钥，可能需要重新生成一个新的密钥，并确保在请求中更新正确的密钥。
为什么我无法获取Schiphol API密钥？
如果你无法获取Schiphol API密钥，首先请确保你已成功注册并登录到Schiphol开放平台。如果已登录但仍无法获取密钥，请检查是否填写了完整的应用信息，并确保所提供的应用描述符合Schiphol平台的使用规定。
错误处理
错误码：
| HTTP 状态码 | “code” | 描述 | “message” 示例 |
|---|---|---|---|
| 400 | “invalid_json” | 请求体无法解码为 JSON 格式。 | “错误解析 JSON 内容。” |
| 400 | “invalid_request_url” | 请求的 URL 无效。 | “无效的请求 URL” |
| 400 | “invalid_request” | 请求不被支持。 | “不支持的请求：<请求名称>。” |
| 400 | “invalid_grant” | 提供的授权凭证（如授权码、资源所有者凭证）或刷新令牌无效、过期、被撤销、不匹配授权请求中的重定向 URI，或发给了其他客户端。参考 OAuth 2.0 文档了解更多信息。 | “无效的授权码：该授权码已被撤销。” |
| 400 | “validation_error” | 请求体与预期的参数模式不匹配。检查 “message” 属性获取更多详细信息。 | “请求体验证失败：body.properties 应该定义，但未定义。” |
| 400 | “missing_version” | 请求缺少必需的 Notion-Version 头。参考版本控制。 | “Notion-Version 头验证失败：Notion-Version 头应该定义，但未定义。” |
| 401 | “unauthorized” | 提供的令牌无效。 | “API 令牌无效。” |
| 403 | “restricted_resource” | 使用的令牌没有执行此操作的权限。 | “API 令牌没有访问此资源的权限。” |
| 404 | “object_not_found” | 使用的令牌对应的资源不存在。该错误还可能表示资源未与令牌所有者共享。 | “无法找到 ID 为 be907abe-510e-4116-a3d1-7ea71018c06f 的数据库。确保相关页面和数据库已与您的集成共享。” |
| 409 | “conflict_error” | 事务无法完成，可能是由于数据冲突。确保参数是最新的，然后重试。 | “保存时发生冲突。请再试一次。” |
| 429 | “rate_limited” | 请求超出了允许的次数限制。减慢速度并重试。更多关于速率限制的详细信息。 | “您已被限流。请稍后几分钟再试。” |
| 500 | “internal_server_error” | 发生了服务器内部错误。 | “发生了意外错误。” |
5. Notion 开放平台 API进阶指引
在获得Notion 开放平台 API密钥之后，即可开启API接口对接，本文整理了多篇使用Notion 开放平台 API的案例，帮助读者更有效地使用Notion 开放平台 API：
创建页面、 创建数据库、 列出所有用户、 创建评论、创建新的子块
6. 常见问题
问题1： 什么是幂简集成平台？
幂简集成是蜜堂有信在2023年打造的一款SAAS产品，建设着国内最全的API平台，为开发者提供全面、高效、易用的API集成管理方案，一站搜索、试用、集成国内和国外API。让用户在AI时代全方位接入互联网，用API连接一切服务和算力，实现价值倍增。
问题2：如何找到Notion 开放平台 API
幂简API平台可以通过以下两种方式找到所需API：通过关键词搜索API(例如，输入’Notion 开放平台 API‘这类品类词，更容易找到结果)、或者从API hub分类页进入寻找。
问题3：Notion 开放平台 API的替代品有哪些？
市场上存在免费、付费两种替代者
例如
Evernote-最佳笔记应用 – 用Evernote整理你的笔记
Relanote-zetelkasten /PKM免费在线笔记应用程序
更多竞品可以在Notion 开放平台找到。
7. 总结
本文详细介绍了Notion开放平台API密钥的获取、测试和使用过程，提供了如何使用curl进行API可用性测试的示例。通过具体的代码示例，开发者可以更好地理解如何通过API获取评论数据。文章还探讨了在使用Notion API时需要注意的速率限制、请求大小限制以及错误处理等问题，为开发者提供了实用的技术支持。本文为开发者使用Notion开放平台API提供了全面的指南，帮助其顺利完成应用集成。
