Skip to main content

This documentation is for an older version of this product. See the latest version of this content.Opens in a new tab

REST サービスの作成の概要

このページでは、REST の概要と InterSystems IRIS® における REST サービスの概要を紹介します。この REST インタフェースを UI ツール (Angular など) で使用すると、データベースや相互運用プロダクションにアクセスできます。また、これを使用して、外部システムから InterSystems IRIS® データ・プラットフォーム・アプリケーションにアクセスできるようにすることもできます。実際の操作を通じた REST サービスの説明は、"Developing REST InterfacesOpens in a new tab" を参照してください。

REST の概要

REST (“Representational State Transfer“ の略称) には、以下の属性があります。

  • REST とは、形式ではなく、アーキテクチャのスタイルです。REST は、多くの場合、メッセージの転送に HTTP を使用し、データの受け渡しに JSON を使用します。ただし、XML またはプレーン・テキストでデータを渡すこともできます。REST は、既存の Web 標準 (HTTP、URL、XML、JSON など) を利用します。

  • REST は、リソース指向です。一般に、リソースは URL で識別され、明示的に HTTP メソッド (GET、POST、PUT、および DELETE など) に基づいた操作を使用します。

  • 一般に、REST には小さいオーバーヘッドがあります。データの記述には XML を使用できますが、軽量のデータ・ラッパである JSON を使用する方が一般的です。JSON では、データをタグで識別しますが、そのタグは公式のスキーマ定義では指定されず、明示的なデータ型を持ちません。

インターシステムズの REST サービスの概要

InterSystems IRIS 2019.2 以降で REST インタフェースを定義するには、以下の 2 つの方法があります。

  • 仕様優先の定義 — 最初に OpenAPI 2.0 仕様を作成してから、API 管理ツールを使用して REST インタフェースのコードを生成します。

  • REST インタフェースの手動コーディング。

仕様優先の定義を使用すると、インターシステムズの REST サービスは形式的には以下のコンポーネントで構成されます。

  • 仕様クラス (%REST.SpecOpens in a new tab のサブクラス)。このクラスには、REST サービスの OpenAPI 2.0 仕様Opens in a new tabが含まれます。インターシステムズでは、仕様内で使用できるさまざまな拡張属性をサポートしています。

  • ディスパッチ・クラス (%CSP.RESTOpens in a new tab のサブクラス)。このクラスは、HTTP 要求を受け取り、実装クラスの適切なメソッドを呼び出します。

  • 実装クラス (%REST.ImplOpens in a new tab のサブクラス)。このクラスでは、REST 呼び出しを実装するメソッドを定義します。

    API 管理ツールによって、実装クラスのスタブ・バージョンが生成されます。その後、これを拡張して、必要なアプリケーション・ロジックを追加します (追加するロジックからこのクラスの外部のコードを呼び出すこともできます)。

    %REST.ImplOpens in a new tab クラスは、HTTP ヘッダの設定やエラーの報告などを行うために呼び出すことができるメソッドを提供します。

  • インターシステムズの Web アプリケーション。インターシステムズの Web ゲートウェイを介して REST サービスへのアクセスを提供します。Web アプリケーションは、REST アクセスを有効にし、特定のディスパッチ・クラスを使用するように構成します。また、REST サービスへのアクセスを制御します。

インターシステムズでは、これらのコンポーネントについて厳格な名前付け規約に従います。アプリケーション名 (appname) を指定すると、仕様クラス、ディスパッチ・クラス、および実装クラスの名前はそれぞれ、appname.specappname.disp、および appname.impl になります。既定では、Web アプリケーションの名前は /csp/appname ですが、別の名前を使用することもできます。

インターシステムズでは、仕様優先のパラダイムをサポートしています。仕様から初期コードを生成でき、仕様が変更された場合は (新しいエンド・ポイントの取得による変更など)、そのコードを再生成できます。この後のセクションで詳しく説明しますが、この時点では、ディスパッチ・クラスを編集してはいけないことを覚えておいてください。ただし、他のクラスは変更可能です。また、仕様クラスをリコンパイルすると、ディスパッチ・クラスが自動的に再生成され、実装クラスが更新されます (編集内容は保持されます)。

REST サービスの手動コーディング

2019.2 より前のリリースの InterSystems IRIS では、仕様優先のパラダイムがサポートされていませんでした。REST サービスは、形式的にはディスパッチ・クラスと Web アプリケーションのみで構成されます。このドキュメントでは、この方法で定義する REST サービスを手動コーディングの REST サービスと呼びます。新しい REST サービスによって定義された REST サービスには仕様クラスが含まれるのに対して、手動コーディングの REST サービスには含まれない点が異なります。このドキュメントの付録 “手動による REST サービスの作成” では、手動コーディングのパラダイムを使用して REST サービスを作成する方法について説明します。同様に、いくつかの API 管理ユーティリティを使用して、手動コーディングの REST サービスを操作することもできます。

インターシステムズの API 管理ツールの概要

REST サービスをより簡単に作成できるように、インターシステムズでは以下の API 管理ツールを提供しています。

  • /api/mgmnt という名前の REST サービス。このサービスを使用して、サーバ上の REST サービスを検出したり、それらの REST サービスの OpenAPI 2.0 仕様Opens in a new tabを生成したりすることができます。また、サーバで REST サービスの作成、更新、または削除を行うこともできます。

  • ^%REST ルーチン。このルーチンは、REST サービスのリスト、作成、および削除に使用できるシンプルなコマンド行インタフェースを提供します。

  • %REST.APIOpens in a new tab クラス。このクラスを使用して、サーバ上の REST サービスを検出したり、それらの REST サービスの OpenAPI 2.0 仕様Opens in a new tabを生成したりすることができます。また、サーバで REST サービスの作成、更新、または削除を行うこともできます。

この章で後述する説明に従って、これらのツールのロギングを設定できます。

有用なサードパーティ・ツールには、PostMan (https://www.getpostman.com/Opens in a new tab) や Swagger エディタ (https://swagger.io/tools/swagger-editor/download/Opens in a new tab) などの REST テスト・ツールがあります。

REST サービスの作成の概要

インターシステムズ製品で REST サービスを作成するための大まかな方法は、以下のとおりです。この手順に従うことをお勧めします。

  1. サービスの OpenAPI 2.0 仕様Opens in a new tabを入手 (または作成) します。

  2. API 管理ツールを使用して、REST サービス・クラスおよび関連する Web アプリケーションを生成します。“REST サービスの作成と編集” を参照してください。

  3. 適切なビジネス・ロジックがメソッドに含まれるように、実装クラスを変更します。“実装クラスの変更” の章を参照してください。

  4. オプションで仕様クラスを変更します。“仕様クラスの変更” の章を参照してください。例えば、CORS のサポートWeb セッションの使用が必要な場合にこの手順を実行します。

  5. セキュリティが必要な場合は、“REST サービスの保護” の章を参照してください。

  6. サービスの OpenAPI 2.0 仕様Opens in a new tabを使用して、“REST API の検出およびドキュメント化” の章に記載されている説明に従ってドキュメントを生成します。

手順 2 については、仕様クラスを手動で作成し (仕様をクラスに貼り付ける)、そのクラスをコンパイルするという別のオプションもあります。このプロセスによって、ディスパッチ・クラスとスタブ実装クラスが生成されます。つまり、/api/mgmnt サービスまたは ^%REST ルーチンを必ず使用しなければならないというわけではありません。このドキュメントでは、この手法についてはこれ以上説明しません。

REST サービス・クラスの詳細

ここでは、仕様クラス、ディスパッチ・クラス、および実装クラスについて詳しく説明します。

仕様クラス

仕様クラスは、REST サービスが従うべきコントラクトを定義するためのものです。このクラスは %REST.SpecOpens in a new tab を拡張し、REST サービスの OpenAPI 2.0 仕様Opens in a new tabが含まれる XData ブロックを含みます。以下は、部分的な例です。

Class petstore.spec Extends %REST.Spec [ ProcedureBlock ]
{

XData OpenAPI [ MimeType = application/json ]
{
{
  "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"
    },
    "license":{
      "name":"MIT"
    }
  },
...

このクラスを変更するには、XData ブロック内の仕様を置換または編集します。クラスのパラメータ、プロパティ、およびメソッドを必要に応じて追加することもできます。仕様クラスをコンパイルすると、コンパイラによって必ずディスパッチ・クラスが再生成され、実装クラスが更新されます (“インターシステムズにおける実装クラスの更新の動作” を参照してください)。

ディスパッチ・クラス

ディスパッチ・クラスは、REST サービスが呼び出されたときに直接呼び出されます。以下は、部分的な例です。

/// Dispatch class defined by RESTSpec in petstore.spec
Class petstore.disp Extends %CSP.REST [ GeneratedBy = petstore.spec.cls, ProcedureBlock ]
{

/// The class containing the RESTSpec which generated this class
Parameter SpecificationClass = "petstore.spec";

/// Default the Content-Type for this application.
Parameter CONTENTTYPE = "application/json";

/// By default convert the input stream to Unicode
Parameter CONVERTINPUTSTREAM = 1;

/// The default response charset is utf-8
Parameter CHARSET = "utf-8";

XData UrlMap [ XMLNamespace = "http://www.intersystems.com/urlmap" ]
{
<Routes>
  <Route Url="/pets" Method="get" Call="findPets" />
  <Route Url="/pets" Method="post" Call="addPet" />
  <Route Url="/pets/:id" Method="get" Call="findPetById" />
  <Route Url="/pets/:id" Method="delete" Call="deletePet" />
</Routes>
}

/// Override %CSP.REST AccessCheck method
ClassMethod AccessCheck(Output pAuthorized As %Boolean) As %Status
{
   ...
}

...

SpecificationClass パラメータは、関連する仕様クラスの名前を示します。UrlMap XData ブロック (URL マップ) では、この REST サービス内の呼び出しを定義します。クラスのこの部分を詳しく理解する必要はありません。

これらの項目の後、URL マップにリストされているメソッドの定義がクラスに含まれます。以下に一例を示します。

ClassMethod deletePet(pid As %String) As %Status
{
    Try {
        If '##class(%REST.Impl).%CheckAccepts("application/json") Do ##class(%REST.Impl).%ReportRESTError(..#HTTP406NOTACCEPTABLE,$$$ERROR($$$RESTBadAccepts)) Quit
        If ($number(pid,"I")="") Do ##class(%REST.Impl).%ReportRESTError(..#HTTP400BADREQUEST,$$$ERROR($$$RESTInvalid,"id",id)) Quit
        Set response=##class(petstore.impl).deletePet(pid)
        Do ##class(petstore.impl).%WriteResponse(response)
    } Catch (ex) {
        Do ##class(%REST.Impl).%ReportRESTError(..#HTTP500INTERNALSERVERERROR,ex.AsStatus())
    }
    Quit $$$OK
}

以下の点に注意します。

  • このメソッドは、実装クラス (この例では petstore.impl) 内で同じ名前でメソッドを呼び出します。これは、そのメソッドからの応答を取得し、%WriteResponse() を呼び出して応答を呼び出し元に書き込みます。%WriteResponse() メソッドは継承されたメソッドであり、すべての実装クラス (すべて %REST.ImplOpens in a new tab のサブクラス) に存在します。

  • このメソッドは他のチェックを行い、エラーの場合は %REST.ImplOpens in a new tab の他のメソッドを呼び出します。

Important:

ディスパッチ・クラスは生成されたクラスなので、絶対に編集しないでください。インターシステムズでは、ディスパッチ・クラスを編集せずに、その一部をオーバーライドするためのメカニズムを用意しています。

実装クラス

実装クラスは、REST サービスの実際の内部実装を格納するためのものです。このクラスは編集可能です (また、その必要があります)。最初は以下の例のような状態です。

/// A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification<br/>
/// Business logic class defined by RESTSpec in petstore.spec<br/>
Class petstore.impl Extends %REST.Impl [ ProcedureBlock ]
{

/// If ExposeServerExceptions is true, then details of internal errors will be exposed.
Parameter ExposeServerExceptions = 0;

/// Returns all pets from the system that the user has access to<br/>
/// The method arguments hold values for:<br/>
///     tags, tags to filter by<br/>
///     limit, maximum number of results to return<br/>
ClassMethod findPets(tags As %ListOfDataTypes(ELEMENTTYPE="%String"), limit As %Integer) As %Stream.Object
{
    //(Place business logic here)
    //Do ..%SetStatusCode(<HTTP_status_code>)
    //Do ..%SetHeader(<name>,<value>)
    //Quit (Place response here) ; response may be a string, stream or dynamic object
}

...

実装クラスの残りの部分には、これと同じような追加のスタブ・メソッドが含まれます。いずれの場合も、これらのスタブ・メソッドには、REST サービスの仕様で定義されたコントラクトに従ったシグニチャがあります。options メソッドについては、実装するスタブ・メソッドは生成されません。代わりに、クラス %CSP.RESTOpens in a new tab によって、options のすべての処理が自動的に実行されます。

API 管理機能のロギングの有効化

API 管理機能のロギングを有効にするには、ターミナルで以下を入力します。

 set $namespace="%SYS"
 kill ^ISCLOG
 set ^%ISCLOG=5
 set ^%ISCLOG("Category","apimgmnt")=5

これによって、API 管理エンドポイントへのあらゆる呼び出しに使用する ^ISCLOG グローバルにエントリが追加されます。

ログをファイルに書き込むには (読みやすくするため)、以下を入力します (引き続き、%SYS ネームスペース内です)。

 do ##class(%OAuth2.Utils).DisplayLog("filename")

filename は、作成するファイルの名前です。このディレクトリは既に存在している必要があります。ファイルが既に存在する場合は、そのファイルが上書きされます。

ログを停止するには、以下を入力します (引き続き、%SYS ネームスペース内です)。

 set ^%ISCLOG=0
 set ^%ISCLOG("Category","apimgmnt")=0

ログの表示

HTTP 要求のログが有効になると、ログ・エントリが ^ISCLOG グローバルに保存されます。このグローバルは %SYS ネームスペースにあります。

管理ポータルを使用してログを表示するには、[システムエクスプローラ][グローバル] に移動して、ISCLOG グローバル (%ISCLOG) ではないことに注意) を表示します。%SYS ネームスペースにいることを確認します。

FeedbackOpens in a new tab