Pre-processing

Pre-processingは、APIエンドポイントのメイン処理が実行される前に呼び出されるユーザー定義のオリジナル処理です。
設定したエンドポイントに対し、アプリケーションに固有の前処理を適用することができます。

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

Pre-processing設定方法

Pre-processingは下記手順で動作します。

  1. オリジナル処理にプログラムを記述
  2. オリジナル処理をエンドポイント設定と関連付ける

それぞれの設定方法について説明します。

オリジナル処理にプログラムを記述

オリジナル処理画面にアクセスし、Pre-processingを実装するためのオリジナル処理を作成します。

Image (fetched from Gyazo)

他の目的で用意されたオリジナル処理との混同を避けるために、下記の規則で設定することを推奨します。

  • あらかじめPre-processing用のカテゴリを作成しておき、オリジナル処理のカテゴリに設定する
  • オリジナル処理のタイトルをエンドポイントのパス名と合わせる

オリジナル処理をエンドポイント設定と関連付ける

1. API LIST画面にアクセスする

メニューよりAPI名を選択し、API LIST画面にアクセスします。

Image (fetched from Gyazo)

2. エンドポイントを選択する

実装対象のエンドポイントを選択し、[Pre-processing] ボタンをクリックします。

Image (fetched from Gyazo)

3. オリジナル処理を関連付ける

カテゴリとタイトル(コンテンツ)を選択し、Pre-processingのために作成したオリジナル処理をエンドポイントに関連付けます。

ここで関連付けるオリジナル処理を間違えた場合、エンドポイントが想定通りに動作しなくなる可能性があるため、ご注意ください。

Image (fetched from Gyazo)

Pre-processingの変数

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

変数名種別
$meta参照
$url参照
$body参照
$errorsAPI制御
$requestAPI制御

参照用の変数

下記の変数は、Pre-processingが動作する時、常にデフォルトでアサインされている参照用の変数です。
エンドポイントの情報や、渡されたリクエスト値を判定するために利用します。

変数名用途
$metaエンドポイントのメタ情報
$urlURLの構成要素
$bodyリクエスト ボディ

$meta

対象エンドポイントのメタ情報を参照するための変数です。

変数名説明
$metaarray連想配列

下記の要素で構成されています。

キー初期値説明
$meta.content_typestringContent-type
$meta.mimestringContent-type
$meta.mime.typestringMIME タイプ
$meta.mime.subtypestringMIME サブタイプ
$meta.output_formatstring"json"クエリ パラメータに指定された_output_format
$meta.langstring次の優先度に基づき決定:
[ブラウザの言語設定 > 主言語設定]
クエリ パラメータに指定された_lang
$meta.charsetstring"utf8"クエリ パラメータに指定された_charset
$meta.http_codestringnull
$meta.api_headerarrayAPI設定
$meta.post_jsonstringGET: null
POST: "{}"
テキスト形式のJSON body

$url

クライアントから指定されたURLの構成要素を参照するための変数です。

変数名説明
$urlarray連想配列

下記の要素で構成されています。
このうち、$url.queryについては、$smarty.getと同等の値を含みます。

キー説明
$url.pathstringエンドポイントのパス (クエリ パラメータを除く)
$url.queryarrayクエリ パラメータを格納した連想配列

例) 下記のエンドポイントに対してリクエストを送信した場合、   /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には下記値が設定されます。

$url
[
  "path" => "/rcms-api/1/preprocess-test"
  "query" => [
    "p1" => "VALUE1",
    "p2" => [
        0 => "VALUE2_0",
        1 => "VALUE2_1"
    ],
    "p3" => [
        "k1" => "VALUE3_1",
        "k2" => "VALUE3_2"
    ]
  ]
]

$body

クライアントから送信されたリクエスト ボディを参照するための変数です。
$smarty.postと同等の値を含みます。

変数名初期値説明
$bodyarrayリクエスト ボディ連想配列

API制御用の変数

下記の変数は、Pre-processingが動作した時点ではまだ宣言されていない変数です。
これらの値を初期化し、値を入れ込むことで、エンドポイントの挙動を制御します。

変数名用途
$errorsエラーの制御
$requestリクエスト値の制御

Pre-processingのオリジナル処理内では、これらの変数を用途以外の目的で宣言しないでください。APIエンドポイントが意図しない挙動をする可能性があります。

$errors

エンドポイントが出力するエラーを制御するための変数です。

入力値を判定し、結果のエラーメッセージを配列に格納することで、エンドポイントに独自のバリデーション処理を実装できます。

変数名初期値説明
$errorsarraynullテキスト配列

コード サンプル

{* 空配列で初期化 *}
{assign_array var='errors' values=''}
{* 入力値の判定 *}
{if $smarty.post.key_name === 'VALUE'}
  {* エラーメッセージを配列に追加 *}
  {assign var='errors.' value='エラーが発生しました。'}
{/if}

エラーレスポンスの形式

HTTP status codeerrors[].codeerrors[].message
422unprocessable_entityerrorsに格納したメッセージ
SampleResponse
// レスポンス サンプル
{
  "errors": [
    {
      "code": "unprocessable_entity",
      "message": "エラーが発生しました。"
    }
  ],
  "x-rcms-request-id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxx"
}

$errors配列に1以上の要素が含まれる場合、レスポンスの形式は下記のようになります。

errors
[
  {"code": "unprocessable_entity", "message": "errorsに格納したメッセージ"}
]

$errors配列が複数のエラー要素を含む場合、エラー個数分のオブジェクトが出力されます。

errors
[
  {"code": "unprocessable_entity", "message": "エラーメッセージ1"},
  {"code": "unprocessable_entity", "message": "エラーメッセージ2"},
  // ...
]

$request

メイン処理に渡すリクエスト値を制御するための変数です。

変数名初期値説明
$requestarraynull連想配列

この変数に次の形式で値を設定することで、メイン処理に渡すリクエスト値(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}

参考チュートリアル

Pre-processingを利用したチュートリアルページです。

困ったときは

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

  • APIのPre-processingとオリジナル処理が関連付いているか
  • 関連付いているオリジナル処理が正しいか
  • 変数名が正しいか
  • 変数に格納したデータの形式が正しいか
  • オリジナル処理の構文が正しいか