外部の 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 メソッド GET POST PUT PATCH *1 DELETE
headers	オブジェクト	必須	リクエストヘッダー 何も指定しない場合は、{} を指定します。 実際のリクエストヘッダーには、headers に指定したパラメーターに加えて、プロキシ API の設定画面の「ヘッダー」で設定した値も送信されます。 詳細は、 外部 の API を実行したときに送信されるデータ - ヘッダー を参照してください。
data	オブジェクト、または文字列	必須	リクエストボディ 何も指定しない場合は、{} を指定します。 値を文字列で指定すると、クエリ文字列として送信されます。 HTTP メソッドに POST／PUT／PATCH *1 を指定したときだけ送信されます。 HTTP メソッドが GET や DELETE のリクエストで、リクエストボディを指定したい場合には、url のクエリ文字列として指定してください 実際のリクエストボディには、headers に指定したパラメーターに加えて、プロキシ API の設定画面の「リクエストボディ」で設定した値も送信されます。 詳細は、 外部 の API を実行したときに送信されるデータ - リクエストボディ を参照してください。
successCallback	関数	省略可	リクエストが完了したあとに実行するコールバック関数 コールバック関数の引数には、次の情報が渡されます。 第 1 引数：レスポンスボディ（文字列） 第 2 引数：ステータスコード（数値） 第 3 引数：レスポンスヘッダー（オブジェクト） 省略すると、 garoon.Promise オブジェクト が返り、レスポンスボディ、ステータスコード、レスポンスヘッダーが格納された配列で解決されます。
failureCallback	関数	省略可	リクエストが失敗した場合に実行するコールバック関数 コールバック関数の引数には、プロキシ API のレスポンスボディ（文字列）が渡されます。 省略すると、 garoon.Promise オブジェクト が返り、プロキシ API のレスポンスボディ（文字列）で棄却されます。

戻り値

successCallback を指定した場合、戻り値はありません。
引数の successCallback を省略した場合、 garoon.Promise オブジェクト が返ります。

利用できる画面

• ポップアップ画面を除くすべての画面

サンプルコード

コールバックを使った記述方法

1
2
3
4
5
6
7

garoon.base.proxy.send('SampleAPI', 'https://api.example.com', 'GET', {}, {}, (body, status, headers) => {
  // success
  console.log(status, JSON.parse(body), headers);
}, (error) => {
  // error
  console.log(error); // proxy APIのレスポンスボディ(文字列)を表示
});

garoon.Promise オブジェクトを使った記述方法

1

await garoon.base.proxy.send('SampleAPI', 'https://api.example.com', 'GET', {}, {});

補足

外部 の 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" }

このとき、次のリクエストヘッダーが送信されます。

1
2
3
4
5

{
  "k1": "v1",
  "k2": "v2",
  "k3": "v3"
}

リクエストボディ

リクエストで送信されるボディは、「Content-Type」ヘッダーとメソッドによって異なります。

GET／DELETE

POST／PUT／PATCH

リクエストヘッダーやリクエストボディにおける重複キーの処理

プロキシ API の設定画面で設定したヘッダーやボディに、同一のキーがある場合は、後に設定した値が優先されます。

たとえば、プロキシ API の設定画面で、ヘッダーを次のように設定したとします。

• キー: k1、値： v1
• キー: k1、値： v1-priority

このとき、次のヘッダーが送信されます。

1
2
3

{
  "k1": "v1-priority"
}

ヘッダーやボディについて、プロキシ API の設定画面で設定した値とこの API で指定した値に同一のキーがある場合は、プロキシ API の設定画面で設定した値が優先されます。

たとえば、プロキシ API の設定画面とこの API で、それぞれ次のように設定したとします。

• プロキシ API の設定画面の「ヘッダー」

  • キー: k1、値： v1
  • キー: k2、値： v2-settings

• この API に指定したリクエストヘッダー

  1 2 3

  { "k2": "v2" }

このとき、次のヘッダーが送信されます。

1
2
3
4

{
  "k1": "v1",
  "k2": "v2-settings"
}

制限事項

クラウド版では、外部に API リクエストを送信したときの実行時間は最大で 30 秒です。30 秒を過ぎるとタイムアウトとなり、エラーが返ります。