外部の API を実行する
外部の API を実行する
Garoon から外部サービスの API を実行します。
この API を利用すると、クロスドメイン制約を回避して、外部 API にリクエストを送信できます。
関数
garoon.base.proxy.send(proxyCode, url, method, headers, data, successCallback, failureCallback)
利用できるバージョン
- クラウド版 Garoon
- パッケージ版 Garoon バージョン 4.6 以降
引数
パラメーター名 | 型 | 必須 | 説明 |
---|---|---|---|
proxyCode | 文字列 | 必須 | プロキシ API の設定画面で設定したプロキシコード プロキシ API の設定方法は、プロキシ API の設定( クラウド版 |
url | 文字列 | 必須 | 実行する API の URL 実行する API の URL には、 url に指定した URL に加えて、プロキシ API の設定画面で設定した「パラメーター」も付与されます。詳細は、 外部 の API を実行したときに送信されるデータ - リクエスト URL を参照してください。 |
method | 文字列 | 必須 | API の実行に使用する HTTP メソッド
|
headers | オブジェクト | 必須 | リクエストヘッダー 何も指定しない場合は、 {} を指定します。実際のリクエストヘッダーには、 headers に指定したパラメーターに加えて、プロキシ API の設定画面の「ヘッダー」で設定した値も送信されます。詳細は、 外部 の API を実行したときに送信されるデータ - ヘッダー を参照してください。 |
data | オブジェクト、または文字列 | 必須 | リクエストボディ 何も指定しない場合は、 {} を指定します。値を文字列で指定すると、クエリ文字列として送信されます。 HTTP メソッドに POST/PUT/PATCH *1 を指定したときだけ送信されます。 HTTP メソッドが GET や DELETE のリクエストで、リクエストボディを指定したい場合には、 url のクエリ文字列として指定してください実際のリクエストボディには、 headers に指定したパラメーターに加えて、プロキシ API の設定画面の「リクエストボディ」で設定した値も送信されます。詳細は、 外部 の API を実行したときに送信されるデータ - リクエストボディ を参照してください。 |
successCallback | 関数 | 省略可 | リクエストが完了したあとに実行するコールバック関数 コールバック関数の引数には、次の情報が渡されます。
garoon.Promise オブジェクト が返り、レスポンスボディ、ステータスコード、レスポンスヘッダーが格納された配列で解決されます。 |
failureCallback | 関数 | 省略可 | リクエストが失敗した場合に実行するコールバック関数 コールバック関数の引数には、プロキシ API のレスポンスボディ(文字列)が渡されます。 省略すると、 garoon.Promise オブジェクト が返り、プロキシ API のレスポンスボディ(文字列)で棄却されます。 |
*1 クラウド版のみ ^
戻り値
successCallback を指定した場合、戻り値はありません。
引数の successCallback を省略した場合、
garoon.Promise
オブジェクト が返ります。
利用できる画面
- ポップアップ画面を除くすべての画面
サンプルコード
コールバックを使った記述方法
|
|
garoon.Promise オブジェクトを使った記述方法
|
|
補足
外部 の API にリクエストが送られる条件
外部 API を実行に対し、実際にリクエストが送られるときの条件は、次のとおりです。
- proxyCode の値が、プロキシ API の設定画面の「プロキシコード」と一致している。
- method の値がプロキシ API の設定画面の「メソッド」と一致している。
- url の値がプロキシ API の設定画面の「URL」と前方一致している。
たとえば、次のような場合には、URL が前方一致していると判断されます。- プロキシ API の設定画面の「URL」:https://api.example.com/
- この API に指定した
url
の値:https://api.example.com/operate.json
外部 の API を実行したときに送信されるデータ
リクエスト URL
プロキシ API の設定画面で設定した「パラメーター」は、 この API で指定した url
に付与されます。
たとえば、プロキシ API の設定画面と、この API で、それぞれ次のように設定したとします。
- プロキシ API の設定画面の「パラメーター」の値
- キー:
k1
、値:v1
- キー:
k2
、値:v2
- キー:
k3
、値:v3
- キー:
- この API に指定した
url
の値:https://api.example.com?k2=v2
このとき、リクエストは「https://api.example.com?k2=v2&k1=v&k1=v1&k2=v2&k3=v3」に送信されます。
リクエストヘッダー
プロキシ API の設定画面で設定した「ヘッダー」は、この API で指定したリクエストヘッダーに付与されます。
たとえば、プロキシ API の設定画面と、この API で、それぞれ次のように設定したとします。
-
プロキシ API の設定画面の「ヘッダー」
- キー:
k1
、値:v1
- キー:
k2
、値:v2
- キー:
-
この API に指定したリクエストヘッダー
1 2 3
{ "k3": "v3" }
このとき、次のリクエストヘッダーが送信されます。
|
|
リクエストボディ
リクエストで送信されるボディは、「Content-Type」ヘッダーとメソッドによって異なります。
GET/DELETE
Content-Type | body に指定した値 | リクエストデータのフォーマット | 送信されるボディの値 | 例 |
---|---|---|---|---|
application/x-www-form-urlencoded | オブジェクト | なし | ボディは送信されません | なし |
application/x-www-form-urlencoded | 文字列 | なし | ボディは送信されません | なし |
x-www-form-urlencoded 以外 | オブジェクト | なし | ボディは送信されません | なし |
x-www-form-urlencoded 以外 | 文字列 | なし | ボディは送信されません | なし |
POST/PUT/PATCH
Content-Type | body に指定した値 | リクエストデータのフォーマット | 送信されるボディの値 | 例 |
---|---|---|---|---|
application/x-www-form-urlencoded | オブジェクト | x-www-form-urlencoded | この API に指定した body の値に、プロキシ API の設定画面で設定した「ボディ」の値を付加したもの |
それぞれ次のように設定したとします。
b_val=%e3%81%88%e3%81%8a%e3%81%8b&a_val=%e3%81%82%e3%81%84%e3%81%86 これは、 b_val=えおか&a_val=あいう がデコードされた値です。 |
application/x-www-form-urlencoded | 文字列 | なし | この API に指定した body の値 |
それぞれ次のように設定したとします。
b_val=%e3%81%88%e3%81%8a%e3%81%8b これは、 b_val=えおか がデコードされた値です。 |
x-www-form-urlencoded 以外 | JSON オブジェクト | なし | この API に指定した body の値に、プロキシ API の設定画面で設定した「ボディ」の値を付加したもの |
それぞれ次のように設定したとします。
b_val=%e3%81%88%e3%81%8a%e3%81%8b&a_val=%e3%81%82%e3%81%84%e3%81%86 これは、 b_val=えおか&a_val=あいう がデコードされた値です。 |
x-www-form-urlencoded 以外 | 文字列 | なし | この API に指定した body の値 | それぞれ次のように設定したとします。
<?xml version="1.0" encoding="UTF-8"?><soap></soap> |
リクエストヘッダーやリクエストボディにおける重複キーの処理
プロキシ API の設定画面で設定したヘッダーやボディに、同一のキーがある場合は、後に設定した値が優先されます。
たとえば、プロキシ API の設定画面で、ヘッダーを次のように設定したとします。
- キー:
k1
、値:v1
- キー:
k1
、値:v1-priority
このとき、次のヘッダーが送信されます。
|
|
ヘッダーやボディについて、プロキシ API の設定画面で設定した値とこの API で指定した値に同一のキーがある場合は、プロキシ API の設定画面で設定した値が優先されます。
たとえば、プロキシ API の設定画面とこの API で、それぞれ次のように設定したとします。
-
プロキシ API の設定画面の「ヘッダー」
- キー:
k1
、値:v1
- キー:
k2
、値:v2-settings
- キー:
-
この API に指定したリクエストヘッダー
1 2 3
{ "k2": "v2" }
このとき、次のヘッダーが送信されます。
|
|
制限事項
クラウド版では、外部に API リクエストを送信したときの実行時間は最大で 30 秒です。30 秒を過ぎるとタイムアウトとなり、エラーが返ります。