kintone REST APIを使ってレコードデータを取得してみよう
kintone REST APIを使ってみよう
では、kintone REST APIの基本的な使い方を学びました。
今回は、次の2つの方法でkintone REST APIを実行し、kintoneアプリのレコードデータを取得する方法を学びます。
- curl
- kintone REST APIリクエストを送信するAPI(
kintone.api()
)
特に後者の方法は、kintone JavaScriptカスタマイズの中で「他のアプリから値を取得」という処理でよく利用します。
curlやREST APIに馴染みがない方のために、基礎的な知識をまとめた
Web APIを使ってみよう
という記事もご用意しています。
ぜひ、こちらも参照ください。
下準備
下準備として、kintoneアプリを作成しましょう。
今回は、アプリストアの
営業支援パック
の「顧客管理(営業支援パック)」のレコードを取得します。
API実行に必要な情報を確認する
まずは、kintone REST APIを実行するために必要な情報を確認します。
今回は、
1件のレコードを取得する API
を実行します。
このAPIのドキュメントを確認すると、次の情報が必要だとわかります。
URL | https://sample.cybozu.com/k/v1/record.json |
HTTPメソッド | GET |
リクエストヘッダー | 「X-Cybozu-API-Token」ヘッダー |
リクエストパラメーター |
|
URLとメソッドはこの情報で十分です。
あとはAPIトークンやアプリID、レコードIDを調ベておきましょう。
APIトークン
「X-Cybozu-API-Token」ヘッダーは、アプリのAPIトークンを使って認証するときに指定するリクエストヘッダーです。
「X-Cybozu-API-Token」ヘッダーにAPIトークンを付与してREST APIを実行すると、APIトークン認証が行われます。
APIトークン認証によって、REST APIの実行のリクエストが正当なリクエストだということを示します。
「顧客管理(営業支援パック)」アプリのAPIトークンを生成しましょう。
今回はレコードを取得するため、「レコード閲覧」権限にチェックを入れます。
手順の詳細は、
APIトークンを生成する
を参考にしてください。
アプリIDとレコードID
アプリIDやレコードIDを取得するには、次の2つの方法があります。
- 方法1:kintone JavaScript APIを使う。
- 方法2:ブラウザーに表示されているkintoneのURLから確認する。
今回は、ブラウザーに表示されているkintoneのURLから確認する方法で、アプリIDやレコードIDを確認しましょう。
- アプリID
「顧客管理(営業支援パック)」の画面を開き、URLを確認してください。
URLの「https://sample.cybozu.com/k/123」の末尾の数字部分が、アプリIDです。
上記の場合、アプリIDは「123」です。 - レコードID
「顧客管理(営業支援パック)」のいずれかのレコードの詳細画面を開き、URLを確認してください。
URLの「https://sample.cybozu.com/k/123/show#record=456」の末尾の数字部分が、レコードIDです。
上記の場合、レコードIDは「456」です。
curlを使ってkintone REST APIを実行する
curlは、APIと通信する際に利用するコマンドラインツールです。
Web APIを使ってみよう
で説明したように、curlは多くのOSに標準でインストールされているため、特別な準備をせずに利用できます。
kintone REST APIは、kintoneカスタマイズのJavaScriptファイルからも実行できますが、curlを利用すると、JavaScriptファイルを用意する必要がなくお手軽にREST APIを実行できます。
まずはcurlを利用してAPIリクエストが成功するか、どのようなレスポンスが返ってくるのかを確認することで、カスタマイズを効率的に進めることができます。
curlコマンドの準備
さっそく、curlを使ってコマンドラインからkintone REST APIを実行してみましょう。
1件のレコードを取得するAPI
の実行に必要な情報は、
API実行に必要な情報を確認する
で調べたとおりです。
URLでリクエストパラメーターを指定する
1件のレコードを取得するAPIを実行するには、「URLにパラメーターを含める場合」と「リクエストボディにパラメーターを含める場合」の2つの方法があります。
今回は「URLにリクエストパラメーターを含める方法」で、APIを実行してみます。
「URLにリクエストパラメーターを含める方法」では、URLにリクエストパラメーターのアプリIDとレコードIDを指定します。
まず、ベースとなるURL「https://sample.cybozu.com/k/v1/record.json」の後に?
をつけます。
次にリクエストパラメーターを「パラメーター名=値」の形式で記述し、リクエストパラメーターが複数ある場合は&
で区切ります。
つまり、今回は?app=アプリID&id=レコードID
という形式でリクエストパラメーターを指定します。
たとえば、アプリIDが11で、レコードIDが1の場合は、次のURLになります。
|
|
メソッドとリクエストヘッダーを指定する
APIの実行に必要な情報のうち、「URL」と「リクエストパラメーター」の2つがそろいました。
あとは残りの「メソッド」と「リクエストヘッダー」を指定すればOKです。
メソッドやリクエストヘッダーの指定方法は、
Web APIを使ってみよう|curl
で学んだとおり、-X
オプションと-H
オプションを使います。
完成したcurlコマンド
完成したcurlコマンドは、次のとおりです。
なお、コマンドの「sample」と「API_TOKEN」は、それぞれ次のように置き換えてください。
- sample:自分のkintoneサブドメイン
- API_TOKEN: API実行に必要な情報を確認する で発行したAPIトークン
|
|
curlコマンドの実行
Windowsの場合はコマンドプロンプト、macOSの場合はターミナルを開きます。
先ほどの「完成したcurlコマンド」を入力して、Enterキーで実行します。
画面上に、指定したレコードIDのレコードの情報が表示されれば成功です。
|
|
警告
Windowsのコマンドプロンプトでは、シングルクオート'
が正しく解釈されないため、次のようにダブルクオート"
に書き換える必要があります。
|
|
kintone.api()
を使ってkintone REST APIを実行する
kintoneでは、kintoneカスタマイズのJavaScriptファイルからkintone REST APIを実行する手段が用意されています。
kintoneカスタマイズで、「別のアプリのレコード情報を、画面に表示しているレコードのフィールドの値としてセットする」「編集したレコードの情報を使って、別のアプリのレコードを更新する」といったユースケースがあるからです。
このようなユースケースの場合、
kintone REST APIリクエストを送信するAPI(kintone.api()
)
というkintone JavaScript APIを使用します。
kintone.api()
の使い方
まずは、kintone.api()
の使い方を学んでいきましょう。
ドキュメント
を確認すると、kintone.api()
は次のように定義されています。
|
|
それぞれの引数には、REST APIの実行に必要な情報を指定したり、REST APIを実行した後の処理を記述したりします。
それでは、引数の詳細を確認してみましょう。
pathOrUrl
pathOrUrl
は、kintone REST APIのURLを指定する箇所です。
たとえば、APIのURLがhttps://sample.cybozu.com/k/v1/record.jsonの場合は、/k/v1/record.json
を指定します。
ゲストスペース内アプリでも動作させたい場合は、
URLを取得するAPI
を使ってkintone.api.url('/k/v1/record.json', true)
を指定します。
method
method
は、HTTPメソッドを指定する箇所です。
1件のレコードを取得する
の場合は、「GET」です。
kintone REST APIでは、一般的なHTTPリクエストメソッドのGET(取得)、POST(作成)、PUT(更新)、DELETE(削除)を使います。
どのHTTPメソッドを使うかは、APIのドキュメントを確認してください。
params
params
は、リクエストパラメーターを指定する箇所です。
リクエストパラメーターはオブジェクト形式で指定します。
リクエストの内容によって、リクエストパラメーターも異なります。
kintone REST APIの各ドキュメントページに記載されている「リクエストパラメーター」を参考に、オブジェクトを作成しましょう。
successCallback
successCallback
は、REST APIの呼び出しが成功したら実行されるコールバック関数を指定する箇所です。
コールバック関数の引数には、REST APIの実行結果を格納したオブジェクトが渡されます。
省略するとPromiseを使って処理を行うことができます。
詳細は
kintoneカスタマイズで非同期処理をする
で説明します。
failureCallback
failureCallback
は、APIの呼び出しが失敗したら実行されるコールバック関数を指定する箇所です。
コールバック関数の引数には、APIのエラー内容を格納したオブジェクトが渡されます。
successCallback
とともに省略すると、Promiseのcatchメソッドでエラー内容を受け取ることができます。
「X-Cybozu-API-Token」ヘッダーは?
curlを使ってREST APIを実行した際は、「X-Cybozu-API-Token」ヘッダーにAPIトークンを指定しました。
APIトークン認証を使って、REST APIの実行が正当なリクエストだと示したかったからです。
実は、kintone.api()
を使ってkintone REST APIを実行する場合、「X-Cybozu-API-Token」ヘッダーを指定する必要はありません。
kintone.api()
でkintone REST APIを実行する場合は、自動的に「セッション認証」という認証方式が使われるからです。
セッション認証では、画面を操作しているユーザーの認証情報が自動的に使われます。
開発者ツールでkintone.api()
を実行する
それでは、kintone.api()
を使って、「顧客管理(営業支援パック)」のレコードを取得してみましょう。
まずは、Webブラウザーの開発者ツールのコンソール上から、kintone.api()
を実行してみます。
kintoneを開き、開発者ツールを表示します。
開発者ツールの表示方法は、
開発者ツールの使い方
を参照してください。
次に、次のコードを開発者ツールのコンソールに貼り付けて実行します。
調べたアプリID
と調べたレコードID
は、「顧客管理(営業支援パック)」のアプリIDとレコードIDに置き換えてください。
|
|
REST APIの実行に成功すると、成功時のコールバック関数successCallback
が実行されます。
successCallback
の引数(resp
)には、REST APIの実行結果(レコード情報)を格納したオブジェクトが渡されます。
今回は、successCallback
の中でresp
をコンソールに表示する処理を記述しています。
そのため、REST APIの実行結果(レコード情報)がコンソールに表示されます。
kintoneカスタマイズファイルでkintone.api()
を実行する
最後に、kintoneカスタマイズのJavaScriptファイルでkintone.api()
を使ってkintone REST APIを実行してみましょう。
レコード一覧画面を表示したときに、指定したレコードの内容を取得するカスタマイズです。
次の内容を記述したJavaScriptファイルを作成します。
調べたアプリID
と調べたレコードID
は、「顧客管理(営業支援パック)」のアプリIDとレコードIDに置き換えてください。
|
|
次に、作成したJavaScriptファイルを「案件管理」アプリに適用します。
JavaScriptファイルやCSSファイルを適用する
アプリを更新し終えたら、「案件管理」アプリのレコード一覧画面を開きます。
指定したレコードの「顧客名」がアラートに表示されれば成功です。
おわりに
今回は、curlとkintone.api()
を使ってkintone REST APIを実行する方法を学びました。
kintone REST APIでも、REST APIの実行に必要な情報をそろえてリクエストを送信することで、kintoneのデータを操作できます。
次回は
kintoneカスタマイズで非同期処理をしてみよう
を学習します。
Promiseを学ぶと、「レコードを保存するときに別のアプリからレコードを取得して、その結果をフィールドにセットする」といった処理を書けます。
補足
kintone REST APIには便利なライブラリがあります。
以下のライブラリを利用すると、用意されたメソッドを呼び出すだけでkintone REST APIを実行でき、コードの記述量を減らすことができます。
kintoneが提供しているkintone REST APIのほか、レコードを一括で処理できるメソッドなどの便利なメソッドも用意されています。
基本的な使い方を確認したい方は、次の説明記事を確認してください。