API 役割ファイル

API 役割は YAML ファイル（名前は RoleName.role.yaml）で定義されています。次に例を示します。

Insured.role.yaml
ServiceRequestSpecialist.role.yaml
Adjuster.role.yaml

API 役割ファイルの場所

API 役割は、Studio 内の Integration > roles ディレクトリで宣言されます。システム API は、役割ファイルを確認するときにこのディレクトリのみを検索します（roles ディレクトリのサブディレクトリは検索されません）。

注: 多くの場合、保険会社がファイルを ClaimCenter のインスタンスに追加するときのベストプラクティスは、保険会社名で命名したサブディレクトリにファイルを追加することです。ただし、役割ファイルでは、保険会社はこのプラクティスに従うことができません。システム API が役割ファイルを使用できるようにするには、ファイルを roles ディレクトリで直接宣言する必要があります。サブディレクトリでは宣言できません。

API 役割ファイルの構造

API 役割は、Studio 内の Integration > roles ディレクトリで宣言されます。すべてのファイルで、以下が指定されます。

役割の名前
関連ユーザーのエンドポイントとエンドポイント操作
関連ユーザーが表示または編集できるフィールド
関連呼び出し元に付与される特別な権限

これらの部分は、どのような順序でも指定できることに注意してください。

API 役割の名前

ファイルで宣言する役割名と、ファイル名に表示される役割名には、同じ文字列を使用することをお勧めします。複数の語からなる名前を API 役割に付ける必要がある場合、ファイル名でアンダースコアを使用し、ファイルの Role Name セクションではスペースを使用することをお勧めします。

例えば、新しい API 役割が Fraud Investigators 用である場合：

ファイル名は Fraud_Investigator.role.yaml にします。
ファイルでは、name: "Fraud Investigator" という名前を宣言します。

内部ユーザーの API 役割の場合：

ClaimCenter 内に適切なユーザーに割り当てられたユーザー役割が存在する必要があります。
API 役割の名前とユーザー役割の名前は同一である必要があります。

外部ユーザーの API 役割の場合：

IDP が各ユーザーを API 役割の名前に関連付けることができる必要があります。
役割名が後に続く cc. または pc. サブ文字列で役割を IDP で識別する必要があります。
- IDP では、役割を識別する文字列の先頭は cc. または pc. にする必要があります。cc. または pc. の後のサブ文字列は、役割の名前に一致する必要があります。例えば、cc.Manager は、Manager という名前の役割と一致します。

サービスの API 役割の場合：

役割には insurercode_name（acme_locationphotos など）のように名前を付けることをお勧めします。
- insurercode は、acme などの保険会社のコードです。
- name は、意味のある名前で、小文字で表します。
サービスを Guidewire Hub に登録するとき、役割名の先頭に cc. または pc. を付ける必要があります。ただし、API 役割ファイル名や Role Name セクションには、その接頭辞を含めないでください。

API 役割のエンドポイント

endpoints セクションで特定される内容は、被付与者が使用できるエンドポイントと、そのエンドポイント上で被付与者が使用できる操作（GET、POST、PATCH、または DELETE）です。このセクションは、許可リストとして機能します。デフォルトでは、呼び出し元はどのエンドポイントに対するどの操作も使用できません。エンドポイントを使用できるようにするには、各エンドポイントと操作を明示的に許可リストに含める必要があります。

endpoints セクションには、エンドポイントのリストが以下のパターンで含まれています。

endpoints:
  - endpoint: <endpoint 1>
    methods:
    - <method 1 on endpoint 1>
    - <method 2 on endpoint 1>
  - endpoint: <endpoint 2>
    methods:
    - <method 1 on endpoint 2>
    - <method 2 on endpoint 2>

`endpoints` セクションのワイルドカード

endpoints セクションでは、アスタリスク（*）のワイルドカードを使用できます。

単一のワイルドカード（*）は、現在のエンドポイントの直下にあるすべてにアクセスできることを示します。次に例を示します。

/common/v1/activities/* は、「/activities の直下にあるすべて」を意味します。
/common/v1/activities/*/notes は、「/activities の直下にあるすべてに対する notes」を意味します。

二重のワイルドカード（**）は、現在のレベルより下位のすべてにアクセスできることを示します。次に例を示します。

/common/v1/activities/** は、「/common/v1/activities のパスからアクセスできるすべてのリソースまたはエンドポイント」を意味します。

** を使用するときの注意

保険会社には、** ワイルドカードは注意して使用することをお勧めします。システム API の今後のリリースで、新しいエンドポイントが追加される可能性があり、これによって、** ワイルドカードで意図せずにユーザーにアクセス権が付与されるからです。例えば、リリース 1.0 で、保険会社が API 役割を作成して、common/v1/activities/** へのアクセス権を提供するとします。リリース 1.0 の時点では、これによって以下に対するアクセス権が提供されます。

common/v1/activities/{activityId}
common/v1/activities/{activityId}/assignees
common/v1/activities/{activityId}/notes

その後、リリース 2.0 で、Guidewire が以下のエンドポイントを追加します。

common/v1/activities/{activityId}/confidentialAnalysis

保険会社がリリース 1.0 で API 役割を作成するときに意図していなかったとしても、API 役割で自動的に新しいエンドポイントへのアクセス権が付与されます。

API 役割のアクセス可能なフィールド

accessibleFields セクションによって、被付与者が表示または編集できる各リソースのフィールドが特定されます。このセクションは、許可リストとして機能します。デフォルトでは、呼び出し元はどのリソースのどのフィールドについても表示や編集をできません。表示および編集を可能にするには、各リソース、フィールド、および権限が明示的に許可リストに含まれている必要があります。

accessibleFields セクションには、リソースのリストが以下のパターンで含まれています。

accessibleFields:
  <Resource 1>:
    edit:
    - <fields the grantee can edit on resource 1>
    view:
    - <fields the grantee can view on resource 1>
  <Resource 2>:
    edit:
    - <fields the grantee can edit on resource 2>
    view:
    - <fields the grantee can view on resource 2>

許可リストでのリソースの指定

リソースはいくつかの方法で指定できます。リソースは明示的に指定できます。例えば、以下はアクティビティリソースのみの権限を指定しています。

accessibleFields:
  Activity:
    edit:
    - <fields the grantee can edit on this resource>
    view:
    - <fields the grantee can view on this resource>

ワイルドカード（*）を使用することもできます。このコンテキストでは「endpoints セクションにリストされたエンドポイントですべてのリソースが使用可能」を意味します。例えば、役割のエンドポイントですべてのリソースを使用できる権限を、以下で指定しています。

accessibleFields:
  "*":
    edit:
    - <fields the grantee can edit on this resource>
    view:
    - <fields the grantee can view on this resource>

許可リストでのフィールドの指定

すべてのリソースについて、edit と view の 2 つのフィールドレベル権限を指定できます。権限が明示的にリストされていない場合、呼び出し元はリソースのどのフィールドについてもその権限を付与されません。

フィールドレベルの権限はいくつかの方法で指定できます。フィールドと権限を明示的に指定できます。例えば、以下の場合、Activity リソースの subject フィールドへの編集アクセス権と、priority フィールドと subject フィールドへの表示アクセス権が付与されます。

accessibleFields:
  Activity:
    edit:
    - "subject"
    view:
    - "priority"
    - "subject"

ワイルドカード（*）を使用することもできます。このコンテキストでは、「すべてのフィールド」を意味します。例えば、以下の場合、Activity リソースの subject フィールドへの編集アクセス権と、すべてのフィールドへの表示アクセス権が付与されます。

accessibleFields:
  Activity:
    edit:
    - "subject"
    view:
    - "*"

API 役割の特殊権限

特殊権限は、エンドポイント、エンドポイント操作、またはフィールドレベルで機能しない権限です。このリリースでサポートされている特殊権限を、以下の表に示します。


権限名	該当するアプリケーション	説明
`restdefervalidation`	PolicyCenter	`deferValidation` クエリパラメータを使用する機能を関連呼び出し元に提供します。詳細については、『Cloud API Business Flows Guide（Cloud API ビジネスフローガイド）』の「Deferred Validation（延期済み検証）」のトピックを参照してください。
`restunmasktaxid`	BillingCenter、ClaimCenter、PolicyCenter、ContactManager	連絡先の `taxId` フィールドが含まれる応答において、マスクされていない完全な `taxId` を返します。

role.yaml ファイルに特殊権限を追加するには、以下の構文を使用します。

permissions:
- <permissionName>

例えば、以下は、restunmasktaxid 権限を役割に付与します。

permissions:
- restunmasktaxid

API 役割の例

以下は、Adjuster.role.yaml ファイルの内容です。

endpoints:
  - endpoint: "/admin/v1/openapi.json"
    methods:
    - "*"
- endpoint: "/claim/v1/**"
    methods:
    - "*"
- endpoint: "/common/v1/**"
    methods:
    - "*"
accessibleFields:
  "*":
    view:
      - "*"
    edit:
      - "*"
name: Adjuster

次の点に注目します。

Adjuster の役割を持つユーザーは、以下のエンドポイントへのアクセス権を付与されます。
- Admin API の openapi.json エンドポイント
- Claim API 内のすべてのエンドポイント
- Common API 内のすべてのエンドポイント
Adjuster の役割を持つユーザーは、それらのエンドポイントでのすべての操作（GET、POST、PATCH など）を使用できます。
Adjuster の役割を持つユーザーは、使用可能なエンドポイントですべてのフィールドを表示および編集できます。