李崇欣 蒋炜航

本文刊登在《程序员》杂志2012年第9期。http://www.programmer.com.cn/13334/

开放与合作是当今互联网的主题之一，而提供Open API也成为了当下互联网服务提供商的一个趋势。在这个趋势下, 服务提供商、第三方应用、以及用户达成了三方共赢的局面：服务提供商通过第三方应用，为用户提供了更加多样化的服务，从而获得更高的用户活跃度与更强的用户粘性；第三方应用通过Open API非常简单地就能够在服务提供商的基础服务之上为用户提供更加精细化的服务，并接入服务提供商的用户群，从而获得快速增长的机会；作为用户，只需要一个账号就能同时享受服务提供商和第三方应用提供的服务。

个人云存储服务是这几年来日益成熟的一类云计算服务。特别是同步网盘和同步云笔记这两类云存储服务，通过同步的机制为个人用户提供了跨平台、跨设备的云存储服务，成为了时下流行的个人云存储服务形态。由于这两类云存储服务所提供的Open API有众多相同之处，本文将以同步网盘（Dropbox、Google Drive）和同步云笔记（有道云笔记、Evernote）的Open API为例，来讨论设计一套个人云存储的Open API需要考虑哪些因素，以及第三方应用应该如何使用个人云存储Open API。

云存储Open API 

图一: Open API应用场景

和其它云服务的Open API一样，云存储Open API的使用场景中包含了三方：服务提供商、第三方应用、以及用户。如图一中所示，云存储服务提供商通过开放Open API，与第三方应用一起提供更加丰富的功能和体验给用户，提高用户的忠诚度和活跃度。从第三方应用的角度看来，通过Open API第三方应用可以将存储服务委派给云存储服务商，从而降低自身的运营成本，专注于提供更有特色的服务。同时第三方应用还可以通过Open API接入云存储服务商的用户群，从而获得高速增长的机会。作为用户，通过Open API既能够从值得信赖的云存储服务提供商那里获得稳定、安全的存储服务，又能够通过授权从丰富多样的第三方应用那儿挑选适合自己需求的功能。可以看出，通过一套设计合理的云存储Open API机制，云存储服务提供商、第三方应用、以及用户可以达到三方共赢的局面。

设计一套云存储Open API需要考虑七个元素：授权、跨平台、向前兼容、数据操作、数据模型、数据传输效率、数据访问权限。接下来我们一起通过实例来探讨这些元素。

1.授权

图二：授权认证流程

云存储服务商通过提供稳定、保密、快速的服务获取用户的信赖，成为用户的个人数据仓库。而用户名和密码就是打开这个重要仓库的钥匙。 出于安全的考虑，用户不应该将自己在云存储服务商处设置的用户名和密码告诉第三方应用。 OAuth就是为解决这类问题（第三方无需使用用户名和密码就能申请获得该用户授权）而设计的一套安全、开放、简易的协议。目前绝大多数同步云笔记和同步网盘的Open API都使用了OAuth协议。

为了使用OAuth协议，第三方应用首先需要从服务提供商处申请Consumer Key与Consumer Secret用来对授权请求进行签名。服务提供商通过Consumer Key可以知道Open API请求来自于哪个第三方应用，以便于对请求进行跟踪和监控。一个典型的OAuth认证授权过程如图二所示：

1) 当用户尝试通过第三方应用访问数据时，第三方用户首先向服务提供商请求一个Request Token，在这个请求中，第三方应用需要带上自己的Consumer Key并通过Consumer Secret进行签名以便服务提供商验证请求合法性。

2)服务提供商在验证第三方应用后返回Request Token。

3)在得到Request Token后，第三方应用将用户重定向至服务提供商的登陆页面，重定向请求中需要加入Request Token以表明身份，同时还会加入一个Callback URL参数，以便用户登录授权结束后返回该页面。

4)用户在服务提供商登陆页面上进行认证授权，如果成功，则重定向至第三方应用传过来的Callback URL。

5) 第三方应用被Callback后，便可以向服务提供商请求Access Toke，在该请求中，第三方应用将使用刚刚得到的Request Secret进行签名。

6)服务提供商在验证Request Token/Secret后向第三方应用返回Access Token/Secret，此时第三方应用便完成了一个用户的授权。

7)在获得Access Token/Secret后，第三方应用便可以使用Access Token/Secret访问这个用户的数据。

虽然整个流程描述起来比较复杂，但是由于这个流程对于任何一个第三方应用都是一致的，第三方应用可以很容易地通过对范例程序的修改来实现这个认证流程。

2. 跨平台

作为提供给第三方应用程序使用的服务接口，OpenAPI必须有跨平台的能力。以Dropbox为例，使用Dropbox Open API的第三方客户端应用所基于的平台包括Windows、Mac、Linux、iOS、Android、Windows Phone等等。同样，基于其Open API的Web应用所使用的编程语言可能是Java、PHP、.Net等。因此如何设计一套跨平台、跨编程语言的Open API是每个云存储服务商要考虑的问题。

目前大多数的Open API采用了基于HTTP的实现方式，同时也解决了跨平台的问题。为了方便第三方应用开发，服务提供商有时候也针对在不同平台对HTTP进行相应的包装，提供对应平台的SDK。

另一种实现Open API的方式是提供RPC接口。相比于HTTP接口，RPC接口更方便使用者开发，不必关心参数的传递方式和返回结果的解析，就像使用本地函数编程一样。但是这类实现方式的代价则是难以跨平台。由Facebook开发并开源的跨语言服务开发框架 — Thrift可以在一定程度上解决这个问题。服务提供商可以用Thrift格式的脚本来定义RPC的参数和返回结果。使用Thrift自带的编译器，Thrift格式的脚本能够被自动编码成为不同语言的实现，例如C++、Java、Python、PHP等等。Evernote就是使用Thrift对外提供跨平台的Open API。

3.向前兼容

在发布了Open API后，服务提供商一般会定期更新Open API，提供更多功能来完善接口。但是第三方往往无法及时地更新自己的应用来使用最新的接口。因此服务提供商需要在一段时间内向前兼容旧版本的Open API。

基于HTTP实现的Open API，常通过在URL中添加版本号来做到向前兼容。以Google Drive为例，下载一个指定文件的HTTP接口为：https://www.googleapis.com/drive/v1/files/{id} 其中v1用来表示该API的版本信息，不同版本的API接口使用的URL不同，这样使得Open API接口也在一定程度上保持了向前兼容。

基于RPC实现的Open API相对来说更难处理向前兼容的问题。在此Thrift框架再次提供了一定的便利性。在保证第三方应用不改变对Thrift RPC调用方式的前提下，服务提供商可以使用Thrift编码添加新的接口和参数。当然，这需要服务提供商对Thrift的工作原理有深入的认识。

4. 数据操作

云存储Open API为第三方应用提供的主要功能是对数据的操作。最常见的数据操作包括对数据的读取、新建、修改、删除和移动。除了这些基本操作之外，还有一些与数据相关的高级操作。比如说版本接口允许第三方应用读取用户旧版本的数据；搜索接口允许第三方应用通过关键词来定位用户的数据；分享接口允许第三方应用将用户的数据分享给其它用户。这些数据操作为第三方应用提供了灵活性和便利性。

5. 数据模型

数据模型定义了第三方应用以何种模式来访问云存储中的数据。云网盘的数据模型往往由文件和目录组成。在这种数据模型下，第三方应用可以对云存储进行诸如创建新的文件、修改已有文件的内容、创建新的目录、修改目录名称等一系列操作。

云笔记的数据模型往往由笔记本、笔记以及资源组成。云笔记的笔记本和笔记可以类比云网盘的目录和文件。但是与没有格式要求的文件相比，笔记由于要能够被云笔记的客户端所解析和渲染给用户，因此笔记往往采用类HTML的标记语言来描述。如果第三方应用需要保存的内容不适合使用标记语言来描述，他们可以使用资源。资源和文件一样以二进制数据的形式保存。云笔记中的资源往往依附某一篇笔记，而一篇笔记可以有多个资源。

除了和用户数据相关的数据模型之外，有一些云服务有时候也提供用户账号的访问。通过访问用户账号，第三方应用可以获得例如用户邮箱、云存储服务总空间、云存储服务已使用空间、昵称、注册时间等等关于用户的信息，并提供更加个性化的服务。

6.数据传输效率

对于基于HTTP的OpenAPI来说，出于跨平台的考虑，数据结构或者对象通常以文本的形式返回给调用者，因此为了能够对数据结构或者对象进行复原，通常使用XML这样的结构化描述语言对数据进行描述，在各个平台上都具有较好的通用性且易于扩展。作为一种较新的结构化描述语言，JSON在支持结构化描述时所引入的额外信息较少，因此相比于XML具有较高的传输效率，在最近几年发布的Open API中得到了广泛的应用。而对于文件和资源这样大块的数据，则通过二进制流的方式高速传输。

对于基于RPC的Open API来说，通常直接将数据结构或者对象串行化后进行传输，相比于XML、JSON这类结构化的描述语言，串行化几乎完全不需要任何额外的信息来辅助传输，同时反串行化相比于解析结构化描述语言也具有更快的速度，因此具有更好的传输效率；而另一方面，在兼容性上串行化通常使用直接加入版本信息的方式，这样在反串行化时便可以根据版本信息进行适当的处理；与RPC一样，串行化也存在通用性较差的问题，难以在各个平台及编程语言下通用，目前比较常见的串行化方法有Google的Protocol Buffers、Thrift Serialization及Apache的Avro等。

 7. 数据访问权限

最基础的访问权限来自于授权机制。第三方应用只有在获得了用户的授权之后才能访问该用户的数据，并且用户可以通过撤销授权来阻止第三方应用继续访问自己的数据。

除了最基础的访问权限，不同的云存储服务提供商采取不同的策略。例如Dropbbox按照应用来区隔空间 – 第三方应用只能访问其对应目录下的文件，而不能访问用户其它文件。

Google Drive使用了更为复杂的文件级别访问权限控制。每一个文件都有对应的访问权限列表，只有当用户使用某个第三方应用开启或者新建的文件，该第三方应用才有权限访问该文件。

常见云存储Open API对比

注：本表仅供参考，最新资料请查询各个云存储服务提供商的官方网站。

第三方应用开发

运用云存储服务提供商的Open API, 第三方应用开发商开发出了多种多样的应用场景。这里希望通过一些案例来帮助大家了解云存储Open API带来了什么样的机会。

有一类第三方应用通过连接多家云存储服务提供商的Open API来实现云存储集成服务，使得用户可以在一个应用中访问和管理多个云存储服务中的数据。这类应用的例子是ES 文件浏览器。

另外一类第三方应用专注于处理特殊格式的数据， 并通过云存储服务提供商的Open API来保存这些数据。比如Lucidchart专注于处理流程图，Smartsheet专注于处理项目管理，而PicMonkey专注于处理相片。它们都通过Google Drive的Open API来实现云存储的功能。

还有一类第三方应用专注于对电子内容进行二次处理，比如说对电子内容进行数字签名、传真电子内容、对电子内容进行分享等等。此外智能设备厂商（扫描仪、打印机、电子笔、智能电视）可以使用云存储Open API来为自己的智能设备添加云存储和云同步的功能。此外，浏览器（例如海豚浏览器）和阅读器（网易云阅读，网易新闻客户端）也通过云存储Open API为用户提供了知识碎片整理和收藏的功能。

我们相信在以开放与合作为主题的当下，云存储Open API是顺应潮流的。在三方共赢的前提下，更多有意义的用户场景将会基于Open API被实现出来。我们拭目以待。