kintone café 福岡 vol.2（kintone rest api・excel連携）

kintone Café 福岡 Vol.2

2014年7月11日 kintone公認エバンジェリスト　山下 竜

＃kintonecafe

Twitter: @yamaryu0508 FB: https://www.facebook.com/ryu.yamashita.3 Blog: http://yamaryu0508.hatenablog.com/

• kintoneの概要（振り返り）

• 「kintone REST API」について（予備知識）

• Excel連携事例（デモ・ハンズオン）

• 今始めると美味しいkintoneビジネスについて（サイボウズ 佐藤さま）

• 今月のアップデートと進化するkintoneカスタマイズデモ（サイボウズ 後迫さま）

• Tipsの現状と未来（サイボウズ 北川さま）

• サイボウズでのkintoneの使われ方（サイボウズ 札辻さま）

Menu for today

※太字：私のパート

kintoneの概要

•コンセプト

•「ファストシステム」

•「3分で業務改善アプリ」

•構成要素

•データ

•ワークフロー

•コミュニケーション

kintone基本概要

「サイボウズプロダクト=チームを強くするツール」の中でも汎用性と専門性を行き来しながら、様々な 業務シーンで活用出来るクラウドデータベース（WebDB）サービス

（出典：「kintone公式サイト」）

• REST API

• レコードやスペースの操作（登録・更新・削除等）、バルクAPI

• ユーザ・組織の操作

• JavaScript/CSSカスタマイズ

• 各種イベントハンドル、情報取得

• プロキシによる外部API連携

• URL指定によるライブラリの読み込み（HTTPS対応）

kintoneカスタマイズ機能（スタンダードコース）

データ レコード スペース ユーザ

UI

基幹システム Excel

他のクラウドREST API

kintone.proxy

「kintone REST API」 について

（参考：「cybozu.com developer network > kintone API」）

• kintoneアプリのレコードやスペースの操作

kintone REST APIの概要

kintone REST APIの用途

プロトコル

• HTTPSプロトコル

フォーマット

• JSON

文字コード

• UTF-8

認証認証

• ユーザ認証（パスワード、APIトークン）

• Basic認証

その他

• 同時処理レコード数100件

• API同時アクセス10件

• https://{subdomain}.cybozu.com/k/v1/{command}.json【通常】

• https://{subdomain}.cybozu.com/k/guest/{space id}/v1/{command}.json【ゲストスペース】

kintone REST APIの概要（続き）URI

リクエストヘッダ

• Host: {subdomain}.cybozu.com:443

• Content-Type:application/json

• 認証情報

リクエスト例（GET/records）

QWRtaW5pc3RyYXRvcjpwYXNzd29y

GETメソッドではContent-Typeは不要

Basic認証を使用していない場合にも空欄で入れておく分には問題ない様子

https://{subdomain}.cybozu.com/k/v1/records.json?app={app id}

　【認証方法の記述】 X-Cybozu-Authorization : {BASE64-encoded "id:password"} Authorization : Basic {BASE64-encoded "id:password"} ※例の{base64-encoded "id:password"}はidをAdministrator、passwordをpasswordとした場合の値としています

HTTPクライアント設定画面

※以降、Google Chromeのアドオン「POSTMAN」を利用しています

リクエスト例（GET/records：続き）リクエスト詳細

https://{subdomain}.cybozu.com/k/v1/records.json?app={app id}

QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==

{subdomain}.cybozu.com

{app id}

リクエスト例（GET/records：続き）レスポンス

"{field code}": { "type" : "{field type}", "value" : "{value}" }

各フィールドはこのように記述されます ・複数値を取りうる{value}は配列になります ・POST/PUTの際はtypeが不要です

フィールドの記述

リクエスト例（POST/records）

HTTPクライアント設定画面

QWRtaW5pc3RyYXRvcjpwYXNzd29y

https://{subdomain}.cybozu.com/k/v1/records.json

リクエスト例（POST/records：続き）リクエスト詳細

POST/PUTメソッドではContent-Lengthが必要（自動補完してくれない言語・ライブラリを利用する場合は要注意）

https://{subdomain}.cybozu.com/k/v1/records.json

QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==

{subdomain}.cybozu.com

リクエスト例（POST/records：続き）

レスポンス

【POSTのレスポンス】 ・ids（レコードID）とrevisions（リビジョン） 【PUTのレスポンス】 ・revisions（リビジョン）

• まずはエラーメッセージからヘッダかボディかを判別するところからだと思います

• ボディっぽい時には「ブラウザHTTPクライアント」に手組みでJSON入力していきながら試行錯誤となります

• リクエストヘッダ・ボディを可視化するのも有効に感じます

• 面倒ですが「ブラウザHTTPクライアント」と「kintone JavaScript API」と簡単なスクリプト言語の3者意見で絞り込めることもあります

kintone REST API エラー潰し

Excel連携事例

Excelとkintoneを共存させるメリット

【Excel】 ・導入企業が多いオフィスツール ・ユーザーも扱いに馴染みがある

【kintone】 ・とにかく共有に強い - テキスト、ファイル - 人と人、人とモノ、社内外等 ・場所やデバイスを選ばない

Excelとkintoneを共存させるメリット（続き）

ありがちな課題／得失 kintone Excel

同じようなデータを複数のExcelで重複管理されている。データも散在状態になっている

○ （共有）

× （重複・散在）

データを集中管理し、安全に同時入力したい ○ （同時入力可）

× （同時入力不可）

ユーザーがExcelに慣れているとツールの変更に協力を得づらいことがある ー ○

（馴染み）既存の決まった帳票フォーマットがあり、ExcelやWordで存在する ー ○

（馴染み）Excel導入済み企業が多く、kintoneの共有機能をネイティブアプリ（実行環境の追加等が不要）として使える

○ （共有）

○ （裾野・馴染み）

今回のアプリ作成シナリオ（物品貸出）

物品確認 書類作成

②発送準備 ③物品情報 ステータス変更

①貸出依頼 ④発送

⑥返送⑦物品返却⑧物品一覧 ステータス変更

依頼

⑤貸出（申込書・貸出票）

• 負担無き管理

• 手間無き書類作成

効率化のポイント（写真等含めてkintoneで

一覧を管理中）

業務フローの課題

物品確認 書類作成

②発送準備 ③物品情報 ステータス変更

①貸出依頼 ④発送

⑥返送⑦物品返却⑧物品一覧 ステータス変更

依頼

⑤貸出（申込書・貸出票）

ステータスを１つ１つ変更するの面倒

貸出管理アプリを帳票出力する方法が考えれるが、Excelに慣れている

（写真等含めてkintoneで 一覧を管理中）

課題解決

物品確認 書類作成

②発送準備 ③物品情報 ステータス変更

①貸出依頼 ④発送

⑥返送⑦物品返却⑧物品一覧 ステータス変更

依頼

⑤貸出（申込書・貸出票）

赤字部分を 『Excel⇔kintone連携』

で負担軽減！

（写真等含めてkintoneで 一覧を管理中）

デモ

※Windows8.1(64bit)、Excel2013(64bit)の環境で動作確認しています

書類作成とステータス変更するExcelシート

物品情報 ステータス変更物品情報ルックアップ

顧客情報ルックアップ

書類作成とステータス変更するExcelシート（続き）顧客情報

①会社コードを入力

②kintone「顧客情報」アプリからルックアップ

顧客情報のルックアップ

書類作成とステータス変更するExcelシート（続き）物品情報

①管理番号を入力

物品情報のルックアップ

②kintone「物品一覧」アプリからルックアップ

書類作成とステータス変更するExcelシート（続き）物品情報物品情報のステータス変更

ボタンで対象物品のステータスを変更

アプリの関係性

ルックアップ

顧客情報 物品管理

ルックアップ

ステータス変更

サンプルダウンロード①「https://github.com/yamaryu0508/kintone-Cafe-Fukuoka-2」にアクセス

②「Download ZIP」をクリックして、 ファイル一式をダウンロード

ルックアップ元のkintoneアプリ

フォーム項目 フィールドの種類 フィールドコード

会社名 文字列（1行） companyName

会社コード 文字列（1行） （重複禁止） companyCode

郵便番号 文字列（1行） zipCode

担当者 文字列（1行） inCharge

電話番号 文字列（1行） tel

メール 文字列（1行） mail

フォーム項目 フィールドの種類 フィールドコード

物品種別 ドロップダウン type

メーカ ドロップダウン maker

型式 文字列（1行） model

レコード番号 - recordNum

管理番号 文字列（1行） （重複禁止） id

稼働区分 ドロップダウン operationStatus

貸出・提供先 文字列（1行） ownerLocation

顧客情報 物品管理

※Vol.1で作った「顧客情報」アプリの修正で対応可能です

• kintone REST APIを利用した基本的なレコード操作（Excel-VBAではMS XML）

• Excel-VBAのイベントプロージャ（セル値変更）でExcelからkintoneのレコードをルックアップ

• Excel-VBAでJSONパースにJSON-Libを利用（64bit版で廃止になったScriptControlの代用）

• 運用に耐えられるアプリらしいExcel

• ロックで入力セルを限定することで、ユーザーに対して入力箇所をガイドし、不用意なシートの変更をさせない

• オフライン時等のエラー処理

• 直近のステータス変更チェック（今回は運用フローでフォロー）

ポイントまとめ

今回のExcel-VBAの部分説明

Module1

ThisWorkbook

今回はJSONパース用に「JSONLib」をインポートします（Tipsを参考にします）

VB画面

イベントプロージャの記述

標準的な記述

今回のExcel-VBAの部分説明ライブラリ読み込み （環境によっては不要）

①「ツール」-「参照設定」をクリック

②「Microsoft XML v*」と「Microsoft Scripting Runtime」にチェック（*は環境によって異なるバージョン番号で、画面中は6.0）

③「OK」をクリック

今回のExcel-VBAの部分説明（続き）IsOnline()関数@Module1

Modulue1冒頭でライブラリ等の準備

Module1後半でインターネット接続状況を確認する関数を定義

今回のExcel-VBAの部分説明（続き）Book全体の定数の宣言@Module1

「Public」でThisWorkbook側でも参照可能になります

[]で括ったパラメータは適宜置き替えください

今回のExcel-VBAの部分説明（続き）マクロ@Module1

ApplyRental()を登録

オフライン時は終了

貸出／返却に対応する2つのマクロを記述します。実態はchangeStatus()関数です。

StopRental()を登録

• 引数・戻り値

• 引数：貸出状態（貸出中／未使用）[String]

• 戻り値：なし

• 説明

• 貸出中／未使用（kintone側のドロップダウンフィールドに対応）のいずれかを引数として渡し、PUT/recordsでレコードの状態を変更する

今回のExcel-VBAの部分説明（続き）changeStatus()関数@Module1の概要

今回のExcel-VBAの部分説明（続き）changeStatus()関数@Module1のコード

②お客さま名と貸出状態を更新

・・・

①PUT/recordsを行うためのJSON文字列の作成

今回のExcel-VBA部分説明（続き）changeStatus()関数@Module1のコード

④レスポンスに応じて、メッセージボックスを表示する

③HTTPリクエストを行う （requestHttp()関数については後述）

• 引数・戻り値

• 引数：JSON文字列[String]

• 戻り値：Excelオブジェクト[Object]

• 説明

• JSONLibを用いたJOSNパーサ

今回のExcel-VBAの部分説明（続き）parseJSON()関数@Module1の概要

• 引数・戻り値

• 引数：クエリ文字列[String]

• 戻り値：URIエンコード文字列[String]

• 説明

• URIエンコードを行う

今回のExcel-VBAの部分説明（続き）URI_Encode()関数@Module1の概要

parseJON()関数@Module1のコード

今回のExcel-VBAの部分説明（続き）

URI_Encode()関数@Module1のコード

（引用：「cybozu.com developer network > Tips > kintone × Excel」）

• 引数・戻り値

• 引数：メソッド[String]、URI[String]、ヘッダ[Dictionary]、ボディ[Variant]

• 戻り値：Excelオブジェクト[Object]

• 説明

• HTTPリクエストを行う

今回のExcel-VBAのポイント解説（続き）requestHttp()関数@Module1の概要

requestHttp()関数@Module1のコード

今回のExcel-VBAの部分説明（続き）

下記を引数として渡し、レスポンスをObjectとして返す関数 　・メソッド（GET/POST/PUT等）[String] 　・リクエストURI[String] 　・リクエストヘッダ[Dictionary] 　・リクエストボディ[Variant]

ShowErrMsg()関数@Module1のコード

今回のExcel-VBAの部分説明（続き）

エラーの種類に応じてメッセージを表示

今回のExcel-VBAの部分説明（続き）イベントプロージャ@ThisWorkbook

シート変更イベントプロージャで、Excel中の値が変更された際に 発動する処理を記述していく

オフライン時は終了

今回のExcel-VBAの部分説明（続き）管理番号によるルックアップ@ThisWorkbook

①ルックアップパラメータが範囲（単一セルでなく複数セル）で渡されることを想定して、イベントの対象ブロックを限定する

今回のExcel-VBAの部分説明（続き）管理番号によるルックアップ@ThisWorkbook

②ルックアップパラメータが入力されたら、kintoneからGET/recordsでレコードを取得し、Excelのセルにルックアップ値をセットする

③レスポンスが空の時は終了

デモに関連する内容は以上です

• 開発コミュニティサイト「cybozu.com developer network」[https://cybozudev.zendesk.com/hc/ja]

• コミュニティ（質問等）、リファレンス、Tips、サンプル、開発者ライセンス申込

• 「kintone REST APIs」[https://cybozudev.zendesk.com/hc/ja/articles/200812990-kintone-REST-APIs]

• kintone REST APIsの公式情報（cybozu.com dev. nw.内）

• 「cybozu.com developer network > Tips > kintone × Excel」[https://cybozudev.zendesk.com/hc/ja/sections/200377340-kintone-Excel]

• Excel連携のTips（cybozu.com dev. nw.内）

参考情報

ご清聴ありがとうございました。