2019年12月の定期メンテナンス で、複数のAPIトークンを使って、kintone REST APIによる複数アプリにまたがるレコードの取得・作成・更新が可能になりました。

今まではパスワード認証でしか実行できなかったREST APIを、APIトークン認証でも実行できるようになりました。
その一例として、ルックアップや関連レコードが設定されたアプリの操作を、複数APIトークンをつかって行う方法を紹介します。

APIトークンによる認証では、リクエストヘッダーのX-Cybozu-API-Tokenに生成したAPIトークンを指定します。
1つのリクエストで複数のAPIトークンを利用するには、2つの方法があります。
指定するAPIトークンがXXXXXXXXXXとYYYYYYYYYYの場合で説明します。

• APIトークンをカンマ区切りで指定する方法
  HTTPリクエストのヘッダーに、APIトークンをカンマ区切りで指定します。

  1 2	# カンマ区切りでAPIトークンを指定 $ curl -X GET 'https://<SUBDOMAIN>.cybozu.com/k/v1/records.json?app=1' -H 'X-Cybozu-API-Token:XXXXXXXXXX,YYYYYYYYYY'

• APIトークンを別々のヘッダーに分ける方法
  curlでは、APIトークンの指定を別々の-Hオプションに分けて指定できます。

  1 2	# 別々のヘッダーで指定 $ curl -X GET 'https://<SUBDOMAIN>.cybozu.com/k/v1/records.json?app=1' -H 'X-Cybozu-API-Token:XXXXXXXXXX' -H 'X-Cybozu-API-Token:YYYYYYYYYY'

今回はcurlコマンドを使って、次の2パターンの操作をします。
curlコマンドでkintone REST APIを実行する方法は curlコマンドでkintone REST APIを実行してみよう で解説しています。
macOS Mojave 10.14.6 / curl 7.54.0で動作確認しています。

• ルックアップの操作
  顧客管理アプリからのルックアップで値をコピーして、案件管理にレコードを登録する。
• 関連レコードの操作
  関連レコードで表示した活動履歴を検索条件にして、案件管理アプリのレコードを検索する。

アプリの追加

アプリストアから「営業支援パック」を追加します。
サンプルアプリを追加する を参考にしてください。
このとき、「サンプルデータを含める」にチェックを入れた状態で追加してください。

kintoneに「顧客管理」「案件管理」「活動履歴」の3つのアプリが作成されます。

追加した各アプリのアプリIDをメモしておいてください。
アプリIDは、アプリを開いたときのURLのhttps://SUBDOMAIN.cybozu.com/k/この部分/です。

APIトークンの生成

APIトークンを生成します。
APIトークンを生成する を参考にしてください。

各アプリで発行するAPIトークンのアクセス権は、次のように設定します。

生成した各トークンはメモしておいてください。

案件管理アプリでは、顧客管理アプリに対して顧客名をキーにルックアップを行い、部署名や担当者名の値をコピーしています。

なお、サンプルコード中の以下の値は、ご利用環境に応じて変更してください。

• <SUBDOMAIN>：ご利用環境のサブドメイン
• <案件管理アプリのアプリID>：メモした案件管理アプリのアプリID
• <ユーザー名とパスワードを：で結合してBase64エンコードした値>：ユーザー名とパスワード名を :（半角コロン）で結合した文字列をBase64エンコードした値
• <案件管理アプリのAPIトークン>：メモした案件管理アプリのAPIトークン
• <顧客管理アプリのAPIトークン>：メモした顧客管理アプリのAPIトークン

Before

ルックアップフィールドを含むレコードの 登録 や、 更新 をする場合、APIトークン認証は利用できず、パスワード認証での実行が必要でした。

1
2

# パスワード認証で、ルックアップフィールドを含むレコードを登録
$ curl -X POST 'https://<SUBDOMAIN>.cybozu.com/k/v1/record.json' -d '{"app": <案件管理アプリのアプリID>, "record": {"顧客名": {"value": "ミヤタシステムズ"}, "案件名": {"value": "パスワード認証で追加"}, "確度": { "value": "80%"}}}' -H 'Content-Type: application/json' -H 'X-Cybozu-Authorization:<ユーザー名とパスワードを:で結合してBase64エンコードした値>'

パスワード認証の場合、REST APIを実行するアカウントが必要です。
また、実行アカウントのkintone操作に対する権限範囲が大きくなりやすいため、認証情報の流出時にリスクが大きくなります。

After

2019年12月の定期メンテナンス以降では、APIトークンを使って、ルックアップフィールドの値を含むレコードの登録や更新操作ができるようになります。
リクエストヘッダーには、レコードを登録したいアプリとルックアップ元アプリのAPIトークンを指定します。

1
2

# アプリのAPIトークンを指定して、ルックアップフィールドを含むレコードを登録
$ curl -X POST 'https://<SUBDOMAIN>.cybozu.com/k/v1/record.json' -d '{"app": <案件管理アプリのアプリID>, "record": {"顧客名": {"value": "ミヤタシステムズ"}, "案件名": {"value": "APIトークン認証で追加"}, "確度": { "value": "80%"}}}' -H 'Content-Type: application/json' -H 'X-Cybozu-API-Token:<案件管理アプリのAPIトークン>,<顧客管理アプリのAPIトークン>'

APIトークンは、生成したアプリに対する操作のみ権限をもつため、セキュリティを考慮できます。

案件管理アプリでは、案件管理アプリの「レコード番号」と活動履歴アプリの「案件管理レコード番号」に一致する活動履歴アプリのレコードを関連レコードとして表示します。
正確には、「案件管理レコード番号（関連レコード一覧紐付け用）」フィールドです。

なお、サンプルコード中の以下の値は、ご利用環境に応じて変更してください。

• <SUBDOMAIN>：ご利用環境のサブドメイン
• <案件管理アプリのアプリID>：メモした案件管理アプリのアプリID
• <活動履歴アプリのアプリID>：メモした活動履歴アプリのアプリID
• <ユーザー名とパスワードを：で結合してBase64エンコードした値>：ユーザー名とパスワード名を :（半角コロン）で結合した文字列をBase64エンコードした値
• <案件管理アプリのAPIトークン>：メモした案件管理アプリのAPIトークン
• <活動履歴アプリのAPIトークン>：メモした活動履歴アプリのAPIトークン

Before

「案件に紐づく活動履歴の対応日時が2018年の案件管理アプリのレコードを取得したい」場合など、関連レコードに表示された情報を検索クエリとして 複数のレコードを取得する 操作は、パスワード認証を使う必要がありました。

1
2
3
4

# パスワード認証で、関連レコードの情報を検索クエリにレコードを取得
# クエリには、以下を指定しています。
# 案件に紐付く活動履歴.対応日時 >= "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:<ユーザー名とパスワードを:で結合してBase64エンコードした値>'

APIトークン認証をする場合は、2つのリクエストに分ける必要があります。
（1）活動履歴アプリに対してレコードを絞り込む。
（2）（1）で取得した活動履歴アプリの「案件管理レコード番号」フィールドの値を使って、案件履歴アプリに問い合わせる。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 活動履歴から対応日時が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トークンを指定します。

1
2
3
4

# アプリの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トークン対応により、複数のアプリにまたがるREST APIでの操作がAPIトークンを使ってできるようになりました。
Cybozu Days 2019で発表がありましたが、2020年以降にはアプリ設定をしてREST APIのAPIトークン対応も予定されています。
ぜひとも今後のkintoneアップデートにご期待ください。

このTipsは、2019年12月版kintoneで動作を確認しています。