アプリケーションのパス（必須）
最終更新日 :
2022年1月4日
バージョン 2016 以前の ColdFusion では、REST サービスの開発後、ColdFusion Administrator にログインして REST アプリケーションを登録する必要がありました。また、アプリケーションに変更を加えるたびに Administrator で REST アプリケーションの再登録と更新を実行する必要がありました。さらに、CFC に関連するエラーのレポートとロギングに問題がありました。
ColdFusion 2018 リリースでは、次の機能がサポートされています。
- CF Administrator での「開発者プロファイルの有効化」の切り替え
- 登録済み API をテストするための RESTPlay アプリケーション
- REST サービスの自動更新（ 信頼できる キャッシュがオフの場合）
- 言語の変更（引数がコンポーネントの場合、ライフサイクルメソッド）
- 簡単なエラートラッキングとデバッグ
- PATCH 動詞のサポート
- カスタム REST パス
- （URL へのアクセスによる）REST API の自動登録
REST Playground アプリケーション
ColdFusion には、REST Playground というアプリケーションが付属します。このアプリケーションは webroot/ restplay にあり、ブラウザーで起動することができます。このアプリケーションは ColdFusion REST サービスをテストするためのクライアントです。
REST Playground アプリを使用するには、ColdFusion Administrator のデバッグとロギング／開発者プロファイルで「開発者プロファイルの有効化」オプションを有効にします。
ブラウザーのアドレスバーに「<hostname>:<port>/restplay」と入力します。REST Playground では、ColdFusion Administrator を使用しなくても REST サービスの追加や管理を行えます。
注意：
REST Playground アプリケーションは本番環境での使用を想定していないので、（Web サーバー経由ではなく）内部サーバー経由でのみアクセスできます。
REST Playground は Swagger ドキュメントからリソースを取得し、それらのリソースを一覧表示します。これらは、CFC メソッドが変更されたり、サービスが起動されたりすると更新されます。
サーバー実行時エラーが発生すると、ステータスコード 500 がクライアントに送信されます。
コンパイル時エラーが発生した場合は、サービスへのアクセスを試みたり、アプリケーションを更新したり（アプリケーションをクリックしたり）すると、それらのエラーが表示されます。
サーバーで開発者プロファイルが無効になっている場合に REST Playground がサービスへのアクセスを試みると、レスポンスステータスコード 401 が送信されます。
REST Playground でのアプリケーションの追加
REST アプリケーションを作成した後、REST Playground インターフェイスを使用してそのアプリケーションを追加します。REST Playground（ocalhost:8500/restplay）を起動し、下の図に示す「+」ボタンをクリックします。
ボタンをクリックした後、次のダイアログボックスで詳細を入力します。
|
|
REST 対応の CFC を含むフォルダーへのパス。 |
|
ホスト（オプション） |
REST サービスのホスト名。例：localhost:8500。 |
|
サービスマッピング（オプション） |
サービスを呼び出すときの REST アプリケーションの ID。 |
|
デフォルトアプリケーションとして設定する（オプション） |
アプリケーションをデフォルトとして設定すると、サービスを呼び出すときに URL 内のアプリケーションの名前を除外できます。デフォルトとして設定できるアプリケーションは各ホストで 1 つのみです。 |
「登録」をクリックすると、REST アプリが登録され、次のように表示されます。
注意：
ColdFusion Administrator に登録されているすべての REST サービスは、ここからすぐに利用できます。アプリを登録し直す必要はありません。
同様に、REST Playground を使用して登録したアプリケーションは ColdFusion Administrator で使用できます。
例：GET
サンプルの Artapp アプリケーションでユーザーの詳細を取得するには、次に示すように URL 内で {id} の値を渡します。
「送信」をクリックすると、次のレスポンスが返されます。
{
"price": 13900,
"id": 2,
"name": "Michael"
}
例：POST
定義されているパラメーターによっては、次の図に示すように POST リクエストを発行できます。
ヘッダーとして渡すようにパラメーターが定義されている場合は、下の図に示すように、ヘッダーセクションにパラメーターを挿入します。
「送信」をクリックするとデータベースにレコードが挿入されます。
REST パスの更新
ColdFusion Administrator の「データとサービス」にある「REST サービス」セクションに REST パスを追加または更新するためのオプションが追加されました。デフォルト値は rest です。
開発者プロファイルの有効化
REST Playground を使用するために、ColdFusion のインストール時に「開発者プロファイル」オプションを有効にすることができます。または、インストール後に、デバッグとロギング／開発者プロファイルの「開発者プロファイルの有効化」設定を有効にすることもできます。
このオプションが ColdFusion（2018 リリース）に導入されたのは、明白なセキュリティ上の理由から、REST Playground アプリは本番プロファイルやその他のプロファイルではなく、開発者プロファイルのみで機能するようにしなければならないからです。
注意：
本番環境の REST サービスでは、開発者プロファイルを無効にすることをお勧めします。
REST CFC の自動更新
すべての CFM および CFC の動作と同様に、REST CFC に加えられた変更も即座に REST リクエストに反映されます。
CFC が再読み込みされるかキャッシュから読み込まれるかは、サーバーの設定で「信頼できるキャッシュ」（サーバーの設定／キャッシュ機能）が有効になっているかどうかに依存します。これは REST CFC にも当てはまります。
注意：
「開発者プロファイル」オプションを有効にすると、「信頼できるキャッシュ」オプションは無効になります。
開発者プロファイルオプションが無効になっているときでも、CFC の変更時に REST サービスを更新する場合は「信頼できるキャッシュ」を無効にできます。
言語の変更
引数がコンポーネントである場合の REST 関数のサポート
引数がコンポーネントである場合は、REST リクエスト本文で対応する JSON オブジェクトを送信する必要があります。
student.cfc
component hint="This is a student cfc"
{
property name="name" type="string" displayname="name" hint="name of student";
property name="age" type="numeric" displayname="age" hint="age of student";
}
restCompTest.cfc
component restpath="student"{
remote any function addStudentPost(student st) httpmethod="POST" restpath="addStudent"
{
studentcomp.name = st.name;
studentcomp.age = st.age;
return studentcomp;
}
}
REST 関数
REST 関数内の access="remote" の記述は省略できます。この動作はすべての REST 対応関数で元から想定されています。
onRESTRequest のサポート
CFC を呼び出したときに呼び出される OnCFCRequest と同様に、REST URL を呼び出したときに呼び出される onRESTRequest が導入されました。メソッドと引数は CFC に対応する URL から導出され、関数に渡されます。
<cffunction name="onRESTRequest" returntype="any" output="true">
<cfargument type="string" name="cfcname" required=true>
<cfargument type="string" name="method" required=true>
<cfargument type="struct" name="args" required=true>
<cflog text="onRESTRequest() Before">
<cfinvoke component = "#cfcname#" method = "#method#" argumentCollection = "#args#" returnVariable = "resultval">
<cflog text="onRESTRequest() After">
<cfreturn "#resultval#">
</cffunction>
restSetResponse の動作の変更
以前のバージョンの ColdFusion では、戻り値の型が void でない場合、restSetResponse(response) で設定されたレスポンスが無視されていました。
このバージョンでは、restSetResponse(response) で設定されたレスポンスが常に考慮されます。
同じ関数を通常の関数（非 REST）として使用する場合、return 文に設定されたレスポンスが送信されます。REST 呼び出しの場合は、return 文を使用して返されるレスポンスが無視されます。
簡単なデバッグとロギング
すべての cfm および cfc エラーメッセージと同様に、エラーが存在する場合は完全なスタックトレースを確認できます。また、エラーが存在する行の番号も表示されます。
コンパイル時と実行時のエラーは、エラーの完全なスタックトレースを含む html レスポンスとして表示されます。
PATCH 動詞のサポート
PATCH をサポートするには、PATCH リソースと同じリソースパスを持つ GET リソースが存在している必要があります。これは PATCH の適用対象となるオブジェクトを取得するために必要となります。GET リソースは PATCH の適用対象となるオブジェクトを返す必要があり、PATCH リソースは値をパッチします。
これらの動作は結合され、結果は PATCH メソッドに引数として渡されます。これにより、パッチされたオブジェクトで関数に何を書き込むかを制御できるようになります。
PATCH の例
component restpath="users" rest="true"
{
import student;
student = createobject("component","student");
student.name = "Joe";
student.age = 22;
remote any function patchuser(struct x) httpmethod="PATCH" restpath="patchuser"
{
// x はパッチされたオブジェクト
return x;
}
remote any function patchuserget() httpmethod="GET" restpath="patchuser"
{
return student;
}
}
送信されるパッチの形式は次のようになります。
[
{
"op" : "replace",
"path" : "/age",
"value" : "40"
}
]
REST アプリケーションの自動登録
REST アプリケーション を自動登録するには、ブラウザーで webroot のパスを指定してアプリケーションにアクセスします。
フォルダー内に REST 対応 cfc （Application.cfc）と何らかの cfm ページ（index.cfm など）が存在している必要があります。（ブラウザーから） cfm ページにアクセスすると、そのフォルダーおよびサブフォルダー内にあるすべての REST サービスが登録されます。
Application.cfc には this.name と 1 つ以上の this.restSettings.* 変数（this.restSettings.restEnabled=true など）が含まれている必要があります。
