FileMaker 17 新功能简介-整合篇（上）

在过去的几周中，相信你对于 FileMaker 17 平台在开发、部署与移动化方面的更新都有了一定的了解，今天我们就来讲讲 FileMaker 17 在整合方面的新功能。

如果要评选 FileMaker 17 平台中最让开发者期待的新功能，恐怕大多数开发者都会投票给正式发布的 Data API。开放了 REST 接口之后，FileMaker 的整合能力得到了极大地提升。开发者可以在任何支持 HTTP 协议的地方通过 Data API 发送请求给 FileMaker Server，来和 FileMaker 定制化 App 做数据交换，比如微信公众号，小程序等等。让 FileMaker 真正地成为了针对全平台的开发工具。

FileMaker Data API 在 FileMaker 16 版本的时候就推出了试用版，在 FileMaker 17 中正式发布。相比较 FileMaker 16 的 Data API 来说，新版本增加了运行脚本以及上传文件至容器字段的支持，并且使用了更加标准化的格式。

我们通过下面这个地址就可以访问到 FileMaker 17 Data API 的指南：https://fmhelp.filemaker.com/docs/17/en/dataapi/。也可以在安装 FileMaker Server 17 之后通过下面的地址来访问 FileMaker Data API 参考：https:///fmi/data/apidoc/

指南之中详细介绍了 Data API 的所有信息，大家在使用 Data API 扩展自己的 App 之前一定要仔细阅读哦。

在使用 Data API 的时候，我们首先需要保证

1

FileMaker Data API 在 FileMaker Server Admin Console - Connectors - FileMaker Data API 中已打开。

2

使用 Data API 登录的帐户中的 fmrest 扩展权限已打开。

在编写 FileMaker Data API 请求之前，我们先来了解一下每一个组成部分。在 FileMaker 17 版本的 Data API 之中，一共支持四种 HTTP method（又叫做 HTTP verb）。分别是：

POST：用于数据库登入、创建记录、执行查找以及上传文件至容器字段。

GET：用于获取一条记录或是一系列的记录。

PATCH：用于编辑记录或是设置全局字段的值。

DELETE：用于数据库登出以及删除记录。

以及五种 HTTP headers：

Content-Type: application/json：用于登入/登出数据库、创建/编辑记录、执行查找以及设置全局字段的值。

Content-Type: multipart/form-data：用于上传文件至容器字段。

Authorization: session-token：除了数据库的登入与登出之外，其他的 Data API 请求都需要在 Headers 之中指定一个有效的 session-token。（登出请求需要在 URL 中指定 token）

X-FM-Data-OAuth-Request-Id 和 X-FM-Data-OAuth-Identifier：用于 OAuth 的登录。

URL 一共有两种，分别是

/fmi/data/v1/databases

/fmi/data/vLatest/database

需要注意的是，FileMaker Data API 只支持 https 的请求。

对于目前版本的 Data API 来说，两者没有任何区别。但是当下一个版本 v2 的 Data API 发布之后，使用 vLatest 的请求会自动使用最新版本，也就是 v2 版本的 Data API。

接下来我将给大家演示一下Data API 请求的具体编写方式。我们使用 Postman 这款功能强大的调试工具来进行 FileMaker Data API 的测试。

我们首先来创建一个登入数据库的请求。从文档中得知，我们需要的 URL 是 /fmi/data/v1/databases/database-name/sessions，其中 database-name 是我们希望登入的数据库名称。接下来我们需要在 Headers 中指定 Content-Type，值是 application/json，以及登录数据库所需要的帐户名称和密码。在 Body 中不需要指定任何信息，只需要填入一个空的大括号即可：{ }

我们将以上信息填入到 Postman 之中，HTTP method 选择 POST。点击 Send 之后，就可以收到 FileMaker Server 的响应了：

可以看到，我们登录成功并且获得了一串 token 用于之后的操作。需要注意的是，如果没有任何操作的话，token 会在 15 分钟后过期，需要重新使用登入请求来获取新的 token。

接下来我们使用这个 token 来获取一下数据库中的记录。使用的 URL 是 /fmi/data/v1/databases/database-name/layouts/layout-name/records，其中 layout-name 是我们想要获得记录的布局名称。在没有指定 _offset 和 _limit 两个参数的情况下，这个请求会返回指定布局中的前 100 条记录。由于我的布局名称是 Meeting Details，包含空格，因此在指定 URL 的时候需要将空格转义为 %20。

之后我们需要将刚刚获得 token 填入到 Headers 中，选择 GET 作为 HTTP method，之后点击 Send：

如图所示，我们得到了 JSON 格式的反馈——Meeting Details 布局中一共有两条记录，每条记录中的数据也都呈现在了我们面前。之后我们就可以将数据做一下整理，再反馈到任一客户端了。

看过了获取记录之后，我们再来看一下编辑记录。我希望将第一条记录中的会议地点，从 Beijing 改为 Shanghai。查阅文档得知，我们需要的 URL 是 /fmi/data/v1/databases/database-name/layouts/layout-name/records/record-id，其中 record-id 可以从上一个请求的反馈之中获得，第一条记录的 Record ID 是 6，并不是 1，这是为什么呢？因为我之前进行过删除记录的操作，现在数据库中存储的第一条记录，并不是最早创建的那条记录了。大家在通过 Data API 编辑记录的时候可要格外注意哦。

接下来我们需要在 Headers 中填入 Content-Type: application/json 以及第一个请求中获得的 token。Body 中我们可以直接从上个请求中把 json 格式的数据复制过来（这也是 FileMaker Data API 中一个很贴心的设置，通过获取记录得到的反馈可以直接用于编辑记录，无需重新输入 json 格式的数据），然后进行一些微调：

{

"fieldData": {

"Location": "Shanghai"

}

}

将 HTTP method 改为 PATCH，然后点击 Send。

编辑记录的反馈很简单，FileMaker Server 只是告诉我们完成请求，没有任何问题，同时把新的 modId 发了回来。从 FileMaker Pro Advanced 之中也可以看到，数据已经成功修改了：

简单介绍了 Data API 之后，接下来我会给大家着重介绍一下FileMaker 17 中新增的两项支持：上传文件到容器字段以及运行脚本。

上传文件到容器的请求使用的是 POST 作为 HTTP method，在 URL 中需要指定数据库名称、布局名称、记录编号、字段名称以及重复项：/fmi/data/v1/databases/database-name/layouts/layout-name/records/record-id/containers/field-name/field-repetition

在 Headers 中需要指定 Content-Type: multipart/form-data 以及 token。在 Body 中选择 form-data，之后指定 upload，以及想要上传的文件。

FileMaker Server 的反馈同样很简单，只有寥寥几行。从 FileMaker Pro Advanced 之中可以看到，文件已经成功上传到了容器字段之中。在 FileMaker 17 版本的 Data API 之中，还不支持将文件上传到入口的容器字段中，所以我们必须指定容器字段所在的布局名称以及相应的记录编号，才可以成功上传。

需要注意的是，FileMaker Data API 在正式发布之后是会计算使用流量的。我们为客户提供了每用户每个月 2 GB 的 Data API 流量，并且可以在一年内进行共享。比如客户购买的是 5 用户版本的用户许可，他将获得 10 GB 每月，也就是 120 GB 每年的 Data API 流量，超出部分才会进行收费。同时，对于在 FileMaker 中向其他软件发送 API 请求所产生的流量是完全没有限制的，只有在其他地方向 FileMaker Server 发送 Data API 请求所获得的反馈，才会计算流量。

对于上传文件到容器来说，无论上传的文件有多大，FileMaker 都只会根据返回值来计算流量。也就是说，我通过一个请求上传了一个 2 GB 的视频文件到我的定制化 App 之中，这其中产生的 Data API 流量就只有返回值，也就是下面这些数据所占用的几十字节而已。

{

"response": {

"modId": "4"

},

"messages": [

{

"code": "0",

"message": "OK"

}

]

}

在 FileMaker 17 版本的 Data API 中运行脚本并不是一个单独的请求，而是作为可选参数在获取记录、创建记录、修改记录、删除记录或是查找记录的时候运行。对于使用 HTTP GET 和 HTTP DELETE methods 的请求来说，需要在 URL 中指定参数，对于使用 HTTP POST 和 HTTP PATCH methods 的请求来说，需要在 Body 中指定参数。下面是支持的脚本参数：

除去三个以 .param 结尾，用来指定 FileMaker 脚本参数的参数以外，通过 Data API 可以在三个时间点来运行脚本。我们来看一下整个过程：

1. 转到 URL 中指定的布局

2. 运行通过 script.prerequest 参数指定的脚本

3. 运行 Data API 请求中指定的操作（获取、创建、编辑、删除、查找）

4. 运行通过 script.presort 参数指定的脚本

5. 运行 Data API 请求中指定的排序操作

6. 运行通过 script 参数指定的脚本

7. 返回 Data API 请求的结果

那么在不同的时间点运行脚本对结果有什么影响呢？我们通过一个具体的例子来看一下。

在我的 App 之中一共有两条会议记录，我希望将会议名称包含 Apple 的会议全部筛选出来。同时，我希望在发送 Data API 请求的时候可以运行一个脚本来创建一条新的空白记录。我需要按照如下格式来编写我的请求。

首先，使用 POST 作为 HTTP method，之后指定如下 URL：/fmi/data/v1/databases/database-name/layouts/layout-name/_find。之后，将 Content-Type: application/json 和 token 填入到 Headers 之中。在 Body 中填入我们的搜索条件：

{

"query":[

{"Title": "=Apple"}]

}

之后填入相应的脚本参数以及脚本名称：

"script": "AddRecord" 或是

“script.prerequest”: “AddRecord”

我们先来看一下使用”script“参数运行脚本所得到的反馈：

由于新建记录的脚本会在 Data API 的查找请求之后运行，因此 FileMaker Server 会返回两条记录——第一条是查找到的结果，第二条是通过脚本新建的空白记录（由于设置了自动输入因此 Date 字段中会有预先输入的数据）。

我们再来看一下使用“script.prerequest” 参数运行脚本所得到的反馈：

可以看到，因为新建记录的脚本在 Data API 的查找请求之前就已经运行完毕了，因此 FileMaker Server 只会返回一条记录，也就是查找到的，Title 中包含 Apple 的那条记录。开发者可以针对不同情况使用不同的脚本参数在不同的时间点来运行脚本。

以上就是 FileMaker 17 版本的 Data API 的一个概览，在文章开头提到的 FileMaker 17 Data API 指南中还有更加详细的介绍。强烈建议在动手配置 FileMaker Data API 之前，先通读整个文档，相信会对 Data API 的配置有很大的帮助。