Index

• 概要

• 使用多个 API令牌进行验证

• 使用多个 API令牌发送请求的范例

  • 准备应用

  • lookup操作

  • 关联记录列表的操作

• 最后

概要

2019年12月的定期维护后，可使用多个API令牌来执行kintone REST API，实现跨应用获取/添加/更新记录。 

这意味着以前只能用密码验证才能执行的REST API也可以用API令牌验证来执行了。
本次介绍其中的一个典型用法，即使用多个API令牌来操作含有lookup及关联记录列表的应用。

使用多个 API令牌进行验证

要使用多个API令牌进行验证，需要在请求头部的“X-Cybozu-API-Token”里指定发行的API令牌。
要在一个请求中指定多个API令牌，有两种方法。

1. 各API令牌用逗号隔开的方式指定
   在HTTP请求头部中，用逗号隔开的方式指定多个API 令牌。
   例：要指定的API令牌为“XXXXXXXXXX”、“YYYYYYYYYY”时
   

   # 用逗号隔开各API令牌的方式    
   $ curl -X GET 'https://<SUBDOMAIN>.cybozu.cn/k/v1/records.json?app=1' \    
     -H 'X-Cybozu-API-Token:XXXXXXXXXX,YYYYYYYYYY'

2. API令牌分别写在不同的头部里时
   curl中，可以用-H选项里分别指定各API令牌。
   例：要指定的API令牌为“XXXXXXXXXX”、“YYYYYYYYYY”时

   # 在不同的头部里指定    
   $ curl -X GET 'https://<SUBDOMAIN>.cybozu.cn/k/v1/records.json?app=1' \    
    -H 'X-Cybozu-API-Token:XXXXXXXXXX' -H 'X-Cybozu-API-Token:YYYYYYYYYY'

使用多个 API令牌发送请求的范例

本次使用curl命令进行以下2种模式的操作。
关于用curl命令执行kintone REST API的方法请参考此文档（日语）。
※ 在macOS Mojave 10.14.6 / curl 7.54.0上确认过可正常运行。

• lookup的操作
  用lookup从客户管理应用中复制值，在案件管理中添加新记录。

• 关联记录列表的操作
  以关联记录里显示的活动记录为筛选条件，搜索案件管理应用里的记录

准备应用

添加应用

为方便大家确认此处介绍的范例，为大家提供了应用模板，请点击链接下载，并加到自己的环境中。
使用现有模板创建应用的方法请参考帮助手册。

导入后kintone中将出现“活动记录（多个API令牌）”、“案件管理（多个API令牌）”、“客户管理（多个API令牌）”这三个应用。

※ 请记住添加的各应用的应用ID。
应用ID是在打开应用时，地址栏里显示的地址https://SUBDOMAIN.cybozu.cn/k/此部分/ 。

 发行API令牌

发行API令牌（参考：发行API令牌）。

在各应用中发行的API令牌的访问权限分别设置如下。

※ 请记下所发行的令牌。

lookup操作

在案件管理应用中，将客户名称作为key从客户管理中lookup数据，复制部门和负责人的值。

另外，请根据自身环境相应更改范例代码中的如下值。

• <SUBDOMAIN>：您自身环境的子域名

• <案件管理应用的应用ID>：刚记下来的案件管理应用的应用ID

• <使用:将用户名和密码连起来并经过Base64编码的值>：用:(半角分号)将用户名和密码连起来的字符串通过 Base64编码的值

• <案件管理应用的API令牌>：刚记下来的案件管理应用的API令牌

• <顾客管理应用的API令牌>：刚记下来的顾客管理应用的API令牌

Before

在对含有lookup字段的记录进行添加/更新时，不可以使用API令牌验证，只能使用密码验证。
例：添加记录（1条）

# 用密码验证添加含有lookup字段的记录    
$ curl -X POST 'https://<SUBDOMAIN>.cybozu.cn/k/v1/record.json' \    
 -d '{"app": <案件管理应用的应用ID>, "record": {"客户名称": {"value": "A信息技术有限公司"}, "案件名称": {"value": "通过密码验证添加"}, "确定率": { "value": "80%"}}}' \    
 -H 'Content-Type: application/json' \    
 -H 'X-Cybozu-Authorization:<用:将用户名和密码连起来的字符串经过Base64编码的值>'

密码验证时，需要可执行REST API的账号。

另外，因为执行用户对kintone的操作权限过大，验证信息外泄时的风险很大。

After

2019年12月定期维护后，可以使用API令牌对包含lookup字段值的记录进行添加/更新了。

在请求头部中指定要添加记录的应用和lookup的复制来源应用的API令牌。

# 指定应用的 API令牌，添加包含lookup字段的记录    
$ curl -X POST 'https://<SUBDOMAIN>.cybozu.cn/k/v1/record.json' \    
 -d '{"app": <案件管理应用的应用ID>, "record": {"客户名称": {"value": "A信息技术有限公司"}, "案件名称": {"value": "通过API令牌验证添加"}, "確度": { "value": "80%"}}}' \    
 -H 'Content-Type: application/json' \    
 -H 'X-Cybozu-API-Token:<案件管理应用的API令牌>,<客户管理应用的API令牌>'

API令牌的权限只能对发行该API的应用进行操作，因此安全性比较有保障。 

关联记录列表的操作

活动记录应用中的，案件管理应用的“记录编号”和活动记录应用里的“案件管理记录编号”一致的记录，通过关联记录列表显示到案件管理应用中。
※准确地说，是“案件管理记录编号（作为关联记录列表的key的字段）”。

另外，请根据自身环境相应更改范例代码中的如下值。

• <SUBDOMAIN>：您自身环境的子域名

• <案件管理应用的应用ID>：刚记下来的案件管理应用的应用ID

• <活动记录应用的应用ID>：刚记下来的活动记录应用的应用ID
  

• <使用:将用户名和密码连起来并经过Base64编码的值>：用:(半角分号)将用户名和密码连起来的字符串通过 Base64编码的值

• <案件管理应用的API令牌>：刚记下来的案件管理应用的API令牌

• <活动记录应用的API令牌>：刚记下来的活动记录应用的API令牌

 Before

“要从案件管理应用获取符合如下条件的记录：关联记录列表内的活动记录的处理时间为2018年的记录”等情况下，
需以关联记录列表内的数据为查询条件，用密码验证进行获取记录的操作。
例：批量获取记录（在查询中指定条件)

# 使用密码验证，搜索关联记录列表的信息并获取记录    
# 查询信息指定如下。    
# 关联给案件管理的活动记录.处理时间 >= "2018-01-01" and 关联给案件管理的活动记录.处理时间 < "2019-01-01"    
$ curl -X GET 'https://<SUBDOMAIN>.cybozu.com/k/v1/records.json?app=<案件关联应用的应用ID>&query=关联给案件管理的活动记录.处理时间%20>=%20"2018-01-01"%20and%20关联给案件管理的活动记录.处理时间%20<%20"2019-01-01"' \    
 -H 'X-Cybozu-Authorization:<关联给案件管理的活动记录.处理时间>'

使用API令牌验证时，需要发送两个请求。 

(1) 从活动记录应用中筛选记录
(2) 用在步骤(1)中获取的活动记录应用的“案件关联记录编号”字段的值，去查询案件管理应用。

# 将活动记录中处理时间为2018年的记录筛选出来带入RESULT    
# 查询条件指定如下。    
# 处理时间 >= "2018-01-01" and 处理时间 < "2019-01-01"    
$ RESULT=$(curl -X GET 'https://<SUBDOMAIN>.cybozu.com/k/v1/records.json?app=<活动记录应用的应用ID>&query=处理时间%20>=%20"2018-01-01"%20and%20处理时间%20<%20"2019-01-01"' \    
 -H 'X-Cybozu-API-Token:<活动记录应用的API令牌>')   
  
# 获取结果中，“案件管理记录编号_用于绑定关联记录列表”的值以[“记录编号1”,"记录编号2",...]的形式带入ANKEN_IDS   
$ ANKEN_IDS=$(echo $RESULT | tr -d '\r\n' | jq -c '[.records[]."案件关联记录编号_用于绑定关联记录列表".value]' | tr -d '\n' | tr -d '[' | tr -d ']')    

# 获取记录编号或ANKEN_IDS一致的案件管理应用的记录    
# 查询条件指定如下。    
# 记录编号 in (ANKEN_IDS)    
$ curl -X GET 'https://<SUBDOMAIN>.cybozu.com/k/v1/records.json?app=<案件管理应用的应用ID>&query=记录编号%20in%20('"$ANKEN_IDS"')' \    
 -H 'X-Cybozu-API-Token:<案件管理应用的API令牌>'

※ 查询结果的处理使用了 jq 命令（※需要安装）。

After 

现在可以用多个API令牌来对关联记录列表进行操作了，使用API令牌验证，只要1次请求即可用关联记录列表中的信息作为查询条件，获取相应的记录。

在查询头部指定要获取记录的应用和关联记录列表的数据来源应用的API令牌。

# 指定应用的API令牌，以关联记录列表的信息作为查询条件获取记录    
# 查询条件指定如下。    
# 关联给案件管理的活动记录的处理时间 >= "2018-01-01" and 关联给案件管理的活动记录.处理时间 < "2019-01-01"    
$ curl -X GET 'https://<SUBDOMAIN>.cybozu.com/k/v1/records.json?app=<案件管理应用的应用ID>&query=关联给案件管理的活动记录.处理时间%20>=%20"2018-01-01"%20and%20关联给案件管理的活动记录.处理时间%20<%20"2019-01-01"' \    
-H 'X-Cybozu-API-Token:<案件管理应用的API令牌>,<活动记录应用的API令牌>'

最后

可使用多个 API令牌后，还可以用API令牌验证跨多个应用进行REST API操作。

我们还将在2020年之后还将发布可对应用设置进行操作的 REST API的 API令牌，敬请期待！

此Tips在2019年12月版 kintone中确认过。