カテゴリー内の他の記事

外部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, 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.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/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'} となります。

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

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

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