外部 API の実行
Garoon カスタマイズで、外部 API を実行するための API です。
この API を利用すると、クロスドメイン制約を回避して、外部 API にリクエストを送信できます。
関数
garoon.base.proxy.send(proxyCode, url, method, headers, data, successCallback, failureCallback)
使用可能なガルーンバージョン
- クラウド版 Garoon
- パッケージ版 Garoon バージョン 4.6.0 以降
引数
パラメータ名 | 指定する値 | 必須 | 説明 |
---|---|---|---|
proxyCode | 文字列 | 必須 |
プロキシ API の設定画面で設定した「プロキシコード」です。 |
url | 文字列 | 必須 | 実行する API のURL を指定します。 ここで指定した URL に加えて、プロキシ API の設定画面で設定した「パラメーター」も送信されます。 |
method | 文字列 | 必須 |
API の実行に使用する HTTP メソッドを GET, POST, PUT, DELETE, PATCH*1 のいずれかで指定します。 |
headers | オブジェクト | 必須 |
リクエストヘッダを指定します。 |
data | オブジェクト/文字列 | 必須 |
リクエストデータを指定します。このパラメータを省略するには、{} を入力します。 値が文字列の場合、フォーマットはクエリ文字列になります。 POST/PUT/PATCH*1 のリクエストにのみ適用されます。GET/DELETE のリクエストでは無視されます。 |
successCallback | 関数 | 省略可 |
リクエストが完了したあとに実行する関数を指定します。関数の引数には、次の 3 つの情報が渡されます。
省略した場合は garoon.Promise オブジェクト*2 が返され、上記のレスポンスボディ、ステータスコード、レスポンスヘッダが格納された配列で解決されます。 |
failureCallback | 関数 | 省略可 |
リクエストが失敗した場合に実行する関数を指定します。 省略した場合は garoon.Promise オブジェクトが返され、proxy API のレスポンスボディ(文字列)で棄却されます。 |
*1 PATCH はクラウド版のみ
*2 garoon.Promise オブジェクトは、then メソッドを持っているオブジェクトです。
▼参考(外部サイト)https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise
返り値
引数の successCallback を省略した場合、garoon.Promise オブジェクトを返します。
successCallbackを 指定した場合返り値はありません(undefined が返ります)。
利用できる画面
ポップアップ画面を除く全ての画面で利用できます。
サンプルコード
コールバックを使った記述方法
garoon.Promise オブジェクトを使った記述方法
外部 API にリクエストが送られる条件
関数「garoon.base.proxy.send()」を使用した次の条件をすべて満たすリクエストが送られます。
- proxyCode パラメータがプロキシ API の設定画面の「プロキシコード」と同一であること
- method パラメータがプロキシ API の設定画面の「メソッド」と同一であること
- url パラメータがプロキシ API の設定画面の「URL」と前方一致すること*2
-
*2 URL の前方一致について
たとえば、次のように URL を指定した場合には、URL が前方一致します。- プロキシ API の設定画面の「URL」
https://api.example.com/ - garoon.base.proxy.send() の url パラメータ
https://api.example.com/operate.json
- プロキシ API の設定画面の「URL」
外部 API 実行時に送信されるデータ
パラメータ
- プロキシ API の設定画面で設定された「パラメーター」は garoon.base.proxy.send() で指定された url パラメータに付加されます。
-
プロキシ API の設定画面に「パラメーター」が設定されており、garoon.base.proxy.send() で指定された url パラメータに QueryString の開始を表す '?' が含まれていない場合は合わせて付加します。
例)次のようにパラメータを指定した場合
-
プロキシ API の設定画面の「パラメーター」
- キー: k1, 値: v1
- キー: k2, 値: v2
- キー: k3, 値: v3
- garoon.base.proxy.send() の URL
- 'https://api.example.com?k2=v2'
リクエストヘッダ
- プロキシ API の設定画面で設定された「ヘッダー」は garoon.base.proxy.send() で指定されたリクエストヘッダに付加されます。
例)次のようにリクエストヘッダを指定した場合
-
プロキシ API の設定画面の「ヘッダー」
- キー: k1, 値: v1
- キー: k2, 値: v2
- garoon.base.proxy.send() のリクエストヘッダ
- {k2: 'v2'}
ボディ
- 以下の表は、メソッド /Content-Type/garoon.base.proxy.send() で指定されたフォーマット毎に送られるリクエストデータの仕様と例をまとめたものです。
メソッド | Content-Type | garoon.base.proxy.send() で指定されたフォーマット | リクエストデータの仕様 | 例 |
---|---|---|---|---|
POST/PUT/PATCH*1 | application/x-www-form-urlencoded | JSON オブジェクト |
フォーマット: x-www-form-urlencoded |
|
POST/PUT/PATCH*1 | application/x-www-form-urlencoded | 文字列 | 外部 API に送られる値:garoon.base.proxy.send() の値 |
|
POST/PUT/PATCH*1 | x-www-form-urlencoded 以外 | JSONオブジェクト | 外部 API に送られる値: garoon.base.proxy.send() の値に設定画面の値を付加したもの |
|
POST/PUT/PATCH*1 | x-www-form-urlencoded 以外 | 文字列 | 外部 API に送られる値: garoon.base.proxy.send() の値 |
|
GET/DELETE | application/x-www-form-urlencoded | JSON オブジェクト | ボディは送られない | なし |
GET/DELETE | application/x-www-form-urlencoded | 文字列 | ボディは送られない | なし |
GET/DELETE | x-www-form-urlencoded 以外 | JSON オブジェクト | ボディは送られない | なし |
GET/DELETE | x-www-form-urlencoded 以外 | 文字列 | ボディは送られない | なし |
*1 PATCH はクラウド版のみ
重複キーの処理(ヘッダ、ボディ)
- プロキシ API の設定画面で同一のキーがある場合、前者の値を優先します。
例)次のようにヘッダを指定した場合
-
- プロキシ API の設定画面の「ヘッダー」
- キー: k1, 値: v1
- キー: k1, 値: v1-priority
- プロキシ API の設定画面の「ヘッダー」
→外部 API 実行時のヘッダは {k1: 'v1-priority'} となります。
- garoon.base.proxy.send() で設定されたキーとプロキシAPIの設定画面で設定されたキーが同一の場合、プロキシ API の設定画面を優先します。
例)次のようにヘッダを指定した場合
-
- プロキシ API の設定画面の「ヘッダー」
- キー: k1, 値: v1
- キー: k2, 値: v2-setting
- garoon.base.proxy.send() のリクエストヘッダ
- {k2: 'v2'}
- プロキシ API の設定画面の「ヘッダー」
→外部 API 実行時のヘッダは {k1:'v1', k2: 'v2-setting'} となります。
制限事項
クラウド版では、外部に API リクエストを送信したときの最大実行時間は 30 秒です。30秒を過ぎるとタイムアウトとなり、エラーが返ります。
記事に関するフィードバック
記事のコメント欄は記事に対するフィードバックをする場となっております。
右の記事フィードバックのためのガイドを参照してコメントしてください。
記事のリンク切れなど、気になる点がある場合も、こちらのフォームからフィードバックいただけますと幸いです。