--- schema_version: "1" id: 9a60d70f5ee2451fccf02840445c8c4f1886ed5ae948aea23ca10c02c794b8b5 title: ポリシースキーマ定義の作成 collection: mulesoft version: current locale: ja-jp portal_url: https://docs.salesforce.com/mulesoft/current/ja-jp/pdk/1.4/policies-pdk-create-schema-definition.md canonical_url: https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-create-schema-definition source_site: docs.mulesoft.com content_type: documentation content_hash: a6bd75ff565f092a8a9ae84934c054148a884a6e2b8cfd773ef2e27404631c63 description: MuleSoft Documentation Site release: "1.4" latest: false --- # ポリシースキーマ定義の作成 [gateway::policy-included-directory.adoc](#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`​ ファイルのコンテンツは次のとおりです。 ```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. [メタデータの定義](#define-metadata) 2. [パラメーターの定義](#define-parameters) 3. [Rust ソースコードでのカスタムパラメーターの使用](#use-custom-parameters-in-rust-source-code) ## [](#define-metadata)メタデータの定義 metadata セクションに表示ラベルを追加することで、ポリシーを適用したときに UI に表示されるデータをわかりやすくすることができます。 メタデータを定義するには、​`gcl.yaml`​ ファイルの ​`metadata`​ セクションを編集します。 サポートされる表示ラベルは次のとおりです。 - `title`​: UI に表示されるポリシー名。 - `description`​: ポリシー動作の簡単な説明。 - `category`​: ポリシーのカテゴリ。設定できるカテゴリは、​`security`​、​`compliance`​、​`transformation`​、​`quality of service`​、​`troubleshooting`​ です。 例: ```yaml metadata: labels: title: JSON Threat Protection description: Protects against malicious JSON in API requests. category: Security ``` `labels`​ は推奨されますが、必須ではありません。 ## [](#define-outbound-policies)アウトバウンドポリシーの定義 デフォルトでは、PDK はインバウンドポリシーとしてポリシーを作成します。アウトバウンドポリシーを作成するには、​`gcl.yaml`​ ファイルの ​`labels`​ セクションを編集します。次のような ​`metadata/capabilities/injectionPoint: outbound`​ 表示ラベルを追加します。 ```yaml metadata: labels: title: My Outbound Policy description: An outbound security policy category: Security metadata/capabilities/injectionPoint: outbound ``` ## [](#define-parameters)パラメーターの定義 パラメーターを追加するには、​`gcl.yaml`​ ファイルの ​`spec.properties`​ セクションを編集します。 例: ```yaml properties: username: type: string password: type: string ``` プロパティを定義した後は、以下を行うことができます。 - [\[define-required-properties-and-default-values\]](#define-required-properties-and-default-values) - [サポートされる種別の定義](#define-supported-types) ### [](#必須プロパティとデフォルト値の定義)必須プロパティとデフォルト値の定義 `gcl.yaml`​ ファイルにリストされている各プロパティを ​`required`​ (必須) として定義し、そのプロパティの ​`default`​ (デフォルト) 値を設定できます。 プロパティを必須として定義するには、​`spec.required`​ オブジェクトにリストします。たとえば、次のポリシーでは ​`password`​ は必須ですが、​`username`​ は必須ではありません。 ```yaml properties: username: type: string password: type: string required: - password ``` 上の設定例のポリシーを適用する際にパスワードを指定しないと、設定はエラーとなります。 次の例では、各プロパティのデフォルト値を定義しています。 ```yaml 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`​ 特性を追加することで、パスワードや証明書などの機密データを保護します。 ```yaml properties: key: type: string default: "YourKey" "@context": { "@characteristics": [ "security:sensitive" ] } ``` ポリシーを適用すると、機密データへの入力値はユーザーには表示されません。 ![重要なパラメーターへの文字入力は黒いドットとして表示されます。](/mulesoft/current/ja-jp/pdk/1.4/_images/sensitive-data.png) **\[表示\]**​ を切り替えると、入力中のデータが表示されます。ただし、すでに保存済みのデータは表示できません。たとえば、上の例の ​**key**​ パラメーターを設定してポリシーを適用した場合、後でポリシーの設定を編集するときにはパラメーターの値を表示することはできません。 ### [](#define-conditional-parameters)条件付きパラメーターの定義 項目を表示する条件を確立して、ポリシー設定パラメーターを動的に表示します。次のコード例では、ユーザーが ​`encryptBody`​ パラメーターで ​`true`​ を選択すると、​`encryptionKey`​ パラメーターが表示されます。 ```yaml properties: encryptBody: type: boolean default: false encryptionKey: type: string "@rendering": "@visibleOn": - property: encryptBody value: true ``` 次のコード例では、​`encryptionKey`​ パラメーターは最初に表示されますが、ユーザーが ​`encryptBody`​ パラメーターで ​`false`​ を選択すると非表示になります。 ```yaml properties: encryptBody: type: boolean default: true encryptionKey: type: string "@rendering": "@visibleOn": - property: encryptBody value: true ``` 条件付きパラメーターには、次の制限があります。 - パラメーターごとに定義できる条件は 1 つのみです。 - 条件パラメーターとしてサポートされているのは、​`string`​、​`boolean`​、または ​`integer`​ パラメーターのみです。 - 条件付きで表示されるパラメーターを ​`object`​ または ​`enum`​ にすることはできません。 - 条件付きで表示される必須プロパティには、デフォルト値が定義されている必要があります。上記の例では、​`encryptionKey`​ が必須であれば、デフォルト値が必要です。 - 条件付き表示をサポートしているのは、ルートレベルのパラメーターのみです。配列またはオブジェクトの内部プロパティは、条件付き表示をサポートしていません。 ### [](#define-enumerated-variables)列挙されたパラメーターの定義 次に示すように、​`enum`​ プロパティでパラメーターを定義してユーザーの入力値を制限します。 ```yaml properties: signingMethod: type: string enum: - rsa - hmac ``` API Manager UI では、​`enum`​ パラメーターは、列挙された値が 3 個までであればラジオボタンとして、それより多い場合はドロップダウン項目として表示されます。ローカルモードで実行されている Flex Gateway の場合、ユーザーはパラメーターを列挙された値の 1 つとして設定する必要があり、設定しなければポリシー設定は失敗します。 列挙されたパラメーターは、​`@visibleOn`​ タグをサポートしていません。変数を動的に表示する方法についての詳細は、​[条件付きパラメーターの定義](#define-conditional-parameters)​を参照してください。 ### [](#define-supported-types)サポートされる種別の定義 ポリシーに正しいデータが入力されることを保証するため、各ポリシーパラメーターでサポートされるデータ型を定義します。 サポートされる種別は次のとおりです。 String (文字列) 文字列型は、データがテキストであることを指定します。 ```yaml properties: password: type: string ``` `string`​ 型では、​`format`​ (形式) 種別も設定できます。 サポートされる形式種別は次のとおりです。 - `dataweave`​: 入力パラメーターが DataWeave 変数であることを指定し、入力を変換する用に Flex Gateway に指示します。DataWeave 式の詳細については、​[DataWeave 式の定義](#dataweave-expressions)​を参照してください。 - `service`​: 入力パラメーターが URI であることを指定し、ポリシーからの HTTP コールを有効にするための Flex Gateway サービスを作成します。 - `ipRange`​: 想定されるテキストが IP 範囲であることを指定し、入力に対して追加の検証を行います。 - `uri`​: 想定されるテキストが URI であることを指定し、入力に対して追加の検証を行います。​`uri`​ は、URI がポリシーから HTTP コールを実行するサービスではない場合にのみ使用してください。 次の yaml スニペットは、すべての文字列形式を設定しています。 ```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`​ 型は、データが浮動小数点値であることを指定します。 例: ```yaml properties: squareRoot: type: number default: 1.414213562 seconds: type: number default: 10 ``` Integer (整数) `integer`​ 型は、データが整数値であることを指定します。 例: ```yaml properties: maxHeaders: type: integer default: 10 ``` Boolean (ブール) `boolean`​ 型は、データがブール値であることを指定します。サポートされる値は ​`true`​ または ​`false`​ です。 例: ```yaml properties: skipValidation: type: boolean default: false requireCredentials: type: boolean default: true ``` Array (配列) `array`​ 型は、データが順序付き要素のリストであることを指定します。​`array`​ 型を使用する場合は、配列に含まれる項目のデータ型を ​`items.type`​ で指定する必要もあります。 例: ```yaml properties: scopes: type: array items: type: string default: ["READ", "WRITE"] ``` Object (オブジェクト) `object`​ 型は、データが複数のプロパティを持つ順序付き要素のリストであることを指定します。​`object`​ 型を使用する場合は、オブジェクトの各要素に対して ​`properties.type`​ を指定する必要もあります。 例: ```yaml properties: user: type: object properties: id: type: string name: type: string required: - id - name default: {"id": "1", "name": "John Doe"} ``` ### [](#dataweave-expressions)DataWeave 式の定義 `string`​ 型のパラメーターの ​`dataweave`​ 形式は、入力パラメーターが DataWeave 式であることを指定します。 `dataweave`​ 変数は、次のように式のバインドをサポートします。 ```yaml : type: string format: dataweave bindings: payload: mimeType: text attributes: true authentication: false vars: [] ``` - `payload`​: 受信要求のボディ。​`mimeType`​ を ​`text`​、​`json`​、または ​`xml`​ のいずれかに定義することで、ペイロードの読み取り方法を設定します。デフォルトでは、​`mimeType`​ は ​`text`​ に設定されます。​`content-type`​ ヘッダーがエバリュエーターにバインドされている場合、ペイロードは ​`content-type`​ ヘッダーの値に従って解釈されます。​`payload`​ 変数の使用を制限するには、payload 変数を次の例のように除外します。 ```yaml bindings: attributes: true authentication: false vars: [] ``` - `attributes`​: 受信要求の属性 (ヘッダーなど)。ポリシーで受信要求から属性を読み取るようにするには、​`attributes`​ を ​`true`​ に設定します。デフォルトでは、​`attributes`​ は ​`true`​ に設定されます。 - `authentication`​: 受信要求の認証情報。ポリシーで受信要求から認証の詳細を読み取るようにするには、​`authentication`​ を ​`true`​ に設定します。デフォルトでは、​`authentication`​ は ​`false`​ に設定されます。 - `vars`​: ポリシーが使用できる変数の名前を指定します。デフォルトでは、​`vars`​ は空です。ポリシーの適用時に、スキーマで定義されていない変数を入力すると、ポリシーはその変数を ​`null`​ として評価します。 サポートされている式のバインドについては、[Predefined Variables](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context)を参照してください。 ポリシーの適用時に、ユーザーの式にポリシーのスキーマで定義されていないバインドが含まれている場合、ポリシーの設定は失敗します。たとえば、ユーザーの式が ​`[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 式の実装)」](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features#use-dataweave-expressions)​を参照してください。 Flex Gateway での DataWeave サポートについての詳細は、[DataWeave Support in Omni Gateway Policies](https://docs.mulesoft.com/gateway/latest/policies-dataweave-support)を参照してください。 ## [](#use-custom-parameters-in-rust-source-code)Rust ソースコードでのカスタムパラメーターの使用 `gcl.yaml`​ ファイルを変更したら、次のいずれかのコマンドを実行して、​`src/generated/config.rs`​ rust ファイルと API Manager UI 用の JSON スキーマに変更を反映させます。 - `make build-asset-files`​ は ​`src/generated/config.rs`​ に変更を反映させるのみです。 ```cmd make build-asset-files ``` - `make build`​ は変更を ​`src/generated/config.rs`​ に変更を反映させてから、ポリシーのターゲットファイルを生成します。ポリシーのターゲットファイルを上書きしたくない場合は、​`make build`​ を実行しないでください。 ```cmd make build ``` ポリシーのコンパイルの詳細については、[カスタムポリシーのコンパイル](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-compile-policies)を参照してください。 `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`​: ```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`​: ```rust pub struct Config { #[serde(alias = "max_chars")] pub max_chars: Option, #[serde(alias = "reject_missing_tokens")] pub reject_missing_tokens: Option, #[serde(alias = "tokenExtractor")] pub token_extractor: pdk::script::Script, } ``` `entrypoint`​ 関数で ​`.operators`​ を次のように使用することで、​`struct Config`​ の値にアクセスできます。 ```rust #[entrypoint] async fn configure(launcher: Launcher, Configuration(configuration): Configuration,) -> Result<(), LaunchError> { let config: Config = serde_json::from_slice(&configuration)?; match config.reject_missing_tokens { ``` ## [](#関連情報)関連情報 - [PDK のトラブルシューティング](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-troubleshooting)