1. Homepage
  2. Mule ゲートウェイ
  3. Mule 3 のポリシー
  4. カスタムポリシー

  5. 設定および定義ファイルの参照

設定および定義ファイルの参照

カスタムポリシーを作成するための、設定ファイル (XML) と定義ファイル (YAML) の完全な技術的リファレンスを次に示します。

ポリシー設定 XML ファイル

ポリシー設定は、ポリシーの実際の実行を実装する XML ファイルです。この設定は、Mule Runtime アプリケーションを作成するときにフロー内の要素を活用することによってこれを実現します。Mule Runtime で使用できるすべての要素をカスタムポリシーで使用できます。

ポリシー設定では、ポリシーの実装を実行する実際のプロセスを定義します。Mule アプリケーションのような構造で、コンテンツを次のタグで囲みます。

<policy>
</policy>

開始 ​<policy>​ タグには、ポリシー内で使用されるすべての Mule XSD ファイルへの参照を含めます。追加できる Mule 要素の中には、対応する XSD 参照も追加する必要があるものもあります。

<policy>​ 要素のパラメーターにプロパティ ​id​ と ​policyName​ を追加すると、分析のために API に関するデータを収集できます。

デフォルトでは、カスタムポリシーを作成すると、次のデフォルト設定プロパティにアクセスできます。これらは、設定 XML ファイル内で参照できます。

プロパティ 説明

policyId

現在のポリシーの一意の ID

endpointUri

API のインバウンドエンドポイントの完全な URI

apiId

API の一意の ID 番号

apiVersionId

API バージョンの一意の ID 番号

apiName

API の名前

isRamlEndpoint

エンドポイントが RAML 定義ファイルにリンクされているかどうかを決定するブール値

isWsdlEndpoint

エンドポイントが WSDL 定義ファイルにリンクされているかどうかを決定するブール値

isHttpEndpoint

エンドポイントが HTTP プロトコルに従っているかどうかを決定するブール値

これらのデフォルトプロパティに加えて、新しいプロパティをポリシー定義 YAML ファイルで指定して、それらをポリシー設定 XML ファイルで参照することができます。

policy タグのプロパティ

policy タグのプロパティは、カスタムポリシー XML 設定の重要な部分です。

  • <policy>​ タグ内の ​order​ プロパティ

  • <before></before> および <after></after> 内の ​order​ プロパティ

これらのプロパティは、ポリシーの実行順序を決定します。

requiresContracts​ プロパティは、クライアント検証に不可欠です。

「Custom Policy Properties Reference (カスタムポリシープロパティリファレンス)」には、これらのプロパティに関する詳細が記載されています。

カスタムポリシーの設定 XML では、ポリシー定義のデフォルトのプロパティセットと、ポリシーテンプレート YAML ファイルで定義されたプロパティにアクセスできます。プロパティを参照するには、次のように 2 つの中括弧で囲まれた名前を入力します。

{{propertyName}}

このトピックでは、​order​ および ​requiresContracts​ プロパティについて説明します。

policy タグの order プロパティ

order​ プロパティを使用してポリシーの実行順序を設定できますが、メッセージプロセッサーでのポリシー実行順序の設定が、policy タグでの実行順序の設定よりも優先されます。順序は 2 よりも大きな整数で設定します。順序値 0 ～ 2 はそれぞれ CORS ポリシー、調整ポリシー、レート制限ポリシー用に予約されています。これらのポリシーは他のポリシーより前に実行する必要があります。次の例は、​<policy>​ タグ内での ​order​ プロパティの設定方法を示しています。

<?xml version="1.0" encoding="UTF-8"?>
<policy id="7777"
        policyName="A"
        order="3"
        xmlns="http://www.mulesoft.org/schema/mule/policy"
        xmlns:mule="http://www.mulesoft.org/schema/mule/core"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:api-platform-gw="http://www.mulesoft.org/schema/mule/api-platform-gw"
        xsi:schemaLocation="http://www.mulesoft.org/schema/mule/policy http://www.mulesoft.org/schema/mule/policy/current/mule-policy.xsd
              http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
              http://www.mulesoft.org/schema/mule/api-platform-gw http://www.mulesoft.org/schema/mule/api-platform-gw/current/mule-api-platform-gw.xsd">

    <before>
         <mule:logger level="INFO" message="POLICY A" />
    </before>

    <pointcut>
        <api-platform-gw:api-pointcut apiName="Leagues API" apiVersion="1.0.0"/>
    </pointcut>
</policy>

before タグまたは after タグの order プロパティ

別の方法として、<before></before> タグと <after></after> タグ内でポリシーの実行順序を設定できます。​before​ タグと ​after​ タグ内での ​`order `​ プロパティの設定は、policy タグ内の他のどの設定よりも優先されます。順序は、2 よりも大きい整数に設定します。次に例を示します。

<?xml version="1.0" encoding="UTF-8"?>
<policy id="2"
       ...

    <before order="4">
       <mule:set-payload value=" before cust2 "/>
       <mule:logger level="INFO" message="#[payload]" />
    </before>

    <before order="3">
       <mule:set-payload value=" before cust2.1 "/>
       <mule:logger level="INFO" message="#[payload]" />
    </before>

policy タグの requiresContracts

次のバージョンは、設定 XML の policy タグの ​requiresContracts​ プロパティをサポートしています。

  • Mule ゲートウェイランタイム 2.2.0 以降

  • Mule Runtime 3.8 以降

それより前のバージョンでは、Mule ゲートウェイランタイムがデフォルトでクライアントログイン情報をキャッシュするため、このプロパティは必要ありません。

重要​: requiresContracts​ プロパティの有効化は、クライアント検証に不可欠です。Anypoint Platform がダウンした場合、ポリシーはクライアントの検証を継続できます。検証チェックはメモリ内で行われるため、ネットワーク上で HTTP 要求を使用するチェックよりも本質的にパフォーマンスが高くなります。

クライアント ID を検証するカスタムポリシーは、多くの場合、MuleSoft が提供する、クライアントを認証するポリシー (クライアント ID 適用ポリシーや SLA ベースのポリシーなど) のバリエーションです。

クライアント ID を検証するカスタムポリシーでは、次のスニペット例のように、​requiresContracts​ を含めて、このブール値プロパティを true に設定します。

<?xml version="1.0" encoding="UTF-8"?>
<policy id="{{policyId}}"
        policyName="Custom Client Id Enforcement"
        online="true"
        requiresContracts="true"
        xmlns="http://www.mulesoft.org/schema/mule/policy"/>
...

API クライアントの ID と認証ログイン情報は、Mule ゲートウェイランタイムまたは Mule Runtime にダウンロードされ、保存されます。検証はランタイム内で行われるため、検証のためにアウトバウンド HTTP 要求を送信する必要はありません。

デフォルトでは、クライアント情報のダウンロードと取得はバックグラウンドで 15 秒ごとに実行されます。ポーリング頻度は、​anypoint.platform.poll_clients_freq​ プロパティを使用して設定できます。このプロパティの設定は、[CloudHub properties (CloudHub プロパティ)] タブまたは ​<MULE_HOME>/conf​ フォルダー内の ​wrapper.conf​ ファイルで行います。

ポリシー定義 YAML ファイル

ポリシー定義ファイルでは、ポリシーの実装時に UI として表示されるポリシーの概要レベルのプロパティ、設定可能プロパティ、表示ラベル、ヒントを定義します。

次の例は、IP 許可リストポリシー定義 YAML ファイルを示しています。

id: ip-whitelist
name: IP Allowlist
description: Limits all service calls to a defined set of IP addresses.
category: Security
standalone: true
requiresConnectivity: false
resourceLevelSupported: true
providedCharacteristics:
  - IP filtered
requiredCharacteristics: []
configuration:
  - propertyName: ipExpression
    name: IP expression
    description: |
      Mule Expression for extracting the IP address from this API request.
      for example, #[message.inboundProperties['http.headers']['X-Forwarded-For']]
    type: expression
    defaultValue:
    optional: true
    sensitive: false
    allowMultiple: false
  - propertyName: ips
    name: Allowlist
    description: Limited list of IP addresses allowed API access
    type: ipaddress
    optional: false
    sensitive: false
    allowMultiple: true

定義する新しいプロパティには、ユーザーがポリシーを適用するときに何を設定するかに基づいて値を指定します。IP 許可リストポリシーの例では、​ipExpression​ プロパティと ​ips​ プロパティの値が必須です。ポリシー設定 XML ファイルは、これらのプロパティを参照します。ユーザーは、それらに値を割り当てるように求められます。

新しいポリシーに関連するポリシー定義値には次のものがあります。

パラメーター 説明

name (名前)

string (文字列) - ポリシー名。

description (説明)

string (文字列) - ポリシーを適用するときにポリシーの詳細に表示される説明。

category (カテゴリ)

string (文字列) - ポリシーのカテゴリ。

standalone (スタンドアロン)

boolean (ブール値) - ポリシーが単独で機能できる場合は true、別のポリシーの一部としてのみ適用可能な場合は false。

providedCharacteristics

array (配列) - このポリシーを適用することによって満たされる省略可能な特性のリスト。

requiresConnectivity

boolean (ブール値) - レガシー内部パラメーター。この機能は実装されていません。

resourceLevelSupported

boolean (ブール値) - true はユーザーがポリシーを特定の API リソースに適用できることを意味し、false はポリシーがすべての API リソースに適用されることを意味します。(Mule 3.8.1 以降)

requiredCharacteristics

array (配列) - このポリシーを適用できるようにするために満たすべき必須特性のリスト。必須特性は、それらを提供する他のポリシーを適用することによって満たすことができます。これによって、ポリシー間の連動関係が可能になります。任意の文字列入力は特性名として有効ですが、その特性を提供する他のポリシーが 1 つ以上存在する必要があります。大文字と小文字は区別されます。

configuration (設定)

array (配列) - ポリシーに関連付けられた設定可能なプロパティのセット。各プロパティのパラメーターの詳細については後述します。

ramlSnippet

string (文字列) - RAML 0.08 仕様で示されたセキュリティスキーム。

ramlV1Snippet

string (文字列) - RAML 1.0 仕様で示されたセキュリティスキーム。

providedCharacterics パラメーター

通常、​providedCharacteristics​ を設定するのは、同時に適用できないポリシー間の競合を避けるためです。たとえば、同時に適用できる OAuth 2.0 ポリシーは 1 つのみです。​OAuth 2.0 protected​ を使用して、OAuth 2.0 ポリシーを 1 つのみ指定します。

既存の特性のリストは次のとおりです。

  • Client ID required

  • CORS enabled

  • Baseline Rate Limiting

  • SLA Rate Limiting

  • Requires authentication

  • IP filtered

  • JSON threat protected

  • Security manager

  • OAuth 2.0 protected

  • OAuth 2.0 provider

  • XML threat protected

このリストは無制限です。任意の文字列入力が特性名として有効です。リスト項目では大文字と小文字が区別されます。

configuration パラメーター

configuration​ パラメーターは、プロパティのセットをリストします。各プロパティには次のパラメーターを含めることができます。

パラメーター 説明

propertyName

string (文字列) - 内部参照用のプロパティ名。

name

string (文字列) - 設定ウィンドウで表示されるプロパティ名。

description

string (文字列) - 設定ウィンドウで表示されるプロパティの説明。

type

string (文字列) - データ型。string (文字列)、boolean (ブール値)、int (整数)、ipaddress、expression (式) (MEL)、keyvalues、rateLimits。type = int の場合、minimumValue と maximumValue を定義します。

optional

boolean (ブール値) - 値の割り当てが省略可能である場合は true。

sensitive

boolean (ブール値) - この項目に含まれる情報が機密情報である場合は true (通常は、パスワードやトークンに使用されます)。サーバーからポリシー情報が要求されると、これらの機密項目は除外されます。

allowMultiple

boolean (ブール値) - 複数の値を割り当てることができる場合は true。

minimumValue

int (整数) - 型が int (整数) で必須の値のみに使用します。

maximumValue

int (整数) - 型が int (整数) で必須の値のみに使用します。

defaultValue

型が int (整数)、boolean (ブール値)、string (文字列)、expression (式) のプロパティにのみ使用します。

propertyName の構文

次のスニペットは、次の型の propertyName パラメーターを定義する方法を示しています。

  • Integer (整数)

  • Boolean (ブール)

  • String (文字列)

  • Map (マップ)

Integer (整数)

type = int の場合、minimumValue と maximumValue を定義する必要があります。

configuration:
 - propertyName: aint
   name: Test Int single between 5 and 10
   description: Some Description
   type: int
   minimumValue: 5
   maximumValue: 10
   optional: true
   sensitive: false
   allowMultiple: false

Boolean (ブール)

configuration:
 - propertyName: aboolean
   name: Test Boolean single
   description: Some Description
   type: boolean
   optional: true
   sensitive: false
   allowMultiple: false
   defaultValue: false

String (文字列)

configuration:
 - propertyName: astring
   name: Test String single
   description: Some Description
   type: string
   optional: true
   sensitive: false
   allowMultiple: false

Map (マップ)

configuration:
 - propertyName: amap
   name: Test Key/Value Map
   description: Some Description
   type: keyvalues
   optional: true
   sensitive: false
   allowMultiple: true

ramlSnippet および ramlV1Snippet パラメーター

カスタムポリシーの YAML に、​ramlSnippet​ パラメーターと ​ramlV1Snippet​ パラメーターを含めることができます。カスタムポリシーを Anypoint Platform に追加すると、RAML .80 スニペットまたは RAML 1 スニペットへのリンクが [Applied policies (適用済みポリシー)] リストに表示されます。

次のスニペットは、MuleSoft が提供する調整 - SLA ベースのポリシーの YAML ファイルのスニペット内の ​ramlSnippet​ パラメーターと ​ramlV1Snippet​ パラメーターを示しています。

id: test
name: test
description: Rosario Central
...
configuration:
  - propertyName: omar
    name: arnaldo
...
  - propertyName: rosario
    name: central
...
ramlSnippet: |
  traits:
  - client-id-required:
      queryParameters:
        client_id:
          type: string
        client_secret:
          type: string
  ...
  /products:
  get:
    is: [client-id-required]
    description: Gets a list of all the inventory products.
ramlV1Snippet: |
  traits:
  client-id-required:
    queryParameters:
      client_id:
        type: string
      client_secret:
        type: string
  ...
  /products:
  get:
    is: [client-id-required]
    description: Gets a list of all the inventory products.

関連情報