---
title: 後処理
description: 後処理は、APIエンドポイントのメイン処理が実行された後にエンドポイントの力に対して行われるユーザー定義のカスタム処理です。 
---

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

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

![Image from Gyazo](https://t.gyazo.com/teams/diverta/712dc9c39f274398ea09960a320c2b16.png)

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

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

![Image from Gyazo](https://t.gyazo.com/teams/diverta/497be3d3af76dcf0c5b3123a62728aa6.png)

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

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

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

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

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

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

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

#### 設定方法

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

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

#### 設定例

```json [Original Output]
{
  "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`

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

![Image from Gyazo](https://t.gyazo.com/teams/diverta/4909b580440f3ea39d2e84aea0fbb7e0.png)

:::tip
- ネストされたJSONオブジェクトは必ず `.` で表し、配列はすべて無視します。  
- ワイルドカードで指定する場合は、`list.images-*`のように設定します。
:::

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

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

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

![Image from Gyazo](https://t.gyazo.com/teams/diverta/6ae9a59173a7d7872e9fcab5292be1b3.png)

#### 項目設定

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

#### 変換処理

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

#### 設定例

```json [Original Output]
{
  "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 |

![Image from Gyazo](https://t.gyazo.com/teams/diverta/9be41b54b69bfc5a01b3c846d7a52369.png)

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

```json [Filtered Output]
{
"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
  }
}
```

### カスタム処理

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

#### カスタム処理の作成

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

![Image from Gyazo](https://t.gyazo.com/teams/diverta/bd5aa3aa781410f063d6234959bfb470.png)
カスタム処理は、他のモジュールで使用されているカスタム処理との混同を避けるため、以下のように設定することをお勧めします。

- あらかじめ後処理用の[カスタム処理カテゴリ](/ja/docs/management/function-category/)を作成し、それを関数のカテゴリとして設定する。
- カスタム関数のタイトルとエンドポイントのパス名を一致させる。

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

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

![Image from Gyazo](https://t.gyazo.com/teams/diverta/05085deba926556df84200a11e3675fa.png)

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

## 後処理の変数
後処理で利用する変数には、特別な意味を持つ予約語が存在します。これらの変数を利用することで、エンドポイントの挙動をカスタマイズできます。

| 変数名 | 種別 |
| :--- | :--- |
| `$json` | 参照 |
| `$processed_json` | API制御 |
| `$errors` | API制御 |
| `$http_code` | API制御 |


## 参照用の変数
### アサインされた変数
下記の変数は、後処理が動作する時、常にデフォルトでアサインされている参照用の変数です。 

| 変数名 | 型 | 説明 |
| :--- | :--- | :--- |
| `$json` | object | API のオリジナルの JSON 出力 |

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

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

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

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

:::info
後処理で$smarty.requestを使用する場合、コンテンツの拡張項目はslugではなく、ext_Xでアサインされることがあります。
:::

## API制御用の変数

| 変数名 | 区分 |型 |説明 |
| :--- | :-- | :-- |:-- |
| `$processed_json` |必須|object|この変数にレスポンスになるJSONの値を代入します。 |
| `$errors` |任意|object|この変数に値を代入すると、エンドポイントがエラーを返します。代入した値はレスポンスのmessage項目になります。 |
| `$http_code` |任意|int|errorsに値が代入されている時、この変数に値を代入すると、元のHTTPコードを上書きします。 |

利用可能なHTTPコードは以下になります。

| コード | 名称 | 意味 |
|---|---|---|
| 400 | Bad Request | クライアントからのリクエストが不正 |
| 401 | Unauthorized | ユーザー認証が無い（未ログイン）ことによるリクエスト失敗 |
| 403 | Forbidden | コンテンツへのアクセス権が無いためにリクエスト失敗（401とは異なりユーザー認証は完了している） |
| 404 | Not Found | 指定されたエンドポイントのコンテンツが存在しないことによるリクエスト失敗 |
| 405 | Method Not Allowed | 許可されていないHTTPメソッドを使用した場合のエラー |
| 406 | Not Acceptable | リクエストの条件に合うレスポンスをサーバーが生成できない場合のエラー |
| 500 | Internal Server Error | クライアントからのリクエストは正しいが、サーバ側でエラーが発生した場合のエラー |

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

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