バージョン 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 アプリケーションの追加
REST アプリケーションの追加

ボタンをクリックした後、次のダイアログボックスで詳細を入力します。

REST アプリケーションの登録
REST アプリケーションの登録

アプリケーションのパス(必須)

REST 対応の CFC を含むフォルダーへのパス。

ホスト(オプション)

REST サービスのホスト名。例:localhost:8500。

サービスマッピング(オプション)

サービスを呼び出すときの REST アプリケーションの ID。

デフォルトアプリケーションとして設定する(オプション)

アプリケーションをデフォルトとして設定すると、サービスを呼び出すときにURL内のアプリケーションの名前を除外できます。デフォルトとして設定できるアプリケーションは各ホストで 1 つのみです。

登録」をクリックすると、REST アプリが登録され、次のように表示されます。

Artapp REST アプリケーション
Artapp REST アプリケーション

注意:

ColdFusion Administrator に登録されているすべての REST サービスは、ここからすぐに利用できます。アプリを登録し直す必要はありません。

同様に、REST Playground を使用して登録したアプリケーションは ColdFusion Administrator で使用できます。

例:GET

サンプルのArtapp アプリケーションでユーザーの詳細を取得するには、次に示すように URL 内で {id} の値を渡します。

リクエストの送信
/users/{id} へのリクエストの送信

送信」をクリックすると、次のレスポンスが返されます。

{

    "price": 13900,

    "id": 2,

    "name": "Michael"

}

例:POST

定義されているパラメーターによっては、次の図に示すように POST リクエストを発行できます。

POST リクエスト
POST リクエスト

ヘッダーとして渡すようにパラメーターが定義されている場合は、下の図に示すように、ヘッダーセクションにパラメーターを挿入します。

POST ヘッダーの詳細
POST ヘッダーの詳細

送信」をクリックするとデータベースにレコードが挿入されます。

REST パスの更新

ColdFusion Administrator の「データとサービス」にある「REST サービス」セクションに REST パスを追加または更新するためのオプションが追加されました。デフォルト値は 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   is patched object   
       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 など)が含まれている必要があります。

本作品は Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License によってライセンス許可を受けています。  Twitter™ および Facebook の投稿には、Creative Commons の規約内容は適用されません。

法律上の注意   |   プライバシーポリシー