こんにちは。今回はAlfrescoのREST APIについて、エラー表示のカスタマイズ方法をご紹介します。

概要

Web Scriptsを用いて作成されたAlfrescoのREST APIは、以下の3つのファイルにより構成されます(詳しくは過去の記事カスタムREST APIの作成方法についてをご参照ください)

• WebScript定義ファイル
• ロジック記述ファイル
• テンプレートファイル

ロジック記述ファイルにエラー時用の処理を記述することで、エラー時に通常のテンプレートファイルではなくエラー表示用テンプレートファイルが用いられるようになります。 エラー表示用テンプレートファイルは通常のテンプレートファイルと同じくftl形式で記述することができ、ファイル名や保存階層により、各REST APIやグループ別にどのエラー表示用テンプレートファイルが使用されるかを定めることができます。

ロジック記述ファイル

ロジック記述ファイルではstatusというHTTPレスポンスの情報を管理するためのルートオブジェクトが用意されており、status.redirectをtrueに設定することでエラー時用のテンプレートファイルが使用されるようになります。また、 status.codeで、HTTPレスポンスコードを設定でき、status.messageでテキストメッセージを設定できます。これらの内容は、エラー表示用テンプレートファイルで${status.code}や${status.message}と記載することで使用できます。
なお、ロジック記述ファイルの処理が例外終了した場合は、以下の内容が設定された状態でエラー表示用テンプレートファイルが使用されます。

• status.code: 500
• status.message: <エラーの通し番号> <例外に対応したエラーメッセージ>

エラー表示用テンプレートファイル

エラー表示用テンプレートファイルは以下の優先度順で探索され、最初に見つかったものが使用されます。

1. 定義ファイルと同じパッケージ上で、特定のステータスコード (ファイル名: <web script id>.<http method>.<format>.<status code>.ftl)
2. 定義ファイルと同じパッケージ上で、任意のステータスコード (ファイル名: <web script id>.<http method>.<format>.status.ftl)
3. 定義ファイルと同じまたは上位のパッケージ上で、任意のステータスコード（ファイル名: <format>.status.ftl)
   • 自パッケージ階層からルートパッケージまで順に探索されます
4. ルートパッケージ上で、特定のステータスコードに対するHTML形式でのレスポンス(ファイル名: <status code>.ftl)
5. ルートパッケージ上で、任意のステータスコードに対するHTML形式でのレスポンス(ファイル名: status.ftl)

このように階層が近い順に見ていくため、基本的にはエラー画面を共通化した上で特定のAPIのみエラー画面を変更するなど、用途に応じたカスタマイズを行うことができます。 なお、条件を満たすエラー表示用テンプレートファイルを自作していない場合は、レスポンスフォーマットに応じたAlfrescoのデフォルトエラー画面が表示されます。

デフォルトで用意されているWeb Scriptsのエラー表示上書き

デフォルトで用意されているWeb Scriptsについても同じ優先度順でエラー表示用テンプレートファイルが探索され、自作ファイルでエラー表示内容を上書きすることができます。 以下に、ユーザ取得API(/alfresco/s/api/people)の500エラーを例として手順を説明します。

1. Web Scripts一覧(http[s]//<host>:<port>/<contextPath>/<servicePath>/index)にアクセスして対象のAPIを探します。 なお、contextPathとservicePathはデフォルトでは以下のように定められています。
   • contextPath
     • ACS: alfresco
     • Share: share
   • servicePath
     • ACS: service(短縮形のsも可)
     • Share: page
   
   
2. 対象のIDと同じ構成のディレクトリ(org/alfresco/repository/person/を以下のディレクトリ内に作成します
   • ACSの場合: {artifactId}-platform/src/main/resources/alfresco/extension/templates/webscripts/
   • Shareの場合: {artifactId}-share/src/main/alfresco/web-extension/site-webscripts/
3. 作成したディレクトリ上にエラー表示用テンプレートファイルpeople.get.json.500.ftlを作成します
   • 例

     {
         "code": ${status.code},
         "mesage": ${status.message},
         "comment": "customize test"
     }

4. サーバを再起動します

本例のAPIでは、http://localhost:8080/alfresco/s/api/people?skipCount=notIntegerのリクエストを実行することで500エラーを発生させることができるため、作成したエラー表示ファイルの内容がレスポンスとして返却されることを確認できます。

以上、エラー表示のカスタマイズ方法のご紹介でした。