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

  4. Mule 4 カスタムポリシーのパブリッシュ

Mule 4 カスタムポリシーのパブリッシュ

以下の手順は、Mule 4 のカスタムポリシーをパブリッシュするためのワークフローの概要です。

  1. ポリシー定義ファイルを作成する。

  2. ポリシー定義アセットを Exchange にパブリッシュする。

  3. 実装ファイルを作成する。

  4. パブリッシュしたポリシー定義にポリシー実装を追加する。

始める前に

Mule 4 のカスタムポリシーをパブリッシュする前に、Anypoint Platform の管理者権限またはコントリビューター権限を持っていることを確認してください。

ポリシー定義ファイルの作成

ポリシー実装をアップロードする前に、JSON と YAML ポリシー定義ファイルを作成する必要があります。必要なファイルは JSON と YAML です。

JSON ファイルは、JSON スキーマ言語を使用して、ポリシーのインターフェースを指定します。API Manager は、JSON ファイルを使用して UI を表示します。

YAML ファイルは、ポリシーカテゴリ、インターフェーススコープ、必要な特性、RAML/OAS スニペットなどのポリシーに関連したメタデータを提供します。

カスタムポリシーの定義例をコピーするか、またはローカルシステムでファイルを作成してください。

JSON スキーマファイルの作成

JSON スキーマファイルは、ポリシーの設定で必要なプロパティやサポートされるプロパティを特定することで、ポリシーのインターフェースを指定します。また、このファイルに追加のアノテーションを含めることで、Anypoint Platform で特別な動作を実行できるようにする各プロパティの種別を絞り込みます。たとえば、Dataweave の検証やシークレットの安全な処理などです。

JSON ファイルには次の項目が含まれている必要があります。

  • 最上位の @コンテキスト

    追加の種別アノテーションで使用するボキャブラリーを参照します。ボキャブラリーの名前空間を指定するための別名は省略可能です。よく使用される名前としては ​security​ や ​config​ があります。

    security 別名と config 別名の値は次のとおりです。

    • security: anypoint://vocabulary/policy.yaml#

    • config: anypoint://vocabulary/policyConfigurationsForUI.yaml#`

  • 最上位のタイトル

  • JSON スキーマ仕様へのリンクを指定した $schema (例参照)

  • object​ のルート種別

  • 最上位の説明

  • 各プロパティには以下を含める必要もあります。

    • タイトル

      タイトルは、API Manager UI が項目名を表示するのに使用します。

    • 説明

      説明は、API Manager UI が項目を説明するのに使用します。

    • 型

      プリミティブ型 (例: integer​、​string​、​object​、​boolean​、​array​) のみがサポートされます。

各プロパティには以下を含めることもできます。

  • 形式

    オプションは ​dataweaveExpression​ と ​ipRange`​ です。

  • デフォルト

    UI で表示されるデフォルト値を入力することができます。

  • @characteristics 配列を使用した @context

    追加のアノテーションによる種別を次のオプションでさらに絞り込みます。

    • config:commaSeparatedValues

      この項目の値によって配列が生成されます。

    • security:sensitive​ API Manager UI でプロパティを入力するときにプロパティをマスクするかどうかを決定します。

基本認証 JSON スキーマのコード例を示します。

 {
  "title": "Basic authentication - Simple",
  "type": "object",
  "description": "Enforces HTTP Basic authentication according to the details configured in the policy.",
  "properties": {
    "username": {
      "title": "User Name",
      "type": "string"
    },
    "password": {
      "title": "User Password",
      "type": "string",
      "@context": {
        "@characteristics": [
          "security:sensitive"
        ]
      }
    }
  },
  "required": [
    "username",
    "password"
  ],
  "unevaluatedProperties": false,
  "@context": {
    "@vocab": "anypoint://vocabulary/policy.yaml#",
    "security": "anypoint://vocabulary/policy.yaml#"
  },
  "$id": "basic-authentication-simple",
  "$schema": "https://json-schema.org/draft/2019-09/schema"
}

定義メタデータ YAML ファイルの作成

YAML ファイルは、ポリシーとその要件に関する情報を提供します。YAML ファイルは、特定のランタイムやバイナリには関連付けられません。

このファイルでは以下の項目を設定する必要があります。

  • ヘッダー

    ヘッダーは #%Policy Definition 0.1 である必要があります。

  • 名前

    API Manager の UI でポリシー名を表示するために使用されるわかりやすい名前。文字列値である必要があります。

  • 説明

    文字列値である必要があります。

  • カテゴリ

    ポリシーが属するカテゴリ。API Manager の UI でポリシーのグループ化や絞り込みを行うために使用されます。任意の文字列値を使用できます。例: security​、​quality of service​、​compliance​、​troubleshooting​、​transformation​。

  • 提供される特性

    ポリシーで提供する特性を定義するために使用するリスト。文字列の配列である必要があります。空白のままにするには、​providedCharacteristics: []​ を使用します。

基本認証定義 YAML ファイルのコード例を示します。

#%Policy Definition 0.1
name: Basic authentication - Simple
description: Enforces HTTP Basic authentication according to the details configured in the policy.
category: Security
providedCharacteristics:
  - Requires authentication
requiredCharacteristics: []
interfaceScope: ["api", "resource"]
interfaceTransformation: []
encryptionSupported: true
violationCategory: authentication

Exchange へのポリシー定義アセットのパブリッシュ

必要なポリシー定義ファイル (JSON および YAML) を作成したら、ポリシー定義アセットを Exchange にパブリッシュします。

詳細は、​「カスタムポリシー定義アセットの作成」​を参照してください。

実装ファイルの作成

ポリシーをランタイムで使用できるようにするのに必要なポリシー実装ファイルは、メタデータファイルとバイナリファイルです。メタデータファイルは、バイナリファイルがどのランタイムバージョンからどのテクノロジーに適用されるかを記述します。メタデータファイルは、YAML ファイルである必要があります。バイナリファイルにはポリシーロジックが含まれ、ランタイムの実行を管理します。このファイルは、Mule 4 ランタイムの場合は JAR ファイルです。

実装メタデータ YAML ファイルの作成

メタデータ YAML ファイルは、ポリシー定義の特定の実装に関する詳細を提供します。1 つのポリシー定義から複数の実装を派生させることができます。それぞれの実装は Exchange では独立したアセットになるか、または同じ Exchange アセットの異なるバージョンになります。

メタデータ YAML ファイルには次の項目が含まれている必要があります。

  • Header (ヘッダー)

    #%Policy Implementation 1.0

  • テクノロジー

    mule4

  • Name (名前)

    実装の名前。

  • minRuntimeVersion

    実装バイナリが互換性を持つ最初のランタイムバージョンを表すセマンティックバージョン。たとえば、Mule バイナリは 4.3.0 以降とのみ互換性を持ちます。

  • supportedJavaVersions

    カスタムポリシーでサポートされる Java バージョンで、​「8」​、​「11」​、​「17」​のいずれかになります。1 つまたは複数のバージョンをリストできます。​supportedJavaVersions​ 項目を追加しない場合、ポリシーでは Java 8 のみがサポートされます。

YAML ファイルには ​Release notes​ を含めることもできます。

実装メタデータ YAML ファイルのコード例を示します。

#%Policy Implementation 1.0
minRuntimeVersion: 4.1.1
supportedJavaVersions: ["8", "11", "17"]
technology: mule4
name: Simple Auth Mule Implementation
releaseNotes: "<some notes here>"

実装バイナリファイルの作成

実装バイナリファイルは、Mule 4 ポリシーの場合は JAR ファイルです。このファイルは、すべての設定項目をサポートし、定義メタデータで記述されているように機能する必要があります。

パブリッシュしたポリシー定義へのポリシー実装ファイルの追加

カスタムポリシー定義アセットを Exchange にパブリッシュしたら、次はパブリッシュしたポリシーにポリシー実装ファイルを追加します。このステップにより、ポリシーがランタイムで使用できるようになります。必要な実装ファイルは、Mule 4 ランタイム用の JAR と YAML メタデータファイルです。

実装ファイルを追加する前に、ポリシーアセットが [Stable (安定)] 状態であることを確認してください。

Anypoint API Manager から API へのポリシーの適用

実装ファイルをパブリッシュしたら、API Manager でポリシーを API に適用できるようになります。ポリシーの適用については、Anypoint API Manager のドキュメントを参照してください。