Workflow 教程(八):利用新的请求方法打造 Web 小程序

JailbreakHum

JailbreakHum

41
目录
  1. ${ item.innerText }

在上个教程《征服 Workflow 最高峰》里,我以为那就是 iOS 的极限了,所以起了一个封顶的名字,谁知道 Workflow 在一个小版本的更新就直接把这个「顶」给掀了。

在 Workflow 的 1.5.3 版里,更新出一个质变的功能:对请求报文的方法有了更完整的支持。以前 Workflow 中的 Get content of URL 这个动作只支持 GET 这个方法,现在它支持了 POSTPUT,并且可以让你自定义 Header

这个变化对于有编程功底的人来说可能是意义重大的,他们脑子里会一下子蹦出来期待已久的使用场景,会说这样真的可以在 Workflow 里写更强大的小程序了。事实也确实是这样,比如以前你可以通过 Workflow,在通知中心里调用 扇贝英语 的语音,来对你不会读的单词发音。而现在,你可以把任何地方遇到的生单词添加到你之后要背的词库里。

对于非程序员来说,「请求」「Header」这些词可能已经让你头晕了。但实际上,这些都是 HTTP 的一些很简单的基础术语,是你每天在使用网络的时候无数次处理的东西,并不难理解。我在这篇文章也将系统地为你普及与本次 Workflow 更新的有关的一切 HTTP 知识。1

实际上我倒是觉得这次更新,难度并不在理解 HTTP,而是在于从 API 文档里找到你需要的东西,尤其是授权的方式。只要找到相应内容,问题就能迎刃而解,所以我也会在文章里特别强调查找 API 的部分。除此之外,API 也不是万年不变的东西,想要做一个长期有用的 Workflow 需要注意你所使用的 API 的变化才行。

本文会讲到以下 4 个实例,点此快速跳转:

原理部分

在这一部分主要解释关于这次 Workflow 更新的 HTTP 术语,并没有着力于整体的认识,整体认识要看实例部分。但因为这次特殊,所以还请从术语部分看起,不然看实例也看不明白。

我们所说的「上网」实际上是一种什么活动呢?大多数的时候,它实际上是从客户端(比如你的电脑或者浏览器等使用网络的工具)对服务器(你可以理解为存放着你要上的那个网站或要用的网络服务的文件的地方)的资源(那些文件)进行操作的过程。而这个操作的过程,我们日常使用中会用到的大部分(包括这次 Workflow 更新的内容),是客户端向服务器发送请求,服务器向客户端返回结果。

图片来自《HTTP 权威指南》

比如你在 Safari 里输入 https://sspai.com/30870 读我上篇 Workflow 的文章《征服 Workflow 最高峰》,实际上做了个什么样的事呢?最简化地说,就是你的客户端(Safari)向少数派的服务器发送了一个「请求」,要求获取的是 https://sspai.com/35818 这个资源(对这个页面本身实质上就是个资源),然后少数派的服务器找到了这个资源,返回到你的客户端(Safari)上。

报文

发送请求和返回结果都要通过「报文 (Message)」实现,分别叫做请求报文(Request Message)和响应报文 (Response Message)。报文有它独特的格式,分为「起始行 (Start Tine)」、「首部 (Header)」和「主体 (Body)」三个部分,这三者的任务是:

  • 起始行:对报文进行描述
  • 首部:包含报文属性
  • 主体(非必须):包含数据

报文的格式(图片来自《HTTP 权威指南》)

方法

通常,请求报文起始行的第一个词,是它请求时所使用的「方法 (method)」,这个方法有 8 种,但与 Workflow 相关的有 3 种:

1. GET

Workflow 一直都有 GET,如果对 Get Contents of URL 不做任何处理,就是执行 GET 这个动作。上一篇教程 是对这个功能的详细说明,不明白的还请从上一篇开始看起。

2. POST

支持 POST 是这次 Workflow 更新的最实质的变化。实践中用于上传数据(在服务器创建数据)上传的内容要放在报文的主体(Body)中。在 Workflow 里,可以上传JSON、Form 或 File 三种格式。三者在 Workflow 里的区别是:JSON 只能传输数据,Form 可以传输数据和文件,File 只能传输文件。具体要使用到哪一个,要看你使用的 API 要求你用什么。

sm.ms 图床文档格式要求

如果没有特殊声明的话,也许要求就没那么严格,你可以在功能交叉的地方随意选择格式。

3. PUT

按照标准来说,PUT 和 POST 不一样的是,PUT 是用来更新数据的,而当服务器上没有指定数据的时候,PUT 也可以创建。但是也有一些特殊情况,用 POST 更新数据,用 PUT 创建新数据。在这不做深入讨论,总之,在我们的具体操作中,使用 POST 还是用 PUT 也要看你所使用的 API 要求你用什么。比如 sm.ms 就要求你使用 POST 来上传图片:

sm.ms 图床文档要求使用 POST

这样的话在实际使用中是你不会因为选择方法而为难的。

状态码

在结果返回的报文的首行,会出现「状态码 (status code)」,状态码是一个对你发送的请求的结果的最简单的判断:

图片来自《HTTP 权威指南》

状态码分类,在《HTTP权威指南》里有对状态码更详细的解释。

在前文图中结果返回的首行里,状态码为 200,后面还接了一句 「OK」,这个 OK 是原因短语 (reason phrase),用于简单说明请求的结果。

实例

了解完术语,我们再来看 Workflow 这个新动作,就不会那么慌了。

本次重点更新的 Get Contents of URL 动作

现在来结合几个简单的实例,来看看这个新动作的每个地方都该怎么选,怎么填。

在这里你要避免幻想 Workflow 有一个统一的规则去做所有的事。因为这次已经涉及到不同产品的 API,每一家都有每一家不同的地方,所以想用哪一家的服务,就要查它的 API,API 也有更换的可能,所以一个 Workflow 用着用着不能用了,要考虑到 API 变化的可能。

上传图片返回链接

这部分用的是 sm.ms 和 Imgur 两个例子,两者比较接近。我感觉 sm.ms 是利用 API 能做到的最简单的动作了,API 相关动作只有一步,需要填写的特殊内容也非常少。而 Imgur 稍微复杂一点,涉及到一点 Token 的内容,可以让你更深一步地认识这个动作。

(1) 图床一:sm.ms

动作下载 >

在这个 Workflow 里,第一步是:获取图片设变量。

为什么要给图设个变量呢?因为在接下来的 Get Contents of URL 里,没有让你选择图片的地方,你只有把你要设成的地方设为一个变量,填到应该填的位置。

第二步:发送请求报文。

首先你一定要给出你发送请求的服务器的位置(URL),然后再说请求什么,这是一个很浅显道理… 在这里你要注意看文档,sm.ms 的文档中要求的 URL 是 https://sm.ms/api/upload

注意这个 URL 最后没有接 /。在 URL 里,接不接这个 / 的意义是不一样的,所以你要严格要求文档的要求来。

下面就要填东西了,首先,请求报文第一项是位于首行的 Method,在这里我们要选 POST,因为上图中的文档里要求我们选 POST。

下一步,Header 部分,什么也不用填。因为在这个 API 里用不上 Header。

在下面是主体 (Body) 部分,这里要根据 API 的要求,填入参数名称(也叫键,英文是 key)和文件:

我们要上传的是图片,属于文件 (File),所以参数名称要填 smfile,然后把我们前面选好的图所设的变量放进来。

请求报文部分就结束了。

第三步:获取 URL。

请求报文结束后,如果你在那一步下面接一个 Quick Look,你会发现它会返回给你一堆东西:

这些是 JSON 文件,也就是返回给你的结果。我们要拿的 URL,在 data 下的 url 里。

所以我们可以用之前在《征服 Workflow 最高峰》提到的方法,通过 Get Dictionary Value 这个动作,一步一步地把这个 url 取出来。

最后的处理,你可以选择将链接复制到剪切板,还可以在复制之后弹出一个通知或者提示(我给的动作是先复制链接,然后再在 Safari 打开网页,这一步借鉴了 @三块五毛 的同样功能的 Workflow,这样可以让新手知道这个 Workflow 成功了)。这样的话,如果你最开始的动作是选择最后一张照片,整个过程是可以不离开通知中心完成的。

(2) 图床二:Imgur

动作下载 >(不能直接用,需要在 Workflow 填入授权信息,填法见下图)

Imgur 这个动作和 sm.ms 非常接近,我只说一下不一样的地方。

不同处一:需要在 Header 中授权

sm.ms 那个动作的 Get Contents of URL 这一步是不需要 Header 的,但在 Imgur 这里需要,因为 Imgur 本质上不是一个完全匿名的图床,它只是提供匿名上传的服务。而当我们在 Imgur 匿名上传图片的时候,需要验证第三方应用身份。

这个第三方应用我们可以自己申请(你也可以不申请直接用我申请好的应用提供的授权信息,填法见上图),申请过程很简单,在 这个页面 填写要你填写的内容,「Authorization type」 这一步选择 「Anonymous usage without user authorization」 即可。

应用建立成功后的页面,会告诉你「如果是上传匿名图片」,你需要把下面的内容填写进 Header:

Authorization: Client-ID YOUR_CLIENT_ID

这里的,这里的 YOUR_CLIENT_ID,就是页面下方显示的 4ba1877d782a602

填完 Header 以后,要填 Body 的部分,这部分我们同样要遵照 Imgur 的 API 文档 中的要求来填写。

图中要求:

  • Method 要使用 POST,所以不能用 PUT 咯。
  • 路径有两个,一个是 https://api.imgur.com/3/image,还有另一个选择是 https://api.imgur.com/3/upload,两个选哪个都可以。
  • 而因为 JSON 不能上传文件,只有 Form 可以上传文件和参数,所以我们要选择 Form。
  • 左边的参数名称要按要求填 image,然后右边放进去刚才设好的图片变量。

填完以后应该是这样

接下来,只要获取图片链接就可以了。上篇教程和前一个例子都谈到这一步该怎么做了,这里就不多说了。

扇贝英语 API

(1) 动作一:上传生单词到扇贝服务器

在我知道的应用里,扇贝单词是目前背单词软件里方法最科学的。而且它有一系列的关联服务,比如扇贝阅读,它可以让在读英文新闻的时候,遇到不认识的单词,就能放进扇贝单词中,以扇贝单词那一套背诵方式去背诵。我一直都想搞一个什么东西,可以非常快的把我阅读过程中遇到的生单词发送到扇贝单词,融入到我正在背的列表里,利用扇贝的记忆曲线设计来记忆这个单词。

现在 Workflow 可以做到这件事了,你可以把不会的单词复制,拉出通知中心跑一个 Workflow 的动作,就能直接把这个单词发到扇贝的服务器上,下次你背单词就能看到这个新单词了。

动作下载 >(这个动作不能下载了就直接使用,需要你登录你的账户,你要仔细看一下下文中的授权过程)

首先,我们还是要看一眼 扇贝单词的 API 文档,来整理一下思路,看看如何下手。

添加单词

很快我们找到「添加单词」的 API,然后发现,它要的参数是 id,单词的 id。那我们就要找,单词的 id 该怎么获得。在网页里搜「id」,你会找到在「查询单词」的部分,有一个 id,看起来像是我们要的东西。

搜索「id」

那怎么获取这个 id?我们再看参数,这次要的是 word,要查的单词。那这好办,我们就是查单词,肯定少不了 word。所以我们可以先搜单词,在搜单词以后返回的 JSON 中,获得单词的 id,然后把这个单词按照「添加单词」那个项的要求去做,就能上传要背的单词了。

在 Workflow 里,我们先做查询单词的动作,根据要求,在 URL 里填入 https://api.shanbay.com/bdc/search/?word={word}。但这里的 {word} 是你要查的单词,在 Workflow 里我们可以把它换成剪切板。然后通过 Get Contents of URL,获得我们第一步的目标,JSON 文件,因为我们要在里面找 id。

找到 id 以后,我们将其附到一个变量上,然后执行添加单词部分要求的各个内容。首先是 URL,这次要填写添加单词而不是查询单词的 URL,所以是:https://api.shanbay.com/bdc/learning/,然后接 Get Contents of URL,方法要选择 POST,因为扇贝要你用 POST。在 Body 部分,我们可以选择 JSON,也可以选择 Form,左边填写参数名称「id」,右边放进去刚才设好的 id 的变量。

看到这,你应该意识到一个问题,这组 API,怎么可能知道我的扇贝账户是啥呢?它不知道我是谁,它怎么能把单词传到我的词库里呢?

是的,它不知道,因为我们少了授权的一步,所以这个动作这样下去会报错。那么该怎么授权?扇贝的授权方式,和 Imgur 那里是不一样的,因为这次,你不是匿名上传了,你需要登录了。

现在大部分服务因为安全原因都已经开始使用 OAuth 2 验证了,使用这种验证方式的服务很多不能在 Workflow 里简单地使用。不过,一些使用 OAuth2 的服务同时提供了一种简化的授权方式,我们可以在浏览器里直接获得一个有固定过期时间的 Token,然后在 Workflow 里,通过这个 Token,让服务器知道我们是谁,最后以我们的身份使用服务。

扇贝允许用户 自行创建小程序 来访问数据,和 Imgur 一样也是填写一些简单的信息即可,只是回调地址要填:https://api.shanbay.com/oauth2/auth/success/Autherition grant Type 要选 Implicit2

应用创建完毕以后,会返回给你 App Key,它是你创建授权页面必须的东西:

按照扇贝的文档,你要把 App Key 和回调地址填入到下面这个链接并打开这个链接:

https://api.shanbay.com/oauth2/authorize/?client_id=YOUR_CLIENT_ID&response_type=token&redirect_uri=YOUR_REGISTERED_REDIRECT_URI

这个链接里大写的 YOUR_CLIENT_ID 就是 App Key,YOUR_REGISTERED_REDIRECT_URI 是之前填的 https://api.shanbay.com/oauth2/auth/success/

如果你嫌自己做一个小程序麻烦,可以使用我做好的应用来授权你的账户,我是得不到你的账户信息的。

做法是,把下面这个链接复制到你的 Safari 里打开,并选择授权:

https://api.shanbay.com/oauth2/authorize/?client_id=46a597fbfac8abf287be&response_type=token&redirect_uri=https://api.shanbay.com/oauth2/auth/success/

然后你会看见这样一个很空的网页,你需要复制这个页面的网址,然后粘贴到笔记本或者什么地方:

https://api.shanbay.com/oauth2/auth/success/#access_token=这里就是你要保存的Token&token_type=Bearer&state=&expires_in=2592000&scope=read+write

再把 #access_token&token_type 之间的东西复制下来,这就是告诉整个 Workflow 你是谁,让你能上传生单词到你的账户的东西。

这个叫做 Token 的东西,应该放在 Workflow 的哪个部分?想想 Imgur 那个 Workflow 的授权过程,放在了 Header 里,所以之类也不例外,你要把这个 Token,以扇贝要求你的格式,放到 Header 里。

它要求的格式是 Authorization: Bearer TOKEN,这个格式前面已经见过了,TOKEN 就是上文链接中让你截取的那部分。再次说明这个 TOKEN 必须是你自己按照上面的步骤生成的,我不能直接给我的 TOKEN,那样你会把单词添加到我的词库里……

以上,整个添加单词动作的关键部分就结束了,首先是获取单词 id,然后是在授权的前提下,把单词 id 发送到扇贝服务器,记录到你的单词表里。

一般来说,只要能获取单词 id,就能上传成功,所以这里就不提怎么判定是否上传成功的办法了。不过前面提供下载的动作,是有判断是否查询成功和上传成功的部分的。

(2) 动作二:让扇贝单词帮你读不认识的单词

iOS 系统用的是机械发音,扇贝词库里有美音也有高贵的英音,遇到不会的单词当然听真人发音更好,利用扇贝单词的 API,你也可以做到这一点。

动作下载 >

这个 Workflow 可以直接在文章中选中单词,运行 Workflow 来获得发音,也可以复制单词,通过通知中心运行来发音。

这个动作算是附赠,它虽然很实用,但是 Workflow 没更新之前就能做到,只是这次思考大家都感兴趣的 API 会是什么的时候,想到了扇贝单词,发现可以实现这么一个功能。

其它有关的 Workflow

  • Macstories 关于这次 Workflow 更新的 文章 里提到了 Toggl/Slack/Todoist 相关的动作,对于使用这些工具的人都是很实用的。
  • Twitter 上的 @Se7en_YXS 做了一个下字幕的 Workflow,用的是 subhd.com 的数据,实用性还可以,不成功或者有不明白的找他问。是位比较踏实的 Power User。

欢迎在评论里留下你利用这次更新制作的 Workflow 来供大家参考,当然也欢迎你写成文章详细说明制作方法。

结语

这次 Workflow 更新,虽然本质上也是拓展 iOS 能力和我们这些用户想象力的一次更新。但实际上普通用户可能很难受益,其中不少人就算是看完这种教程也未必能摸明白。我也是在发布后临时学习相关知识后赶出的这篇文章。所以我的感想并不是 Workflow 变得又强大了,而是你有多快就会被淘汰,有多快就会变得想追都追不上的问题。

虽然 iOS 的自动化之路真正走得没多久,但步子迈得并不算小。就在一两年前,在不越狱的前提下,iOS 上的「效率工具」所能用的就只有 URL Schemes,它已经足够简单,但还是很多人不愿意学。后来 Workflow 来了,把一些通过 URL Schemes 做的事搞得更简单了,还完成了许多 URL Schemes 做不成的事,但那些不愿意学 URL Schemes 的人,也学不会 Workflow 的大部分能耐。现在 Workflow 又进化到了可以做 POST 和 PUT 这样的事了,这些人更不会想学了。

大概所有领域都是这样,走在前面的人,每次只用学很少一部分东西,就能继续保持不掉队。但从一开始就懒的人,会越来越跟不上。当然,你可以不屑,可以选择欣赏路边风景,可以重复机械的操作,可以永远伸手。但你可能体会不到这种踏实下来,为了自己困扰的问题去学习一套东西,最后解决掉它的快感。

最后感谢 Pomotodo 的前端 @c4605 在这篇文章写作中对我的关于技术方面的指导。我们说好了,技术概念解释错误的,他替我撕?。


  1. 当然介乎篇幅也不能完全把这部分东西说清楚,在这部分主要参考的是 《HTTP 权威指南》,大家可以看第一部分的前三章,就能了解到足够的内容了。 ↩︎
  2. 为什么要这么选?因为这都是扇贝要求的,详情见该文档页尾。 ↩︎

继续阅读 中文互联网内最好的 Workflow 系列教程(共 8 篇) >


41


App 打开

商务合作

bd@sspai.com

网站反馈

feedback@sspai.com