（著者：kintoneエバンジェリスト 山下 竜）
Webサービスのいち機能として提供されることが当たり前になってきたWeb-APIですが、これをkintoneでマッシュアップしたいと思った時に役立つ豆知識をひとつご紹介したいと思います。
今回はWebサービスのAPIドキュメントページでAPIへのアクセス方法としてしばしばサンプルで示されることが多いcurlコマンドと、kintoneのJavaScriptカスタマイズで外部サービスのAPIへアクセスできるkintone.proxy()の対応関係を整理し、更にサンプルを通してkintone.proxy()による外部Webサービスとの連携方法について理解を深めたいと思います。
なお、kintone.proxy()に関する内容は現時点で確認したものになり、今後拡張・変更になることがあるかもしれませんので、ご注意ください。
curlコマンドとkintone.proxy()の対応関係
APIドキュメントのページでcurlコマンドの例が与えられたときに、kintone.proxy()でどのように読み替えたらよいか、対応関係をまとめたいと思います。
|
curlコマンド (オプションと値) |
kintone.proxy(url, method, headers, data, callback, errback) | ||
| 記載箇所 | 記載例 | ||
| ①リクエスト URL | "http://xxx.xxx.xxx" | 第1引数「url」 | 'http://xxx.xxx.xxx' |
| ②リクエストメソッド | -X {method} | 第2引数「method」 | '{method}' |
| ③リクエストヘッダ | -H "{headerKey}:{headerValue}" | 第3引数「headers」 | {"{headerKey}":"{headerValue}"} |
| ④リクエストデータ(フォーム形式) | -d "{key}={value}" | 第4引数「date」 | ' "{key}={value}" ' |
| ⑤リクエストデータ(JSON形式) | -d 'JSON文字列' | 第4引数「date」 | 'JSON文字列'もしくはJSONオブジェクト |
| ⑥Basic 認証 | -u "{id}:{password}" | 第３引数「headers」 | '{"Authorization" : "Basic {basicToken}"}' |
各項目の補足説明をさせて頂きます。
①→リクエスト URL
- curlコマンドでは正味の引数になりますので、コマンドオプションはありません
②→リクエストメソッド
- GET、POST、PUT、DELETEのいずれかを指定できます
③→リクエストヘッダ
- 複数指定する必要があるときには、curlコマンドでは「-H "{headerKey}:{headerValue}" 」をセットとして、必要数書き並べられます。kintone.proxy()では「{"{headerKey1}":"{headerValue1}", "{headerKey2}":"{headerValue2}", ・・・}」といったようにコンマで必要数を連結してください
④→リクエストデータ(フォーム形式)
- curlコマンドで「-d」のオプションでは通常フォーム形式データを言っており、対応するContent-Typeは「application/x-www-form-urlencoded」として処理されています（「-H」での明示不要）ので、kintone.proxy()ではこれをヘッダに追加しておくと良いです。
- 複数指定する必要があるときには、curlコマンドでは「-d {key}:{value}」をセットとして、必要数書き並べられます。kintone.proxy()では、「'{key1}={value1}&{key2}={value2}&・・・'」といったように「&」で必要数連結してください
- curlコマンドでは{value}部分をURLエンコード化する「--data-urlencode」といったオプションが使われることがありますが、これに対応するためにはkintone.proxy()では、JavaScript中で「encodeURIComponent({value})」を経由させておくと良いです
⑤→リクエストデータ(JSON形式)
- curlコマンドで「-d」のオプションはJSON形式のデータにも対応しています。ただ、先ほどのフォーム形式と異なり、対応するContent-Typeである「application/json」はcurlコマンドでも「-H」によって明示されることになります。一方、kintone.proxy()でもこれをヘッダに追加しておく必要があります
- curlコマンドでは「JSON文字列」でしか指定のしようがありませんが、kintone.proxy()では、「JSON文字列」でも「JSONオブジェクト」でも大丈夫です。
⑥→Basic認証
- curlコマンドで「-u」のオプションはBasic認証に用いられています。これをkintone.proxy()で対応させるには、ヘッダの方に「"Authorization":"Basic {BasicToken}"」といった具合に追加してあげることで解決されます。なお、「{BasicToken}」は「{id}:{password}」をBASE64エンコードしたものとなります（kintone REST APIと同じですね）。
さて、予備知識を確認したところで、実践に移っていきたいと思います。kintoneに触れられている方であればJSON形式データの取扱には慣れてあるかと思いますので、今回は用例も少ないフォーム形式データの例をお届けしたいと思います。
連携サンプル(Twilio/電話：フォーム形式データ)
フォーム形式データでAPIアクセス出来るサービスは、現在開催中のMA10（Mashup Awards）でもkintone APIをはじめとして、「Twilio（KDDIウェブコミュニケーションズ）」、「SendGrid（SendGrid）」、「TypeTalk（nulab）」等様々なものが紹介されています（著者自身でkintone.proxy()からのアクセスをそれぞれ確認しました）。今回はその中から「Twilio」の「電話（Call）」を例に進めていきたいと思います。
kintoneアプリとしては、kintoneに登録された電話番号とメッセージをもとにTwilio API経由で音声通知するというものになります。
Twilioにはトライアルアカウントもありますので、実際にTwilioで試してみたいという方はアカウント取得等こちらを参考にされると良いかと思います。
APIドキュメント（Twilio）で示されるcurlコマンドによるAPIリクエスト例
(「https://www.twilio.com/voice/api」より)
トライアルアカウント作成後にもこれと同じようなページが出現しますが、この情報を参考に、kintoneアプリとカスタマイズ用のJavaScriptを準備していきましょう。
【認証情報】
|
パラメータ |
説明 |
|
{AccountSid} |
アカウント取得時に与えられるID |
|
{AuthToken} |
アカウント取得時に与えられるパスワード |
【リクエストデータ】
|
パラメータ |
説明 |
|
To='{To}' |
{To}は宛先番号。「+819012345678」のようにハイフンなしの国際電話番号表記 |
|
From='{From}' |
{To}は宛先番号（アカウント取得後指定される）。「+819012345678」のようにハイフンなしの国際電話番号表記 |
|
Url='{twiMlUrl}' |
{twiMlUrl}は、TwiML（TwilioのXML）をホストしているURL。Twimletsを利用することで、動的に設定可能 |
※詳しいTwilio APIのドキュメントはこちらをご覧ください。
kintoneアプリの準備
次のフィールドを含むアプリをご準備ください。
|
フィールド名（例） |
フィールドコード |
フィールドタイプ |
|
宛先番号 |
To |
リンク（電話番号）もしくは、文字列１行 |
|
メッセージ |
Body |
文字列複数行 |
JavaScriptソースコード
動作確認
「ダイヤル」ボタンを押して、「電話をかけました！」とメッセージが出れば発信成功です。そして、宛先の電話で着信するとメッセージが流れます。※トライアルでは、登録した番号のみへ発信可能で、案内メッセージが流れます。
注意事項
今回のkintoneアプリ周辺の注意点は次の通りです。
- 筆者はMacintoshのGoogle Chromeでkintoneアプリの動作確認を行いました ※現在MacintoshとGoogle Chromの組み合わせはcybozuの動作対象外なので利用する場合はご注意ください。詳しくはこちらをご参照ください。
- JavaScript中に認証情報を含んでいますので、必要に応じて都度入力にしたり、アクセス権を制限する等設定してください。
- 冒頭でも述べました通り、kintone.proxy()に関する内容は現時点で確認したものになり、今後拡張・変更になることがあるかもしれませんので、ご注意ください
- 今回例に挙げさせてもらいましたTwilio APIの取扱いを含め、サンプルの利用に際しては自己責任でお願い致します
最後に
今回は、外部サービスで提供されるAPIをkintone.proxy()でアクセスするための豆知識としてcurlコマンドとの対応関係について触れ、サンプルをご紹介しました。
kintone.proxy()は、今回のサンプルのように組合せ次第では本来サーバが必要になるような開発がサーバレスで出来てしまう優れ機能です。kintoneエバンジェリストの斎藤さんもこの機能を使った事例を紹介されています（関連リンク：「kintone Café 東京 Vol.1」発表レポート、スライド）。
外部サービスとのAPI連携が必要になった際にはkintoneとkintone.proxy()でのマッシュアップを検討されてはいかがでしょうか？
このTipsは、2014年9月版で確認したものになります。
記事に関するフィードバック
記事のコメント欄は記事に対するフィードバックをする場となっております。
右の記事フィードバックのためのガイドを参照してコメントしてください。
記事のリンク切れなど、気になる点がある場合も、こちらのフォームからフィードバックいただけますと幸いです。