仕様クラスの変更

概要

以下のテーブルは、仕様クラスを変更する理由をリストし、必要な変更内容を簡単にまとめたものです。

仕様クラスをコンパイルすると、コンパイラによって、同じパッケージにディスパッチ・クラスが必ず再生成され、実装クラスが更新されます (“インターシステムズにおける実装クラスの更新の動作” を参照してください)。

コンテンツ・タイプ、応答の文字セット、または入力ストリームの処理のオーバーライド

クラス・パラメータを仕様クラスに追加し、リコンパイルするだけで、REST サービスのいくつかの重要な要素をオーバーライドすることができます。

• 既定では、REST サービスは application/json のコンテンツ・タイプを想定します。これをオーバーライドするには、以下のパラメータを仕様クラスに追加します。

  Parameter CONTENTTYPE = "some-content-type";
  

  

  some-content-type は MIME コンテンツ・タイプです。

• 既定では、REST サービスの応答メッセージは UTF-8 形式です。これをオーバーライドするには、以下のパラメータを仕様クラスに追加します。

  Parameter CHARSET = "some-character-set";
  

  

  some-content-type-here は文字セットの名前です。

• 既定では、REST サービスは入力文字ストリームを Unicode に変換します。この処理を行わないようにするには、以下のパラメータを仕様クラスに追加します。

  Parameter CONVERTINPUTSTREAM = 0";
  

  

その後、リコンパイルします。これにより、これらの変更内容がディスパッチ・クラスにコピーされます。

サービス・メソッドの名前のオーバーライド

既定では、コンパイラは、操作の operationId を使用して、対応する REST 呼び出しによって呼び出されるメソッドの名前を決定します。別の名前を指定することもできます。そのためには、仕様クラスの OpenAPI XData ブロック内の操作に以下を追加します。

"x-ISC_ServiceMethod":"alternatename"

以下に例を示します。

    "/pets":{
      "get":{
        "description":"Returns all pets from the system that the user has access to",
        "operationId":"findPets",
        "x-ISC_ServiceMethod":"ReturnPets",
        "produces":[
          "application/json",
          "application/xml",
          "text/xml",
          "text/html"
        ],

その後、リコンパイルします。これにより、この新しいメソッドがディスパッチ・クラスと実装クラスに追加されます。必ず、実装クラスを編集し、この新しいメソッドの実装を提供してください。

REST サービスでの CORS のサポート

CORS (Cross-Origin Resource Sharing) を使用すると、別のドメインで実行されているスクリプトからサービスにアクセスすることができます。

通常、ブラウザは 1 つのドメインからスクリプトを実行している場合、同じドメインへの XMLHttpRequest の呼び出しを許可しますが、別のドメインへ呼び出される場合は許可しません。このブラウザ動作により、機密データを不正使用するおそれのある悪意のあるスクリプトの作成が制限されます。悪意のあるスクリプトにより、ユーザは与えられた許可を使用して別のドメインの情報にアクセスできますが、ユーザの知らない者が機密情報を他の用途に用いることもできます。こうしたセキュリティの問題を回避するため、通常ブラウザはこの種のクロスドメイン呼び出しを許可しません。

CORS (Cross-Origin Resource Sharing) を使用しない場合、REST サービスにアクセスするスクリプトを使用する Web ページは通常、REST サービスを提供するサーバと同じドメインにある必要があります。一部の環境では、スクリプトを使用する Web ページを REST サービス提供サーバとは異なるドメインに置くと便利です。CORS はこのような配置を可能にします。

以下ではブラウザが CORS で XMLHttpRequest を処理する方法を簡略化して説明します。

1. ドメイン DomOne にある Web ページのスクリプトにはドメイン DomTwo にある InterSystems IRIS REST サービスへの XMLHttpRequest が含まれます。XMLHttpRequest には CORS のカスタム・ヘッダがあります。

2. ユーザはこの Web ページを閲覧してスクリプトを実行します。Web ページを含むドメインとは異なるドメインへの XMLHttpRequest をユーザのブラウザは検出します。

3. ユーザのブラウザは InterSystems IRIS REST サービスへ特別な要求を送信します。これは XMLHttpRequest の HTTP 要求メソッドおよび元の Web ページのドメイン (この例では DomOne) を示します。

4. 要求が許可されると、応答には要求された情報が含まれます。許可されない場合、CORS が要求を許可しなかったことを示すヘッダのみで応答は構成されます。

CORS ヘッダの処理方法の定義

REST サービスが CORS ヘッダを受け入れるようにした場合、既定では、サービスはすべての CORS 要求を受け入れます。REST サービスが CORS 要求を検証し、処理を続行するかどうかを決定するようにする必要があります。例えば、信頼されたスクリプトのみを含むドメインを含む許可リストを提供することができます。そのためには、以下の作業を行う必要があります。

• %CSP.RESTOpens in a new tab のサブクラスを作成します。このクラスで、最初のサブセクションの説明に従って OnHandleCorsRequest() メソッドを実装します。

• 仕様クラスを変更してリコンパイルし、ディスパッチ・クラスを再生成します。

この結果、ディスパッチ・クラスは、%CSP.RESTOpens in a new tab ではなく、カスタム・クラスを継承するため、既定の CORS ヘッダの処理をオーバーライドする OnHandleCorsRequest() の定義を使用するようになります。

OnHandleCorsRequest() の定義

%CSP.RESTOpens in a new tab のサブクラスで、OnHandleCorsRequest() メソッドを定義します。このメソッドで CORS 要求を検証し、応答ヘッダを適宜設定する必要があります。

このメソッドを定義するには、CORS プロトコルの詳細に精通している必要があります (ここでは説明しません)。

また、要求を検証し、応答ヘッダを設定する方法を理解しておくことも必要です。そのためには、既定で使用されるメソッド、つまり %CSP.RESTOpens in a new tab の HandleDefaultCorsRequest() メソッドを確認すると役立ちます。このセクションでは、このメソッドが起源、資格情報、ヘッダ、および要求メソッドをどのように処理するかを説明し、バリエーションを提示します。この情報を使用して、独自の OnHandleCorsRequest() メソッドを記述することができます。

以下のコードは起源を取得し、それを使用して応答ヘッダを設定します。バリエーションの候補の 1 つは、許可リストに照らして起源をテストすることです。ドメインが許可されている場合、応答ヘッダを設定します。許可されていない場合は、応答ヘッダを空の文字列に設定します。

#; Get the origin
Set tOrigin=$Get(%request.CgiEnvs("HTTP_ORIGIN"))

#; Allow requested origin
Do ..SetResponseHeaderIfEmpty("Access-Control-Allow-Origin",tOrigin) 

以下の行では認証ヘッダが含まれるように指定します。

#; Set allow credentials to be true
Do ..SetResponseHeaderIfEmpty("Access-Control-Allow-Credentials","true")

以下の行では受信する要求からヘッダと要求メソッドを取得します。ヘッダと要求メソッドが許可されているかどうかをテストするコードを記述する必要があります。許可されている場合、それらを使用して応答ヘッダを設定します。許可されていない場合は、応答ヘッダを空の文字列に設定します。

#; Allow requested headers
Set tHeaders=$Get(%request.CgiEnvs("HTTP_ACCESS_CONTROL_REQUEST_HEADERS"))
Do ..SetResponseHeaderIfEmpty("Access-Control-Allow-Headers",tHeaders)

#; Allow requested method
Set tMethod=$Get(%request.CgiEnvs("HTTP_ACCESS_CONTROL_REQUEST_METHOD"))
Do ..SetResponseHeaderIfEmpty("Access-Control-Allow-Method",tMethod)

Important:

既定の CORS ヘッダの処理は、機密データを扱う REST サービスには適していません。

仕様クラスの変更

OnHandleCorsRequest() の実装を含む、%CSP.RESTOpens in a new tab のカスタム・サブクラスを定義したら、以下の手順を実行します。

1. 新しいプロパティとして x-ISC_DispatchParent が info オブジェクトに追加されるように、仕様クラスの OpenAPI XData ブロックを編集します。このプロパティの値は、カスタム・クラスの完全修飾名でなければなりません。

   例えば、OpenAPI XData ブロックが以下のようであるとします。

     "swagger":"2.0",
     "info":{
       "version":"1.0.0",
       "title":"Swagger Petstore",
       "description":"A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification",
       "termsOfService":"http://swagger.io/terms/",
       "contact":{
         "name":"Swagger API Team"
       },
   ...
   

   

   %CSP.RESTOpens in a new tab のカスタム・サブクラスの名前が test.MyDispatchClass であるとします。この場合、XData ブロックを以下のように変更します。

     "swagger":"2.0",
     "info":{
       "version":"1.0.0",
       "title":"Swagger Petstore",
       "description":"A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification",
       "termsOfService":"http://swagger.io/terms/",
       "x-ISC_DispatchParent":"test.MyDispatchClass",
       "contact":{
         "name":"Swagger API Team"
       },
   ...
   

   

2. 仕様クラスをコンパイルします。このアクションによって、ディスパッチ・クラスが再生成されます。このクラスは、カスタム・ディスパッチ・スーパークラスを拡張したものになります。そのため、独自に記述した OnHandleCorsRequest() メソッドを使用するようになります。

REST での Web セッションの使用

REST の目的の 1 つは、ステートレスにすることです。つまり、ある REST 呼び出しから次の呼び出しまでの間、サーバに情報を保存しないということです。複数の REST 呼び出しを通して 1 つの Web セッションを保持することは、ステートレス・パラダイムを崩すことになりますが、1 つの Web セッションを保持する理由が 2 つあります。

• 接続時間を最小限に抑える — REST 呼び出しごとに新しい Web セッションを作成する場合、REST 呼び出しによってサーバ上で新しいセッションを確立する必要があります。Web セッションを保持することで、REST 呼び出しの接続が高速化します。

• 複数の REST 呼び出し間でデータを保持する — 場合によっては、複数の REST 呼び出し間でデータを保持することが、ビジネス要件を効率的に満たすために必要になることがあります。

複数の REST 呼び出しにわたって 1 つの Web セッションを使用できるようにするには、仕様クラスで UseSession パラメータを 1 に設定します。以下に例を示します。

Parameter UseSession As Integer = 1;

その後、このクラスをリコンパイルします。

UseSession が 1 である場合、REST サービスの複数の呼び出しにわたって 1 つの Web セッションが保持されます。このパラメータが 0 (既定値) である場合は、REST サービスの呼び出しごとに新しい Web セッションが使用されます。