外部APIの実行

フォローする

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

関数

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

引数

パラメータ名 指定する値 必須 説明
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'}となります。

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

直接的に記事と関連がないご質問はcybozu developer コミュニティをご活用ください。

ログインしてコメントを残してください。
Powered by Zendesk