1. Homepage
  2. Flex Gateway ポリシー開発キット (PDK) (1.3)
  3. カスタムポリシーの開発

  4. ポリシースキーマ定義の作成

ポリシースキーマ定義の作成

gateway::policy-included-directory.adocにリストされているポリシーと同様に、カスタムポリシーにも設定パラメーターがあります。設定パラメーターを使用して、カスタムポリシーの使いやすさを向上させ、より幅広い API 設定をサポートします。

カスタム設定パラメーターを定義するには、​definition/gcl.yaml​ ファイルを編集します。​gcl.yaml​ ファイルは、Gateway Configuration Language (GCL) で書かれています。ただし、このチュートリアルを使用するには GCL の事前知識は不要です。

make build-asset-file​ コマンドを実行すると、​gcl.yaml​ で定義した設定パラメーターが変数として ​src/generated/config.rs​ ファイルに保存されます。Rust ソースコードの実装に必要なユーザー入力は、​gcl.yaml​ ファイルに設定します。

接続モードで動作する Flex Gateway にポリシーを適用すると、API Manager UI に設定パラメーターが表示されます。ローカルモードで動作する Flex Gateway にポリシーを適用する場合は、ポリシーの設定が保存されている ​yaml​ ファイルを自分で配布する必要があります。

デフォルトの ​gcl.yaml​ ファイルのコンテンツは次のとおりです。

apiVersion: gateway.mulesoft.com.v1alpha1
kind: Extension
metadata:
    labels:
        title: my-custom-policy
        category: Custom
spec:
    extends:
        - name: extension-definition
    properties:
        stringProperty:
        type: string

gcl.yaml​ ファイルには 2 つのセクションがあります。

  • metadata​: ポリシーに関する情報を定義します。

  • properties​: ポリシーの設定パラメーターを定義します。

スキーマを定義する手順は、次のとおりです。

  1. メタデータの定義

  2. パラメーターの定義

  3. Rust ソースコードでのカスタムパラメーターの使用

メタデータの定義

metadata セクションに表示ラベルを追加することで、ポリシーを適用したときに UI に表示されるデータをわかりやすくすることができます。

メタデータを定義するには、​gcl.yaml​ ファイルの ​metadata​ セクションを編集します。

サポートされる表示ラベルは次のとおりです。

  • title​: UI に表示されるポリシー名。

  • description​: ポリシー動作の簡単な説明。

  • category​: ポリシーのカテゴリ。設定できるカテゴリは、​security​、​compliance​、​transformation​、​quality of service​、​troubleshooting​ です。

例:

metadata:
    labels:
        title: JSON Threat Protection
        description: Protects against malicious JSON in API requests.
        category: Security

labels​ は推奨されますが、必須ではありません。

アウトバウンドポリシーの定義

デフォルトでは、PDK はインバウンドポリシーとしてポリシーを作成します。アウトバウンドポリシーを作成するには、​gcl.yaml​ ファイルの ​labels​ セクションを編集します。次のような ​metadata/capabilities/injectionPoint: outbound​ 表示ラベルを追加します。

metadata:
    labels:
        title: My Outbound Policy
        description: An outbound security policy
        category: Security
        metadata/capabilities/injectionPoint: outbound

パラメーターの定義

パラメーターを追加するには、​gcl.yaml​ ファイルの ​spec.properties​ セクションを編集します。

例:

properties:
    username:
        type: string
    password:
        type: string

プロパティを定義した後は、以下を行うことができます。

必須プロパティとデフォルト値の定義

gcl.yaml​ ファイルにリストされている各プロパティを ​required​ (必須) として定義し、そのプロパティの ​default​ (デフォルト) 値を設定できます。

プロパティを必須として定義するには、​spec.required​ オブジェクトにリストします。たとえば、次のポリシーでは ​password​ は必須ですが、​username​ は必須ではありません。

properties:
    username:
        type: string
    password:
        type: string
required:
    - password

上の設定例のポリシーを適用する際にパスワードを指定しないと、設定はエラーとなります。

次の例では、各プロパティのデフォルト値を定義しています。

properties:
    username:
        type: string
        default: user1
    password:
        type: string
        default: 12345678
required:
    - password

ポリシーを適用する際に必須プロパティの値を設定しないと、そのプロパティではデフォルト値が使用されます。

必須ではないプロパティでは、API Manager UI が、プロパティに対して設定されているデフォルト値を推奨します。必須ではないプロパティで値を指定しないと、そのプロパティは設定されません。

下表に示す設定に基づいてポリシーを API Manager で適用すると、​username​ の推奨値として ​user2​ が表示されますが、値を省略すると、このプロパティは設定されません。

ポリシーの設定

有効な設定

設定の状況

{}

{"password": "12345678"}

Success (成功)

{"username": "user2"}

{"password": "12345678",
"username": "user2"}

Success (成功)

{"password": "password"}

{"password": "password"}

Success (成功)

{"password": "password",
"username": "user2"}

{"password": "password",
"username": "user2"}

Success (成功)

機密データの定義

security:sensitive​ 特性を追加することで、パスワードや証明書などの機密データを保護します。

properties:
    key:
        type: string
        default: "YourKey"
        "@context": {
        "@characteristics": [
          "security:sensitive"
        ]
      }

ポリシーを適用すると、機密データへの入力値はユーザーには表示されません。

重要なパラメーターへの文字入力は黒いドットとして表示されます。

[表示]​ を切り替えると、入力中のデータが表示されます。ただし、すでに保存済みのデータは表示できません。たとえば、上の例の ​key​ パラメーターを設定してポリシーを適用した場合、後でポリシーの設定を編集するときにはパラメーターの値を表示することはできません。

条件付きパラメーターの定義

項目を表示する条件を確立して、ポリシー設定パラメーターを動的に表示します。次のコード例では、ユーザーが ​encryptBody​ パラメーターで ​true​ を選択すると、​encryptionKey​ パラメーターが表示されます。

properties:
    encryptBody:
        type: boolean
        default: false
    encryptionKey:
        type: string
        "@rendering":
            "@visibleOn":
                - property: encryptBody
                  value: true

次のコード例では、​encryptionKey​ パラメーターは最初に表示されますが、ユーザーが ​encryptBody​ パラメーターで ​false​ を選択すると非表示になります。

properties:
    encryptBody:
        type: boolean
        default: true
    encryptionKey:
        type: string
        "@rendering":
            "@visibleOn":
                - property: encryptBody
                  value: true

条件付きパラメーターには、次の制限があります。

  • パラメーターごとに定義できる条件は 1 つのみです。

  • 条件パラメーターとしてサポートされているのは、​string​、​boolean​、または ​integer​ パラメーターのみです。

  • 条件付きで表示されるパラメーターを ​object​ または ​enum​ にすることはできません。

  • 条件付きで表示される必須プロパティには、デフォルト値が定義されている必要があります。上記の例では、​encryptionKey​ が必須であれば、デフォルト値が必要です。

  • 条件付き表示をサポートしているのは、ルートレベルのパラメーターのみです。配列またはオブジェクトの内部プロパティは、条件付き表示をサポートしていません。

列挙されたパラメーターの定義

次に示すように、​enum​ プロパティでパラメーターを定義してユーザーの入力値を制限します。

  properties:
    signingMethod:
      type: string
      enum:
        - rsa
        - hmac

API Manager UI では、​enum​ パラメーターは、列挙された値が 3 個までであればラジオボタンとして、それより多い場合はドロップダウン項目として表示されます。ローカルモードで実行されている Flex Gateway の場合、ユーザーはパラメーターを列挙された値の 1 つとして設定する必要があり、設定しなければポリシー設定は失敗します。

列挙されたパラメーターは、​@visibleOn​ タグをサポートしていません。変数を動的に表示する方法についての詳細は、​条件付きパラメーターの定義​を参照してください。

サポートされる種別の定義

ポリシーに正しいデータが入力されることを保証するため、各ポリシーパラメーターでサポートされるデータ型を定義します。

サポートされる種別は次のとおりです。

String (文字列)

文字列型は、データがテキストであることを指定します。

properties:
    password:
        type: string

string​ 型では、​format​ (形式) 種別も設定できます。

サポートされる形式種別は次のとおりです。

  • dataweave​: 入力パラメーターが DataWeave 変数であることを指定し、入力を変換する用に Flex Gateway に指示します。DataWeave 式の詳細については、​DataWeave 式の定義​を参照してください。

  • service​: 入力パラメーターが URI であることを指定し、ポリシーからの HTTP コールを有効にするための Flex Gateway サービスを作成します。

  • ipRange​: 想定されるテキストが IP 範囲であることを指定し、入力に対して追加の検証を行います。

  • uri​: 想定されるテキストが URI であることを指定し、入力に対して追加の検証を行います。​uri​ は、URI がポリシーから HTTP コールを実行するサービスではない場合にのみ使用してください。

    次の yaml スニペットは、すべての文字列形式を設定しています。

    properties:
    externalService:
        type: string
        format: service
        default: "https://auth-service:9000/login"
    token:
        type: string
        format: dataweave
        default: "#[splitBy(attributes.headers['Authorization'], ' ')[1]]"
    blockedIps:
        type: string
        format: ipRange
        default: "192.168.3.1/30"
    loginUrl:
        type: string
        format: uri
        default: "https://anypoint.mulesoft.com/login"
Number (数値)

number​ 型は、データが浮動小数点値であることを指定します。

例:

properties:
    squareRoot:
        type: number
        default: 1.414213562
    seconds:
        type: number
        default: 10
Integer (整数)

integer​ 型は、データが整数値であることを指定します。

例:

properties:
    maxHeaders:
        type: integer
        default: 10
Boolean (ブール)

boolean​ 型は、データがブール値であることを指定します。サポートされる値は ​true​ または ​false​ です。 例:

properties:
    skipValidation:
        type: boolean
        default: false
    requireCredentials:
        type: boolean
        default: true
Array (配列)

array​ 型は、データが順序付き要素のリストであることを指定します。​array​ 型を使用する場合は、配列に含まれる項目のデータ型を ​items.type​ で指定する必要もあります。

例:

properties:
    scopes:
        type: array
        items:
            type: string
        default: ["READ", "WRITE"]
Object (オブジェクト)

object​ 型は、データが複数のプロパティを持つ順序付き要素のリストであることを指定します。​object​ 型を使用する場合は、オブジェクトの各要素に対して ​properties.type​ を指定する必要もあります。

例:

properties:
    user:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required:
        - id
        - name
      default: {"id": "1", "name": "John Doe"}

DataWeave 式の定義

string​ 型のパラメーターの ​dataweave​ 形式は、入力パラメーターが DataWeave 式であることを指定します。

dataweave​ 変数は、次のように式のバインドをサポートします。

<configuration-parameter>:
 type: string
 format: dataweave
 bindings:
   payload:
     mimeType: text
   attributes: true
   authentication: false
   vars: []

  • payload​: 受信要求のボディ。​mimeType​ を ​text​ または ​json​ のどちらかに定義することで、ペイロードの読み取り方法を設定します。デフォルトでは、​mimeType​ は ​text​ に設定されます。​payload​ 変数の使用を制限するには、payload 変数を次のように除外します。

    bindings:
   attributes: true
   authentication: false
   vars: []

  • attributes​: 受信要求の属性 (ヘッダーなど)。ポリシーで受信要求から属性を読み取るようにするには、​attributes​ を ​true​ に設定します。デフォルトでは、​attributes​ は ​true​ に設定されます。

  • authentication​: 受信要求の認証情報。ポリシーで受信要求から認証の詳細を読み取るようにするには、​authentication​ を ​true​ に設定します。デフォルトでは、​authentication​ は ​false​ に設定されます。

  • vars​: ポリシーが使用できる変数の名前を指定します。デフォルトでは、​vars​ は空です。ポリシーの適用時に、スキーマで定義されていない変数を入力すると、ポリシーはその変数を ​null​ として評価します。

サポートされている式のバインドについては、Predefined Variablesを参照してください。

ポリシーの適用時に、ユーザーの式にポリシーのスキーマで定義されていないバインドが含まれている場合、ポリシーの設定は失敗します。たとえば、ユーザーの式が ​[authentication.principal]​ で、​authentication​ が ​true​ に設定されていない場合は、次のようなエラーが発生します。

test-local-flex-1  | [flex-gateway-envoy][error] wasm log main: [policy: ingress-http-jwt-auth-v1-0-impl-1.default][api: ingress-http.default.svc] Launcher problem: Failed to parse configuration '{"dw":"P[[\".\", \"0-24\", [\":ref\", \"0-14\", \"authentication\"], [\":str\", \"15-24\", \"principal\"]], \"#[authentication.principal]\"]"}'. Cause: Error compiling expression: Unknown symbol `authentication` at line 1 column 141

ポリシーで DataWeave 式を評価するには、式を解決するためのスクリプトを提供する必要があります。Rust ソースコードに DataWeave 式を実装する方法については、​「Implement DataWeave Expressions (DataWeave 式の実装)」​を参照してください。

Flex Gateway での DataWeave サポートについての詳細は、DataWeave Support in Flex Gateway Policiesを参照してください。

Rust ソースコードでのカスタムパラメーターの使用

gcl.yaml​ ファイルを変更したら、次のいずれかのコマンドを実行して、​src/generated/config.rs​ rust ファイルと API Manager UI 用の JSON スキーマに変更を反映させます。

  • make build-asset-files​ は ​src/generated/config.rs​ に変更を反映させるのみです。

    make build-asset-files

  • make build​ は変更を ​src/generated/config.rs​ に変更を反映させてから、ポリシーのターゲットファイルを生成します。ポリシーのターゲットファイルを上書きしたくない場合は、​make build​ を実行しないでください。

    make build

    ポリシーのコンパイルの詳細については、カスタムポリシーのコンパイルを参照してください。

gcl.yaml​ ファイルで定義されているプロパティは、次のように ​config.rs​ Rust ファイルの Rust データ型にマッピングされます。

gcl.yaml config.rs

string

String

uri​ 文字列

String

ipRange​ 文字列

String

dataveave​ 文字列

pdk::script::Script

number

f64

integer

i64

boolean

bool

array

指定された項目種別を含む ​vec

object

指定されたプロパティ種別を含む ​struct

gcl.yaml​ でパラメーターが必須として定義されていない場合、​config.rs​ の対応するパラメーターは Option オブジェクトにラップされます。

ラップ解除する前に、そのパラメーターが存在することを確認してください。存在しないパラメーターをラップ解除すると、​panic!​ が発生する場合があります。

次のいずれかの例を使用して、パラメーターが存在することを確認してください。

  • if let Some(val) = myValue

  • if myValue.is_some() {myValue.unwrap()}

たとえば、次の ​gcl.yaml​ ファイルは、その下に示す ​struct​ を ​config.rs​ で生成します。

  1. gcl.yaml​:

    properties:
    tokenExtractor:
      type: string
      format: dataweave
      default: "#[dw::core::Strings::substringAfter(attributes.headers['Authorization'], 'Bearer ')]"
    reject_missing_tokens:
      type: boolean
    max_chars:
      type: number
  required:
    - tokenExtractor

  2. config.rs​:

    pub struct Config {
    #[serde(alias = "max_chars")]
    pub max_chars: Option<f64>,
    #[serde(alias = "reject_missing_tokens")]
    pub reject_missing_tokens: Option<bool>,
    #[serde(alias = "tokenExtractor")]
    pub token_extractor: pdk::script::Script,
}

entrypoint​ 関数で ​.operators​ を次のように使用することで、​struct Config​ の値にアクセスできます。

#[entrypoint]
async fn configure(launcher: Launcher, Configuration(configuration): Configuration,) -> Result<(), LaunchError> {
    let config: Config = serde_json::from_slice(&configuration)?;
    match config.reject_missing_tokens {

関連情報