カテゴリー内の他の記事

外部APIの実行

外部 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 のいずれかで指定します。
headers オブジェクト 必須

リクエストヘッダを指定します。
ここで指定したパラメータに加えて、プロキシ API の設定画面で設定した「ヘッダー」も送信されます。

data オブジェクト/文字列 必須

リクエストデータを指定します。このパラメータを省略するには、{} を入力します。
ここで指定したデータに加えて、プロキシ API の設定画面で設定した「ボディ」も送信されます。

値が文字列の場合、フォーマットはクエリ文字列になります。

POST/PUT のリクエストにのみ適用されます。GET/DELETE のリクエストでは無視されます。
GET/DELETE のリクエストの場合、外部 API の URL のクエリ文字列でパラメータをセットします。

successCallback 関数 省略可

リクエストが完了したあとに実行する関数を指定します。関数の引数には、次の 3 つの情報が渡されます。

  • 第一引数:レスポンスボディ(文字列)
  • 第二引数:ステータスコード(数値)
  • 第三引数:レスポンスヘッダ(オブジェクト)

省略した場合は garoon.Promise オブジェクト*1 が返され、上記のレスポンスボディ、ステータスコード、レスポンスヘッダが格納された配列で解決されます。

failureCallback 関数 省略可

リクエストが失敗した場合に実行する関数を指定します。
関数の引数には、proxy API のレスポンスボディ(文字列)が渡されます。

省略した場合は garoon.Promise オブジェクトが返され、proxy API のレスポンスボディ(文字列)で棄却されます。

*1 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.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'} となります。

記事に関するフィードバック

記事のコメント欄は記事に対するフィードバックをする場となっております。
右の記事フィードバックのためのガイドを参照してコメントしてください。
記事のリンク切れなど、気になる点がある場合も、こちらのフォームからフィードバックいただけますと幸いです。

サインインしてコメントを残してください。