最終更新日 :
2025年10月14日
説明
onRestRequest 関数は、RESTful web サービスを公開している ColdFusion アプリケーションへの HTTP REST 呼び出しを傍受する Application.cfc イベントハンドラーです。このメソッドは、REST リクエストが対象の CFC メソッドに到達する前に横断的関心事（認証、ログ、レート制限、応答の動的な変更など）を一元的に処理するための場所となります。
一般的な使用例：
- 認証と承認：無効または未承認のリクエストをブロックします。
- リクエストログ：すべての API 呼び出しの監査証跡を記録します。
- API レート制限：クライアントごとにリクエストを制限することで、API の乱用を防止します。
- カスタムエラー応答またはメンテナンスモード：システムダウンタイム中に統一された応答を返します。
- CORS またはヘッダーインジェクション：適切な HTTP ヘッダーで動的に応答します。
シンタックス
function onRestRequest(restRequest) {
// カスタムロジックをここに記述
}
パラメーター
- restRequest：（構造体）受信した REST 呼び出しに関する情報（CFC、メソッド、引数など）。
構造体の例
restRequest = {
cfcname : "myapi.user",
method : "getUser",
args : { id="123" },
httpMethod: "GET",
headers : { Authorization="Bearer xxxxxx", ...}
};
使用方法
- Application.cfc で定義されている場合は、関連する CFC メソッドが実行される前に、REST API リクエストを受信するたびに呼び出されます。
- リクエストの一元的な傍受を可能にし、必要に応じてその流れや出力を変更できます。
- リクエストをブロックしたり、通常の処理をオーバーライドしたりするには、restSetResponse() を呼び出し、それ以降のアクションを省略します。
例
基本的なログ記録
component {
function onRestRequest(restRequest) {
writeLog(text="REST call: #serializeJSON(restRequest)#", file="rest-access.log");
}
}
API キー認証
component {
function onRestRequest(restRequest) {
var headers = getHttpRequestData().headers;
if (!structKeyExists(headers, "x-api-key") || headers["x-api-key"] != application.expectedApiKey) {
restSetResponse({status=401, content="Unauthorized"});
return false;
}
}
}
レート制限
component {
function onRestRequest(restRequest) {
var ip = cgi.remote_addr;
if (application.requestTracker[ip] > 100) {
restSetResponse({status=429, content="Too Many Requests"});
return false;
}
// リクエスト数を増加、必要に応じてリセット
}
}
CORS 処理
component {
function onRestRequest(restRequest) {
var origin = getHttpRequestData().headers["origin"];
// trusted.com からのみ許可する
if (origin == "https://trusted.com") {
restSetResponse({status=200, headers={"Access-Control-Allow-Origin"=origin}});
} else {
restSetResponse({status=403, content="CORS error"});
return false;
}
}
}
