はじめに
2019年12月の定期メンテナンス で、複数のAPIトークンを使って、kintone REST APIによる複数アプリにまたがるレコードの取得・作成・更新が可能になりました。
今まではパスワード認証でしか実行できなかったREST APIを、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'
複数のAPIトークンを利用したリクエスト例
今回は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トークン認証は利用できず、パスワード認証での実行が必要でした。
|
|
パスワード認証の場合、REST APIを実行するアカウントが必要です。
また、実行アカウントのkintone操作に対する権限範囲が大きくなりやすいため、認証情報の流出時にリスクが大きくなります。
After
2019年12月の定期メンテナンス以降では、APIトークンを使って、ルックアップフィールドの値を含むレコードの登録や更新操作ができるようになります。
リクエストヘッダーには、レコードを登録したいアプリとルックアップ元アプリのAPIトークンを指定します。
|
|
APIトークンは、生成したアプリに対する操作のみ権限をもつため、セキュリティを考慮できます。
関連レコードの操作
案件管理アプリでは、案件管理アプリの「レコード番号」と活動履歴アプリの「案件管理レコード番号」に一致する活動履歴アプリのレコードを関連レコードとして表示します。
正確には、「案件管理レコード番号(関連レコード一覧紐付け用)」フィールドです。
なお、サンプルコード中の以下の値は、ご利用環境に応じて変更してください。
<SUBDOMAIN>
:ご利用環境のサブドメイン<案件管理アプリのアプリID>
:メモした案件管理アプリのアプリID<活動履歴アプリのアプリID>
:メモした活動履歴アプリのアプリID<ユーザー名とパスワードを:で結合してBase64エンコードした値>
:ユーザー名とパスワード名を :(半角コロン)で結合した文字列をBase64エンコードした値<案件管理アプリのAPIトークン>
:メモした案件管理アプリのAPIトークン<活動履歴アプリのAPIトークン>
:メモした活動履歴アプリのAPIトークン
Before
「案件に紐づく活動履歴の対応日時が2018年の案件管理アプリのレコードを取得したい」場合など、関連レコードに表示された情報を検索クエリとして 複数のレコードを取得する操作は、パスワード認証を使う必要がありました。
|
|
APIトークン認証をする場合は、2つのリクエストに分ける必要があります。
(1)活動履歴アプリに対してレコードを絞り込む。
(2)(1)で取得した活動履歴アプリの「案件管理レコード番号」フィールドの値を使って、案件履歴アプリに問い合わせる。
|
|
リクエスト結果の処理には jqコマンド (要インストール)を利用しています。
After
今回、複数APIトークンでの関連レコードの操作が可能となりました。
APIトークン認証を使って、1回のリクエストで関連レコードに表示された情報をクエリで指定し、レコードを取得できるようになりました。
リクエストヘッダーには、レコードを取得したいアプリと関連レコードとして表示したいアプリのAPIトークンを指定します。
|
|
おわりに
複数APIトークン対応により、複数のアプリにまたがるREST APIでの操作がAPIトークンを使ってできるようになりました。
Cybozu Days 2019で発表がありましたが、2020年以降にはアプリ設定をしてREST APIのAPIトークン対応も予定されています。
ぜひとも今後のkintoneアップデートにご期待ください。
このTipsは、2019年12月版kintoneで動作を確認しています。