外部APIの実行 – cybozu developer network

外部 API の実行

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

関数

garoon.base.proxy.send(proxyCode, url, method, headers, data, successCallback, failureCallback)

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

クラウド版 Garoon
パッケージ版 Garoon バージョン 4.6.0 以降

引数

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

パラメータ

プロキシ 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 実行時の URL は 'https://api.example.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/PATCH^*1	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/PATCH^*1	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/PATCH^*1	x-www-form-urlencoded 以外	JSONオブジェクト	外部 API に送られる値: garoon.base.proxy.send() の値に設定画面の値を付加したもの	設定画面: [キー] a_val [値] あいう garoon.base.proxy.send(): {b_val: 'えおか'} リクエストボディ: {b_val: 'えおか', a_val: 'あいう'}
POST/PUT/PATCH^*1	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 以外	文字列	ボディは送られない	なし

^*1 PATCH はクラウド版のみ

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

プロキシ 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'} となります。

制限事項

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