外部のAPIを実行する – コラボフォームサポート

コラボフォームJavaScript APIを使って、外部のREST APIを実行する方法について説明します。

コラボフォームJavaScript APIでは、クロスドメインの制限を回避して外部のREST APIを呼び出すための関数が用意されています。
外部APIの認証情報（APIキー・Bearer Token・カスタムヘッダー等）はサーバー側（プロキシAPI）で管理されるため、フォームを利用するユーザーに情報が漏れることはありません。

外部APIを呼び出すには、事前に管理者がプロキシAPIのエンドポイント設定を登録する必要があります。
詳細は「プロキシAPIとは？」をご確認ください。

また、利用したい外部APIサービスでIPアドレス制限をしている場合は、以下のIPアドレスからのアクセスを許可する必要があります。

18.178.206.89
54.64.93.248

外部APIの呼び出し

collaboform.proxy.call() は非同期で処理され、Promise を返します。サーバーからデータを受信すると then() で登録したハンドラーが呼び出されます。form.confirm や form.submit ハンドラーで戻り値を return すると、API コールが完了するまで画面遷移が待機されます。

collaboform.proxy.call(endpointCode, options).then(function(response) {
    // 応答受信後の処理
}).catch(function(error) {
    // 失敗時の処理（タイムアウトなど）
});

引数

引数名	タイプ	説明
endpointCode	string	管理者が設定したエンドポイントコード。エンドポイントコードの設定方法は「プロキシAPI一覧」をご確認ください。
options	object	追加のリクエスト情報（任意）。詳細は後述します。

options 引数の詳細

プロパティ	タイプ	説明
headers	object	追加のリクエストヘッダー。プロキシAPI設定と重複した場合は管理者設定が優先されます。
query	object	追加のクエリパラメーター。プロキシAPI設定と重複した場合は管理者設定が優先されます。
body	object	リクエストボディ。プロキシAPI設定とオブジェクト単位で再帰的にマージされます。同一キーは管理者設定が優先され、options 引数側にしかないキーは保持されます。詳細は後述します。
parseType	string	相手サーバーから受信したボディ部の変換方法。「json」（デフォルト）、「text」、「base64」を指定できます。

body のマージ挙動

プロキシAPI設定とoptions 引数側の body はオブジェクト単位で再帰的にマージされます。同一キーはプロキシAPI設定が優先され、options 引数側にしかないキーは追加されます。

// プロキシAPI設定の body
// {
//   "sender": {
//     "name": "system",
//     "address": "no-reply@example.com"
//   }
// }

collaboform.proxy.call('notify-endpoint', {
    body: {
        sender: {
            name: 'user',               // プロキシAPI設定が優先されるため上書きされない
            replyTo: 'user@example.com' // options 引数側にしかないキーは追加される
        }
    }
});

// 実際に送信される body
// {
//   "sender": {
//     "name": "system",               // プロキシAPI設定が優先
//     "address": "no-reply@example.com",
//     "replyTo": "user@example.com"   // options 引数側のキーが追加される
//   }
// }

body 使用時の注意

HTTPメソッドが「GET」「HEAD」「DELETE」の場合、「options.body」の値は無視されます。
「options.body」を指定した場合、リクエストヘッダーに「Content-Type: application/json」が自動的に付与されます（プロキシAPI設定またはoptions 引数側の設定で「Content-Type」が既に指定されている場合はその設定値が使用されます）。

parseType 引数の詳細

値	説明
json	受信したデータをJSON形式とみなして自動変換した結果を返します。「response.body」はオブジェクト型になります（デフォルト）
text	受信したデータはプレーンテキストとして返します。「response.body」は文字列型になります
base64	受信したデータをBASE64形式にエンコードした状態で返します。画像ファイルなどを受信したい場合に有用です

完了ハンドラー

相手サーバーからの応答を受信すると、「then()」で登録した完了ハンドラー関数が呼び出されます。
完了ハンドラー関数が受け取る「response」オブジェクトの内容を示します。

プロパティ名	タイプ	説明
success	boolean	成功系の応答（statusが200〜299または304）なら「true」失敗系の応答（4xx / 5xx）なら「false」
status	number	相手サーバーが返した応答HTTPステータスコード
headers	object	相手サーバーから受信したヘッダー
body_type	string	bodyのデータ形式。「string」、「object」、「base64」のいずれかの値をとります
body	string / object	相手サーバーから受信したボディ部

相手サーバーからの応答があれば完了ハンドラーが呼ばれますが、その結果が失敗系（ステータスが4xx / 5xxなど）であっても同様です。実装にあたっては「success」プロパティまたは「status」プロパティを参照して処理を振り分けてください。

エラーハンドラー

通信エラーが発生した場合、「catch()」で登録したエラーハンドラー関数が呼び出されます。

エラーの種類	受け取り方
外部APIが4xx / 5xxを返した	「.then()」が呼ばれます（「response.success」が「false」）
タイムアウト（120秒超過）	「.catch()」が呼ばれます
通信障害	「.catch()」が呼ばれます
「options」の指定が不正（「query」「headers」にオブジェクト以外、「parseType」に無効な値）	「.catch()」が呼ばれます

記述例

クエリパラメーターを追加する

collaboform.events.on('form.show', function(data) {
    collaboform.proxy.call('search-endpoint', {
        query: { keyword: data.parts['fidSearchWord'].value }
    }).then(function(response) {
        if (response.success) {
            console.log('検索結果:', response.body);
        } else {
            console.log('外部APIエラー:', response.status);
        }
    }).catch(function(error) {
        console.error('通信エラーが発生しました');
    });
});

リクエストボディを追加する

collaboform.events.on('form.show', function(data) {
    collaboform.proxy.call('notify-endpoint', {
        body: {
            name: data.parts['fidName'].value,
            email: data.parts['fidEmail'].value
        }
    }).then(function(response) {
        // 応答受信後の処理
    }).catch(function() {
        // エラー時の処理
    });
});

テキストレスポンスを受け取る

collaboform.proxy.call('text-endpoint', {
    parseType: 'text'
}).then(function(response) {
    console.log(response.body); // 文字列
});

確認画面への遷移を API コール完了まで待機する

form.confirm ハンドラーで proxy.call() の戻り値を return すると、API コールが完了するまで確認画面への遷移が待機されます。form.submit でも同様に利用できます。

.then() の中で return false を返すと遷移をキャンセルできます。.catch() が呼ばれた場合（通信エラーなど）は遷移が継続されます。

collaboform.events.on('form.confirm', function(data) {
    return collaboform.proxy.call('validate-endpoint')
        .then(function(response) {
            if (!response.success) {
                return false; // 遷移をキャンセル
            }
        }).catch(function() {
            // 通信エラー時は遷移を継続
        });
});

制限事項

外部APIの呼び出しはシステムを保護するために以下の制限があります。

接続先のプロトコルは「https://」のみ対応しています。（管理者がエンドポイント設定で指定）
「localhost」およびローカルネットワークアドレスへの接続は禁止されています。
相手サーバーから受信できるボディ部は最大で 10MiB（10,485,760バイト） です。
相手サーバーからの応答待ち時間（受信タイムアウト）は 120秒 です。
リダイレクトには対応していません。外部APIが3xxを返した場合はそのままレスポンスとして返されます。
「options.headers」のヘッダー値にASCII文字以外（日本語など）を含めることはできません。含めた場合は外部APIの呼び出しは行われず、完了ハンドラーが「{ success: false, status: 400 }」で呼び出されます。
「options.headers」では以下のヘッダーは指定できません。
- Host
- Authorization
- X-Forwarded-For
- X-Forwarded-Host
- Transfer-Encoding
- Content-Length

外部APIの呼び出し

引数

options 引数の詳細

body のマージ挙動

body 使用時の注意

parseType 引数の詳細

完了ハンドラー

エラーハンドラー

記述例

クエリパラメーターを追加する

リクエストボディを追加する

テキストレスポンスを受け取る

確認画面への遷移を API コール完了まで待機する

制限事項

関連記事