12. API Gateway¶

ここでは、API Gateway に登録したカスタム REST API を呼び出す方法について説明します。

12.1. CustomApi インスタンスの生成¶

API 呼び出し前に CustomApi インスタンスを生成します。以下に例を示します。

var sayHello = new Nebula.CustomApi("hello", "GET", "sayHello");

コンストラクタには３つの引数を指定します。

第1引数: カスタムAPIの名前を指定します
第2引数: HTTP メソッドを文字列で指定します。GET, POST, PUT, DELETE のいずれかを指定します。
第3引数: カスタムAPI のサブパスを指定します。

12.2. API の実行¶

APIを呼び出すには execute() を使用します。

sayHello.execute({name: "Taro Nichiden"})
    .then(function(response) {
        // 成功時の処理
        // response: レスポンス
    })
    .catch(function(error) {
        // 失敗時の処理
        // errorにはエラー要因がJSON 形式で返る。内容は以下のとおり。
        //  - status        : ステータスコード
        //  - statusText    : エラーメッセージ
        //  - responseText  : レスポンスメッセージ
    });

12.2.1. リクエストデータの指定¶

execute の引数には、サーバに引き渡すデータを指定します。データの指定方法は、HTTP メソッドにより異なります。

メソッドが GET/DELETE の場合は、データはクエリパラメータに格納されます。データは JSON Object として用意してください。キー・値がそれぞれクエリパラメータの名前・値となります。

メソッドが POST/PUT の場合は、データはリクエストボディに格納されます。

文字列を指定した場合は、文字列がそのままボディに格納されます。
Object を指定した場合は、JSON文字列に変換されます。
Blob および Buffer を指定した場合は、バイナリデータが格納されます。

Content-Type を指定したい場合は、setContentType で指定します。以下に JSON を送信する場合の例を示します。

var api = new Nebula.CustomApi("api1", "GET", "method1")
    .setContentType("application/json");

api.execute({key1: 100, key2: 200})
   .then(...)

12.2.2. レスポンスデータの受信¶

API呼び出しが成功した場合は、then() でレスポンスを受信します。

受信データがテキストデータ(JSON含む)だった場合は文字列でレスポンスが渡されます。
受信データがバイナリデータだった場合は、Blob (ブラウザの場合)または Buffer (Node.jsの場合)オブジェクトが渡されます。

バイナリデータを受信したい場合は、API呼び出し時に setBinaryResponse() を指定する必要があります。以下に例を示します。

var api = new Nebula.CustomApi("api1", "GET", "get_file")
    .setBinaryResponse();

api.execute({filename: "file1.jpg"})
    .then(function(response) {
        // response は blob または buffer
    })
    .catch(function(error) {
        ...
    });

注意

バイナリでデータを受け取る場合、エラー発生時はステータスコードのみが取得可能です。 (ステータステキストやレスポンステキストは取得不可)

12.2.3. レスポンスヘッダの受信¶

レスポンスヘッダを合わせて受信したい場合は、setReceiveResponseHeaders() を実施する必要があります。また、then() で受け取るレスポンスの形式が変更になります。

以下に例を示します。

var api = new Nebula.CustomApi("hello", "GET", "sayHello")
    .setReceiveResponseHeaders(true); // レスポンスヘッダを受信する設定

api.execute({filename: "file1.jpg"})
    .then(function(response) {
        var body = response.body; // ボディ
        var headers = response.headers; // ヘッダ
        var contentType = headers["content-type"];
        ...
    })
    .catch(function(error) {
        ...
    });

上記の通り、then() で受け取るレスポンスは、以下のようなオブジェクトとなります。 headers に格納されるヘッダ名は全て小文字に正規化されます。

{
    body: ...,  // ボディ(文字列, JSON, blob, buffer など)
    headers: {  // ヘッダ
        "content-type": "application/json",
        ...
    }
}

12.2.4. Rawデータ受信¶

Node.js の場合、Bufferにデータを蓄積せずに、ダウンロードデータを逐次処理することができます。メモリが少ない環境や、ファイルサイズが大きい場合に適しています。

以下は逐次ファイルに書き込む場合の例です。

const fs = require('fs');

// pipe を使用する場合
var writable = fs.createWriteStream("localfile.jpg");
customApi.executeRaw()
    .then((message) => {
        message.pipe(writable);
    })
    .catch(function(error) {
        // エラー時の処理
    });

// data を実装する場合
customApi.executeRaw()
    .then((message) => {
        message.on('data', () => {....});
        message.on('end', () => {....});
        message.on('error', () => {....});
        message.on('close', () => {....});
    })
    .catch(function(error) {
        // エラー時の処理
    });