---
title: カスタム処理と紐づいたAPIエンドポイントを作成する
description: カスタム処理を利用することで、APIエンドポイントの標準機能だけでは実現が難しい処理を自由に追加できます。そのため、様々なユースケースに柔軟に対応できます。
---

Kurocoではカスタム処理と紐づいたエンドポイントの作成ができます。  

## カスタム処理を利用することのメリット

カスタム処理を利用することで、APIエンドポイントの標準機能だけでは実現が難しい処理を自由に追加できます。そのため、様々なユースケースに柔軟に対応できます。

例として、下記対応が可能です。

- リクエスト/レスポンス内容を変更する
- APIへの処理をフックする
- 独自のセキュリティ制御を実装する

このチュートリアルでは、カスタム処理とエンドポイントを紐付ける方法を紹介します。

## GETエンドポイントとカスタム処理を作成する

まずはGETエンドポイントの例を紹介します。  
ここでは例として、`PlainCustomFunction`という名前のカスタム処理をAPIエンドポイントと紐付けます。

### GETエンドポイントを作成する

カスタム処理と紐づけるためのエンドポイントを作成します。

エンドポイント一覧画面より、[新しいエンドポイントの追加]をクリックします。

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

今回は下記のように作成しました。

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

| 設定項目 | 設定           |             |
| :------- | :------------- | :---------- |
| パス |  | plain-custom-endpoint |
|  | 有効/無効 | 有効 |
| モデル | カテゴリー | API |
|  | モデル | Api、v1 |
|  | オペレーション | request_api |
| サマリー(任意) |  | PlainCustomFunction<br/>**注：わかりやすい名前を記載してください。後に作成するカスタム処理名の記載を推奨します。**|
| ディスクリプション(任意) | | PlainCustomFunctionと紐づくGETエンドポイントです。<br/>**注：わかりやすい説明を記載してください。カスタム処理の意図/機能の記載を推奨します。** |
| 基本設定 | name | PlainCustomFunction<br/>**注:後に作成するカスタム処理のslugを指定します。** |

:::tip
`use_path_param`のパラメータを有効にすると、`/rcms-api/1/external_api/{data_id}`のようにパスパラメータを受け付けます。   
詳しい使い方は以下のドキュメントを参照してください。
- [コンテンツカテゴリ毎にキャッシュがクリアされるリストのエンドポイントを作成する](/ja/docs/tutorials/create-an-endpoint-that-clears-the-cache-by-content-category/)
:::

### GETエンドポイント用のカスタム処理を作成する

次に、作成したGETエンドポイント用のカスタム処理を作成します。

カスタム処理一覧画面より、[追加]をクリックします。

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

下記の設定で作成します。

|項目   |説明  |
| :--- | :--- |
|タイトル|PlainCustomFunction|
|カテゴリ|未分類|
|識別子|PlainCustomFunction|
|処理|下記ソースコードの内容を記載してください。|
|ステータス|有効|

```php [ソースコード]
{assign var="data" value=”Hello!"}
```

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

#### request_api に使用できる変数

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

#### 利用可能なHTTPコード

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

### GETエンドポイントの動作確認をする
それでは、作成したエンドポイントの動作確認をします。
今回はSwaggerUI画面から確認します。

エンドポイント一覧画面より、[Swagger UI]をクリックします。

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

先ほど作成した、`plain-custom-endpoint`をクリックします。

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

[Try it out]をクリックします。

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

[Execute]をクリックします。

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

すると、Response bodyにカスタム処理で作成した内容が表示されていることが確認できます。

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

以上で、GETエンドポイントとカスタム処理の紐付け完了です。

## POSTエンドポイントとカスタム処理を作成する

次に、POSTエンドポイントの例を紹介します。
ここでは例として、`PlainCustomFunctionPost`という名前のカスタム処理を作成することとし、サマリー/ディスクリプションに説明例を記載しています。

### POSTエンドポイントを作成する

カスタム処理と紐づけるためのエンドポイントを作成します。

エンドポイント一覧画面より、[新しいエンドポイントの追加]をクリックします。

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

今回は下記のように作成しました。

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

| 設定項目 | 設定           |             |
| :------- | :------------- | :---------- |
| パス | | plain-custom-endpoint-post |
|  | 有効/無効 | 有効 |
| モデル | カテゴリー | API |
|  | モデル | Api、v1 |
|  | オペレーション | request_api_post |
| サマリー(任意) |  | PlainCustomFunctionPost<br/>**注：わかりやすい名前を記載してください。後に作成するカスタム処理名の記載を推奨します。**|
| ディスクリプション(任意) | | PlainCustomFunctionPostと紐づくPOSTエンドポイントです。<br/>**注：わかりやすい説明を記載してください。カスタム処理の意図/機能の記載を推奨します。** |
| 基本設定 | name | PlainCustomFunctionPost<br/>**注:後に作成するカスタム処理のslugを指定します。** |

### POSTエンドポイント用のカスタム処理を作成する

次に、作成したPOSTエンドポイント用のカスタム処理を作成します。

カスタム処理一覧画面より、[追加]をクリックします。

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

下記の設定で作成します。

|項目   |説明  |
| :--- | :--- |
|タイトル|PlainCustomFunctionPost|
|カテゴリ|未分類|
|識別子|PlainCustomFunctionPost|
|実行内容|下記ソースコードの内容を記載してください。|
|ステータス|有効|

```php [ソースコード]
{assign var="message" value="Hello "|cat:$smarty.post.name}
{assign var="data" value=$message}
```

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

#### request_api_post に使用できる変数

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

#### 利用可能なHTTPコード

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

### POSTエンドポイントの動作確認をする

それでは、作成したエンドポイントの動作確認をします。
今回はSwaggerUI画面から確認します。

エンドポイント一覧画面より、[Swagger UI]をクリックします。

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

先ほど作成した、`plain-custom-endpoint-post`をクリックします。

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

[Try it out]をクリックします。

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

Response body に以下のように入力します。
```json
{
  "name": "Kuroco"
}
```

[Execute]をクリックします。

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

すると、Response bodyにカスタム処理で作成した内容が表示されていることが確認できます。

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

以上で、POSTエンドポイントとカスタム処理の紐付け完了です。

### 任意のリクエスト変数を付与する

上述の通り作成したエンドポイントは任意のリクエスト変数を受け付ける事ができます。  
カスタム処理内でリクエスト変数を扱うには以下のように記述します。

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

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

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

```php [ソースコード]
{assign var="message" value="Hello "|cat:$smarty.request.name}
{assign var="data" value=$message}
```

#### 正常終了メッセージ・エラーメッセージを返す

レスポンスにエラーメッセージ(`errors`) や正常終了メッセージ(`messages`) を送信したい場合は、カスタム処理にて以下のように記述します。

```smarty [ソースコード]
{assign var="message" value="Hello "|cat:$smarty.post.name}
{assign var="data" value=$message}
{if $smarty.post.name|strlen > 10}
    {append var="errors" value="name should be less than 10 characters."}
{else}
    {append var="messages" value="name is valid."}
{/if}
```

この例では、POST変数`name`に10文字以上の文字列が指定された場合はエラー、それ以外は正常終了メッセージをレスポンスしています。

SwaggerUI画面のRequest bodyに以下のように記載し、[Execute]をクリックしてみましょう。

```json
{
  "name": "Kuroco"
}
```

実行結果（正常終了メッセージ）：
![Image from Gyazo](https://t.gyazo.com/teams/diverta/252b5fed66e614c4a8353e94d8495f50.png)

正常終了メッセージがレスポンスされる事を確認できました。


次にSwaggerUI画面のRequest bodyに以下のように記載し、[Execute]をクリックしてみましょう。

```json
{
  "name": "KurocoDiverta"
}
```

実行結果（エラー）：
![Image from Gyazo](https://t.gyazo.com/teams/diverta/cb16431da0b385d05d1605c6025b9ab8.png)

エラーメッセージがレスポンスされる事を確認できました。  

## カスタム処理の実装例について

以上でカスタム処理とAPIエンドポイントの紐付け方法の紹介を終わります。
このチュートリアルではシンプルに紐付けの方法のみの説明にとどめましたが、カスタム処理の実装についてもっと詳しく知りたい場合は、下記ユースケース別のチュートリアルを参照してください。

- [カスタム処理を利用して、APIエンドポイントに独自のスタブを設定する](/ja/docs/tutorials/setting-up-stubs-on-api-endpoints-using-custom-functions/)
- [カスタム処理を利用して、APIに独自のバリデーションを実装する](/ja/docs/tutorials/how-to-implement-original-validation-in-api-by-using-function/)
- [カスタム処理を利用して、APIのメイン処理に渡すリクエスト値を書き換える](/ja/docs/tutorials/how-to-overwrite-request-for-api-main-process-by-using-function/)
