kintoneからデータを取得してみよう【kintone REST API】

連載第18回の目的

連載第18回と第19回では、Excel VBAにおけるkintone REST APIの活用について紹介します。サイボウズが提供するこのAPIは、同社のサービスkintoneの操作のための機能を無償で提供します。今回は、このkintone REST APIを使用して、kintoneアプリからデータを読み取り、手元のExcelワークシートに反映して活用するサンプルを作成します（図1）。 今回は、kintone REST APIの概要を紹介し、API呼び出しのテストまでを取り上げます。

• 図1：完成サンプルイメージ

▼完成サンプルのExcelファイル
https://github.com/wateryinhare62/mynavi_excelvba_webservice

なお、本連載では動作確認をWindows 10 Pro（64bit）、Microsoft 365（Excel 16.0、VBA 7.1）で行っています。旧バージョンや単体のExcelで試す場合にはご注意ください。

kintoneの概要

kintone（キントーン）は、サイボウズ株式会社（以降、Cybozu）が提供するクラウドサービスの一つです。業務アプリをノーコードあるいはローコードで開発できるのが特徴です。同社のクラウドサービスには、他にグループウェアのサイボウズ Officeとガルーン（Garoon）、メール管理のメールワイズなどがあります。

kintoneについて

kintoneでは、個々の業務システムは「アプリ」と呼ばれ、データベースとコミュニケーションツールで構成されます。これにより、データを蓄積、取得するだけでなく、「いいね」を付けたりコメントを付与したりすることができます。本記事では、サンプルアプリの一つである「顧客リスト」に蓄積されているデータ（会社名や担当者名など）をExcelに取り込んで活用する事例を紹介します。

Cybozu Developer Networkについて

VBAからkintoneを利用するにあたり、まずはデータを取得するkintoneの環境を準備します。Cybozuでは、開発者向けに無料で使えるkintoneの環境を提供しており、いくつかの手続きを踏むことによって利用することができます。 kintoneとGaroonについては、カスタマイズと外部サービスとの連携を目的としたAPIが提供されています。Cybozu Developer Networkは、これらAPIのドキュメントやチュートリアル、コミュニティをコンテンツとして提供しており、メンバーになることで利用できるようになります。APIの利用自体にはCybozu Developer Networkのメンバーであることは必須ではありませんが、有用なチュートリアルが整備されており、コミュニティも活発であることから、加入しておくと有用です。
以前は、後述する開発者ライセンスの取得にはCybozu Developer Networkのメンバーであることが前提でしたが、現在ではメンバーであるなしにかかわらず開発者ライセンスを取得できるようです。

kintone APIについて

kintone APIには、REST APIとJavaScript APIが提供されています。このうちREST APIは、取得、作成、更新、削除などの基本的な機能に加えて、カーソルを用いたレコードアクセス、コメント、プロセス管理などの機能も備えています。本記事で使っていくのは、このREST APIです。
リクエストはAPIパスとクエリパラメータ、それに必要に応じてリクエストボディによって行われます。リクエストボディ、レスポンスボディともにJSON形式となっており、データの取り扱いが容易になっています。

開発者ライセンスの取得

kintoneの利用には、開発者ライセンスを取得します。

開発者ライセンスに申し込む

開発専用のアプリ環境である開発者ライセンスでは、開発用途に限定したアプリが利用可能で、サンプルデータを自由にインストールして検証作業に活用することができます。ただし、Cybozuのサービスの中ではkintoneのみが利用可能、スタンダードプランと同等、実稼働環境としては利用できない、ユーザー数は5個まで、ディスク容量は25GBまで、1年間の利用であるなどの制限があります。「cybozu developer network」(https://cybozu.dev/ja/)から、以下の手順で開発者ライセンスを申し込みます。なお、同一人物が複数の開発者ライセンスに申し込むことは規約違反となりますので注意してください。
「cybozu developer network」ページから［開発環境を取得］をクリックします（図2）。

• 図2：cybozu developer network

「kintone 開発者ライセンス（開発環境）」ページで、［開発者ライセンスを申し込む］をクリックします。あらかじめ、［利用規約を確認する］をクリックして利用規約を読んでおきましょう（図3）。

• 図3：kintone 開発者ライセンス（開発環境）

「kintone 開発者ライセンス 申し込みフォーム」ページで、フォームに必要事項を記入して［申し込む］をクリックします（図4）。

• 図4：kintone 開発者ライセンス 申し込みフォーム

しばらくして、利用方法などが記載されたメールが到着すれば利用可能となります。

サンプルアプリを追加する

開発環境を取得できたら、メールに記載されている情報を使ってサンプルアプリを追加します。サンプルアプリにはサンプルデータを含めることができるので、ただちにデータが利用可能になります。ここではExcelサンプルの目的である「顧客リスト」アプリを追加します。サンプルアプリは以下のように追加します。
メールに記載されているアクセスURL（https://xxxxxx.cybozu.com/、xxxxxは各自のサブドメイン）にWebブラウザでアクセスし、ログイン名（メールアドレス）、パスワードを使ってログインします（図5）。

• 図5：ログイン

「インフォメーション」ページで、「サービス」ペインの［kintone］をクリックします（図6）。

• 図6：インフォメーション

「ポータル」ページで、「アプリ」ペインの［＋］をクリックします（図7）。

• 図7：ポータル

「kintoneアプリストア」ページの「おすすめのアプリ」から、［顧客リスト］をクリックします。このとき、［このアプリを追加する］の方はクリックしないでください（図8）。

• 図8：kintoneアプリストア

「顧客リスト｜kintoneアプリストア」ページの［サンプルデータを含める］にチェックを入れ、［このアプリを追加］アプリをクリックします（図9）。

• 図9：顧客リスト｜kintoneアプリストア

「ポータル」ページの「アプリ」ペインに、「顧客リスト」が表示されていればアプリ追加は成功です（図10）。

• 図10：ポータル（アプリ追加後）

「顧客リスト」をクリックして開いたページから、アプリID（URL「https://xxxxx.cybozu.com/k/1/」の「1」の部分）を控えておきます（図11）。これは、サンプル作成時にアプリIDとして使用するデータになります。

• 図11：「顧客リスト」アプリ

APIの使用を準備する

kintone REST APIの利用には、APIトークンが必要になります。APIトークンは、以下の手順で取得できます。
アプリのページ右上にある歯車アイコン右の［∨］をクリックして開くメニューから、［カスタマイズ／サービス連携］－［APIトークン］をクリックします（図12）。

• 図12：「APIトークン」を選択

「APIトークン」画面に切り替わるので、［生成する］をクリックして生成されるAPIトークンをコピーしてテキストファイル等に保存しておき、サンプルを作成するときに参照できるようにします。アクセス権は、今回は［レコード閲覧］のみで構いません。メモを適切に設定して［保存］をクリックします（図13）。なお、作成したトークンはいつでもこの画面から確認できます。

• 図13：取得したAPIトークン

APIの呼び出しをテストする

APIトークンの取得ができたので、APIの呼び出しを始めることができます。スクリプトを書く前に、APIが正しく呼び出せるかテストしておきましょう。返されるJSONデータの理解はスクリプトの読みこなしに必要なので、基本的な構成を理解しておいてください。

APIの利用方法について

kintone REST APIについては、下記にリファレンスがありますので、全容を知りたい場合には参照してください。

▼kintone REST API - cybozu developer network
https://cybozu.dev/ja/kintone/docs/rest-api/

エンドポイントは以下のようになります。

https://＜サブドメイン＞.cybouzu.com/k/v1/＜APIパス＞＜クエリパラメータ＞

＜APIパス＞の部分には、APIの種類に応じたパス文字列を指定します。表1に、参照系をはじめとする基本的なAPIについて、目的とGET/POSTの別、APIパスをまとめます。

▲表1：基本的なkintone REST API

単一レコードの参照や登録、更新ではrecord.json（単数形）になり、複数レコードの参照や登録、更新、削除ではrecords.json（複数形）になります。このように、対象によって微妙にAPIパスが異なるので注意してください。なお、他のAPIパスには、コメント関連のcomment.json、プロセス管理のrecord(s)などがあります。詳細は上記ドキュメントを参照してください。
＜クエリパラメータ＞の部分は、APIによって異なってきます。例えば1件のレコードを取得するAPIでは、表2のクエリパラメータを指定します。

▲表2：1件のレコードを取得する際のクエリパラメータ

複数件のレコードを取得するAPIでは、表3のクエリパラメータを指定します。

▲表3：複数件のレコードを取得する際のクエリパラメータ

クエリ文字列は、SQLのwhere句のように「Name in ("Cybozu") and Address like "東京都"」のような形式で指定できます。詳細は、ドキュメントを参照してください。
なお、クエリパラメータは、JSON形式の文字列で、リクエストボディとして指定することもできます。
APIトークンは、URLに現れないようにするためにリクエストヘッダに含めます。X-Cybozu-API-Tokenを使って、取得したAPIトークンを送信するようにしてください。

"X-Cybozu-API-Token": "APIトークン"

テストを実行する

今回使用するAPIでは、上記のようにリクエストヘッダに認証情報（APIトークン）を埋め込みます。よってWebブラウザではテストできないので、第6回などと同様にPowerShellのInvoke-WebRequestコマンドを使ってリクエストを発行していきます。以下、詳細は省くので必要に応じて第6回の説明を参照してください。なお、Invoke-WebRequestコマンドに与えるURLのサブドメインとアプリID部分は、各自のサブドメインと作成したアプリのものを指定してください。リクエストは、records.jsonを指定して複数レコードの取得、クエリパラメータtotalCountをtrueにしてレコード数も取得しています。

> $headers = @{
  "X-Cybozu-API-Token" = "…各自生成したAPIトークンを入れる…"
}
> $result = Invoke-WebRequest "https://subdomain.cybozu.com/k/v1/records.json?app=1&totalCount=true" -Headers $headers
> $result
StatusCode        : 200
StatusDescription : OK
Content           : {"records":[{"備考":{"type":"MULTI_LINE_TEXT","value":""},"レコード番号":{"type":"RECORD_NUMBER","v
                    alue":"20"},"更新者":{"type":"MODIFIER","value":{"code":"nao@naosan.jp","name":"山内
                    直"}},"作成者":{"typ…
RawContent        : HTTP/1.1 200 OK
                    Server: nginx
                    Date: Thu, 23 Nov 2023 05:06:20 GMT
                    Transfer-Encoding: chunked
                    Connection: keep-alive
                    Vary: Accept-Encoding
                    X-Frame-Options: SAMEORIGIN
                    Referrer-Policy: same-origi…
Headers           : {[Server, System.String[]], [Date, System.String[]], [Transfer-Encoding, System.String[]], [Connect
                    ion, System.String[]]…}
Images            : {}
InputFields       : {}
Links             : {}
RawContentLength  : 23745
RelationLink      : {}

上記のように、Invoke-WebRequestコマンドの実行でエラーメッセージなどが何も表示されず、$resultの表示で「StatusCode : 200」となっていれば成功です。
ここで、受信したJSONデータの構造を見てみましょう。内容をリスト1に示します。$result.Contentの出力ではインデントや改行がなく見にくいので、ConvertFrom-JsonコマンドレットとConvertTo-Jsonコマンドレットをパイプでつないで成形しています。