REST エンドポイントジェネレータ
REST エンドポイントジェネレータは、カスタムデータモデルエンティティに対して一連の生成済みエンドポイントを作成するためのツールです。エンドポイントの機能の大部分を定義する一連のファイルはこのツールによって生成されますが、追加のコンフィギュレーションが必要です。
- このトピックでは、REST エンドポイントジェネレータの概要を説明します。
- REST エンドポイントジェネレータの実行方法については、REST エンドポイントジェネレータの実行を参照してください。
- リソース定義ファイルのコンフィギュレーションの詳細については、リソース定義ファイルのコンフィギュレーションを参照してください。
- グルーおよび実装クラスのコンフィギュレーションの詳細については、生成されたエンドポイントのグルーおよび実装クラスのコンフィギュレーションを参照してください。
- 権限のコンフィギュレーションの詳細については、生成されたエンドポイントの権限のコンフィギュレーションを参照してください。
REST エンドポイントジェネレータの概要
一般に、保険会社は自社のビジネスモデルに固有の新しいエンティティを用いて、InsuranceSuite アプリケーションのデータモデルを拡張します。このデータモデルエンティティを「カスタムエンティティ」といいます。
これらのカスタムエンティティのいくつかを Cloud API に公開することにより、呼び出し元アプリケーションが以下の操作を実行できるようにすることができます。
- これらのエンティティに保存されているデータを取得する。
- これらのエンティティの新しいインスタンスを作成する。
- 必要に応じて、これらのエンティティを変更または削除する。
このため、Cloud API には REST エンドポイントジェネレータが含まれています。REST エンドポイントジェネレータは、カスタムエンティティ用の一連の CRUD エンドポイントを生成するツールです。
カスタム CRUD エンドポイントのアーキテクチャ
「CRUD エンドポイント」とは、特定のリソースタイプのコレクションの GET、およびそのリソースタイプの要素の GET、POST、PATCH、DELETE のためのエンドポイントを指す用語です。「CRUD」という用語は、Create（作成）、Read（読み取り）、Update（更新）、Delete（削除）の頭字語です。
ハイレベルアーキテクチャ
下図に、Cloud API 内の一連のカスタム CRUD エンドポイントのハイレベルアーキテクチャを示します。これらのエンドポイントは、CustomEntity_Ext という名前のカスタムエンティティのためのものです。
5 つの CRUD エンドポイントがありますが、そのすべてが同じタイプのリソースとやり取りするわけではありません。
- 最初の 2 つの CRUD エンドポイントは、GET（コレクション用）および POST のためのものです。これらのエンドポイントは、
customEntitiesExtという名前のコレクションリソースとやり取りします（リソース名に複数形が使用されていることに注目してください）。 - 最後の 3 つの CRUD エンドポイントは、GET（特定の要素用）、PATCH、DELETE のためのものです。これらのエンドポイントは、
customEntityExtという名前の要素リソースとやり取りします（リソース名に単数形が使用されていることに注目してください）。
- コレクションリソース（
customEntitiesExt）は、要素リソースを使用します。 - 要素リソース（
customEntityExt）は、データモデルエンティティにマップされます。 - データモデルエンティティ（
CustomEntity_Ext）は、データベースからのデータの取得およびデータベースへのデータの送信に使用されます。
アーキテクチャを定義するファイル
下図に示すように、CRUD エンドポイントアーキテクチャは一連のファイルで定義されます。
swagger ファイル：エンドポイント自体（パス、操作、関連リソース）を定義します。
スキーマファイル：要素リソースとコレクションリソースで使用されるスキーマを定義します。
マッピングファイル：データモデルエンティティから要素リソースへの情報のマッピングを定義します。この情報は、GET で使用されるだけでなく、POST や PATCH の応答でも使用されます。
アップデータファイル：要素リソースからデータモデルエンティティへの情報のマッピングを定義します。この情報は、POST と PATCH で使用されます。
eti ファイル：データモデルエンティティを定義します。
エンドポイントがアプリケーションとやり取りする方法のロジックを定義する一連のファイルもあります。
- apiconfig ファイルは「グルー」ファイルです。その目的の 1 つは、要素リソースおよびコレクションリソースを対応する 「Resource」Gosu ファイルにマップすることです。コレクションリソースの場合、このファイルはデフォルトの並べ替え順を指定することもできます。
- 実装の詳細を定義する 2 つの「実装」ファイルがあります。
- <collection>Resource.gs ファイル：コレクションの使用に必要な動作を定義する Gosu ファイルです。これには、データベースからコレクションを取得する方法などの動作が含まれます。
- <element>Resource.gs ファイルは、要素の使用に必要な動作を定義する Gosu ファイルです。これには、新しい要素を初期化する方法などの動作が含まれます。
- 権限を定義する 2 組の「認証」ファイルがあります。
- エンドポイントの呼び出し元のエンドポイントアクセスを定義する 1 つ以上の role.yaml ファイルがあります。
- エンドポイントの呼び出し元のリソースアクセスを定義する一連の access.yaml ファイルがあります。
アーキテクチャと REST エンドポイントジェネレータ
特定のカスタムエンティティに対して REST エンドポイントジェネレータを実行すると、カスタムエンティティに対して CRUD エンドポイントをサポートするのに必要なファイルが作成または変更されます。下図は、CustomEntity_Ext という名前のエンティティに対してツールを実行した場合に作成または変更されるファイルをまとめたものです。
以下の規則に注意してください。
- <API> は、エンドポイントが配置されている API の名前を表します。
- データモデルエンティティファイル（CustomEntity_Ext.eti）は、REST エンドポイントジェネレータによって作成も変更もされないため、オレンジ色で示してあります。このファイルは、ジェネレータの実行前に存在している必要があります。
- swagger ファイル（
<API>_ext-1.0.swagger.yaml）は、REST エンドポイントジェネレータによって変更されるものの、追加のコンフィギュレーションは不要であるため、茶色で示してあります。 - 青色で示した残りのファイルは、REST エンドポイントジェネレータによって作成または変更されます。これらのファイルは、追加のコンフィギュレーションが必要か、推奨されます。
REST エンドポイントジェネレータの制限事項
- ベースコンフィギュレーションデータモデルエンティティに既に関連エンドポイントがある場合、対応するリソースにフィールドを追加できます。詳細については、スキーマコンフィギュレーションの概要を参照してください。それ以外の場合は、それらのエンドポイントをコンフィギュレーションすることはできません。
- ベースコンフィギュレーションデータモデルエンティティに関連エンドポイントがない場合、REST エンドポイントジェネレータを使用してエンドポイントを作成することはできません。
カスタムリソースの生成時に、カスタムエンティティに接尾辞「_Ext」がない場合、REST エンドポイントジェネレータはファイル名およびファイルの内容に含まれるリソースの名前に接尾辞「Ext」または「ext」を追加します。
REST エンドポイントジェネレータは CRUD エンドポイントのみを生成します。ビジネスアクションの POST（/assign や /submit エンドポイントなど）の作成には使用できません。
カスタムエンティティ用の CRUD エンドポイントの生成手順
既存のカスタムエンティティ用の CRUD エンドポイントを生成するには、以下を実行する必要があります。
- REST エンドポイントジェネレータを実行する
- まず、一連のプロンプトが表示されます。プロンプトへの回答により、エンドポイントの定義が決まります。
- すべてのプロンプトに回答するとファイルが生成され、必要に応じて変更します。コンフィギュレーションが必要な部分を特定しやすくするために、コンフィギュレーションが必要なファイルには「
TODO RestEndpointGenerator」というコメントが追加されます。
- リソースを定義するファイルをコンフィギュレーションする。これには、以下が含まれます。
- swagger ファイル（任意）
- スキーマファイル
- マッピングファイル
- アップデータファイル
- グルーおよび実装 Gosu ファイルをコンフィギュレーションする。これには、以下が含まれます。
- apiconfig.yaml ファイル
- 要素リソースファイル
- コレクションリソースファイル
- 権限ファイルをコンフィギュレーションする。これには、以下が含まれます。
- 関連する role.yaml ファイル
- 関連する access.yaml ファイル
特殊なユースケース
連携グラフ
連携グラフは、Guidewire App Events で使用されるデータモデルグラフで、送信連携の一環として外部アプリケーションに送信される一連のビジネス情報を定義します。例えば、クレームグラフはクレームに関して送信される情報を定義します。連携グラフの詳細については、『App Events Guide（アプリイベントガイド）』を参照してください。
カスタムエンティティのエンドポイントを生成する際、リソースに親リソースがあり、その親リソースが連携グラフに属する場合、その連携グラフにカスタムエンティティのリソースを追加することもできます。詳細については、生成されたエンドポイントに関するその他の考慮事項を参照してください。
ClaimCenter Policy エンティティの子孫
ClaimCenter には、Policy エンティティとそのすべての子エンティティに関係する特別な機能があります。Policy エンティティ（またはそのいずれかの子）がカスタムエンティティの親である場合、REST エンドポイントジェネレータは特別な方法でエンドポイントの生成を実行します。その違いについては、生成されたエンドポイントに関するその他の考慮事項を参照してください。
サブタイプ付きエンティティ
サブタイプ付きカスタムエンティティ用のエンドポイントを生成できます。その際、「共有」エンドポイントか「独立」エンドポイントを選択できます。
- 「共有」エンドポイントは、情報の大半がスーパータイプレベルで宣言される場合に適しています。この場合、リソースにはスーパータイプフィールドと、各サブタイプからのサブタイプフィールドが含まれています。
- 「独立」エンドポイントは、各サブタイプレベルで十分な量の情報がある場合に適しています。この場合、リソースにはスーパータイプフィールドのみが含まれ、サブタイプフィールドは省略されます。サブタイプレベルの情報にアクセスするには、サブタイプごとに REST エンドポイントジェネレータを再実行する必要があります。
サブタイプ付きエンティティ用のエンドポイントの生成については、生成されたエンドポイントに関するその他の考慮事項を参照してください。
ルートリソース
カスタムエンティティのエンドポイントを生成する場合、カスタムエンティティは既存の親エンティティの子であることがほとんどであり、関連 REST リソースには、その親リソースを介してアクセスします。
例えば、CustomEntity_Ext という名前のカスタムエンティティがあるとします。これは、既存の Activity エンティティの子です。CustomEntity_Ext インスタンスに関する情報には、親 Activity を介してアクセスします。この場合、エンドポイントは以下の構造を使用します。
- GET
/common/v1/activities/{activityId}/custom-entity-ext - GET
/common/v1/activities/{activityId}/custom-entity-ext/{CustomEntityExtID}
それに対し、カスタムエンティティのエンドポイントをルートリソースとして生成することも可能です。この場合、関連 REST リソースには直接アクセスします。
例えば、CustomEntity_Ext という名前のカスタムエンティティがあるとします。エンドポイントは、関連リソースをルートリソースとして生成されます。この場合、エンドポイントは以下の構造を使用します。
- GET
/common/v1/custom-entity-ext - GET
/common/v1/custom-entity-ext/{CustomEntityExtID}
ルートリソースのエンドポイント生成については、生成されたエンドポイントに関するその他の考慮事項を参照してください。