REST サービスの作成と編集

InterSystems IRIS では、いくつかの方法で REST サービスを作成および変更できます。主な方法として、/api/mgmnt/ サービスの呼び出し、^%REST ルーチンの使用、%REST.API クラスの使用の 3 つがあります。REST サービスを作成するこれら 3 種類の方法では、サービス・クラスの生成に使用する REST サービスの OpenAPI 2.0 (Swagger とも呼ばれます) 記述を作成する必要があります。サードパーティによって定義された REST サービスを実装する場合、そのサードパーティによってこの OpenAPI 2.0 の記述が提供されることがあります。OpenAPI 2.0 の記述の形式の詳細は、OpenAPI 2.0 仕様Opens in a new tabを参照してください。

サービス・クラスを生成した後、REST サービスの詳しい構築手順を "実装クラスの変更" および "仕様クラスの変更" で確認します。

/Api/mgmnt/ サービスの使用

REST サービスを作成、更新、および削除する方法の 1 つでは /api/mgmnt/ サービスを呼び出します。

このサービスには、Web サービスのリストおよびドキュメント化に使用できるオプションも用意されています。

/api/mgmnt を使用した REST サービスの作成

/api/mgmnt/ を使用したサービス・クラスの生成

最初の手順では、REST サービス・クラスを以下のように生成します。

REST サービスの OpenAPI 2.0 の記述 (JSON 形式) を作成または入手します。
PostMan (https://www.getpostman.com/Opens in a new tab) などの REST テスト・ツールを入手します。
テスト・ツールで、HTTP 要求メッセージを以下のように作成します。
- HTTP アクションとして、POST を選択または指定します。
- URL として、以下の形式の URL を指定します。
  http://localhost:52773/api/mgmnt/v2/namespace/myapp
  localhost はサーバの名前です。52773 は、InterSystems IRIS が実行されている Web サーバ・ポートです。namespace は、REST サービスを作成するネームスペースです。myapp は、クラスを作成するパッケージの名前です。
- 要求の本文として、Web サービスの OpenAPI 2.0 の記述 (JSON 形式) を貼り付けます。
- 要求の本文のタイプを JSON (application/json) として指定します。
- IRISUsername パラメータと IRISPassword パラメータの値を指定します。IRISUsername については、%Developer ロールのメンバであり、指定されたネームスペースに対する読み取り/書き込みアクセス権を持っているユーザを指定します。
要求メッセージを送信します。
呼び出しが成功すると、InterSystems IRIS は、指定されたパッケージおよびネームスペースに disp クラス、impl クラス、および spec クラスを作成します。
テスト・ツールで、応答メッセージを確認します。要求が成功した場合、応答メッセージは以下の例のようになります。
```
{
    "msg": "New application myapp created"
}
```

基本の REST サービスを完成させるには、インターシステムズの Web アプリケーションを作成し、実装を定義します (“実装クラスの変更” の章を参照してください)。これらの手順を実行する順序はどちらが先でもかまいません。

Web アプリケーションの作成

この手順では、REST サービスへのアクセスを提供する Web アプリケーションを作成します。管理ポータルで、以下の手順を実行します。

[システム管理]→[セキュリティ]→[アプリケーション]→[Web アプリケーション] の順にクリックします。
[新規 Web アプリケーション作成] をクリックします。
以下の値を指定します。
- 名前 — Web アプリケーションの名前。InterSystems IRIS のこのインスタンス内で一意でなければなりません。最も一般的なのは、Web アプリケーションが実行されるネームスペースに基づいた名前 (/csp/namespace) です。
- ネームスペース — クラスを生成したネームスペースを選択します。
- アプリケーション有効 — このチェック・ボックスにチェックを付けます。
- 有効 — [REST] を選択します。
- ディスパッチ・クラス — ディスパッチ・クラスの完全修飾名を入力します。これは常に package.disp でなければなりません。package は、生成されたクラスが格納されているパッケージの名前です。
このページの他のオプションの詳細は、"アプリケーションの作成" を参照してください。
[保存] をクリックします。

/api/mgmnt を使用した REST サービスの更新

インターシステムズの API 管理ツールを使用すると、実装クラスに加えた編集内容を変更することなく、生成されたクラスを更新することができます。実装クラスは必要に応じて再生成されますが、編集内容は保持されます。

更新を正常に完了すると、InterSystems IRIS によって、指定したパッケージに disp クラスと spec クラスが再生成され、編集内容を保持した状態で impl クラスが更新されます。応答メッセージは以下の例のようになります。

{
    "msg": "Application myapp updated"
}

インターシステムズにおける実装クラスの更新の動作

impl クラスを以前に編集した場合、それらの編集内容は以下のように保持されます。

すべてのメソッドの実装は、そのまま残ります。
新しく追加したクラス・メンバは、そのまま残ります。

ただし、クラスおよび生成された各メソッドの説明 (/// コメント) は再生成されます。実装メソッドのシグニチャが変更された場合は (仕様が変更されたことによるものなど)、シグニチャが更新され、そのクラス・メソッドに以下のコメントが追加されます。

/// WARNING: This method's signature has changed.

/api/mgmnt を使用した REST サービスの削除

インターシステムズの API 管理ツールを使用すると、REST サービスを簡単に削除することもできます。そのためには、以下のように操作します。

REST テスト・ツールを使用して、HTTP 要求メッセージを以下のように作成します。
- HTTP アクションとして、DELETE を選択または指定します。
- URL として、以下の形式の URL を指定します。
  http://localhost:52773/api/mgmnt/v2/namespace/myapp
  localhost はサーバの名前です。52773 は、InterSystems IRIS が実行されている Web サーバ・ポートです。namespace は、REST サービスを作成するネームスペースです。myapp は、REST サービス・クラスが格納されているパッケージの名前です。
- IRISUsername パラメータと IRISPassword パラメータの値を指定します。IRISUsername については、%Developer ロールのメンバであり、指定されたネームスペースに対する読み取り/書き込みアクセス権を持っているユーザを指定します。
要求メッセージを送信します。
呼び出しが成功すると、InterSystems IRIS は、指定されたパッケージおよびネームスペース内の disp クラスと spec クラスを削除します。
ただし、impl クラスは削除しません。
テスト・ツールで、応答メッセージを確認します。要求が成功した場合、応答メッセージは以下の例のようになります。
```
{
    "msg": "Application myapp deleted"
}
```
実装クラスを手動で削除します。
安全のために、/api/mgmnt サービスでは、実装クラスが自動的に削除されることはありません。実装クラスには、非常に多くのカスタマイズが含まれている可能性があるからです。
この REST サービスについて以前に作成した Web アプリケーション (ある場合) を削除します。そのためには、以下のように操作します。
1. 管理ポータルで、[システム管理]→[セキュリティ]→[アプリケーション]→[Web アプリケーション] の順にクリックします。
2. Web アプリケーションが表示されている行で [削除] をクリックします。
3. [OK] をクリックして削除を確定します。

^%REST ルーチンの使用

^%REST ルーチンは、シンプルなコマンド行インタフェースです。いずれのプロンプトでも、以下の回答を入力できます。

前の質問に戻ります。

現在のオプションをすべてリストするメッセージが表示されます。

q または quit (大文字/小文字の区別なし)

ルーチンを終了します。

また、それぞれの質問では、その質問に対する既定の回答が括弧で囲んで表示されます。

^%REST を使用したサービスの作成

REST サービスを作成する際には、REST サービスの OpenAPI 2.0 仕様Opens in a new tabから開始し、それを使用して REST サービス・クラスを生成することをお勧めします。^%REST ルーチンを使用してこの作業を行うには、以下の手順を実行します。

REST サービスの OpenAPI 2.0 仕様Opens in a new tab (JSON 形式) を入手します。仕様をファイルとして保存するか、仕様にアクセスできる URL を書き留めます。
ターミナルで、REST サービスを定義するネームスペースに移動します。
以下のコマンドを入力して、^%REST ルーチンを開始します。
```
do ^%REST
```
最初のプロンプトで、REST サービスの名前を入力します。この名前は、生成されたクラスのパッケージ名として使用されます。有効なパッケージ名を使用してください。list、l、quit、または q という名前を使用する場合は (大文字/小文字のどのような組み合わせでも)、名前を二重引用符で囲みます。例えば、"list" のように入力します。
次のプロンプトで、Y (大文字/小文字の区別なし) と入力して、このサービスを作成することを確認します。
続いて、使用する OpenAPI 2.0 仕様の場所を入力するように求められます。完全パス名または URL を入力します。
次のプロンプトで、Y (大文字/小文字の区別なし) と入力して、この仕様を使用することを確認します。
このネームスペースの指定したパッケージ内に disp クラス、impl クラス、および spec クラスが作成されます。その後、以下のような出力が表示されます。
```
-----Creating REST application: myapp-----
CREATE myapp.spec
GENERATE myapp.disp
CREATE myapp.impl
REST application successfully created.
```
次に、Web アプリケーションも作成するかどうかを尋ねられます。この Web アプリケーションを使用して、REST サービスにアクセスします。
この時点では、以下の操作を行うことができます。
- Y (大文字/小文字の区別なし) と入力して、Web アプリケーションを今すぐ作成します。
- N (大文字/小文字の区別なし) と入力して、ルーチンを終了します。
  “Web アプリケーションの作成” に記載されている説明に従って、Web アプリケーションを別途作成することができます。
Y と入力した場合、Web アプリケーションの名前を入力するように求められます。
この名前は、InterSystems IRIS のこのインスタンス内で一意でなければなりません。既定では、Web アプリケーションが実行されるネームスペースに基づいた名前 (/csp/namespace) です。
Web アプリケーションの名前を入力するか、Enter キーを押して既定の名前をそのまま使用します。
その後、以下のような出力が表示されます。
```
-----Deploying REST application: myapp-----
Application myapp deployed to /csp/myapp
```
“実装クラスの変更” の章に記載されている説明に従って、実装を定義します。

^%REST を使用したサービスの削除

^%REST ルーチンを使用して REST サービスを削除するには、以下の手順を実行します。

ターミナルで、REST サービスがあるネームスペースに移動します。
以下のコマンドを入力して、^%REST ルーチンを開始します。
```
do ^%REST
```
最初のプロンプトで、REST サービスの名前を入力します。
REST サービスの名前が不明な場合は、L (大文字/小文字の区別なし) と入力します。すべての REST サービスがリストされ、REST サービスの名前の入力を求めるプロンプトが再度表示されます。
指定した名前の REST サービスが見つかると、以下のようなプロンプトが表示されます。
```
REST application found: petstore
Do you want to delete the application? Y or N (N):
```
Y (大文字/小文字の区別なし) と入力して、このサービスを削除することを確認します。
(オプション) 実装クラスを手動で削除します。
安全のために、このルーチンでは、実装クラスが自動的に削除されることはありません。実装クラスには、非常に多くのカスタマイズが含まれている可能性があるからです。

%REST.API クラスの使用

このセクションでは、%REST.API クラスを使用して REST サービスを作成、更新、および削除する方法について説明します。

%REST.API クラスを使用したサービスの作成または更新

REST サービスを作成する際には、REST サービスの OpenAPI 2.0 仕様Opens in a new tabから開始し、それを使用して REST サービス・クラスを生成することをお勧めします。%REST.APIOpens in a new tab クラスを使用してこの作業を行うには、以下の手順を実行します。

REST サービスの OpenAPI 2.0 仕様Opens in a new tab (JSON 形式) を入手し、仕様をファイルとして保存します。
このファイルは、UTF-8 でエンコードされている必要があります。
REST サービスを定義するネームスペースで、このファイルを使用して %DynamicObjectOpens in a new tab のインスタンスを作成します。
次に、%REST.APIOpens in a new tab クラスの CreateApplication() メソッドを呼び出します。このメソッドには、以下のシグニチャがあります。
```
classmethod CreateApplication(applicationName As %String, 
                              swagger As %DynamicObject = "", 
                              ByRef features, 
                              Output newApplication As %Boolean, 
                              Output internalError As %Boolean) 
                              as %Status
```
引数は以下のとおりです。
- applicationName は、クラスを生成するパッケージの名前です。
- swagger は、OpenAPI 2.0 仕様Opens in a new tabを表す %DynamicObjectOpens in a new tab のインスタンスです。
  この引数は、仕様の URL、仕様が格納されているファイルのパス名、または空の文字列として指定することもできます。
- 参照渡しにする必要がある features は、追加オプションを保持する多次元配列です。
  - features("addPing") が 1 で、swagger が空の文字列である場合、生成されたクラスには、テストを目的とした ping() メソッドが含まれます。
  - features("strict") が 1 (既定値) である場合、仕様内のすべてのプロパティがチェックされます。features("strict") が 0 である場合は、コードの生成に必要なプロパティのみがチェックされます。
- 出力として返される newApplication は、メソッドによって新しいアプリケーションが作成されたのか (true)、既存のアプリケーションが更新されたのかを示すブーリアン値です。
- 出力として返される internalError は、内部エラーが発生したかどうかを示すブーリアン値です。
メソッドによって新しいアプリケーションが生成された場合、InterSystems IRIS は、指定されたパッケージに disp クラス、impl クラス、および spec クラスを作成します。
メソッドによって既存のアプリケーションが更新された場合、InterSystems IRIS は、指定されたパッケージ内の disp クラスと spec クラスを再生成し、編集内容を保持して impl クラスを更新します。
OpenAPI 2.0 仕様が無効な場合、変更は行われません。
“REST サービスの作成と編集” の説明に従って、REST サービスにアクセスする Web アプリケーションを作成します。
“実装クラスの変更” の章に記載されている説明に従って、実装を定義します。

以下に最初の手順の例を示します。

 set file="c:/2downloads/petstore.json"
 set obj = ##class(%DynamicAbstractObject).%FromJSONFile(file)
 do ##class(%REST.API).CreateApplication("petstore",.obj,,.new,.error)
 //examine error and decide how to proceed...
 ...

%REST.API クラスを使用したサービスの削除

%REST.APIOpens in a new tab クラスを使用して REST サービスを削除するには、以下の手順を実行します。

REST サービスがあるネームスペースで、%REST.APIOpens in a new tab クラスの DeleteApplication() メソッドを呼び出します。このメソッドには、以下のシグニチャがあります。
```
classmethod DeleteApplication(applicationName As %String) as %Status
```
applicationName は、REST サービス・クラスが格納されているパッケージの名前です。
(オプション) 実装クラスを手動で削除します。
安全のために、このクラス・メソッドでは、実装クラスが自動的に削除されることはありません。実装クラスには、非常に多くのカスタマイズが含まれている可能性があるからです。
この REST サービスについて以前に作成した Web アプリケーション (ある場合) を削除します。そのためには、以下のように操作します。
1. 管理ポータルで、[システム管理]→[セキュリティ]→[アプリケーション]→[Web アプリケーション] の順にクリックします。
2. Web アプリケーションが表示されている行で [削除] をクリックします。
3. [OK] をクリックして削除を確定します。

実装クラスの変更

REST サービスの作成の概要