kintone REST APIを使ってみよう

目次

kintone REST APIとは

kintone REST APIは、kintoneのレコードやアプリ、スペースを操作できるAPIです。
kintoneで管理しているデータを外部システムに渡すときや、外部システムからkintoneへデータを登録、更新、削除するときに利用できます。

API実行に必要な情報

kintone REST APIリクエストを行う際、次の4つの情報が必要です。

URL

利用したいAPIのパスを指定します。どのリソースに対してリクエストを行うかをURLで指定します。
URLの一覧は、 REST API一覧を確認してください。

メソッド

URLで指定したリソースをどう扱うのか指定します。
GET/POST/PUT/DELETEのいずれかを指定します。

リクエストヘッダー

APIを実行するリクエストには、認証のためのヘッダーを追加する必要があります。
kintone REST APIのリクエストヘッダーに格納できる認証情報は、次の2種類があります。

  • パスワード認証
    リクエストヘッダーに「X-Cybozu-Authorization」ヘッダーを追加し、値には「ログイン名:パスワード」をBASE64エンコードしたものを指定します。
  • APIトークン認証
    アプリごとに生成するAPIトークンを使用して、kintone REST APIを処理できます。
    リクエストヘッダーに「X-Cybozu-API-Token」ヘッダーを追加し、値にはアプリごとに生成するAPIトークンを指定します。
    APIトークンを生成する方法は、 APIトークンを生成する (External link) を確認してください。

APIトークンを使用すると、よりセキュアにREST APIを実行できます。
アプリごとに生成するため、他のアプリに影響を与えることがありません。

リクエストヘッダーの仕様や制限を知りたい場合は kintone REST APIの共通仕様を確認してください。

リクエストパラメーター

Web APIの記事で、REST APIのリクエストパラメーターの役割について説明しました。
kintone REST APIでは、次の値をリクエストパラメーターに設定します。

  • アプリID
  • レコードID
  • recordオブジェクト
    詳細は フィールド形式を参照してください。
  • スペースの本文に設定する文章など。

リクエストの内容によって、APIに渡すパラメーターも異なるため、kintone REST APIの各ドキュメントページに記載されている「パラメーター」を参考に、パラメーターを指定してください。

ここまではkintone REST APIの基礎知識について説明しました。
次の内容では実例を用いてkintone REST APIの使い方を説明していきます。

UseCase:レコードデータを取得してみる

kintone REST APIを実行して、1件のレコードデータを取得してみましょう。

まずはkintone REST APIの実行において、必要なアプリIDレコードIDを確認する方法を紹介します。

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

今回は、ブラウザーに表示されているkintoneのURLから確認してみましょう。

  • アプリID
    IDを確認したいアプリの画面を開き、URLを確認してください。
    URLの「https://sample.cybozu.com/k/123」の末尾の数字部分は、アプリIDです。
    上記の場合、アプリIDは123になります。
  • レコードID
    IDを確認したいレコードの詳細画面を開き、URLを確認してください。
    URLの「https://sample.cybozu.com/k/123/show#record=456」の末尾の数字部分は、レコードIDです。
    上記の場合、レコードIDは456になります。

curlの書き方

curlとは、APIと通信する際に利用するコマンドラインツールのことです。
多くのOSに標準でインストールされているため、特別なツールや環境を用意する必要はありません。
シンプルなコマンドでAPIを実行できます。

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

さっそく、curlを使ってコマンドラインからkintone REST APIを実行してみましょう。
1件のレコードを取得するAPIでkintoneアプリのレコードの内容を取得します。

下準備として、kintoneアプリを作成し、レコードを1件追加しておいてください。
ブラウザーのURLでアプリIDとレコードIDを確認しておきます。

また、 APIトークンを生成する (External link) を参考にして、APIトークンを発行しておきます。
今回はレコードを取得するので、「レコード閲覧」権限にチェックを入れます。

レコードを1件取得するにあるとおり、 レコードを取得するためのURLは、「https://sample.cybozu.com/k/v1/record.json」、リクエストパラメーターはappidです。

URLにリクエストパラメーターを含める方法で、appとidを指定してみましょう。
ベースとなるURL https://sample.cybozu.com/k/v1/record.jsonの後に?をつけます。
リクエストパラメーターを「パラメーター名=値」の形式で記述し、リクエストパラメーターが複数ある場合は&で区切ります。 そのため、?app=アプリID&id=レコードIDという形式でリクエストパラメーターを指定します。

1
2
3
# アプリ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'

画面上に、作成したレコードの情報が表示されるはずです。

kintone.api()の書き方

kintone上でkintone REST APIを利用する手段として、 kintone REST APIリクエストを送信するAPIが用意されています。
kintone REST APIリクエストを行う場合に利用する関数は次のとおりです。

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

pathOrUrl

REST APIでデータを操作する際に、どのリソースに対してリクエストを行うかをURLで指定する必要があります。
kintone REST APIリクエストを送信する際、引数のpathOrUrl部分でURLを指定します。
たとえば、APIのURLが「https://sample.cybozu.com/k/v1/xxx.json」の場合は、/k/v1/xxx.jsonを指定します。
ゲストスペース内アプリでも動作させる場合は、 URLを取得するAPIを使ってkintone.api.url("/k/v1/xxx.json", true)を指定します。

method

リソースに対して行う操作を指定する必要があります。
kintone REST APIでは、HTTPの一般的なリクエストメソッドGET(取得)、POST(作成)、PUT(更新)、DELETE(削除)を使って、操作を指定します。
たとえば、「レコードの取得(1件)」のリクエストを行うときは、method引数にGETを指定します。

params

リクエストを送信するときに、APIへ渡したいパラメーターをオブジェクトで指定します。
リクエストの内容によって、APIに渡すパラメーターも異なります。
kintone REST APIの各ドキュメントページに記載されている「リクエストパラメーター」を参考に、オブジェクトを作成しましょう。

successCallback

successCallbackは、APIの呼び出しが成功したら実行されるコールバック関数です。
コールバック関数の引数には、APIの実行結果を格納したオブジェクトが渡されます。
省略するとPromiseを使って処理を行うことができます。
詳細は kintoneカスタマイズで非同期処理をするで説明します。

failureCallback

failureCallbackは、APIの呼び出しが失敗したら実行されるコールバック関数です。
コールバック関数の引数には、APIのエラー内容を格納したオブジェクトが渡されます。
successCallbackと合わせて省略すると、Promiseのcatchメソッドでエラー内容を受け取ることができます。

サンプルコード

先ほど調べたレコードIDをRECORD_IDに指定して、レコード内容を取得するサンプルコードは次のとおりです。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
(() => {
  'use strict';
  const RECORD_ID = '調べたレコードID';
  kintone.events.on('app.record.detail.show', (event) => {
    const url = kintone.api.url('/k/v1/record.json', true);

    // リクエストパラメータ
    const body = {
      app: kintone.app.getId(),
      id: RECORD_ID
    };

    kintone.api(
      url, // pathOrUrl
      'GET', // method
      body, // params
      (resp) => { // 成功時のコールバック関数
        console.log(resp);
      }
    );
  });
})();

リクエストが成功するとAPIの実行結果を格納したオブジェクトが引数(resp)に渡され、成功時のコールバック関数が実行されます。

おわりに

基本的なkintone REST APIの使い方を紹介しました。
しかし、「レコードを保存するときに別のアプリからレコードを取得して、その結果をフィールドにセットする」といった処理ではPromiseを利用してコードを書く必要があります。
次回は、 kintoneカスタマイズで非同期処理をしてみようを学習しましょう。

tips
補足

kintone REST APIには便利なライブラリがあります。
以下のライブラリを利用すると、用意されたメソッドを呼び出すだけでkintone REST APIを実行でき、コードの記述量を減らすことができます。 kintoneが提供しているkintone REST APIのほか、レコードを一括で処理できるメソッドなどの便利なメソッドも用意されています。

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