警告

2020 年 8 月改訂のセキュアコーディングガイドライン に抵触する内容が含まれています。認証情報が漏洩した場合の影響を考慮して慎重に検討してください。
該当箇所：JavaScriptプログラムの7行目。

Webサービスのいち機能として提供されることが当たり前になってきたWeb-APIですが、これをkintoneでマッシュアップしたいと思った時に役立つ豆知識をひとつ紹介します。

ドキュメントでAPIへのアクセス方法としてサンプルでよく使われるcurlコマンドと、kintone JavaScriptカスタマイズで外部のAPIへアクセスできる kintone.proxy()の対応関係を整理します。
さらにサンプルを通してkintone.proxy() による外部Webサービスとの連携方法について理解を深めたいと思います。

なお、kintone.proxy() に関する内容は現時点で確認したもので、今後拡張・変更されることがあるかもしれませんので、ご注意ください。

APIドキュメントのページでcurlコマンドの例が与えられたときに、kintone.proxy() でどのように読み替えたらよいか、対応関係をまとめたいと思います。

各項目の補足説明は次のとおりです。

• 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}）を経由させておくとよいです。

• curlコマンドで-dのオプションはJSON形式のデータにも対応しています。ただ、先ほどのフォーム形式と異なり、対応するContent-Typeのapplication/jsonはcurlコマンドでも-Hによって明示されることになります。一方、kintone.proxy() でもこれをヘッダーに追加しておく必要があります。
• curlコマンドでは「JSON文字列」でしか指定のしようがありませんが、kintone.proxy() では、「JSON文字列」でも「JSONオブジェクト」でも大丈夫です。

• curlコマンドで-uのオプションはBasic認証に用いられています。
  これをkintone.proxy()に対応させるには、ヘッダーの方に"Authorization":"Basic {BasicToken}"と追加します。
• {BasicToken}は、{id}:{password}をBASE64エンコードした値です（kintone REST APIと同じですね）。

さて、予備知識を確認したところで、実践に移っていきたいと思います。kintoneに触れられている方ならJSON形式データの取扱には慣れているかと思いますので、今回は用例も少ないフォーム形式データの例をお届けしたいと思います。

kintone APIをはじめとして、フォーム形式データのAPIを提供しているサービスはいくつかあります。次はその一例です（著者自身でkintone.proxy() からのアクセスをそれぞれ確認しました）。

• Twilio （ KDDIウェブコミュニケーションズ ）
• SendGrid （ SendGrid ）

今回はその中から「Twilio」の「電話（Call）」を例に進めていきたいと思います。

kintoneアプリとしては、kintoneに登録された電話番号とメッセージをもとにTwilio API経由で音声通知するというものになります。

Twilioにはトライアルアカウントもありますので、実際にTwilioで試してみたいという方は次のページでアカウントを取得できます。
Try Twilio Free を参考にされるとよいかと思います。

（「 https://www.twilio.com/en-us/voice/api 」より）

トライアルアカウント作成後にもこれと同じようなページが出現しますが、この情報を参考に、kintoneアプリとカスタマイズ用のJavaScriptを準備していきましょう。

詳しいTwilio APIのドキュメントは Twilio Doc を確認してください。

次のフィールドを含むアプリをご準備ください。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

/*
 * Twilio x kintone
 * Copyright (c) 2014 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
 */
(function() {

  'use strict';

  // パラメータの初期化
  const ACCOUNT_SID = '{AccountSid}';
  const BASIC_TOKEN = '「{AccountSid}:{AuthToken}」をBASE64エンコードしたもの';
  const FROM = '{（アカウント取得後指定される）発信番号}';

  // kintoneに登録されたメッセージを電話発信する関数
  function dial(event) {
    // レコード情報を取得
    const rec = event.record;
    // 必要なTwiML（TwilioのXML）を記述
    const twiMl = '<Response><Say voice="woman" language="ja-jp">' + rec.Body.value + '</Say></Response>';
    // 上のTwiMLのアクセスヘージURLを与えてくれるTwimletsを利用
    const twiMlUrl = 'http://twimlets.com/echo?Twiml=' + encodeURIComponent(twiMl);
    // Twilio API（Call）のリクエストURL
    const url = 'https://api.twilio.com/2010-04-01/Accounts/' + ACCOUNT_SID + '/Calls.json';
    // リクエストヘッダ
    const headers = {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: 'Basic ' + BASIC_TOKEN
    };
    // リクエストデータ
    const contents = 'From=' + encodeURIComponent(FROM) +
                             '&To=' + encodeURIComponent(rec.To.value) +
                             '&Url=' + encodeURIComponent(twiMlUrl);
    // kintone.proxy()による外部APIアクセス
    kintone.proxy(url, 'POST', headers, contents, (body, status, _headers) => {
      console.log(status, body);
      if (status === 201) {
        alert('電話をかけました！');
      } else {
        alert('発信出来ませんでした！');
      }
    });
    return event;
  }

  // レコード詳細画面に電話発信用のダイヤルボタンを追加
  kintone.events.on('app.record.detail.show', (event) =>{
    const check = document.getElementsByName('dial');
    if (check.length === 0) {
      const button = document.createElement('button');
      button.appendChild(document.createTextNode('ダイヤル'));
      button.setAttribute('name', 'dial');

      const span = document.createElement('span');
      span.appendChild(button);

      const elButtonSpace = kintone.app.record.getHeaderMenuSpaceElement();
      elButtonSpace.appendChild(span);

      button.addEventListener('click', () => {
        dial(event);
      });
    }
    return event;
  });
})();

「ダイヤル」ボタンを押して、「電話をかけました！」とメッセージが出れば発信成功です。そして、宛先の電話で着信するとメッセージが流れます。
トライアルでは、登録した番号のみへ発信可能で、案内メッセージが流れます。

今回のkintoneアプリ周辺の注意点は次のとおりです。

• 筆者はmacOSのGoogle Chromeでkintoneアプリの動作確認を行いました。cybozu.comの対応Webブラウザーは 動作環境 を参照してください。
• JavaScript中に認証情報を含んでいますので、必要に応じて都度入力にしたり、アクセス権を制限する等設定してください。
• 冒頭でも述べましたとおり、kintone.proxy() に関する内容は現時点で確認したもので、今後拡張・変更になることがあるかもしれませんので、ご注意ください。
• 今回例に挙げたTwilio APIの取扱いを含め、サンプルの利用に際しては自己責任でお願いします。

今回は、外部サービスで提供されるAPIをkintone.proxy()でアクセスするための豆知識としてcurlコマンドとの対応関係について触れ、サンプルを紹介しました。

kintone.proxy() は、今回のサンプルのように組み合わせ次第では本来サーバーを必要となるような開発がサーバーレスでできてしまう優れ機能です。
この機能を使った事例は 「kintone Café 東京 Vol.1」発表レポート で紹介されました。（ 資料 ）

外部サービスとのAPI連携が必要になった際にはkintoneとkintone.proxy() でのマッシュアップを検討されてはいかがでしょうか？

このTipsは、2014年9月版kintoneで動作を確認しています。