kintone REST APIを使ってみようでは、kintone REST APIの基本的な使い方を学びました。
今回は、次の2つの方法でkintone REST APIを実行し、kintoneアプリのレコードデータを取得する方法を学びます。

• curl
• kintone REST APIリクエストを送信するAPI（kintone.api()）

特に後者の方法は、kintoneカスタマイズの中で「別のアプリのレコードデータを取得する」という処理でよく利用します。

下準備として、kintoneアプリを作成しましょう。
今回は、アプリストアの 営業支援パック の「顧客管理（営業支援パック）」のレコードを取得します。

まずは、kintone REST APIを実行するために必要な情報を確認します。
今回は、 1件のレコードを取得する APIを実行します。
このAPIのドキュメントを確認すると、次の情報が必要だとわかります。

URLとメソッドはこの情報で十分です。
あとはAPIトークンやアプリID、レコードIDを調ベておきましょう。

「X-Cybozu-API-Token」ヘッダーは、アプリのAPIトークンを使って認証するときに指定するリクエストヘッダーです。
「X-Cybozu-API-Token」ヘッダーにAPIトークンを付与してREST APIを実行すると、APIトークン認証が行われます。
APIトークン認証によって、REST APIの実行のリクエストが正当なリクエストだということを示します。

「顧客管理（営業支援パック）」アプリのAPIトークンを生成しましょう。
今回はレコードを取得するため、「レコード閲覧」権限にチェックを入れます。
手順の詳細は、 APIトークンを生成する を参考にしてください。

アプリIDやレコードIDを取得するには、次の2つの方法があります。

• 方法1：kintone JavaScript APIを使う。
  • アプリのIDを取得する
  • レコードIDを取得する
• 方法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は、APIと通信する際に利用するコマンドラインツールです。
Web APIを使ってみようで説明したように、curlは多くのOSに標準でインストールされているため、特別な準備をせずに利用できます。

kintone REST APIは、kintoneカスタマイズのJavaScriptファイルからも実行できますが、curlを利用すると、JavaScriptファイルを用意する必要がなくお手軽にREST APIを実行できます。
まずはcurlを利用してAPIリクエストが成功するか、どのようなレスポンスが返ってくるのかを確認することで、カスタマイズを効率的に進めることができます。

さっそく、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になります。

1

https://sample.cybozu.com/k/v1/record.json?app=11&id=1

メソッドとリクエストヘッダーを指定する

APIの実行に必要な情報のうち、「URL」と「リクエストパラメーター」の2つがそろいました。
あとは残りの「メソッド」と「リクエストヘッダー」を指定すればOKです。
メソッドやリクエストヘッダーの指定方法は、 Web APIを使ってみよう｜curlで学んだとおり、-Xオプションと-Hオプションを使います。

完成したcurlコマンド

完成したcurlコマンドは、次のとおりです。
なお、コマンドの「sample」と「API_TOKEN」は、それぞれ次のように置き換えてください。

• sample：自分のkintoneサブドメイン
• API_TOKEN： API実行に必要な情報を確認するで発行したAPIトークン

1
2

# アプリIDが11でレコードIDが1の場合 
curl -X GET 'https://sample.cybozu.com/k/v1/record.json?app=11&id=1' -H 'X-Cybozu-API-Token: API_TOKEN'

Windowsの場合はコマンドプロンプト、macOSの場合はターミナルを開きます。
先ほどの「完成したcurlコマンド」を入力して、Enterキーで実行します。
画面上に、指定したレコードIDのレコードの情報が表示されれば成功です。

1
2
3
4

curl -X GET 'https://sample.cybozu.com/k/v1/record.json?app=11&id=1' -H 'X-Cybozu-API-Token: API_TOKEN'

# 実行結果
{"record":{"備考":{"type":"MULTI_LINE_TEXT","value":""},"レコード番号":{"type":"RECORD_NUMBER","value":"1"},"更新者":{"type":"MODIFIER","value":{"code":"yamada-taro","name":"User (not visible)"}},"作成者":{"type":"CREATOR","value":{"code":"yamada-taro","name":"User (not visible)"}},"郵便番号":{"type":"SINGLE_LINE_TEXT","value":"3300041"},"$revision":{"type":"__REVISION__","value":"1"},"部署名":{"type":"SINGLE_LINE_TEXT","value":"ソリューション営業グループ"},"メールアドレス":{"type":"LINK","value":"mori_jun@example.com"},"担当者名":{"type":"SINGLE_LINE_TEXT","value":"森 惇"},"更新日時":{"type":"UPDATED_TIME","value":"2024-07-08T03:52:00Z"},"顧客名":{"type":"SINGLE_LINE_TEXT","value":"林田商会"},"住所":{"type":"SINGLE_LINE_TEXT","value":"埼玉県浦和市××××"},"TEL":{"type":"LINK","value":"090-××××-××××"},"FAX":{"type":"LINK","value":"050-××××-××××"},"作成日時":{"type":"CREATED_TIME","value":"2024-07-08T03:52:00Z"},"$id":{"type":"__ID__","value":"1"}}}

kintoneでは、kintoneカスタマイズのJavaScriptファイルからkintone REST APIを実行する手段が用意されています。
kintoneカスタマイズで、「別のアプリのレコード情報を、画面に表示しているレコードのフィールドの値としてセットする」「編集したレコードの情報を使って、別のアプリのレコードを更新する」といったユースケースがあるからです。
このようなユースケースの場合、 kintone REST APIリクエストを送信するAPI（kintone.api()）というkintone JavaScript APIを使用します。

まずは、kintone.api()の使い方を学んでいきましょう。
ドキュメントを確認すると、kintone.api()は次のように定義されています。

1

kintone.api(pathOrUrl, method, params, successCallback, failureCallback)

それぞれの引数には、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メソッドでエラー内容を受け取ることができます。

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()を使って、「顧客管理（営業支援パック）」のレコードを取得してみましょう。
まずは、Webブラウザーの開発者ツールのコンソール上から、kintone.api()を実行してみます。

kintoneを開き、開発者ツールを表示します。
開発者ツールの表示方法は、 開発者ツールの使い方を参照してください。

次に、次のコードを開発者ツールのコンソールに貼り付けて実行します。
調べたアプリIDと調べたレコードIDは、「顧客管理（営業支援パック）」のアプリIDとレコードIDに置き換えてください。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

const APP_ID = '調べたアプリID';
const RECORD_ID = '調べたレコードID';
const pathOrUrl = kintone.api.url('/k/v1/record.json', true);
const method = 'GET';
const params = {
  app: APP_ID,
  id: RECORD_ID
};
const successCallback = (resp) => {
  // APIの実行結果をコンソールに表示する
  console.log(resp);
};
const failureCallback = (error) => {
  // エラー結果をコンソールに表示する
  console.error(error);
};

kintone.api(pathOrUrl, method, params, successCallback, failureCallback);

REST APIの実行に成功すると、成功時のコールバック関数successCallbackが実行されます。
successCallbackの引数（resp）には、REST APIの実行結果（レコード情報）を格納したオブジェクトが渡されます。
今回は、successCallbackの中でrespをコンソールに表示する処理を記述しています。
そのため、REST APIの実行結果（レコード情報）がコンソールに表示されます。

最後に、kintoneカスタマイズのJavaScriptファイルでkintone.api()を使ってkintone REST APIを実行してみましょう。
レコード一覧画面を表示したときに、指定したレコードの内容を取得するカスタマイズです。

次の内容を記述したJavaScriptファイルを作成します。
調べたアプリIDと調べたレコードIDは、「顧客管理（営業支援パック）」のアプリIDとレコードIDに置き換えてください。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

(() => {
  'use strict';
  const APP_ID = '調べたアプリID';
  const RECORD_ID = '調べたレコードID';

  kintone.events.on('app.record.index.show', (event) => {
    const pathOrUrl = kintone.api.url('/k/v1/record.json', true);
    const method = 'GET';
    const params = {
      app: APP_ID,
      id: RECORD_ID,
    };
    const successCallback = (resp) => {
      const record = resp.record;
      window.alert(`顧客名：${record.顧客名.value}`);
    };
    const failureCallback = (error) => {
      window.alert('エラーが発生しました');
      console.error(error);
    };

    kintone.api(pathOrUrl, method, params, successCallback, failureCallback);
  });
})();

次に、作成した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のほか、レコードを一括で処理できるメソッドなどの便利なメソッドも用意されています。

• @kintone/rest-api-client
• kintone Java Client

基本的な使い方を確認したい方は、次の説明記事を確認してください。

• kintone JavaScript Client
• kintone Java Client