後処理

後処理は、APIエンドポイントのメイン処理が実行された後にエンドポイントの力に対して行われるユーザー定義のカスタム処理です。
設定したエンドポイントに対し、アプリケーションに固有の後処理を適用できます。

ヒント

Post-processingに実装した処理は、API情報(Swagger UI)の画面やOpenAPIのopenapi.jsonファイルに反映されないため、表示されている情報と実際の仕様に差異が生じる可能性もあります。そのため、カスタマイズ箇所の仕様については、エンドポイントの説明の項目に記載することを推奨します。

後処理の設定方法

後処理はブロック毎に設定を定義します。 各ブロックは、直前のブロックの実行結果を入力として受け取りながら、定義した順番に実行されます。

処理ブロックの数に制限はありません。
[追加する]をクリックすると、新しい空のブロックがシリーズの最後に追加されます。

備考

出力許可リストは、他の処理（カスタム処理など）の手前で実行するとSQLなどの内部処理にも効果があります。
パフォーマンスの向上が期待できますので、可能な場合は出力許可リストを最上位に設定することをお勧めします。

後処理の種類

現在、Kurocoは以下の3種類の処理をサポートしています。

後処理の種類	説明
出力許可リスト	ホワイトリスト型のフィルターです。出力に残すフィールドのリストを定義し、他のすべてのフィールドは削除されます。
出力変換リスト	指定したフィールドに対して、フィールドの削除、キー名の変更、Kurocoで定義済みの関数適用ができます。
カスタム処理	カスタム処理で独自に記述したプログラムをエンドポイントにリンクさせます。

それぞれの処理について、以下で詳細を説明します。

出力許可リスト

list や details のAPI は多くの情報を返しますが、その中の特定のフィールドをユーザーから隠したりオプションにしたい場合があります。

出力許可リストは設定したフィールドのみが返されるようになる、ホワイトリスト型のフィルターとして利用します。 レスポンスとして得たいすべてのフィールドを設定してください。

ヒント

ブラックリスト型のフィルターを適用したい場合は出力変換リストを利用してください。

設定方法

JSON 出力のフィールドへのフルパスを、ルートから順に指定します。配列はスキップして、オブジェクトのみを指定します (フィルターは、配列内のすべてのオブジェクトに適用されます。)

ヒント

許可リストにフィールドが指定されていない場合やパス名に誤りがある場合、エンドポイントは空のJSONオブジェクトを出力します。

設定例

{
  "list": [
    {
      "subject": "First article",
      "contents": "The contents of the first article",
      "sponsors": ["Company X"]
    },
    {
      "subject": "Second article",
      "contents": "The contents of the second article",
      "sponsors": ["Company Y"]
    }
  ],
  "pageInfo": {
    "totalCnt": 7,
    "pageNo": 1,
    ...
  }
}

例えば、上記のAPIレスポンスから、sponsorsだけを削除したいとします。
残すフィールドは以下の3つです。

• list.subject
• list.contents
• pageInfo

以下のように設定します。

ヒント

ネストされたJSONオブジェクトは必ず . で表し、配列はすべて無視します。

出力許可リストは容易に設定できますが、柔軟性に欠ける場合があります。より詳細なカスタマイズが必要な場合は、出力変換リスト や カスタム処理 を利用してください。

出力変換リスト

出力変換リストでは、各フィールドに対して処理の内容を設定できます。

[処理を追加する]をクリックすると、特定のフィールドの処理を設定するサブブロックが追加されます。出力変換リストには2種類の[削除]機能があり、右側の[削除する]ボタンは対応するサブブロックの行を削除し、下側の[削除する]ボタンはブロック全体を削除します。

項目設定

フィールド	説明
フィールド	対象フィールドのパスは許可リストと同様の方法で指定します。配列をスキップし、ネストされたオブジェクトはドット区切りで指定してください。 フィルタは指定したフィールド内のすべての要素に適用されます。 存在しないフィールドを入力した場合、「名称」に入力した名前の新しいフィールドが作成されます。こちらを利用して、任意の静的データをAPIに簡単に追加することができます。
フィールドのコピー・削除	削除：削除にチェックを入れると、レスポンスから指定したフィールドが削除されます。 コピー：コピーにチェックを入れて、「名称」を記入すると、指定したフィールドをコピーして、名称に記入したフィールド名で新しいフィールドが作成されます。 元のフィールドと値は保存されます。
名称	フィールドの新しい名前を指定します。新しいフィールドは、元のフィールドと同じ階層に追加されます。 注意: パスの指定はできませんので、ドット記法を使って元のフィールドと異なるネスト構造を設定することはできません。
処理	フィールドに適用する任意の処理を1つ以上選択します。複数の処理がある場合は、選択した順番に適用されます。各処理の具体的な動作は変換処理を参照してください。 [-]をクリックすると処理の削除ができます。
削除	対象のサブブロックの行を削除します。

変換処理

処理名	動作
Null	元の値をそのままコピーします。
Truncate	指定した最大文字以下になるよう左から値を切り詰めます。 例：値=あいうえお、最大長=3 ⇒ あいう 空白のまま (または 0 に設定) にすると、最大長はデフォルトで 10 になります。
Trim	文字列の先頭と末尾からすべてのスペース/タブを削除します。 注意： この関数は、値を文字列形式に変換します。
Strtotime	PHPのstrtotime関数を値に適用します。
Date format	PHPのdata関数を値に適用し、Unixタイムスタンプにフォーマットします。
Locale Date Format	値にpg_dateformat関数を適用します。
Uppercase	すべての文字を、大文字に変換します。
Lowercase	すべての文字を、小文字に変換します。
Sprintf	値にPHPのsprintf関数を適用します。既存の値が第二引数として使用され、%s やその他の指定子を使ってアクセスすることができます。
Nl2br	文字列内の全ての改行(\n, \r, \r\n) の前に <br />を挿入します。htmlにレンダリングするときに便利です。
FileSize	指定されたパスにファイルが存在する場合、そのファイルのバイトサイズを取得します。
ImageSize	指定されたパスに画像が存在する場合、そのバイトサイズを取得します。

設定例

{
  "list": [
    {
      "subject": "First article",
      "contents": "The contents of the first article",
      "sponsors": ["Company X"]
    },
    {
      "subject": "Second article",
      "contents": "The contents of the second article",
      "sponsors": ["Company Y"]
    }
  ],
  "pageInfo": {
    "totalCnt": 7,
    "pageNo": 1,
    ...
  }
}

例えば、上記のAPIレスポンスでsubjectの文字列を全て大文字にし、title という名称の新しいフィールドを追加したいとします。
フィールドの設定は以下のようになります。

項目	設定
フィールド	list.subject
フィールドのコピー・削除	[コピー]をチェックします。
名称	title
処理	Uppercase

処理が実行された新しいAPIレスポンスは以下になります。

{
"list":
  [
    {
      "subject": "First article",
      "contents": "The contents of the first article",
      "sponsors": [
        "Company X"
      ],
      "title": "FIRST ARTICLE"
    },
    {
      "subject": "Second article",
      "contents": "The contents of the second article",
      "sponsors": [
        "Company Y"
      ],
      "title": "SECOND ARTICLE"
    }
  ],
"pageInfo":
  {
    "totalCnt": 7,
    "pageNo": 1
  }
}

カスタム処理

もし、より複雑な機能を持ちたい場合は、データをどのように変換するかを定義したカスタム処理を作成し、それをエンドポイントにリンクさせる事で対応可能です。

カスタム処理の作成

[カスタム処理]を参考に、後処理で利用するカスタム処理を作成してください。

カスタム処理は、他のモジュールで使用されているカスタム処理との混同を避けるため、以下のように設定することをお勧めします。

• あらかじめ後処理用のカスタム処理カテゴリを作成し、それを関数のカテゴリとして設定する。
• カスタム関数のタイトルとエンドポイントのパス名を一致させる。

カスタム処理を対象のエンドポイントと紐づける

1. 左サイドバーメニューの[API]をクリックし、対象のエンドポイント一覧画面を選択します。
2. リストから対象のエンドポイントを選択し、[後処理]をクリックします。
3. ドロップダウンリストから[カスタム処理]を選択し、カテゴリーを選択して、リスト表示さた他カスタム処理を選択する。
4. [保存]をクリックします

注意

選択したカスタム処理が間違っていると、エンドポイントが期待通りに動作しません。カスタム処理を正しくリンクしたことを再確認することをお勧めします。

後処理に利用できる変数

アサインされた変数

後処理にはあらかじめ以下の変数がアサインされています。また、返り値は後処理が出力する処理の結果です。 これらの変数を使用して、エンドポイントの動作を自由にカスタマイズできます。

変数名	種類	説明
$json	変数	API のオリジナルの JSON 出力
$processed_json	返り値	この変数に値を代入すると、元のJSONレスポンスを上書きします。

リクエスト変数

後処理内でリクエスト変数を扱うには以下のように記述します。

• GET変数 : $smarty.get.hoge
• POST変数 : $smarty.post.foo

また、上記をまとめたリクエスト変数も利用可能です。

• リクエスト変数 : $smarty.request.piyo

{assign var="message" value="Hello "|cat:$smarty.request.name}
{assign var="data" value=$message}

困ったときは

後処理が想定通りに動作しない場合は、下記のポイントを確認してください。

• APIの後処理とカスタム処理が関連付いているか
• 関連付いているカスタム処理が正しいか
• 変数名が正しいか
• 変数に格納したデータの形式が正しいか
• カスタム処理の構文が正しいか