iOS 快捷指令搭配 Notion API，更快速地编辑内容

iOS 快捷指令搭配 Notion API，更快速地编辑内容

Matrix 首页推荐  

Matrix 是少数派的写作社区，我们主张分享真实的产品体验，有实用价值的经验与思考。我们会不定期挑选 Matrix 最优质的文章，展示来自用户的最真实的体验和观点。  

文章代表作者个人观点，少数派仅对标题和排版略作修改。

---

我在推荐 Notion 的时候，总是会提起 Notion 更适合大屏使用，这不仅是因为数据库的数据一旦多了，在手机屏幕上看就显得很局促，更是因为一旦数据多又遇上网络原因，Notion 在手机上加载的速度会变慢。

我目前不仅使用 Notion 作为主力的知识管理笔记软件，把正在学习的知识记录在 Notion 上，同时，Notion 也是我的 GTD 管理软件，我倾向于把待办事项或转瞬即逝的灵感记录在 Notion 对应页面里，方便事后直接对事项进行管理和追踪。

比如说，我不再在豆瓣上标记想看或正在看的电影条目，转而在 Notion 上新建一个数据库对它们进行管理。

这个时候，问题就来了。如果我刚好没有正在使用电脑，却需要在 Notion 里记录我想看某一部电影，但我的片单数据库很庞大，我受够了等待 Notion App 缓慢的加载，我不需要查看整个数据库，却要等待整个数据库加载完成。我就在想，有没有什么更快捷直接的方式可以让我不用打开 App 又可以往 Notion 发送数据呢？

于是我想起了「iOS 快捷指令」。

iOS 快捷指令

iOS 快捷指令是什么？对少数派的读者来说，想必是再熟悉不过了，我就不多介绍了。

在使用快捷指令往 Notion 发送数据的过程中，我们可能会用到这四个操作。

第一个是「要求输入」。这个操作会弹出一个对话框，要求用户输入信息。如果我们要发送到 Notion 的数据是自己手动输入的话，就可以用上它。

第二个是「获取剪贴板」。这个操作会把你刚刚复制的内容传递到下一个操作里。如果我们要把复制的内容发送到 Notion 就可以使用它。

其他操作可以视每个人具体情况来选择使用，以上两个是我目前会用到的，所以就简单介绍一下。

第三个是「添加到变量」。这个操作可以把一些信息存储到一个变量里，方便后续调用。这个操作不是必需用到的，也可以用别的方式存储变量，但我在这里还是提一下吧。

最重要的一个是「获取 URL 内容」。这个操作可以设置指定的 HTTP 请求方法来访问指定 URL。这正是向 Notion 发送数据的关键步骤。

HTTP 请求

你可能会不解，向 Notion 发送数据，和获取 URL 内容有什么关系呢？它们看起来似乎完全是相反的操作。

这里就需要解释一下什么是 HTTP 请求了。

HTTP 请求就是指客户端向服务端发送处理信息的请求，当我们使用浏览器上网的时候，浏览器就是客户端，提供服务的另外一端就是服务端。

处理信息的请求有多种，有 GET、POST、HEAD、PATCH、DELETE等，其中最常用的就是 GET 和 POST，对应着我们上网浏览内容和把内容发到网上这两种行为。

当我们通过一个网页链接（即 URL）访问服务器时，如果访问成功，网页包含的内容便会展示在我们面前。这就是一个 HTTP 请求的过程，所使用的 HTTP 方法是「GET」。

我把 GET 请求理解为向服务端请求「你把我要看的东西给我」。

当我们打开一个网站，往上边填写内容时，用到的 HTTP 方法则是「POST」。POST 请求就是把数据提交给服务端，服务端根据客户端提交的数据来做出相应的回复，有的时候服务端可能会新建资源来储存你的请求或者对已有资源进行修改。

我把 POST 请求理解为向服务器请求「你把这份数据给我记下来」。

我们在 Notion 里记录内容，就是在进行 POST 请求，这些请求通常情况下都是由浏览器来帮我们处理，我们也可以通过自己编写程序来访问 Notion 进行 POST 请求。

在电脑上，我们可以用 Python 之类的语言来写代码，在手机上，快捷指令就提供了「获取 URL 内容」这个操作，让我们可以编写这样的请求，而且，快捷指令的视觉化设计让使用者不需要有什么编程基础就能够轻松上手。

解释完 HTTP 的 POST 请求方法后，我们需要进一步了解 POST 附带的数据格式应该怎么写，即平时我们直接打字输入的内容，服务器是看不懂的，我们需要将内容转化为服务器看得懂的格式，发送给它，它才能将其正确地记录下来。

这就需要用到 Notion 的 API 了。

不过，在讲 Notion API 之前，或许我们需要先知道 API 是什么。

我看了一些讲解「API 是什么」的视频，通常情况下大家都会举例来解释——

假设你现在要做一个与天气相关的应用程序，你需要天气数据，你可以选择自己想办法费时费力地去获取数据，也可以寄希望于气象机构能够给你提供天气数据，这就相当于你要吃饭，你可以选择自己做饭，亦可以选择去餐馆吃饭。

你需要知道气象机构具体如何统计数据的吗？不需要，你要的只是数据，就像你不需要知道厨师是怎么做菜的，只要他们能把菜端上来就行。

那么，你要如何让气象机构给你提供数据呢？你或许认识气象机构里的科学家，他们可以直接给你个人发送数据，但如果你一天24小时，每小时都要问一次，连续问足365天，她们回答得过来吗？又或者，这世界上有成千上百个与天气相关的应用程序，它们都挤过来问，可行吗？

这时候就需要 API 出场了。气象机构写一个 API，定义了用户该如何获取到气象数据，比如要用什么 HTTP 方法访问什么地址、数据格式应该怎么写等等，这样，不只是你，世界上任何一个人想要访问气象数据，只要按照 API 说的，操作就行了。类比到餐馆的例子，API 就是服务员和菜单，任何一个食客要吃到菜，不用每个人都挤到后厨和厨师说，只需要根据菜单来点菜就行，菜就能端上桌了。

图源：cleveroad

UI 大家都知道，是用户操作应用程序时的界面，它和 API 很类似，都是所有使用者遵守同一套规则就可以实现应用程序提供的功能，且均不需要知道应用程序内部是如何运作的。

UI 和 API 确实有共通之处，从名字就可以看出。UI 是「User Interface」的缩写，通常被翻译为「用户界面」，而 API 则是「Application Programming Interface」的缩写，通常被翻译为「应用程序接口」，但如果是逐字对应的直译的话，我会翻译为「应用程序编程界面」。如果理解了 UI 是面向 User（面向人类）的话，那也就能顾名思义地理解 API 是面向 Programming 的，是给程序使用的界面/接口。

所以，我们平时通过网页或App访问 Notion 时就是在使用着 Notion 的 UI，而现在我们要写一个脚本，把数据上传到 Notion，就势必需要用到 Notion 的 API。接下来，我们就要透过了解 Notion API，就能够知道要用什么 HTTP 方法和要把数据转换成什么格式发送给 Notion， Notion 才能读懂。

Notion Integration

要能够顺利使用 Notion API，最重要的是要先拥有使用 API 的权限，也就是要先创建一个 Notion Integration。

Notion Integration 是什么？根据介绍和翻译，它可以被理解为是「一个集合了创建、阅读和编辑功能的集成工具」，根据功能也可以被理解为是一个机器人，这个机器人可以修改你 Notion 库里的内容。

为什么必须要拥有一个 Notion Integration？就像我们使用 Notion 时，首先需要登录账号才能改动 Notion 库里的内容一样，同理，当我们使用 Notion API 去修改工作区里的内容时，Notion 也要先验证你是不是拥有修改权限的那个人，总不能什么人都可以放进来随意修改吧。

怎么验证？就是对暗号，你告诉它，你有这个 Notion Integration 的 token（令牌），它就放你进去了。

如何创建 Notion Integration？ 

Integration 在此页面（https://www.notion.so/my-integrations）点击「Create new integration」可以自行创建。

Integration 名称必填，用于在有多个不同功用的 Integration 的时候区分它们。关联的工作区（Associated workspace）必填，选择要使用此 Integration 来工作的工作区即可。Logo 选填，功能（Capabilities）一般采用默认设置。如此操作，我们现在就拥有了一个有权限的机器人。

如何获取 token？

在 Notion 使用界面的左上角，打开「Settings & Members」，在左侧侧边栏选择「Integrations」，找到你要使用的那个 Integration，点击它右边的三个小黑点，就有复制 token 的选项，粘贴出来就可以看到明文的 token。

如何授权 Notion Integration？

最后一步，授权。创建了 Integration 之后，它还什么都控制不了，你要到你想让它控制的 Page 那里授权让它可以使用。具体步骤为点击 Page 右上角的「Share」，再点击「Invite」，选择你的 Integration 即可。现在，它就拥有权限修改你这个 Page 里的内容啦。

创建快捷指令

我们首先来到快捷指令这个 App 的界面，点击右上角的「+」，即可开始创建快捷指令。

准备传递的内容

先问自己一个问题，我要把什么内容发送到 Notion？

举开头提的例子，我要在 Notion 里记录想看的电影或者剧集，这时候我需要手动输入片名等信息，那么我就可以用上「要求输入」这个操作。

请求含某某提示的文本，点击「提示」可以修改对话框弹出来会提示的信息，比如可以输入「影片名称是？」，点击「文本」可以修改输入数据的类型，可以是文本，是数字，或者是日期时间等等，这里我用到的就是「文本」。

接着，使用「添加到变量」这个操作，把输入的文本内容，存储到叫「影片名称」的变量里，方便后续使用。

我的片单数据库里还有两个信息要填，一个用于分类是剧集还是电影，一个用于分类是想看还是已经在看了。所以依样画葫芦，我又添加了两个「要求输入」的操作，并分别存储到「影片形式」和「影片状态」这两个变量里。（「剧集/电影」和「想看/在看」原本在 Notion 中就是单选选项，所以也可以使用「从菜单中选取」这个操作来添加至变量中。）

把内容传递到 Notion

现在我们准备好了要发到 Notion 的内容，接着就要确定怎么把这些内容发到 Notion 里了。前面介绍的「获取 URL 内容」这时候就正式派上用场了。

我们可以先打开 Notion API 的页面（https://developers.notion.com/），选择「API Reference」。在这里，Notion 展示了一些范例，我们可以逐步来了解怎么看懂这些页面，学会如何把 Notion API 转化进 iOS 快捷指令。

在左侧侧边栏，Notion API 提供了很多功能，可以创建一个数据库（Create a database），或者查看页面内容（Retrieve a page），或者在页面里增加一个模块（Append block children）等等。那么，我们要怎么确定要使用哪个功能呢？

所以我们需要再次明确，我要用 Notion API 实现什么？比如，我要把想看影片加入我的片单数据库。这个动作对 Notion 来说，就是在某个数据库里添加一页，所以我需要的就是「Create a page」，这一页就是讲解怎么在数据库里添加一条新的数据的。请注意，这个操作是在已有的数据库里新增，而不是在你的 Notion 库里新增一个 Page， Notion API 无法做到后者。

确定好使用哪个功能之后，我们现在可以正式进入 iOS 快捷指令编写操作了。

「获取 URL 内容」这个操作，第一个要填的，是URL，就是问你要访问哪个链接，把数据发送给它。我们可以在「Create a page」大标题下看到 Notion 给的链接，这里用到的是「https://api.notion.com/v1/pages」。

接着要填写的是，使用什么方法。方法在链接前会注明，这里用到的是「POST」这个方法。

选择「POST」之后，接下来要填写头部。头部，就简单理解为是放一些验证信息的地方吧，用于告诉服务器你是谁、你来自哪里之类的。前边提到的 Notion Integration 就是用于此处的。

具体要填写的内容，可以通过查看 Shell 语言的示例来找到，标注「-H」的这三行就是必填的头部信息。

点击「添加新头部」，「键」就是填冒号左边的信息，「文本」就是填冒号右边的信息。

「Content-Type」是键，「application/json」是文本，「Notion-Version」是键，「2022-02-22」是文本。值得注意的是，「Bearer '"$NOTION_API_KEY"'」应该把「'"$NOTION_API_KEY"'」替换成你的 Integration 的 token，假设我的 token 是「secret_LteipcmxfX5zu6eCZ0iLyHL6Q57e8zg2K31fLAfBNNb」，那么「Authorization」是键，「Bearer secret_LteipcmxfX5zu6eCZ0iLyHL6Q57e8zg2K31fLAfBNNb」就是文本。

填写完头部之后，就需要写请求体了。请求体是「JSON」格式，默认不需要改动。

点击「添加新字段」，就可以开始填写我们要发送给 Notion 的数据了，参考的部分就是 Shell 语言里「- -data」这部分内容。

点击「添加新字段」之后需要选择的是布尔值、词典、数组、数字或文本这五个选项，我有一个方法，大家可以记住，看到冒号后面是大括号就选「词典」，看到冒号后面是中括号就选「数组」，看到冒号后面是引号就选「文本」就行了。

比如说第一个必填信息是「parent」，必须注明是哪个数据库，Notion 才可以往里面新增数据。「parent」冒号后面跟着大括号，那就选「词典」，键就填「parent」，点击「0项」继续填写，又遇到要添加新字段选择格式，我们看到「database_id」冒号后面跟着的是引号，那就选「文本」，键就填「database_id」，文本呢，填写的是你要新增数据的数据库的 id。数据库 id 可以通过链接查看，在「?v=」前的32个字符就是数据库 id，填写进去即可。

请求内容的第一部分就填完了。

接下来的「icon」和「cover」不是必须填的，这两个指的是数据库的 icon 和封面，自己在客户端上手动调整就好。

来到必填的「properties」，这里就是放你的数据的地方，不填怎么告诉 Notion 你要新增什么数据上去呢？

再次点击「添加新字段」，「properties」冒号后跟着大括号，那就选择「词典」，键是「properties」。点击「0项」，再点击「添加新字段」，「Name」冒号后跟着大括号，选择「词典」。

这时候稍等一下，键不是一定要填写「Name」，这只是 Notion 的示例而已，键要填写的，是你这个数据库里类型为「Title」的那个属性的名称，在我的情况中，键就是「片名」。

继续点击「0项」，再点击「添加新字段」，「title」冒号后面跟着中括号，那就选「数组」，键是「title」。在数组里点击「添加新字段」，因为「text」冒号后面跟着大括号，所以选择「词典」。但这时却不需要填写键了，而是变成灰色不可修改的「项目1」，无需理会，继续点击「0项」和「添加新字段」。因为「text」部分还没有填写，所以仍然因为它冒号后是大括号而选择「词典」，键填「text」。点击「0项」和「添加新字段」，因为「content」冒号后面跟着引号，所以选 择「文本」，键填「content」。而文本部分，则选择变量「影片名称」即可。这样子，Notion 就会以输入的影片名称作为标题来创建新页面。

从刚刚的举例中，不难看出，在示例里，和「Name」同级别的部分都是根据实际情况来修改的部分，而和「title」同级别的部分指的就是属性的类型，比如「Food group」后面的「select」就是指单选类型，「Description」后面的「rich_text」就是指文本类型，「Price」后面的「number」就是指数字类型。

更多不同类型，但又没有出现在示例里的，可以参照我梳理下来的这部分内容进行填写。有下划线和黑色字部分就是根据实际情况来修改的，其他部分就是固定的。

现在，我们再把「影片状态」和「影片形式」这两个变量加进「properties」，就完成了发送给 Notion 请求的这部分操作。

最后，我们可以再加一个「从输入中获取文本」的操作，可以输出向 Notion 发送请求后的结果，用于检查这个快捷指令是否能够正常运行。如果输出中没有提示出现 error，那么基本上这个快捷指令运行起来就没问题了，之后要保留下来或者删掉就任君选择了。

我们还可以给这个快捷指令改一个名称，并添加到主屏幕上就可以快速使用啦。

这个教程，虽然表面上是在讲如何使用快捷指令在 Notion 数据库里添加新的页面的具体操作，但实际上是在讲如何看懂 Notion API 里那些让人眼花缭乱的内容并加以使用。Notion API 各个功能的使用方法其实是大差不离的，你可以通过举一反三的方法来订制适合自己使用情况的快捷指令，比如用它来进行快速的记账，或者把复制的文本内容发送到 Notion 等等。

> 下载 少数派 2.0 客户端、关注 少数派公众号，解锁全新阅读体验 📰 

> 实用、好用的 正版软件，少数派为你呈现 🚀