外部のAPIを実行する

コラボフローJavaScript APIを使って、外部WebサイトのREST APIを実行する方法について説明します。

コラボフローJavaScript APIでは、クロスドメインの制限を回避して、外部WebサイトのREST APIを呼び出すための関数が用意されています。

関数はそれぞれHTTPメソッド毎に用意されており、どの関数も非同期で処理され、Promiseを返します。
サーバーからデータを受信したらthen()で登録したハンドラーが呼び出されます。

外部APIの定義

リクエストするHTTPメソッドごとにAPIがあります。

// GETリクエストを送信
collaboflow.proxy.get(url, headers, parseType).then(function (response) {
    // 応答受信後の処理
}).catch(function (error) {
    // 失敗時の処理（サーバーから応答が無い、JSON変換エラーなど）
});

// HEADリクエストを送信
collaboflow.proxy.head(url, headers, parseType).then(function (response) {
    // …
});

// POSTリクエストを送信
collaboflow.proxy.post(url, headers, data, parseType).then(function (response) {
    // …
});

// PUTリクエストを送信
collaboflow.proxy.put(url, headers, data, parseType).then(function (response) {
    // …
});

// DELETEリクエストを送信
collaboflow.proxy.delete(url, headers, data, parseType).then(function (response) {
    // …
});

// PATCHリクエストを送信
collaboflow.proxy.patch(url, headers, data, parseType).then(function (response) {
    // …
});

引数

引数名	タイプ	説明
url	string	リクエスト先のURL
headers	object	リクエスト先に送信するHTTPヘッダー。ヘッダー名をキーとした連想配列です。
data	string / object	相手サーバーに送信するボディ部。詳細は後述します。
parseType	string	相手サーバーから受信したボディ部の変換方法。"text"、"json"、"base64"または空文字列""を指定できます。詳細は後述します。

data引数の詳細

data引数はリクエスト先に送信するボディ部として扱います。渡すタイプに応じて変換動作が変わります。

• オブジェクトを渡した場合
  JSON形式に変換してから送信します。 Content-Typeには「application/json; charset=UTF-8」が自動設定されます。

• 文字列を渡した場合
  そのまま送信します。URLエンコードなどの変換はしないので必要に応じて事前に処理してください。 Content-Typeには「application/x-www-form-urlencoded」（フォーム形式扱い）が自動設定されます。

自動変換されるJSON形式が相手サーバーと合わない場合や特殊な形式で送信したい場合は文字列渡しが有用です。自前で文字列化やエンコード行うと共にheaders引数でContent-Typeヘッダーの指定も検討してください。

parseType引数の詳細

parseTypeは相手サーバーから受信したボディ部をどのように扱うかを決定します。 省略か空文字列を指定すると相手サーバーから受信したContent-Typeヘッダーに基づいて自動判別されます。

• text
  受信したデータはプレーンテキストとして返します。
  response.body は文字列型になります。HTMLを受け取る場合などに有用です。

• json
  受信したデータはJSON形式とみなして自動変換した結果を返します。
  response.body はオブジェクト型（連想配列）になります。

• base64
  受信したデータをBASE64形式にエンコードした状態で返します。
  response.body は文字列型になります。画像ファイルなどを受信したい場合に有用です。 BASE64形式を元のバイナリデータに戻すには自前で デコード処理などが必要です。

完了ハンドラー

相手サーバーからの応答を受信すると、then()で登録した完了ハンドラー関数が呼び出されます。
完了ハンドラー関数が受け取るresponseオブジェクトの内容を示します。

プロパティ名	タイプ	説明
success	boolean	成功系の応答（statusが200～299または304）なら true
status	numeric	相手サーバーが返した応答HTTPステータスコード
status_text	string	相手サーバーが返した応答HTTPステータス文字列
headers	object	相手サーバーから受信したヘッダー
body_type	string	bodyのデータ形式。"string"、"object"、"base64"のいずれかの値をとります。
body	string / object	相手サーバーから受信したボディ部。受信したContent-Typeヘッダーによる自動判断またはparseType引数で指定した変換結果が収まっています。

相手サーバーからの応答があれば完了ハンドラーが呼ばれますが、その結果が失敗系（ステータスが403や500など）であっても同様です。実装にあたってはsuccessプロパティまたはstatusプロパティを参照して処理を振り分ける・リトライするなども検討してください。

記述例

GETリクエスト

URLクエリパラメーターは予めURLエンコードした状態で渡します。

collaboflow.proxy.get(
    "https://api.example.com/search?q=%E6%9D%B1%E4%BA%AC&apikey=xxxxxxxxxxxxxxxxx"
).then(function (response) {
    console.log(response.body);
});

POSTリクエスト

collaboflow.proxy.post(
    "https://api.example.com/search",
    { "X-ApiKey": "xxxxxxxxxxxxxxxxx" },
    { "category": "animal", "keywords": ["cat", "dog"] },
    "json"
).then(function (response) {
    if(response.status === 200) {
        // 受信したヘッダー
        console.log(response.headers);
        // 受信した内容
        console.log(response.body);
    }
});

制限事項

外部APIの呼び出しはシステムやブラウザーを保護するために以下の制限があります。
これらの制限はクラウド版／パッケージ版ともに同じで変更することはできません。

• 相手サーバーから受信できるボディ部は最大で10MiB（10,485,760バイト）です。受信したヘッダーは含みません。
• 相手サーバーからの応答待ち時間（受信タイムアウト）は120秒です。
• 各リクエストはコラボフローのWebサーバーを経由して行われます。
  コラボフローのWebサーバーからアクセスできないURLにはアクセスできません。送信元IPアドレス等によるアクセス制限を設定している場合は、相手サーバー等で別途設定が必要です。