Clever Geek Handbook

InterSystemsプラットフォームでのRESTful Web APIの構築-2

はじめに



4年前、私はHabréに関する最初の記事を書きました。この記事はInterSystemsプラットフォームでのRESTful Web APIの作成に当てられました。 それ以来、多くの時間が経過し、RESTful Web APIの作成作業を大幅に簡素化したいくつかの新しいリリースがリリースされました。 この記事ではこれらの変更について説明し、InterSystemsプラットフォームでRESTful Web APIを作成するためのヒントを提供します。







内容





RESTful Web APIアーキテクチャ



読者がRESTful Web APIとは何か、InterSystemsプラットフォーム（バージョン2014.1以降で利用可能）でのその実装の基本に精通していることを願っています。 これは、特に多くの記事/ウェビナー/トレーニングコースの主題であり、私の以前の記事です。 いずれにせよ、まず始めたいのは、RESTful Web APIを含むアプリケーションの一般的な高レベルのアーキテクチャです。 次のようになります。













この図は、決定の主なレベルを示しています。







データ



InterSystemsプラットフォーム上のストアドクラス。







ターミナルAPI



データインタラクションレイヤー。 このAPIを使用しない限り、データを変更しないでください。

このAPIのメソッドはデバイスに書き込みません。 端末APIは以下を返す場合があります。









Web API



着信要求を端末APIが理解できる形式に変換し、端末APIのメソッドを呼び出します。 端末APIの実行結果がクライアントに返されます。

Web APIはデータと直接対話しません。 RESTful Web APIではなくWeb APIという用語を使用しています。 Web APIは、たとえばHaSoですでに複数 回 記述されているInterSystemsプラットフォームでもサポートされているWebSocketプロトコルに基づいて、異なるアーキテクチャを使用して実装できます。







お客様



通常、JavaScript（ただし、必ずしもそうではない）アプリケーションはエンドユーザーが利用できます。 このレベルには、データベースとの直接接続がなく、メインのビジネスロジックがロードされ、アプリケーションの状態が保存されている必要があります。 通常、最も単純なビジネスロジックのみがこのレベルになります。承認インターフェイス、入力された値の有効性とフォーマットコンプライアンスのチェック、クライアントに既にアップロードされたデータ（並べ替え、グループ化、カウント）による簡単な操作。







この分離により、アプリケーションの構成可能性が向上し、エラーのデバッグ、検索、修正が容易になります。 本質的に、これはアプリケーションを構築するための3層アーキテクチャです。







ブローカー



ブローカーは、RESTful Web APIのロジックを含むクラスです。 それらは：









パスの例： 







 <Route Url="/path/:param1/:param2" Method="GET" Call="Package.Class:ClassMethod" />


ClassMethod



は任意のクラスメソッドです。







ブローカーの分離



「物理」分離



RESTful Web APIには多くの方法（メソッド）があるため、1つのブローカーはすぐにメソッドでオーバーロードされます。 これを防ぐには、ブローカーを次のようにいくつかのクラスに分割します。

ブローカーの分離







どこで：









論理パーティションとバージョニング



通常、ブローカーにはパスが含まれています—呼び出されるURIとメソッドのマッピングですが、ブローカーはパスに加えて、相互に要求を「渡す」ことができます。 次のようになります。 







 <Map Prefix="/form" Forward="Destination.Broker"/>


これにより、ブローカーを関連付けられたサブジェクト領域に分割し、APIのバージョン管理を提供できます。







ブローカーの論理的な分離







ブローカーオプション



以下は、RESTful Web APIのブローカーに設定することが推奨されるパラメーターです。 







 Parameter CONTENTTYPE = {..#CONTENTTYPEJSON}; Parameter CHARSET = "UTF-8"; Parameter UseSession As BOOLEAN = 1;


責任は次のとおりです。









すべてのブローカーは1つの抽象ブローカーから継承するため、これらのパラメーターを抽象ブローカーで1回指定するだけで十分です（最初のスーパークラスのパラメーターのみが継承されます）。







コードの一般化



RESTful Web APIを記述するときによく発生する問題の1つは、ブローカーからブローカーへのコードのコピーアンドペーストです。これにより、大量のパスとコード行が作成されます。 これを回避するには、メソッドジェネレーターを記述するために必要なすべてのメタ情報を含む％Dictionaryパッケージと組み合わせてコード生成を使用することをお勧めします 。 コード生成の積極的な使用例は、RESTFormsライブラリです。 さらに、コード生成を使用すると、RESTful Web APIの均一性を高めることができます。







CORS



別のドメインのリソースへのアクセスをWebページに提供できる最新のブラウザーのテクノロジー 。 CORSを使用してRESTful Web APIへのアクセスを有効にするには、ブローカーに次のパラメーターを追加します。 







 Parameter HandleCorsRequest = 1;


これにより、他のドメインからのアクセスが提供されます。 これは安全ではないため、 OnHandleCorsRequest



メソッドの署名もオーバーライドする必要があります。 







 ClassMethod OnHandleCorsRequest(pUrl As %String) As %Status {}


このメソッドは、リクエストの発信元を確認する必要があります。たとえば、Webアプリケーションのホスト名と一致する必要があります。 Originを取得するには、次の方法を使用できます。 







 ClassMethod GetOrigins() As %String { set url = %request.GetCgiEnv("HTTP_REFERER") return $p(url,"/",1,3) // get http(s)://origin.com:port }


認証



1人のユーザーが1つのライセンスを消費して1つのセッション内で作業するには、次の条件が満たされるようにシステム管理ポータルでRESTおよびCSPアプリケーションを構成する必要があります。







  1. すべてのブローカーで、 Parameter UseSession = 1;



    。
  2. すべてのWebアプリケーションは、認証のみで使用できます。
  3. すべてのWebアプリケーションにはセッションタイムアウト（900、3600）があります。
  4. すべてのアプリケーションには、同じGroupById



    値がGroupById



    ます。
  5. すべてのアプリケーションは同じCookie Path



    値を持ちます。


デバッグおよびテストツール



デバッグには、次のような外部ツールを使用できます。









curlやwgetなどのコマンドラインツールを使用しないことを強くお勧めします。







外部および内部デバッグツールについては、 InterSystems Developer Communityの一連の記事（ パート1-外部ツール 、 パート2-内部ツール ）で詳しく説明されています。







例



以下に、RESTful Web APIの例をいくつか示します。







MDX2JSONとDeepSeeWebクライアント



MDX2JSON -RESTful Web APIは、特に、DeepSeeのキューブ、ピボット、ダッシュボード、およびその他の多くの要素に関する情報を提供します。MDXリクエストの実行結果により、最新のWebまたはモバイルアプリケーションの分析ソリューションのユーザーインターフェイスをDeepSeeに埋め込むことができます。 バージョン2014.1以降で動作します。

DeepSeeWebは、DeepSeeユーザーポータルの代替実装を提供するAngularJSアプリケーションです。 簡単にカスタマイズできます。 MDX2JSONをバックエンドとして使用します。 以下は、DeepSeeWebでレンダリングされたダッシュボードの例です。







ディープシーウェブ







DeepSeeに関する詳細な記事。







EnsembleWorkflowおよびEnsembleWorkflowUIクライアント



インターシステムズの統合プラットフォームには、自動化されたビジネスプロセスに参加できるEnsembleワークフローサブシステムがあります。 Ensemble Workflow RESTful Web APIおよびEnsembleWorkflowUIクライアント。 RESTful Web APIは、ユーザータスクへのアクセスを提供します。 バージョン2014.1以降で動作します。 これが視覚化の外観です。







EnsembleWorkflowUI







EnsembleWorkflowUI







RESTForms



RESTFormsは、最新のWebアプリケーション向けのInterSystems 2016.1+プラットフォーム上の汎用RESTful Web APIデータバックエンドです。







RESTFormsで使用できるパスの一部を次に示します。







URL 説明
情報 クラス一覧
情報/すべて すべてのクラスのメタ情報
info /：クラス 1つのクラスのメタ情報
オブジェクト/：クラス/：id オブジェクトを取得
オブジェクト/：クラス/：id /：プロパティ オブジェクトのプロパティを取得
オブジェクト/：クラス オブジェクトを作成
オブジェクト/：クラス/：id 動的オブジェクトからオブジェクトを更新する
オブジェクト/：クラス クラスオブジェクトからオブジェクトを更新
オブジェクト/：クラス/：id アイテムを削除
オブジェクト/：クラス/：クエリ SQLクエリを実行する


このプロジェクトでは、コードの一般化が積極的に使用されています（コード生成と%Dictionary



パッケージの使用）。







AngularおよびReactクライアントが利用可能です。次のようになります。







クラスリスト







ジョンソン



JavaScript Object Notationは、RESTful Web APIとともに使用されるテキストベースのデータ交換形式です。 InterSystemsプラットフォームでのJSONサポートはバージョン2009.2から登場しましたが、バージョン2016.2で大幅に改善されました。 ドキュメントで JSONの使用について詳しく読んでください。







結論





参照資料





More articles:


All Articles