前処理
前処理は、APIエンドポイントのメイン処理が実行される前に呼び出されるユーザー定義のカスタム処理です。
設定したエンドポイントに対し、アプリケーションに固有の前処理を適用できます。
前処理に実装した処理は、API情報(Swagger UI)の画面やopenapi.jsonファイルに反映されないため、表示されている情報と実際の仕様に差異が生じる可能性もあります。そのため、カスタマイズ箇所の仕様については、エンドポイントのディスクリプションに記載することを推奨します。
前処理設定方法
前処理は下記手順で動作します。
- カスタム処理にプログラムを記述
- カスタム処理をエンドポイント設定と関連付ける
それぞれの設定方法について説明します。
カスタム処理にプログラムを記述
カスタム処理画面にアクセスし、前処理を実装するためのカスタム処理を作成します。
他の目的で用意されたカスタム処理との混同を避けるために、下記の規則で設定することを推奨します。
- あらかじめ前処理用のカテゴリを作成しておき、カスタム処理のカテゴリに設定する
- カスタム処理のタイトルをエンドポイントのパス名と合わせる
カスタム処理をエンドポイント設定と関連付ける
1. API LIST画面にアクセスする
メニューよりAPI名を選択し、API LIST画面にアクセスします。
2. エンドポイントを選択する
実装対象のエンドポイントを選択し、[前処理] ボタンをクリックします。
3. カスタム処理を関連付ける
カテゴリとタイトル(コンテンツ)を選択し、前処理のために作成したカスタム処理をエンドポイントに関連付けます。
ここで関連付けるカスタム処理を間違えた場合、エンドポイントが想定通りに動作しなくなる可能性があるため、ご注意ください。
前処理の変数
前処理で利用する変数には、特別な意味を持つ予約語が存在します。これらの変数を利用することで、エンドポイントの挙動をカスタマイズできます。
| 変数名 | 種別 |
|---|---|
| $meta | 参照 |
| $url | 参照 |
| $body | 参照 |
| $errors | API制御 |
| $request | API制御 |
参照用の変数
下記の変数は、前処理が動作する時、常にデフォルトでアサインされている参照用の変数です。
エンドポイントの情報や、渡されたリクエスト値を判定するために利用します。
| 変数名 | 用途 |
|---|---|
| $meta | エンドポイントのメタ情報 |
| $url | URLの構成要素 |
| $body | リクエスト ボディ |
$meta
対象エンドポイントのメタ情報を参照するための変数です。
| 変数名 | 型 | 説明 |
|---|---|---|
| $meta | object | エンドポイントのすべてのメタ情報 |
下記の要素で構成されています。
| キー | 型 | 初期値 | 説明 |
|---|---|---|---|
| $meta.content_type | string | Content-type | |
| $meta.mime | string | Content-type | |
| $meta.mime.type | string | MIME タイプ | |
| $meta.mime.subtype | string | MIME サブタイプ | |
| $meta.output_format | string | "json" | クエリ パラメータに指定された_output_format |
| $meta.lang | string | 次の優先度に基づき決定: [ブラウザの言語設定 > 主言語設定] | クエリ パラメータに指定された_lang |
| $meta.charset | string | "utf8" | クエリ パラメータに指定された_charset |
| $meta.http_code | string | null | |
| $meta.api_header | object | API設定 | |
| $meta.post_json | string | GET: null POST: "{}" | テキスト形式のJSON body |
$url
クライアントから指定されたURLの構成要素を参照するための変数です。
| 変数名 | 型 | 説明 |
|---|---|---|
| $url | object | エンドポイントのパスとクエリパラメータのデータ |
下記の要素で構成されています。
このうち、$url.queryについては、$smarty.getと同等の値を含みます。
| キー | 型 | 説明 |
|---|---|---|
| $url.path | string | エンドポイントのパス (クエリ パラメータを除く) |
| $url.query | object | クエリ パラメータを格納した連想配列 |
例) 下記のエンドポイントに対してリクエストを送信した場合、
/https://your-api-domain/rcms-api/1/endpoint_name?p1=VALUE1&p2[]=VALUE2_0&p2[]=VALUE2_1&p3[k1]=VALUE3_1&p3[k2]=VALUE3_2
$urlには下記値が設定されます。
{
"path": "/rcms-api/1/endpoint_name"
"query": {
"p1": "VALUE1",
"p2": [
"VALUE2_0",
"VALUE2_1"
],
"p3": {
"k1": "VALUE3_1",
"k2": "VALUE3_2"
}
}
}
$body
クライアントから送信されたリクエスト ボディを参照するための変数です。
$smarty.postと同等の値を含みます。
| 変数名 | 型 | 説明 |
|---|---|---|
| $body | object | リクエスト ボディ |
API制御用の変数
下記の変数は、前処理が動作した時点ではまだ宣言されていない変数です。
これらの値を初期化し、値を入れ込むことで、エンドポイントの挙動を制御します。
| 変数名 | 用途 |
|---|---|
| $http_code | HTTPレスポンスコードの制御 |
| $errors | エラーの制御 |
| $request | リクエスト値の制御 |
前処理のカスタム処理内では、これらの変数を用途以外の目的で宣言しないでください。APIエンドポイントが意図しない挙動をする可能性があります。
$http_code
エンドポイントが出力するHTTPレスポンスコードを制御する為の変数です。
利用可能なHTTPコードは以下になります。
| コード | 名称 | 意味 |
|---|---|---|
| 400 | Bad Request | クライアントからのリクエストが不正 |
| 401 | Unauthorized | ユーザー認証が無い（未ログイン）ことによるリクエスト失敗 |
| 403 | Forbidden | コンテンツへのアクセス権が無いためにリクエスト失敗（401とは異なりユーザー認証は完了している） |
| 404 | Not Found | 指定されたエンドポイントのコンテンツが存在しないことによるリクエスト失敗 |
| 408 | Request Timeout | リクエストがタイムアウトした場合のエラー |
| 500 | Internal Server Error | クライアントからのリクエストは正しいが、サーバ側でエラーが発生した場合のエラー |
コード サンプル
{if `エラー判定処理`}
{assign var=http_code value=404}
{assign_array var=errors values=''}
{assign var=errors. value='コンテンツが存在しません'}
{/if}
$errors
エンドポイントが出力するエラーを制御するための変数です。
入力値を判定し、結果のエラーメッセージを配列に格納することで、エンドポイントに独自のバリデーション処理を実装できます。
| 変数名 | 型 | 初期値 | 説明 |
|---|---|---|---|
| $errors | object | null | テキスト配列 |
コード サンプル
{* 空配列で初期化 *}
{assign_array var='errors' values=''}
{* 入力値の判定 *}
{if $smarty.post.key_name === 'VALUE'}
{* エラーメッセージを配列に追加 *}
{assign var='errors.' value='エラーが発生しました。'}
{/if}
エラーレスポンスの形式
| HTTP status code | errors[].code | errors[].message |
|---|---|---|
| 422 | unprocessable_entity | errorsに格納したメッセージ |
// レスポンス サンプル
{
"errors": [
{
"code": "unprocessable_entity",
"message": "エラーが発生しました。"
}
],
"x-rcms-request-id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxx"
}
$errors配列に1以上の要素が含まれる場合、レスポンスの形式は下記のようになります。
[
{"code": "unprocessable_entity", "message": "errorsに格納したメッセージ"}
]
$errors配列が複数のエラー要素を含む場合、エラー個数分のオブジェクトが出力されます。
[
{"code": "unprocessable_entity", "message": "エラーメッセージ1"},
{"code": "unprocessable_entity", "message": "エラーメッセージ2"},
// ...
]
$request
メイン処理に渡すリクエスト値を制御するための変数です。
| 変数名 | 型 | 初期値 | 説明 |
|---|---|---|---|
| $request | object | null | メイン処理に渡すリクエストボディ |
この変数に次の形式で値を設定することで、メイン処理に渡すリクエスト値(GET/POST)を追加、または上書きできます。
{assign var='request.対象のキー名' value='値'}
既に指定されているリクエスト値を元に値を設定するためには、以下の参照用変数を利用します。
| 変数名 | 備考 |
|---|---|
| $url.query | $smarty.get で代替可能 |
| $body | $smarty.post で代替可能 |
コード サンプル
{* 空配列で初期化 *}
{assign_array var='request' values=''}
{* リクエスト値の有無を判定 *}
{if $url.query.filter}
{* クエリパラメータの上書き *}
{assign
var='request.filter'
value="`$url.query.filter AND topics_id in [1, 2, 3]"}
{/if}
参考チュートリアル
前処理を利用したチュートリアルページです。
困ったときは
前処理が想定通りに動作しない場合は、下記のポイントを確認してください。
- APIの前処理とカスタム処理が関連付いているか
- 関連付いているカスタム処理が正しいか
- 変数名が正しいか
- 変数に格納したデータの形式が正しいか
- カスタム処理の構文が正しいか
サポート
お探しのページは見つかりましたか？解決しない場合は、問い合わせフォームからお問い合わせいただくか、Slackコミュニティにご参加ください。