kintone の REST API を使ってみた。

はじめに

今回は kintone の REST API について紹介したいと思います。 前回は kintone で JavaScript API を使用して「kintone と地図連携による顧客リストの可視化」について紹介しました。

freedom-tech.hatenablog.com

kintone で JavaScript API を使用することで、kintone が提供するアプリをカスタマイズすることができました。REST API を使用することで、kintone アプリのレコードの操作やフォーム設計情報の取得、スペースを操作することができます。ですので、外部連携することができますので、例えば、ArcGIS などのアプリから REST API でデータを取得することもできます。

kintone REST API の詳細については kintone REST APIの共通仕様 をご覧いただければと思います。

今回は REST API を使用した例として curl コマンドによる取得と kintone REST API を実行できる API クライアントをオープンソースで提供しており、そちらも紹介したいと思います。API クライアントとして、JavaScript を使用しました。

REST API 取得先のデータを整備

まず、初めに REST API を使用するために取得先のデータを整備します。kintone アプリストアでアプリを作成します。今回は、不動産物件マスタを使用しました。

そして、ダミーの物件データを登録します。

作成した不動産物件マスタから REST API で物件データを取得してみます。

kintone の REST API の利用

取得先のデータが準備できたらいよいよ REST API を使用してデータを取得します。

kintone で REST API を使用するためにユーザー認証が必要になってきます。ユーザー認証として、
1. パスワード認証
2. APIトークン認証
3. セッション認証
などがあり、OAuthクライアントを使用しての認証もできます。詳細は、ユーザー認証 をご覧ください。

今回は APIトークン認証を使用しましたので、こちらのステップで紹介します。

APIトークンの設定は簡単でアプリの設定画面でトークンが作成できます。

トークン作成の詳細については、以下をご覧ください。 jp.cybozu.help

それでは、初めに curl コマンドで実行してみます。リクエストヘッダに「X-Cybozu-API-Token」を追加し、アプリごとに生成するAPI トークンを値に指定して実行します。

$ curl -H "X-Cybozu-API-Token: sIEoGFatBUnXTCeGpitnHZmC2h9CDfMuJ2FGOtqp" "https://iyz2z1ez9ear.cybozu.com/k/v1/record.json?app=9&id=1"

curl コマンドでは、レコード ID を指定してレコードの内容を取得しました。リクエストパラメータとして、app にアプリの ID を指定し、id には、レコード ID を指定します。

詳細は、以下のレコードの取得（GET）をご覧ください。 https://developer.cybozu.io/hc/ja/articles/202331474#step1

また、その他の REST API については、kintone REST API 一覧 をご覧ください。

次に kintone REST API を実行できる API クライアントを使用した例を紹介したいと思います。オープンソースの API クライアントとして JavaScript で提供されている kintone JavaScript Client (@kintone/rest-api-client) を使用しました。@kintone/rest-api-client は kintone REST API を JavaScript で扱う際に必要な処理をまとめたライブラリです。

@kintone/rest-api-client は GitHub にインストールから使い方までが紹介されています。 github.com

@kintone/rest-api-client は、ブラウザ環境と Node.js 環境があり、今回は Node.js 環境を使用しました。以下に簡単な手順を紹介します。

1．初めに @kintone/rest-api-client をインストールします。

$ npm install @kintone/rest-api-client

2．require で読み込みます。

const { KintoneRestAPIClient } = require("@kintone/rest-api-client");

実際のコードは以下になります。実行結果は、curl コマンドで実行した時と同じ内容です。

const { KintoneRestAPIClient } = require("@kintone/rest-api-client");

const client = new KintoneRestAPIClient({
    baseUrl: "https://iyz2z1ez9ear.cybozu.com",
    // Use API token authentication
    auth: { apiToken: "sIEoGFatBUnXTCeGpitnHZmC2h9CDfMuJ2FGOtqp" }
});

client.record
    .getRecords({ app: "9" })
    .then((resp) => {
        console.log(resp.records);
    })
    .catch((err) => {
        console.log(err);
    });

上記のコードは index.js として作成し、以下のコマンドで実行します。

$ node index.js 

[
  {
    'レコード番号': { type: 'RECORD_NUMBER', value: '37' },
    '物件所在地': { type: 'SINGLE_LINE_TEXT', value: '東京都足立区千住５丁目30-1' },
    '更新者': { type: 'MODIFIER', value: [Object] },
    '作成者': { type: 'CREATOR', value: [Object] },
    'オーナー電話番号': { type: 'LINK', value: '03-6703-0250' },
    '管理会社住所': { type: 'SINGLE_LINE_TEXT', value: '' },
    '$revision': { type: '__REVISION__', value: '1' },
    '更新日時': { type: 'UPDATED_TIME', value: '2022-02-11T09:37:00Z' },
    'オーナー企業名_氏名': { type: 'SINGLE_LINE_TEXT', value: 'A企業/A太郎' },
    '管理会社電話番号': { type: 'LINK', value: '03-6703-0286' },
    '経度': { type: 'SINGLE_LINE_TEXT', value: '139.8072422' },
    '物件名': { type: 'SINGLE_LINE_TEXT', value: 'トップ北千住_307号室' },
    '緯度': { type: 'SINGLE_LINE_TEXT', value: '35.7543576' },
    'オーナー住所': { type: 'SINGLE_LINE_TEXT', value: '' },
    '管理会社名': { type: 'SINGLE_LINE_TEXT', value: 'B管理会社' },
    '作成日時': { type: 'CREATED_TIME', value: '2022-02-11T09:37:00Z' },
    '$id': { type: '__ID__', value: '37' }
  },
 :
 :

ここまでの手順などより詳細な内容は、cybozu developer network の kintone JavaScript Client (@kintone/rest-api-client) をご覧ください。

さいごに

前回は、kintone で JavaScript API を使用してアプリのカスタマイズを行いました。今回は、そのアプリから REST API を使用してデータの取得を行いました。REST API を使用することで、ArcGIS などのプラットフォームとも容易に連携できると思いました。Outh2.0 などの認証にも対応していたりと、プラットフォームとしては完成度が高いとも思いました。また、次回も kintone で何かしてみたいと思います。