コンフィギュレーションファイルの概要

REST のコンテキストでは、リソースは、REST 要求または REST 応答に含まれるデータのコレクションです。例えば、REST エンドポイントを介してアクティビティを作成する場合は次のようになります。

  • 要求には、作成するアクティビティに関する情報（アクティビティの件名や期日など）を指定するリソースが含まれています。
  • リソースには、作成されたアクティビティに関する情報（アクティビティの件名や期日、アクティビティの ID やステータスなどのアプリケーションによって作成された情報など）を指定するリソースが含まれています。

Cloud API では、すべてのリソースが最大 3 つのファイルで定義されます。このドキュメントでは、これらのファイルを総称してスキーマコンフィギュレーションファイルと呼びます。

  • スキーマファイル、要素リソースとコレクションリソースによって使用されるスキーマの構造を定義します。
  • マッピングファイル、情報がデータモデルエンティティから要素リソースにどのようにマップされるかを定義します。
    • この情報は、GET と、POST や PATCH の応答で使用されます。
  • アップデータファイル、情報が要素リソースからデータモデルエンティティにどのようにマップされるかを定義します。
    • この情報は、POST と PATCH で使用されます。

スキーマ機能に関連するファイルが他に 2 つあります。

  • swagger ファイル、エンドポイントそれ自体を定義します。各エンドポイントの定義には以下が含まれています。
    • エンドポイントパス（/common/v1/activities/{activityId} など）
    • パスに対して許可される処理（GET や PATCH など）
    • エンドポイントの resourceType（Activity など）と関連する子リソース。
  • apiconfig ファイル、リソースコレクションのデフォルトの並べ替え（もしあれば）を定義します。

スキーマコンフィギュレーションファイルのアーキテクチャ

下の図は、Activity データモデルエンティティのスキーマコンフィギュレーションファイルのアーキテクチャを示しています。


スキーマコンフィギュレーションファイルのアーキテクチャ
  • Activity.eti ファイルは、Activity データモデルエンティティを定義します。このファイルはデータモデルの一部であって、Cloud API の一部ではないことに注意してください。
  • スキーマファイルは、Cloud API で Activity データモデルオブジェクトとやり取りするために使用可能な次の 2 つのリソースを定義します。
    1. Activity リソース。単一のリソースに関する情報をキャプチャします。
    2. Activities リソース。リソースのコレクションに関する情報をキャプチャします。
  • マッピングファイルは、データが Activity データモデルエンティティから Activity リソースにどのようにマップされるかを定義します。
  • アップデータファイルは、データが Activity リソースから Activity データモデルエンティティにどのようにマップされるかを定義します。
  • swagger ファイルは、エンドポイントの CRUD 操作を定義します。エンドポイント（/common/v1/activities/{activityId} など）をそのルートリソース（Activity リソース）に関連付けます。
  • apiconfig ファイルは、Activities コレクションリソースのデフォルトの並べ替え順序を定義します。

すべてのスキーマファイルが Swagger 2 仕様に準拠しています。構文の詳細については、https://swagger.io/specification/v2/ を参照してください。

スキーマファイル、マッピングファイル、およびアップデータファイルは、JSON スキーマ構文を使用した JSON 形式です。JSON スキーマ構文の詳細については、http://json-schema.org/ を参照してください。

スキーマコンフィギュレーションファイルを変更する理由

カスタムエンティティ用のエンドポイントの生成

REST エンドポイントジェネレータは、カスタムデータモデルエンティティ用の CRUD エンドポイントを生成するツールです。また、REST エンドポイントジェネレータは、生成されたエンドポイントで使用されるリソースのスキーマ定義ファイルも作成します。ただし、これらのファイルは未完成です。開発者は、必ず、リソース定義ファイルで追加のコンフィギュレーションを実行する必要があります。

REST エンドポイントジェネレータの詳細については、REST エンドポイントジェネレータを参照してください。

ベースコンフィギュレーションリソースの拡張

Cloud API には、ベースコンフィギュレーション内の複数のデータモデルエンティティに対する CRUD 操作を実行するエンドポイントが含まれています。例えば、GET /common/v1/activities エンドポイントは、Activity データモデルエンティティのインスタンスを問い合わせます。保険会社は、カスタムフィールドを追加することによって、これらのモデルエンティティを拡張できます。また、これらのフィールドを REST エンドポイントに公開することもできます。さらに、カスタムデータモデルフィールドにマップするカスタムリソースプロパティを追加するようにスキーマ定義ファイルをコンフィギュレーションすることができます。

ベースコンフィギュレーションスキーマを拡張するには：

  1. 必要に応じて、基礎となるデータモデルエンティティを新しいフィールドで拡張します。
    1. 詳細については、『コンフィギュレーションガイド』を参照してください。
  2. 該当するスキーマ、マッピング、およびアップデータ拡張ファイルをコンフィギュレーションします。
    1. 詳細については、スカラーのコンフィギュレーション、複合データ型のコンフィギュレーション、外部キーのコンフィギュレーション、および1 対 1 のコンフィギュレーションを参照してください。
  3. 必要に応じて、追加のプロパティ動作を定義する属性を追加します。
    1. 詳細については、追加のスキーマ動作を参照してください。

Cloud API へのベースコンフィギュレーションファイルの公開

Cloud API で公開されるデータモデルエンティティの場合は、ベースコンフィギュレーションで、特定のエンティティ内のすべてのフィールドが Cloud API に公開されるわけではありません。これらのフィールドの 1 つまたは複数を Cloud API に公開しなければならない場合があります。

例えば、User データモデルエンティティは Cloud API に公開されます。VacationStatus フィールドも公開されます。しかし、ExperienceLevel フィールドは公開されません。保険会社は、ExperienceLevel フィールドを Cloud API に公開したい場合があります。

これを行うためのアプローチは、ベースコンフィギュレーションリソースを拡張するときと同じプロセスを辿ります。唯一の違いは、目的のフィールドがすでに存在しているため、データモデルを拡張する必要がないことです。

連携グラフ

Cloud API スキーマは、Guidewire App Events で使用される連携グラフを定義するために使用されます。連携グラフは、送信連携の一部として外部アプリケーションに送信される一連のビジネス情報を定義するデータモデルグラフです。例えば、クレームグラフは、クレームに関して送信される情報を定義します。保険会社は、特定の情報が連携グラフに含まれていることを保証するように Cloud API スキーマを拡張できます。連携グラフの詳細については、『App Events Guide』を参照してください。