外部APIの実行

Garoon から外部のAPIを実行できます。

関数

garoon.base.proxy.send(proxyCode, url, method, headers, data, callback, error)

使用可能なガルーンバージョン

Garoon on cybozu.com
パッケージ版バージョン 4.6.0以降

引数

パラメータ名	指定する値	必須	説明
proxyCode	文字列	必須	プロキシAPIの設定画面で設定した「プロキシコード」です。プロキシAPIの設定方法についてはGaroon 管理者ガイドをご参照ください。
url	文字列	必須	実行する API のURL を指定します。ここで指定したURLに加えて、プロキシAPIの設定画面で設定した「パラメーター」も送信されます。
method	文字列	必須	API の実行に使用するHTTP メソッドを、GET、POST、PUT、DELETE のいずれかで指定します。
headers	オブジェクト	必須	リクエストヘッダを指定します。ここで指定したパラメータに加えて、プロキシAPIの設定画面で設定した「ヘッダー」も送信されます。
data	オブジェクト/文字列	必須	リクエストデータを指定します。このパラメータを省略するには、{}を入力します。ここで指定したデータに加えて、プロキシAPIの設定画面で設定した「ボディ」も送信されます。値が文字列の場合、フォーマットはクエリ文字列になります。 POST/PUTのリクエストにのみ適用されます。GET/DELETEのリクエストでは無視されます。GET/DELETEのリクエストの場合、外部APIのURLのクエリ文字列でパラメータをセットします。
callback	関数	省略可	リクエストが完了したあとに実行する関数を指定します。関数の引数には、次の3 つの情報が渡されます。第一引数：レスポンスボディ（文字列）第二引数：ステータスコード（数値）第三引数：レスポンスヘッダ（オブジェクト）省略した場合はgaroon.Promiseオブジェクト^*1 が返され、上記のレスポンスボディ、ステータスコード、レスポンスヘッダが格納された配列で解決されます。
error	関数	省略可	リクエストが失敗した場合に実行する関数を指定します。関数の引数には、proxy APIのレスポンスボディ(文字列)が渡されます。 callbackを省略した場合はgaroon.Promiseオブジェクトが返され、proxy APIのレスポンスボディ(文字列)で棄却されます。

^*1 garoon.Promiseオブジェクトは、thenメソッドを持っているオブジェクトです。
▼参考(外部サイト)https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise

返り値

引数のcallbackを省略した場合、garoon.Promiseオブジェクトを返します。

callbackを指定した場合返り値はありません（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実行時に送信されるデータ

パラメータ

プロキシ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.github.com?k2=v2'

→外部API実行時のURLは 'https://api.github.com?k2=v2&k1=v&k1=v1&k2=v2&k3=v3' となります。

リクエストヘッダ

プロキシAPIの設定画面で設定された「ヘッダー」はgaroon.base.proxy.send()で指定されたリクエストヘッダに付加されます。

例）次のようにリクエストヘッダを指定した場合

プロキシAPIの設定画面の「ヘッダー」
- キー: k1, 値: v1
- キー: k2, 値: v2
garoon.base.proxy.send()のリクエストヘッダ
- {k2: 'v2'}

→外部API実行時のヘッダは {k1: 'v1', k2: 'v2'}となります。

ボディ

以下の表は、メソッド/Content-Type/garoon.base.proxy.send()で指定されたフォーマット毎に送られるリクエストデータの仕様と例をまとめたものです。

メソッド	Content-Type	garoon.base.proxy.send()で指定されたフォーマット	リクエストデータの仕様	例
POST/PUT	application/x-www-form-urlencoded	JSONオブジェクト	フォーマット: x-www-form-urlencoded 外部APIに送られる値: garoon.base.proxy.send ()の値に設定画面の値を付加したもの	設定画面: [キー] a_val [値] あいう garoon.base.proxy.send(): {b_val: 'えおか'} リクエストボディ: 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=あいう)
POST/PUT	application/x-www-form-urlencoded	文字列	外部APIに送られる値:garoon.base.proxy.send ()の値	設定画面: [キー] a_val [値] あいう garoon.base.proxy.send(): b_val=%e3%81%88%e3%81%8a%e3%81%8b (デコードされた値: b_val=えおか) リクエストボディ: b_val=%e3%81%88%e3%81%8a%e3%81%8b (デコードされた値: b_val=えおか)
POST/PUT	x-www-form-urlencoded 以外	JSONオブジェクト	外部APIに送られる値: garoon.base.proxy.send ()の値に設定画面の値を付加したもの	設定画面: [キー] a_val [値] あいう garoon.base.proxy.send(): {b_val: 'えおか'} リクエストボディ: {b_val: 'えおか', a_val: 'あいう'}
POST/PUT	x-www-form-urlencoded 以外	文字列	外部APIに送られる値: garoon.base.proxy.send()の値	設定画面: [キー] a_val [値] あいう garoon.base.proxy.send(): <?xml version="1.0" encoding="UTF-8"?><soap></soap> リクエストボディ: <?xml version="1.0" encoding="UTF-8"?><soap></soap>
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 以外	文字列	ボディは送られない	なし

重複キーの処理（ヘッダ、ボディ）

プロキシAPIの設定画面で同一のキーがある場合、前者の値を優先します。

例）次のようにヘッダを指定した場合

- プロキシAPIの設定画面の「ヘッダー」
  - キー: k1, 値: v1
  - キー: k1, 値: v1-priority

→外部API実行時のヘッダは{k1: 'v1-priority'}となります。

garoon.base.proxy.send()で設定されたキーとプロキシAPIの設定画面で設定されたキーが同一の場合、プロキシAPIの設定画面を優先します。

例）次のようにヘッダを指定した場合

- プロキシAPIの設定画面の「ヘッダー」
  - キー: k1, 値: v1
  - キー: k2, 値: v2-setting
- garoon.base.proxy.send()のリクエストヘッダ
  - {k2: 'v2'}

→外部API実行時のヘッダは{k1:'v1', k2: 'v2-setting'}となります。