• 作者: 作者
  • 时间:
  • 分类: 文章

最近尝试对接 Notion API，结果在密钥登录环节卡住了，折腾了好半天才搞定。看了一圈社区，发现不少人都有类似的困扰。既然已经踩过坑了，就干脆把排查思路和解决方案整理一下，希望能帮到同样遇到这个问题的朋友。

1. 检查 Integration Token 是否正确

首先最基础的一点，确保你拿到的密钥是正确的“Integration Secret”，而不是“Internal Integration Token”或者其他什么乱七八糟的串。

  • 密钥位置：去 Notion 的 My Integations 页面，找到你创建的应用。点进去后，在“Capabilities”或者“Secrets”那一栏复制“Internal Integration Token”。
  • 复制粘贴：复制的时候千万别多复制个空格，或者少复制个字符，这东西可是很敏感的。

2. 确认数据库已正确授权

这一点特别容易忽略，也是大多数人报错的根源。拿到了密钥并不代表你能访问所有的页面和数据库。

Notion 的 API 权限是基于“邀请”机制的。哪怕你是 Integration 的创建者，你也得手动把你的这个 Integration 添加到具体的 Page 或者 Database 里。

  • 操作步骤：打开你需要操作的数据库所在的 Notion 页面。
  • 点击右上角的 ...（更多选项）。
  • 往下拉找到 Add connections（或者叫 Connections），然后搜索你刚才创建的 Integration 名称。
  • 确认添加：选中并确认。只有这一步做完，你的 API 密钥才有权限读写这个数据库。

3. API 版本与 Header 头部配置

如果你在写代码调用，还得检查一下代码里的配置。

  • Authorization Header：格式必须是 Authorization: Bearer <你的密钥>。注意 Bearer 后面有个空格，而且密钥本身不需要额外的引号包裹。
  • Notion-Version Header：Notion API 会迭代，虽然目前通常兼容性不错，但最好在 Header 里指定版本号，比如 Notion-Version: 2022-06-28，防止因为接口变动导致莫名其妙的错误。

4. 排查网络与代理问题

如果你在国内环境直接调用 Notion API，大概率会超时报错。

  • 网络连通性：Notion 的 API 域名可能会受到网络波动影响。ping 一下 api.notion.com 看看通不通。
  • 设置代理：如果直连不通，你的代码里需要配置代理（Proxy）。如果你用的是 Python 的 requests 库，可以设置 proxies 参数；如果是 Node.js，可以在 httpsAgent 里走代理服务。

5. 验证工具推荐

别一上来就在复杂的项目里改代码调 bug，先用简单的工具验证一下密钥是不是好的。

  • Postman / Apifox：新建一个 Request，填上 API 地址（比如 https://api.notion.com/v1/users/me），填好 Header，发个 GET 请求。如果能返回用户信息，说明密钥和网络都没问题，那就是你代码逻辑写的有问题了。
  • Curl 命令：在终端里直接跑一条 curl 命令也是最快的方法之一。

总结

遇到“密钥登录不了”或者“Unauthorized”的时候，别慌，按这个顺序查：

  1. 密钥抄对了吗？
  2. 数据库里邀请这个 Integration 了吗？（重点！)
  3. 网络能不能连上 api.notion.com？
  4. 代码 Header 格式对不对？

通常只要你把权限 Add 进去，问题就解决了一大半。希望这篇分享能帮你救火！

标签: none

评论已关闭