# mulesoft Omni Gateway Policy Development Kit (PDK) (pdk) - Full Documentation # CORS ライブラリ関数の使用
Flex Gateway ポリシー開発キット (PDK) のクロスオリジンリソース共有 (CORS) ライブラリを使用したポリシープロジェクトの例は、 「CORS Validation Policy Example (CORS 検証ポリシーの例)」​を参照してください。
CORS は、Web アプリケーションが別のドメインで定義されたリソースにアクセスするためのメカニズムです。ブラウザーでは、デフォルトで CORS がサポートされています。PDK CORS ライブラリは、 [CORS W3C 勧告](https://fetch.spec.whatwg.org/)​の標準に準拠しており、受信要求を検証してリソースを保護する一連のツールが用意されています。 ## [](#cors-configuration)CORS 設定インスタンスを定義する CORS ライブラリは、​`pdk::cors`​ モジュールから使用できます。このモジュールでは、受信要求の検証メソッドを定義するための ​`cors::Configuration`​、​`cors::OriginGroup`​、​`cors::AllowedMethod`​ 構造とそれらのビルダーが提供されます。たとえば、次のコードスニペットでは、​`cors::Configuration`​ インスタンスをハードコード化する関数を定義します。 ```Rust use pdk::cors; fn create_cors_configuration() -> cors:Configuration { cors::Configuration::builder() .public_resource(false) .support_credentials(true) .origin_groups(vec![cors::OriginGroup::builder() .origin_group_name("default group".to_string()) .plain_origins(vec!["http://www.the-origin-of-time.com".to_string()]) .access_control_max_age(60) .headers(vec![ "x-allow-origin".to_string(), "x-yet-another-valid-header".to_string(), ]) .exposed_headers(vec!["x-forwarded-for".to_string()]) .allowed_methods(vec![ cors::AllowedMethod::builder() .method_name("POST".to_string()) .allowed(true) .build() .unwrap(), cors::AllowedMethod::builder() .method_name("PUT".to_string()) .allowed(true) .build() .unwrap(), ]) .build() .unwrap()]) .build() .unwrap(); } ``` ### [](#configuration-methods)cors::Configuration 構造の設定パラメーター
プロパティ 必須または省略可能 デフォルト値 説明

origin_groups

省略可能

空の ​Vec

cors::OriginGroup​ で設定可能なオリジンのグループが含まれる ​Vec​。

public_resource

省略可能

false

CORS 設定が公開リソースとして適用されるかどうかを示すブール値。

support_credentials

省略可能

false

CORS 設定が Cookie、認証ヘッダー、TLS クライアント証明書などのログイン情報をサポートするかどうかを示すブール値。
### [](#origin-group-methods)cors::OriginGroup 構造の設定パラメーター
プロパティ 必須または省略可能 デフォルト値 説明

plain_origins

省略可能

空の ​Vec

グループに含まれるオリジンの ​Vec​。例: http://www.the-origin-of-time.com​。

access_control_max_age

省略可能

30

新しいプレフライト要求を送信する前にプレフライト応答をキャッシュする期間 (秒)。

allowed_methods

省略可能

空の ​Vec

cors::AllowedMethod​ で設定可能な許可される HTTP メソッドの ​Vec​。

headers

省略可能

空の ​Vec

プレフライト要求の HTTP ヘッダーの ​Vec​。

exposed_headers

省略可能

空の ​Vec

ブラウザーの JavaScript でアクセスできるヘッダーの ​Vec​。
### [](#allowed-methods)cors::AllowedMethod 構造の設定パラメーター
プロパティ 必須または省略可能 説明

method_name

必須

メソッド名。

is_allowed

必須

メソッドが許可されるかどうかを示すブール値。サポートされている値は、​CONNECT​、​DELETE​、​GET​、​OPTIONS​、​PATCH​、​POST​、​PUT​、または ​TRACE​ です。
## [](#applying-cors-to-an-incoming-request)CORS 検証メソッド `cors::Cors`​ 構造には、指定された ​`cors::Configuration`​ インスタンスに対して受信ヘッダーを検証する ​`check_headers()`​ メソッドが含まれます。​`cors::Cors::check_headers()`​ メソッドは、​`Result`​ 構造を返します。CORS 検証に失敗した場合の結果は ​`Err`​ になります。検証に通過すると、要求は ​`Ok`​ になり、​`cors::Check`​ 構造を評価できます。 ### [](#corscheck-構造の使用可能なメソッド)`cors::Check`​ 構造の使用可能なメソッド
メソッド 種別 説明

response_type()

cors::ResponseType

受信要求に必要なアクションの種別が含まれる列挙を返します。列挙値についての詳細は、​cors::ResponseType​ 列挙応答値​を参照してください。

headers()

&[(String, String)]

応答に追加するヘッダーのリスト。

into_headers()

Vec<(String, String)>

cors::Check​ 構造をコンシュームして、応答に追加するヘッダーのリストを返します。
### [](#enum-response)`cors::ResponseType`​ 列挙応答値
値 説明

Preflight

受信要求は CORS プレフライト要求であるため、ポリシーで早期に応答する必要があります。

Main

受信要求は CORS メイン要求であるため、要求はアップストリームに進みます。
## [](#cors-検証ポリシーを記述する)CORS 検証ポリシーを記述する CORS 検証ポリシーを記述する手順は、次のとおりです。 1. `cors::Configuration`​ インスタンスを定義する ​`#[entrypoint]`​ 関数を定義します。次の例の ​`create_cors_configuration()`​ は、[CORS 設定インスタンスを定義する](#cors-configuration)の例で定義された関数です。 ```rust use pdk::*; use pdk::cors; #[entrypoint] async fn configure(launcher: Launcher) -> Result<(), LaunchError> { let cors_configuration = create_cors_configuration(); let filter = on_request(|rs| request_filter(rs, &cors_configuration)) .on_response(response_filter); launcher.launch(filter).await } ``` 2. CORS 検証メソッドを使用して受信要求を検証する ​`request_filter()`​ 関数を定義します。返される​`フロー`​には、​`cors::Cors::check_headers()`​ から返されたヘッダーを ​`response_filter()`​ に渡す ​`Vec<(String, String)>`​ が含まれている必要があります。 ```rust async fn request_filter( request_headers_state: RequestHeadersState, cors_configuration: &cors::Configuration<'_>, ) -> Flow> { // Create a new CORS checker. let cors = cors::Cors::new(cors_configuration); let request_headers = request_headers_state.handler().headers(); let cors_result = cors.check(&request_headers); match cors_result { // The CORS validation was succesful. Ok(cors_check) => match cors_check.response_type() { // A CORS preflight fetch was requested, return an early response. cors::ResponseType::Preflight => { Flow::Break(Response::new(200).with_headers(check.into_headers())) } // This is a CORS main request, continue and pass the headers to the response. cors::ResponseType::Main => { logger::info!("Main CORS response."); Flow::Continue(check.into_headers()) } }, // The CORS validation failed. The request must be refused. Err(cors_error) => { Flow::Break(Response::new(200)) } } } ``` 3. CORS 検証メソッドを使用して応答を検証する ​`response_filter()`​ 関数を定義します。 `RequestData`​ には、​`cors::Cors::check_headers()`​ で返されるヘッダーが含まれます。 ```rust async fn response_filter(state: ResponseHeadersState, data: RequestData>) { // Take the headers to add from the request data. let RequestData::Continue(headers_to_add) = data else { return; }; // Add the headers to the response for (name, value) in headers_to_add.iter() { state.handler().set_header(name, value); } } ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features) # CORS ライブラリ関数の使用
Flex Gateway ポリシー開発キット (PDK) のクロスオリジンリソース共有 (CORS) ライブラリを使用したポリシープロジェクトの例は、 「CORS Validation Policy Example (CORS 検証ポリシーの例)」​を参照してください。
CORS は、Web アプリケーションが別のドメインで定義されたリソースにアクセスするためのメカニズムです。ブラウザーでは、デフォルトで CORS がサポートされています。PDK CORS ライブラリは、 [CORS W3C 勧告](https://fetch.spec.whatwg.org/)​の標準に準拠しており、受信要求を検証してリソースを保護する一連のツールが用意されています。 ## [](#cors-configuration)CORS 設定インスタンスを定義する CORS ライブラリは、​`pdk::cors`​ モジュールから使用できます。このモジュールでは、受信要求の検証メソッドを定義するための ​`cors::Configuration`​、​`cors::OriginGroup`​、​`cors::AllowedMethod`​ 構造とそれらのビルダーが提供されます。たとえば、次のコードスニペットでは、​`cors::Configuration`​ インスタンスをハードコード化する関数を定義します。 ```Rust use pdk::cors; fn create_cors_configuration() -> cors:Configuration { cors::Configuration::builder() .public_resource(false) .support_credentials(true) .origin_groups(vec![cors::OriginGroup::builder() .origin_group_name("default group".to_string()) .plain_origins(vec!["http://www.the-origin-of-time.com".to_string()]) .access_control_max_age(60) .headers(vec![ "x-allow-origin".to_string(), "x-yet-another-valid-header".to_string(), ]) .exposed_headers(vec!["x-forwarded-for".to_string()]) .allowed_methods(vec![ cors::AllowedMethod::builder() .method_name("POST".to_string()) .allowed(true) .build() .unwrap(), cors::AllowedMethod::builder() .method_name("PUT".to_string()) .allowed(true) .build() .unwrap(), ]) .build() .unwrap()]) .build() .unwrap(); } ``` ### [](#configuration-methods)cors::Configuration 構造の設定パラメーター
プロパティ 必須または省略可能 デフォルト値 説明

origin_groups

省略可能

空の ​Vec

cors::OriginGroup​ で設定可能なオリジンのグループが含まれる ​Vec​。

public_resource

省略可能

false

CORS 設定が公開リソースとして適用されるかどうかを示すブール値。

support_credentials

省略可能

false

CORS 設定が Cookie、認証ヘッダー、TLS クライアント証明書などのログイン情報をサポートするかどうかを示すブール値。
### [](#origin-group-methods)cors::OriginGroup 構造の設定パラメーター
プロパティ 必須または省略可能 デフォルト値 説明

plain_origins

省略可能

空の ​Vec

グループに含まれるオリジンの ​Vec​。例: http://www.the-origin-of-time.com​。

access_control_max_age

省略可能

30

新しいプレフライト要求を送信する前にプレフライト応答をキャッシュする期間 (秒)。

allowed_methods

省略可能

空の ​Vec

cors::AllowedMethod​ で設定可能な許可される HTTP メソッドの ​Vec​。

headers

省略可能

空の ​Vec

プレフライト要求の HTTP ヘッダーの ​Vec​。

exposed_headers

省略可能

空の ​Vec

ブラウザーの JavaScript でアクセスできるヘッダーの ​Vec​。
### [](#allowed-methods)cors::AllowedMethod 構造の設定パラメーター
プロパティ 必須または省略可能 説明

method_name

必須

メソッド名。

is_allowed

必須

メソッドが許可されるかどうかを示すブール値。サポートされている値は、​CONNECT​、​DELETE​、​GET​、​OPTIONS​、​PATCH​、​POST​、​PUT​、または ​TRACE​ です。
## [](#applying-cors-to-an-incoming-request)CORS 検証メソッド `cors::Cors`​ 構造には、指定された ​`cors::Configuration`​ インスタンスに対して受信ヘッダーを検証する ​`check_headers()`​ メソッドが含まれます。​`cors::Cors::check_headers()`​ メソッドは、​`Result`​ 構造を返します。CORS 検証に失敗した場合の結果は ​`Err`​ になります。検証に通過すると、要求は ​`Ok`​ になり、​`cors::Check`​ 構造を評価できます。 ### [](#corscheck-構造の使用可能なメソッド)`cors::Check`​ 構造の使用可能なメソッド
メソッド 種別 説明

response_type()

cors::ResponseType

受信要求に必要なアクションの種別が含まれる列挙を返します。列挙値についての詳細は、​cors::ResponseType​ 列挙応答値​を参照してください。

headers()

&[(String, String)]

応答に追加するヘッダーのリスト。

into_headers()

Vec<(String, String)>

cors::Check​ 構造をコンシュームして、応答に追加するヘッダーのリストを返します。
### [](#enum-response)`cors::ResponseType`​ 列挙応答値
値 説明

Preflight

受信要求は CORS プレフライト要求であるため、ポリシーで早期に応答する必要があります。

Main

受信要求は CORS メイン要求であるため、要求はアップストリームに進みます。
## [](#cors-検証ポリシーを記述する)CORS 検証ポリシーを記述する CORS 検証ポリシーを記述する手順は、次のとおりです。 1. `cors::Configuration`​ インスタンスを定義する ​`#[entrypoint]`​ 関数を定義します。次の例の ​`create_cors_configuration()`​ は、[CORS 設定インスタンスを定義する](#cors-configuration)の例で定義された関数です。 ```rust use pdk::*; use pdk::cors; #[entrypoint] async fn configure(launcher: Launcher) -> Result<(), LaunchError> { let cors_configuration = create_cors_configuration(); let filter = on_request(|rs| request_filter(rs, &cors_configuration)) .on_response(response_filter); launcher.launch(filter).await } ``` 2. CORS 検証メソッドを使用して受信要求を検証する ​`request_filter()`​ 関数を定義します。返される​`フロー`​には、​`cors::Cors::check_headers()`​ から返されたヘッダーを ​`response_filter()`​ に渡す ​`Vec<(String, String)>`​ が含まれている必要があります。 ```rust async fn request_filter( request_headers_state: RequestHeadersState, cors_configuration: &cors::Configuration<'_>, ) -> Flow> { // Create a new CORS checker. let cors = cors::Cors::new(cors_configuration); let request_headers = request_headers_state.handler().headers(); let cors_result = cors.check(&request_headers); match cors_result { // The CORS validation was succesful. Ok(cors_check) => match cors_check.response_type() { // A CORS preflight fetch was requested, return an early response. cors::ResponseType::Preflight => { Flow::Break(Response::new(200).with_headers(check.into_headers())) } // This is a CORS main request, continue and pass the headers to the response. cors::ResponseType::Main => { logger::info!("Main CORS response."); Flow::Continue(check.into_headers()) } }, // The CORS validation failed. The request must be refused. Err(cors_error) => { Flow::Break(Response::new(200)) } } } ``` 3. CORS 検証メソッドを使用して応答を検証する ​`response_filter()`​ 関数を定義します。 `RequestData`​ には、​`cors::Cors::check_headers()`​ で返されるヘッダーが含まれます。 ```rust async fn response_filter(state: ResponseHeadersState, data: RequestData>) { // Take the headers to add from the request data. let RequestData::Continue(headers_to_add) = data else { return; }; // Add the headers to the response for (name, value) in headers_to_add.iter() { state.handler().set_header(name, value); } } ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features) # CORS ライブラリ関数の使用
Flex Gateway ポリシー開発キット (PDK) のクロスオリジンリソース共有 (CORS) ライブラリを使用したポリシープロジェクトの例は、 「CORS Validation Policy Example (CORS 検証ポリシーの例)」​を参照してください。
CORS は、Web アプリケーションが別のドメインで定義されたリソースにアクセスするためのメカニズムです。ブラウザーでは、デフォルトで CORS がサポートされています。PDK CORS ライブラリは、 [CORS W3C 勧告](https://fetch.spec.whatwg.org/)​の標準に準拠しており、受信要求を検証してリソースを保護する一連のツールが用意されています。 ## [](#cors-configuration)CORS 設定インスタンスを定義する CORS ライブラリは、​`pdk::cors`​ モジュールから使用できます。このモジュールでは、受信要求の検証メソッドを定義するための ​`cors::Configuration`​、​`cors::OriginGroup`​、​`cors::AllowedMethod`​ 構造とそれらのビルダーが提供されます。たとえば、次のコードスニペットでは、​`cors::Configuration`​ インスタンスをハードコード化する関数を定義します。 ```Rust use pdk::cors; fn create_cors_configuration() -> cors:Configuration { cors::Configuration::builder() .public_resource(false) .support_credentials(true) .origin_groups(vec![cors::OriginGroup::builder() .origin_group_name("default group".to_string()) .plain_origins(vec!["http://www.the-origin-of-time.com".to_string()]) .access_control_max_age(60) .headers(vec![ "x-allow-origin".to_string(), "x-yet-another-valid-header".to_string(), ]) .exposed_headers(vec!["x-forwarded-for".to_string()]) .allowed_methods(vec![ cors::AllowedMethod::builder() .method_name("POST".to_string()) .allowed(true) .build() .unwrap(), cors::AllowedMethod::builder() .method_name("PUT".to_string()) .allowed(true) .build() .unwrap(), ]) .build() .unwrap()]) .build() .unwrap(); } ``` ### [](#configuration-methods)cors::Configuration 構造の設定パラメーター
プロパティ 必須または省略可能 デフォルト値 説明

origin_groups

省略可能

空の ​Vec

cors::OriginGroup​ で設定可能なオリジンのグループが含まれる ​Vec​。

public_resource

省略可能

false

CORS 設定が公開リソースとして適用されるかどうかを示すブール値。

support_credentials

省略可能

false

CORS 設定が Cookie、認証ヘッダー、TLS クライアント証明書などのログイン情報をサポートするかどうかを示すブール値。
### [](#origin-group-methods)cors::OriginGroup 構造の設定パラメーター
プロパティ 必須または省略可能 デフォルト値 説明

plain_origins

省略可能

空の ​Vec

グループに含まれるオリジンの ​Vec​。例: http://www.the-origin-of-time.com​。

access_control_max_age

省略可能

30

新しいプレフライト要求を送信する前にプレフライト応答をキャッシュする期間 (秒)。

allowed_methods

省略可能

空の ​Vec

cors::AllowedMethod​ で設定可能な許可される HTTP メソッドの ​Vec​。

headers

省略可能

空の ​Vec

プレフライト要求の HTTP ヘッダーの ​Vec​。

exposed_headers

省略可能

空の ​Vec

ブラウザーの JavaScript でアクセスできるヘッダーの ​Vec​。
### [](#allowed-methods)cors::AllowedMethod 構造の設定パラメーター
プロパティ 必須または省略可能 説明

method_name

必須

メソッド名。

is_allowed

必須

メソッドが許可されるかどうかを示すブール値。サポートされている値は、​CONNECT​、​DELETE​、​GET​、​OPTIONS​、​PATCH​、​POST​、​PUT​、または ​TRACE​ です。
## [](#applying-cors-to-an-incoming-request)CORS 検証メソッド `cors::Cors`​ 構造には、指定された ​`cors::Configuration`​ インスタンスに対して受信ヘッダーを検証する ​`check_headers()`​ メソッドが含まれます。​`cors::Cors::check_headers()`​ メソッドは、​`Result`​ 構造を返します。CORS 検証に失敗した場合の結果は ​`Err`​ になります。検証に通過すると、要求は ​`Ok`​ になり、​`cors::Check`​ 構造を評価できます。 ### [](#corscheck-構造の使用可能なメソッド)`cors::Check`​ 構造の使用可能なメソッド
メソッド 種別 説明

response_type()

cors::ResponseType

受信要求に必要なアクションの種別が含まれる列挙を返します。列挙値についての詳細は、​cors::ResponseType​ 列挙応答値​を参照してください。

headers()

&[(String, String)]

応答に追加するヘッダーのリスト。

into_headers()

Vec<(String, String)>

cors::Check​ 構造をコンシュームして、応答に追加するヘッダーのリストを返します。
### [](#enum-response)`cors::ResponseType`​ 列挙応答値
値 説明

Preflight

受信要求は CORS プレフライト要求であるため、ポリシーで早期に応答する必要があります。

Main

受信要求は CORS メイン要求であるため、要求はアップストリームに進みます。
## [](#cors-検証ポリシーを記述する)CORS 検証ポリシーを記述する CORS 検証ポリシーを記述する手順は、次のとおりです。 1. `cors::Configuration`​ インスタンスを定義する ​`#[entrypoint]`​ 関数を定義します。次の例の ​`create_cors_configuration()`​ は、[CORS 設定インスタンスを定義する](#cors-configuration)の例で定義された関数です。 ```rust use pdk::*; use pdk::cors; #[entrypoint] async fn configure(launcher: Launcher) -> Result<(), LaunchError> { let cors_configuration = create_cors_configuration(); let filter = on_request(|rs| request_filter(rs, &cors_configuration)) .on_response(response_filter); launcher.launch(filter).await } ``` 2. CORS 検証メソッドを使用して受信要求を検証する ​`request_filter()`​ 関数を定義します。返される​`フロー`​には、​`cors::Cors::check_headers()`​ から返されたヘッダーを ​`response_filter()`​ に渡す ​`Vec<(String, String)>`​ が含まれている必要があります。 ```rust async fn request_filter( request_headers_state: RequestHeadersState, cors_configuration: &cors::Configuration<'_>, ) -> Flow> { // Create a new CORS checker. let cors = cors::Cors::new(cors_configuration); let request_headers = request_headers_state.handler().headers(); let cors_result = cors.check(&request_headers); match cors_result { // The CORS validation was succesful. Ok(cors_check) => match cors_check.response_type() { // A CORS preflight fetch was requested, return an early response. cors::ResponseType::Preflight => { Flow::Break(Response::new(200).with_headers(check.into_headers())) } // This is a CORS main request, continue and pass the headers to the response. cors::ResponseType::Main => { logger::info!("Main CORS response."); Flow::Continue(check.into_headers()) } }, // The CORS validation failed. The request must be refused. Err(cors_error) => { Flow::Break(Response::new(200)) } } } ``` 3. CORS 検証メソッドを使用して応答を検証する ​`response_filter()`​ 関数を定義します。 `RequestData`​ には、​`cors::Cors::check_headers()`​ で返されるヘッダーが含まれます。 ```rust async fn response_filter(state: ResponseHeadersState, data: RequestData>) { // Take the headers to add from the request data. let RequestData::Continue(headers_to_add) = data else { return; }; // Add the headers to the response for (name, value) in headers_to_add.iter() { state.handler().set_header(name, value); } } ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features) # DataWeave 式の使用
DataWeave 式を使用するポリシープロジェクトの例は、 「クエリポリシーの例」​を参照してください。
入力 DataWeave 式パラメーターが有効な場合、ポリシーは式を解析して ​`pdk::script::Script`​ 式に変換します。スクリプトの結果を得る手順は次のとおりです。 1. Evaluator を作成します。 2. スキーマ定義で定義されている各パラメーターのバインディング関数を呼び出します。 - `vars`​: 各ポリシーの ​`vars`​ の ​`bind_vars`​ メソッドを呼び出します。すべての ​`vars`​ がバインドされた後、Evaluator は式の解決を試みます。式にスキーマで定義されている以外の ​`vars`​ が含まれている場合、それらは ​`null`​ に解決されます。 - `attributes`​: `bind_attributes`​ メソッドを ​`AttributesBinding`​ trait の実装で呼び出します。Flex Gateway ポリシー開発キット (PDK) は、​`RequestHeaderState`​、​`RequestHeaderState`​、および ​[HTTP コール](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-http-request)​の応答のそれぞれに対して新しい ​`HandlerAttributesBinding`​ をインスタンス化することで、この trait を実装します。 - `authentication`​: `bind_authentication`​ メソッドを ​`AuthenticationBinding`​ trait の実装で呼び出します。PDK は、​`AuthenticationData`​ に対してこの trait を実装しています。ポリシーに認証情報を挿入するには、​[「認証情報の挿入」](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-inject-parameters#authentication)​を参照してください。 - `payload`​: `bind_payload`​ メソッドを ​`PayloadBinding`​ の実装で呼び出します。PDK は、​`RequestBodyState`​、​`ResponseBodyState`​、および ​[HTTP コール](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-http-request)​の応答に対して、この trait の実装を提供します。

スキーマ定義で定義されているバインディングのメソッドのみを呼び出します。たとえば、​attributes​ バインディングを使用しない場合は、​bind_attributes​ メソッドを呼び出さないでください。

DataWeave 式の定義の詳細については、​「DataWeave 式」​を参照してください。
3. すべての式変数をバインドしたら、​`eval`​ メソッドを呼び出して結果を取得します。 ## [](#example-evaluator-code)DataWeave 式の評価 たとえば、次のポリシースキーマ定義の ​`tokenExtractor`​ DataWeave 式を評価する手順は、次のとおりです。 ```yaml apiVersion: gateway.mulesoft.com/v1alpha1 kind: Extension metadata: labels: title: jwt-auth category: Custom spec: extends: - name: extension-definition namespace: default properties: tokenExtractor: type: string format: dataweave default: "#[vars.myVar]" bindings: payload: mimeType: text attributes: true authentication: true vars: - myVar required: - tokenExtractor ``` 以下の Rust スニペットを使用します。 ```rust // Copyright 2024 Salesforce, Inc. All rights reserved. mod generated; use anyhow::Result; use crate::generated::config::Config; use pdk::authentication::{Authentication, AuthenticationHandler}; use pdk::logger::info; use pdk::hl::*; use pdk::script::{Evaluator, HandlerAttributesBinding, Value}; async fn request_filter( state: RequestState, stream: StreamProperties, auth: Authentication, mut evaluator: Evaluator<'_>, ) { evaluator.bind_vars("myVar", "myVal"); evaluator.bind_authentication(&auth.authentication()); let state = state.into_headers_state().await; evaluator.bind_attributes(&HandlerAttributesBinding::new(state.handler(), &stream)); let state = state.into_body_state().await; evaluator.bind_payload(&state); if let Ok(value) = evaluator.eval() { match value { Value::Null => info!("value was null!"), Value::Bool(val) => info!("value was Bool: {val}"), Value::Number(val) => info!("value was Number: {val}"), Value::String(val) => info!("value was String: {val}"), Value::Array(val) => info!("value was Array: {val:?}"), Value::Object(val) => info!("value was Object: {val:?}"), } } } #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&bytes)?; launcher .launch(on_request(|request, stream, auth| { request_filter(request, stream, auth, config.token_extractor.evaluator()) })) .await?; Ok(()) } ``` ## [](#式が解決されたことの確認)式が解決されたことの確認 すべての値がバインドされる前に、いくつかの式を解決することができます。たとえば、​`#[vars.myVar]`​ という式を解決するためには、​`attributes`​、​`payload`​、そしていずれの ​`authentication`​ も解決する必要はありません。 バインディングメソッドのいずれかが呼び出された後、そのメソッドを呼び出すことで、式が完全に解決されたことを確認できます。 ```rust evaluator.is_ready() ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features) # DataWeave 式の使用
DataWeave 式を使用するポリシープロジェクトの例は、 「クエリポリシーの例」​を参照してください。
入力 DataWeave 式パラメーターが有効な場合、ポリシーは式を解析して ​`pdk::script::Script`​ 式に変換します。スクリプトの結果を得る手順は次のとおりです。 1. Evaluator を作成します。 2. スキーマ定義で定義されている各パラメーターのバインディング関数を呼び出します。 - `vars`​: 各ポリシーの ​`vars`​ の ​`bind_vars`​ メソッドを呼び出します。すべての ​`vars`​ がバインドされた後、Evaluator は式の解決を試みます。式にスキーマで定義されている以外の ​`vars`​ が含まれている場合、それらは ​`null`​ に解決されます。 - `attributes`​: `bind_attributes`​ メソッドを ​`AttributesBinding`​ trait の実装で呼び出します。Flex Gateway ポリシー開発キット (PDK) は、​`RequestHeaderState`​、​`RequestHeaderState`​、および ​[HTTP コール](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-http-request)​の応答のそれぞれに対して新しい ​`HandlerAttributesBinding`​ をインスタンス化することで、この trait を実装します。 - `authentication`​: `bind_authentication`​ メソッドを ​`AuthenticationBinding`​ trait の実装で呼び出します。PDK は、​`AuthenticationData`​ に対してこの trait を実装しています。ポリシーに認証情報を挿入するには、​[「認証情報の挿入」](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-inject-parameters#authentication)​を参照してください。 - `payload`​: `bind_payload`​ メソッドを ​`PayloadBinding`​ の実装で呼び出します。PDK は、​`RequestBodyState`​、​`ResponseBodyState`​、および ​[HTTP コール](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-http-request)​の応答に対して、この trait の実装を提供します。

スキーマ定義で定義されているバインディングのメソッドのみを呼び出します。たとえば、​attributes​ バインディングを使用しない場合は、​bind_attributes​ メソッドを呼び出さないでください。

DataWeave 式の定義の詳細については、​「DataWeave 式」​を参照してください。
3. すべての式変数をバインドしたら、​`eval`​ メソッドを呼び出して結果を取得します。 ## [](#example-evaluator-code)DataWeave 式の評価 たとえば、次のポリシースキーマ定義の ​`tokenExtractor`​ DataWeave 式を評価する手順は、次のとおりです。 ```yaml apiVersion: gateway.mulesoft.com/v1alpha1 kind: Extension metadata: labels: title: jwt-auth category: Custom spec: extends: - name: extension-definition namespace: default properties: tokenExtractor: type: string format: dataweave default: "#[vars.myVar]" bindings: payload: mimeType: text attributes: true authentication: true vars: - myVar required: - tokenExtractor ``` 以下の Rust スニペットを使用します。 ```rust // Copyright 2024 Salesforce, Inc. All rights reserved. mod generated; use anyhow::Result; use crate::generated::config::Config; use pdk::authentication::{Authentication, AuthenticationHandler}; use pdk::logger::info; use pdk::hl::*; use pdk::script::{Evaluator, HandlerAttributesBinding, Value}; async fn request_filter( state: RequestState, stream: StreamProperties, auth: Authentication, mut evaluator: Evaluator<'_>, ) { evaluator.bind_vars("myVar", "myVal"); evaluator.bind_authentication(&auth.authentication()); let state = state.into_headers_state().await; evaluator.bind_attributes(&HandlerAttributesBinding::new(state.handler(), &stream)); let state = state.into_body_state().await; evaluator.bind_payload(&state); if let Ok(value) = evaluator.eval() { match value { Value::Null => info!("value was null!"), Value::Bool(val) => info!("value was Bool: {val}"), Value::Number(val) => info!("value was Number: {val}"), Value::String(val) => info!("value was String: {val}"), Value::Array(val) => info!("value was Array: {val:?}"), Value::Object(val) => info!("value was Object: {val:?}"), } } } #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&bytes)?; launcher .launch(on_request(|request, stream, auth| { request_filter(request, stream, auth, config.token_extractor.evaluator()) })) .await?; Ok(()) } ``` ## [](#式が解決されたことの確認)式が解決されたことの確認 すべての値がバインドされる前に、いくつかの式を解決することができます。たとえば、​`#[vars.myVar]`​ という式を解決するためには、​`attributes`​、​`payload`​、そしていずれの ​`authentication`​ も解決する必要はありません。 バインディングメソッドのいずれかが呼び出された後、そのメソッドを呼び出すことで、式が完全に解決されたことを確認できます。 ```rust evaluator.is_ready() ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features) # DataWeave 式の使用
DataWeave 式を使用するポリシープロジェクトの例は、 「DataWeave ポリシーの例」​を参照してください。
入力 DataWeave 式パラメーターが有効な場合、ポリシーは式を解析して ​`pdk::script::Script`​ 式に変換します。スクリプトの結果を得る手順は次のとおりです。 1. Evaluator を作成します。 2. スキーマ定義で定義されている各パラメーターのバインディング関数を呼び出します。 - `vars`​: 各ポリシーの ​`vars`​ の ​`bind_vars`​ メソッドを呼び出します。すべての ​`vars`​ がバインドされた後、Evaluator は式の解決を試みます。式にスキーマで定義されている以外の ​`vars`​ が含まれている場合、それらは ​`null`​ に解決されます。 - `attributes`​: `bind_attributes`​ メソッドを ​`AttributesBinding`​ trait の実装で呼び出します。Flex Gateway ポリシー開発キット (PDK) は、​`RequestHeaderState`​、​`RequestHeaderState`​、および ​[HTTP コール](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-http-request)​の応答のそれぞれに対して新しい ​`HandlerAttributesBinding`​ をインスタンス化することで、この trait を実装します。 - `authentication`​: `bind_authentication`​ メソッドを ​`AuthenticationBinding`​ trait の実装で呼び出します。PDK は、​`AuthenticationData`​ に対してこの trait を実装しています。ポリシーに認証情報を挿入するには、​[「認証情報の挿入」](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-inject-parameters#authentication)​を参照してください。 - `payload`​: `bind_payload`​ メソッドを ​`PayloadBinding`​ の実装で呼び出します。PDK は、​`RequestBodyState`​、​`ResponseBodyState`​、および ​[HTTP コール](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-http-request)​の応答に対して、この trait の実装を提供します。

スキーマ定義で定義されているバインディングのメソッドのみを呼び出します。たとえば、​attributes​ バインディングを使用しない場合は、​bind_attributes​ メソッドを呼び出さないでください。

DataWeave 式の定義の詳細については、​「DataWeave 式」​を参照してください。
3. すべての式変数をバインドしたら、​`eval`​ メソッドを呼び出して結果を取得します。 ## [](#example-evaluator-code)DataWeave 式の評価 たとえば、次のポリシースキーマ定義の ​`tokenExtractor`​ DataWeave 式を評価する手順は、次のとおりです。 ```yaml apiVersion: gateway.mulesoft.com/v1alpha1 kind: Extension metadata: labels: title: jwt-auth category: Custom spec: extends: - name: extension-definition namespace: default properties: tokenExtractor: type: string format: dataweave default: "#[vars.myVar]" bindings: payload: mimeType: text attributes: true authentication: true vars: - myVar required: - tokenExtractor ```

Flex Gateway では、バイナリ型の結果を伴う DataWeave 式はサポートされません。​dw::Binaries::fromBase64('dXNlcjpwYXNz')​ 関数を使用するには、結果を文字列に変換してください。​dw::util::Coercions::toString(binary: Binary, encoding: String): String​ 関数を使用してバイナリ出力を文字列に変換します。たとえば、​[dw::util::Coercions::toString(dw::core::Binaries::fromBase64('dXNlcjpwYXNz'), 'UTF-8')]​ となります。デフォルトで ​[splitBy(dw::core::Binaries::fromBase64('dXNlcjpwYXNz'), ':')]​ などのバイナリを変換する別の関数を使用している場合は、バイナリの手動変換をスキップできます。
以下の Rust スニペットを使用します。 ```rust // Copyright 2024 Salesforce, Inc. All rights reserved. mod generated; use anyhow::Result; use crate::generated::config::Config; use pdk::authentication::{Authentication, AuthenticationHandler}; use pdk::logger::info; use pdk::hl::*; use pdk::script::{Evaluator, HandlerAttributesBinding, Value}; async fn request_filter( state: RequestState, stream: StreamProperties, auth: Authentication, mut evaluator: Evaluator<'_>, ) { evaluator.bind_vars("myVar", "myVal"); evaluator.bind_authentication(&auth.authentication()); let state = state.into_headers_state().await; evaluator.bind_attributes(&HandlerAttributesBinding::new(state.handler(), &stream)); let state = state.into_body_state().await; evaluator.bind_payload(&state); if let Ok(value) = evaluator.eval() { match value { Value::Null => info!("value was null!"), Value::Bool(val) => info!("value was Bool: {val}"), Value::Number(val) => info!("value was Number: {val}"), Value::String(val) => info!("value was String: {val}"), Value::Array(val) => info!("value was Array: {val:?}"), Value::Object(val) => info!("value was Object: {val:?}"), } } } #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&bytes)?; launcher .launch(on_request(|request, stream, auth| { request_filter(request, stream, auth, config.token_extractor.evaluator()) })) .await?; Ok(()) } ``` ## [](#式が解決されたことの確認)式が解決されたことの確認 すべての値がバインドされる前に、いくつかの式を解決することができます。たとえば、​`#[vars.myVar]`​ という式を解決するためには、​`attributes`​、​`payload`​、そしていずれの ​`authentication`​ も解決する必要はありません。 バインディングメソッドのいずれかが呼び出された後、そのメソッドを呼び出すことで、式が完全に解決されたことを確認できます。 ```rust evaluator.is_ready() ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features) # Exchange へのカスタムポリシーのアップロード カスタムポリシーの開発サイクルでは、ポリシーを Exchange にアップロードして新しい Exchange アセットを作成し、ポリシーのバージョンを管理したり、他のユーザーに配布したりできます。Exchange についての詳細は、[Anypoint Exchange の概要](https://docs.mulesoft.com/jp/exchange/)を参照してください。 ローカルモードで実行されるカスタムポリシーは、Exchange にパブリッシュする必要はありません。ただし、Exchange は便利なバージョン管理ツールとして利用できます。ローカルモードで使用するカスタムポリシーを配布するのは自分の責任となります。 ポリシーを Exchange にアップロードする際には、以下のいずれかを選択できます。 - [カスタムポリシーのパブリッシュ](#publish)​ ポリシーのバージョンがまだ開発中の段階でポリシーをパブリッシュします。これにより、ポリシーバージョンをテストして編集できます。 - [カスタムポリシーのリリース](#release)​ ポリシーをリリースして、ポリシーの確定版を作成します。ポリシーをリリースした後でポリシーを編集するには、新しいポリシーバージョンを作成する必要があります。 ポリシーをパブリッシュまたはリリースするたびに、Exchange に新しい​`安定状態の`​アセットが作成されます。​`安定`​状態のアセットの詳細については、​[「Stable State Assets (安定状態のアセット)」](https://docs.mulesoft.com/jp/exchange/lifecycle#stablet-state)​を参照してください。 ポリシーを Exchange にアップロードしたら、see [カスタムポリシーの適用](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-apply-policies)を参照してください。 ## [](#始める前に)始める前に - [Anypoint Platform CLI](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-prerequisites#cli)​ に対する認証で使用する接続アプリケーションに、​`[Exchange Contributor (Exchange コントリビュータ)]`​ スコープが適用されていることを確認します。 - [ポリシーをコンパイルします](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-compile-policies)​。 ## [](#publish)カスタムポリシーをパブリッシュする カスタムポリシーをパブリッシュするには、ポリシーのルートフォルダーから ​`make publish`​ コマンドを実行します。 ```ssh make publish ``` アセットをパブリッシュすると、​`DEV`​ という表示ラベルの付いたアセットが Exchange に表示されます。 ![DEV という表示ラベルが付いて Exchange に表示されたポリシー。](/mulesoft/current/ja-jp/pdk/1.2/_images/pdk-dev-asset.png) アセットのグループ ID、アセット ID、アセットバージョン (GAV) が次のように表示されます。 - **groupID**​: `` - **assetID**​: `my-custom-policy-dev` ポリシーをパブリッシュすると、​**assetID**​ の後ろに ​`-dev`​ が付加されます。 - **version**​: `1.0.0-20230618115723` ポリシーをパブリッシュすると、​**version**​ の後ろにタイムスタンプが付加されます。 publish コマンドを再実行すると、ポリシーアセットの新しい場合が作成され、更新されたタイムスタンプが付加されます。以前にパブリッシュしたポリシーバージョンも引き続き使用できます。 ## [](#release)カスタムポリシーをリリースする カスタムポリシーをリリースするには、ポリシーのルートフォルダーから ​`make release`​ コマンドを実行します。 ```ssh make release ``` リリースされたポリシーには ​`DEV`​ は付加されません。アセットの GAV は次のようになります。 - **groupID**​: `` - **assetID**​: `my-custom-policy` リリースされたポリシーの ​**assetID**​ の後ろには ​`-dev`​ は付加されません。 - **version**​: `1.0.0` リリースされたポリシーの ​**assetID**​ の後ろにはタイムスタンプは付加されません。 アセットのリリース後に ​`make release`​ コマンドを再実行すると、競合エラーが発生します。 ポリシーの次のバージョンの作業を開始するには、​`Cargo.toml`​ ファイルでバージョン番号を更新してください。 たとえば、最新バージョンが ​`1.0.0`​ であれば、​`Cargo.toml`​ ファイルを次のように更新してマイナーリリースの作業を開始します。 ```toml name = "my-custom-policy" version = "1.1.0" ``` ## [](#関連情報)関連情報 - [カスタムポリシーの適用](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-apply-policies) - [PDK のトラブルシューティング](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-troubleshooting) # Exchange へのカスタムポリシーのアップロード カスタムポリシーの開発サイクルでは、ポリシーを Exchange にアップロードして新しい Exchange アセットを作成し、ポリシーのバージョンを管理したり、他のユーザーに配布したりできます。Exchange についての詳細は、[Anypoint Exchange の概要](https://docs.mulesoft.com/jp/exchange/)を参照してください。 ローカルモードで実行されるカスタムポリシーは、Exchange にパブリッシュする必要はありません。ただし、Exchange は便利なバージョン管理ツールとして利用できます。ローカルモードで使用するカスタムポリシーを配布するのは自分の責任となります。 ポリシーを Exchange にアップロードする際には、以下のいずれかを選択できます。 - [カスタムポリシーのパブリッシュ](#publish)​ ポリシーのバージョンがまだ開発中の段階でポリシーをパブリッシュします。これにより、ポリシーバージョンをテストして編集できます。 - [カスタムポリシーのリリース](#release)​ ポリシーをリリースして、ポリシーの確定版を作成します。ポリシーをリリースした後でポリシーを編集するには、新しいポリシーバージョンを作成する必要があります。 ポリシーをパブリッシュまたはリリースするたびに、Exchange に新しい​`安定状態の`​アセットが作成されます。​`安定`​状態のアセットの詳細については、​[「Stable State Assets (安定状態のアセット)」](https://docs.mulesoft.com/jp/exchange/lifecycle#stablet-state)​を参照してください。 ポリシーを Exchange にアップロードしたら、see [カスタムポリシーの適用](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-apply-policies)を参照してください。 ## [](#始める前に)始める前に - [Anypoint Platform CLI](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-prerequisites#cli)​ に対する認証で使用する接続アプリケーションに、​`[Exchange Contributor (Exchange コントリビュータ)]`​ スコープが適用されていることを確認します。 - [ポリシーをコンパイルします](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-compile-policies)​。 ## [](#publish)カスタムポリシーをパブリッシュする カスタムポリシーをパブリッシュするには、ポリシーのルートフォルダーから ​`make publish`​ コマンドを実行します。 ```ssh make publish ``` アセットをパブリッシュすると、​`DEV`​ という表示ラベルの付いたアセットが Exchange に表示されます。 ![DEV という表示ラベルが付いて Exchange に表示されたポリシー。](/mulesoft/current/ja-jp/pdk/1.3/_images/pdk-dev-asset.png) アセットのグループ ID、アセット ID、アセットバージョン (GAV) が次のように表示されます。 - **groupID**​: `` - **assetID**​: `my-custom-policy-dev` ポリシーをパブリッシュすると、​**assetID**​ の後ろに ​`-dev`​ が付加されます。 - **version**​: `1.0.0-20230618115723` ポリシーをパブリッシュすると、​**version**​ の後ろにタイムスタンプが付加されます。 publish コマンドを再実行すると、ポリシーアセットの新しい場合が作成され、更新されたタイムスタンプが付加されます。以前にパブリッシュしたポリシーバージョンも引き続き使用できます。 ## [](#release)カスタムポリシーをリリースする カスタムポリシーをリリースするには、ポリシーのルートフォルダーから ​`make release`​ コマンドを実行します。 ```ssh make release ``` リリースされたポリシーには ​`DEV`​ は付加されません。アセットの GAV は次のようになります。 - **groupID**​: `` - **assetID**​: `my-custom-policy` リリースされたポリシーの ​**assetID**​ の後ろには ​`-dev`​ は付加されません。 - **version**​: `1.0.0` リリースされたポリシーの ​**assetID**​ の後ろにはタイムスタンプは付加されません。 アセットのリリース後に ​`make release`​ コマンドを再実行すると、競合エラーが発生します。 ポリシーの次のバージョンの作業を開始するには、​`Cargo.toml`​ ファイルでバージョン番号を更新してください。 たとえば、最新バージョンが ​`1.0.0`​ であれば、​`Cargo.toml`​ ファイルを次のように更新してマイナーリリースの作業を開始します。 ```toml name = "my-custom-policy" version = "1.1.0" ``` ## [](#関連情報)関連情報 - [カスタムポリシーの適用](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-apply-policies) - [PDK のトラブルシューティング](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-troubleshooting) # Exchange へのカスタムポリシーのアップロード カスタムポリシーの開発サイクルでは、ポリシーを Exchange にアップロードして新しい Exchange アセットを作成し、ポリシーのバージョンを管理したり、他のユーザーに配布したりできます。Exchange についての詳細は、[Anypoint Exchange の概要](https://docs.mulesoft.com/jp/exchange/)を参照してください。 ローカルモードで実行されるカスタムポリシーは、Exchange にパブリッシュする必要はありません。ただし、Exchange は便利なバージョン管理ツールとして利用できます。ローカルモードで使用するカスタムポリシーを配布するのは自分の責任となります。 ポリシーを Exchange にアップロードする際には、以下のいずれかを選択できます。 - [カスタムポリシーのパブリッシュ](#publish)​ ポリシーのバージョンがまだ開発中の段階でポリシーをパブリッシュします。これにより、ポリシーバージョンをテストして編集できます。 - [カスタムポリシーのリリース](#release)​ ポリシーをリリースして、ポリシーの確定版を作成します。ポリシーをリリースした後でポリシーを編集するには、新しいポリシーバージョンを作成する必要があります。 ポリシーをパブリッシュまたはリリースするたびに、Exchange に新しい​`安定状態の`​アセットが作成されます。​`安定`​状態のアセットの詳細については、​[「Stable State Assets (安定状態のアセット)」](https://docs.mulesoft.com/jp/exchange/lifecycle#stablet-state)​を参照してください。 ポリシーを Exchange にアップロードしたら、see [カスタムポリシーの適用](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-apply-policies)を参照してください。 ## [](#始める前に)始める前に - [Anypoint Platform CLI](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-prerequisites#cli)​ に対する認証で使用する接続アプリケーションに、​`[Exchange Contributor (Exchange コントリビュータ)]`​ スコープが適用されていることを確認します。 - [ポリシーをコンパイルします](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-compile-policies)​。 ## [](#publish)カスタムポリシーをパブリッシュする カスタムポリシーをパブリッシュするには、ポリシーのルートフォルダーから ​`make publish`​ コマンドを実行します。 ```ssh make publish ``` アセットをパブリッシュすると、​`DEV`​ という表示ラベルの付いたアセットが Exchange に表示されます。 ![DEV という表示ラベルが付いて Exchange に表示されたポリシー。](/mulesoft/current/ja-jp/pdk/1.4/_images/pdk-dev-asset.png) アセットのグループ ID、アセット ID、アセットバージョン (GAV) が次のように表示されます。 - **groupID**​: `` - **assetID**​: `my-custom-policy-dev` ポリシーをパブリッシュすると、​**assetID**​ の後ろに ​`-dev`​ が付加されます。 - **version**​: `1.0.0-20230618115723` ポリシーをパブリッシュすると、​**version**​ の後ろにタイムスタンプが付加されます。 publish コマンドを再実行すると、ポリシーアセットの新しい場合が作成され、更新されたタイムスタンプが付加されます。以前にパブリッシュしたポリシーバージョンも引き続き使用できます。 ## [](#release)カスタムポリシーをリリースする カスタムポリシーをリリースするには、ポリシーのルートフォルダーから ​`make release`​ コマンドを実行します。 ```ssh make release ``` リリースされたポリシーには ​`DEV`​ は付加されません。アセットの GAV は次のようになります。 - **groupID**​: `` - **assetID**​: `my-custom-policy` リリースされたポリシーの ​**assetID**​ の後ろには ​`-dev`​ は付加されません。 - **version**​: `1.0.0` リリースされたポリシーの ​**assetID**​ の後ろにはタイムスタンプは付加されません。 アセットのリリース後に ​`make release`​ コマンドを再実行すると、競合エラーが発生します。 ポリシーの次のバージョンの作業を開始するには、​`Cargo.toml`​ ファイルでバージョン番号を更新してください。 たとえば、最新バージョンが ​`1.0.0`​ であれば、​`Cargo.toml`​ ファイルを次のように更新してマイナーリリースの作業を開始します。 ```toml name = "my-custom-policy" version = "1.1.0" ``` ## [](#関連情報)関連情報 - [カスタムポリシーの適用](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-apply-policies) - [PDK のトラブルシューティング](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-troubleshooting) # Flex Gateway ポリシー開発キット (PDK) の前提条件 Flex Gateway ポリシー開発キット (PDK) の使用を開始する前に、以下の前提条件を確認します。 ## [](#flex-gateway)Flex Gateway PDK のチュートリアルでは、​[Flex Gateway がダウンロード済み](https://docs.mulesoft.com/gateway/latest/install)​で、製品に関する予備知識があることを前提としています。 Policies created with PDK might be compatible with Omni Gateway versions that aren’t compatible with PDK’s integration testing framework. The Omni Gateway version used for testing doesn’t affect the functionality of the policy when deployed to a different Omni Gateway version. See the following table to ensure your Omni Gateway’s compatibility:
Component Minimum Omni Gateway Version Maximum Omni Gateway Version

Policies

1.6.1

Latest

Testing Framework

1.6.1

Latest
## [](#rust-requirements)PDK を使用するための Rust の要件 1. Git ダウンロードとインストールの方法は、 [「Installing Git (Git のインストール)」](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)​を参照してください。 2. Rust プログラミング言語バージョン v1.74.0 ～ v1.83.0: 1. Rust をインストールまたは更新するには、次の curl コマンドを実行します。 ```ssh curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ```
curl がインストールされていない場合は、 「Install curl (curl のインストール)」​を参照してください。
2. PDK で使用される ​`wasm32-wasi`​ コンパイルターゲットは Rust v1.84.0 で非推奨になるため、Rust を最新の互換性のある最新バージョンにダウングレードします。 ```ssh rustup default 1.83.0 ``` 3. Rust WebAssembly システムインターフェース (WASI) クレート Rust WASI をインストールまたは更新するには、次のコマンドを実行します。 ```ssh rustup target add wasm32-wasi ``` 4. Cargo Generate Cargo Generate をインストールまたは更新するには、次のコマンドを実行します。 ```ssh cargo install --locked cargo-generate@0.22.0 ``` ## [](#サポートされているオペレーティングシステム)サポートされているオペレーティングシステム - macOS - Ubuntu Ubuntu を使用するには、​[PDK を使用するための Rust の要件](#rust-requirements)​ をインストールした後で、以下のコマンドを使用して必要なパッケージをインストールします。 ```ssh sudo apt install -y build-essential sudo apt install -y pkg-config sudo apt install -y libssl-dev ``` - Windows
PDK では、カスタムポリシーの開発とテストでのみ Windows をサポートしています。ただし、Flex Gateway は本番環境では Windows をサポートしていません。
PDK で提供されている ​`make`​ コマンドを実行するには、以下をインストールします。 1. [Windows の PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.3) 2. 次のいずれかの Make: - [Make for Windows](https://gnuwin32.sourceforge.net/packages/make.htm) - Chocolatey: ```ssh choco install make ``` ## [](#cli)Anypoint CLI PDK 用の Anypoint CLI を設定する手順は、次のとおりです。 1. [Anypoint CLI 4.x v1.4.4 以降をインストールします](https://docs.mulesoft.com/jp/anypoint-cli/latest/install)​。
自分の Anypoint CLI 4.x バージョンを確認するには、​「Verify the Core Package Version (コアパッケージバージョンを確認する)」​を参照してください。
2. [接続アプリケーション](https://docs.mulesoft.com/jp/access-management/connected-apps-overview)​を使用して、​[Anypoint Platform CLI に対して認証します](https://docs.mulesoft.com/jp/anypoint-cli/latest/auth)​。 接続アプリケーションで認証を行うには、アプリケーションのクライアント ID とクライアントシークレットを提供します。
Anypoint Platform に対する認証では、​[View Organization (組織の表示)]​ および ​[View Environment (環境の表示)]​ スコープに加えて、Exchange へのカスタムポリシーのアップロードを完了するために、接続アプリケーションに ​[Exchange Contributor (Exchange コントリビュータ)]​ スコープを適用しておく必要があります。
3. Anypoint CLI PDK プラグインをインストールまたは更新するには、次のコマンドを実行します。 ```ssh anypoint-cli-v4 plugins:install anypoint-cli-pdk-plugin ``` ## [](#docker)Docker Docker は、PDK で用意されている​[ローカルデバッグ環境](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-debug-local)​と​[インテグレーションテストフレームワーク](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-integration-tests)​を使用するために必要です。Docker がなくてもポリシーのビルドとパブリッシュは可能です。 Docker をインストールするには、 [「Install Docker (Docker のインストール)」](https://docs.docker.com/get-docker/)​を参照してください。
ポリシーの開発とテストのみが目的であれば、Windows の Docker で Flex Gateway をローカルモードで実行することもできます。ただし、Flex Gateway は本番環境では Windows をサポートしていません。
## [](#visual-studio-推奨-ide)Visual Studio (推奨 IDE) PDK は、 [Rust in Visual Studio Code プラグイン](https://code.visualstudio.com/docs/languages/rust)​がインストールされていれば、 [Microsoft Visual Studio](https://code.visualstudio.com/)​ など、どの IDE やテキストエディターでも使用できます。 ## [](#関連情報)関連情報 - [PDK のアップグレード](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-upgrade-pdk) - [ポリシー開発キットのアーキテクチャの概要](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-architecture) - [カスタムポリシーの開発](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-develop-custom-policies) # Flex Gateway ポリシー開発キット (PDK) の前提条件 Flex Gateway ポリシー開発キット (PDK) の使用を開始する前に、以下の前提条件を確認します。 ## [](#flex-gateway)Flex Gateway PDK のチュートリアルでは、​[Flex Gateway がダウンロード済み](https://docs.mulesoft.com/gateway/latest/install)​で、製品に関する予備知識があることを前提としています。 Policies created with PDK might be compatible with Omni Gateway versions that aren’t compatible with PDK’s integration testing framework. The Omni Gateway version used for testing doesn’t affect the functionality of the policy when deployed to a different Omni Gateway version. See the following table to ensure your Omni Gateway’s compatibility:
Component Minimum Omni Gateway Version Maximum Omni Gateway Version

Policies

1.6.1

Latest

Testing Framework

1.6.1

Latest
## [](#rust-requirements)PDK を使用するための Rust の要件 1. Git ダウンロードとインストールの方法は、 [「Installing Git (Git のインストール)」](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)​を参照してください。 2. Rust プログラミング言語バージョン v1.87.0 以降 Rust をインストールまたは更新するには、次の curl コマンドを実行します。 ```ssh curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ```
curl がインストールされていない場合は、 「Install curl (curl のインストール)」​を参照してください。
3. Rust WebAssembly システムインターフェース (WASI) クレート Rust WASI をインストールまたは更新するには、次のコマンドを実行します。 ```ssh rustup target add wasm32-wasip1 ``` 4. Cargo Generate Cargo Generate をインストールまたは更新するには、次のコマンドを実行します。 ```ssh cargo install --locked cargo-generate@0.22.0 ``` ## [](#サポートされているオペレーティングシステム)サポートされているオペレーティングシステム - macOS - Ubuntu Ubuntu を使用するには、​[PDK を使用するための Rust の要件](#rust-requirements)​ をインストールした後で、以下のコマンドを使用して必要なパッケージをインストールします。 ```ssh sudo apt install -y build-essential sudo apt install -y pkg-config sudo apt install -y libssl-dev ``` - Windows
PDK では、カスタムポリシーの開発とテストでのみ Windows をサポートしています。ただし、Flex Gateway は本番環境では Windows をサポートしていません。
PDK で提供されている ​`make`​ コマンドを実行するには、以下をインストールします。 1. [Windows の PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.3) 2. 次のいずれかの Make: - [Make for Windows](https://gnuwin32.sourceforge.net/packages/make.htm) - Chocolatey: ```ssh choco install make ``` ## [](#cli)Anypoint CLI PDK 用の Anypoint CLI を設定する手順は、次のとおりです。 1. [Anypoint CLI 4.x v1.4.4 以降をインストールします](https://docs.mulesoft.com/jp/anypoint-cli/latest/install)​。
自分の Anypoint CLI 4.x バージョンを確認するには、​「Verify the Core Package Version (コアパッケージバージョンを確認する)」​を参照してください。
2. [接続アプリケーション](https://docs.mulesoft.com/jp/access-management/connected-apps-overview)​を使用して、​[Anypoint Platform CLI に対して認証します](https://docs.mulesoft.com/jp/anypoint-cli/latest/auth)​。 接続アプリケーションで認証を行うには、アプリケーションのクライアント ID とクライアントシークレットを提供します。
Anypoint Platform に対する認証では、​[View Organization (組織の表示)]​ および ​[View Environment (環境の表示)]​ スコープに加えて、Exchange へのカスタムポリシーのアップロードを完了するために、接続アプリケーションに ​[Exchange Contributor (Exchange コントリビュータ)]​ スコープを適用しておく必要があります。
3. Anypoint CLI PDK プラグインをインストールまたは更新するには、次のコマンドを実行します。 ```ssh anypoint-cli-v4 plugins:install anypoint-cli-pdk-plugin ``` ## [](#docker)Docker Docker は、PDK で用意されている​[ローカルデバッグ環境](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-debug-local)​と​[インテグレーションテストフレームワーク](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-integration-tests)​を使用するために必要です。Docker がなくてもポリシーのビルドとパブリッシュは可能です。 Docker をインストールするには、 [「Install Docker (Docker のインストール)」](https://docs.docker.com/get-docker/)​を参照してください。
ポリシーの開発とテストのみが目的であれば、Windows の Docker で Flex Gateway をローカルモードで実行することもできます。ただし、Flex Gateway は本番環境では Windows をサポートしていません。
## [](#visual-studio-推奨-ide)Visual Studio (推奨 IDE) PDK は、 [Rust in Visual Studio Code プラグイン](https://code.visualstudio.com/docs/languages/rust)​がインストールされていれば、 [Microsoft Visual Studio](https://code.visualstudio.com/)​ など、どの IDE やテキストエディターでも使用できます。 ## [](#関連情報)関連情報 - [PDK のアップグレード](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-upgrade-pdk) - [ポリシー開発キットのアーキテクチャの概要](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-architecture) - [カスタムポリシーの開発](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-develop-custom-policies) # Flex Gateway ポリシー開発キット (PDK) の概要 ポリシーは、セキュリティの管理、トラフィックの制御、API の適応性の向上に役立つ規制を適用します。Flex Gateway には多くの​[ポリシーが用意されています](https://docs.mulesoft.com/gateway/latest/policies-included-directory)​が、ビジネスニーズをすべてカバーできるとは限りません。 Flex Gateway ポリシー開発キット (PDK) は、カスタムポリシーを簡単に開発できるようにするソフトウェア開発キットです。 PDK は、Rust ソースコードの実装から Exchange でのポリシーのリリースまで、ポリシー開発のライフサイクルをガイドする手順を提供します。あらかじめ用意されているポリシーと同様に、接続モードで動作している Flex Gateway には API Manager を使用し、ローカルモードで動作している Flex Gateway には YAML 設定ファイルを使用して、カスタムポリシーを適用できます。 PDK は、ポリシー作成を始めるのに便利な​[ポリシー例](https://docs.mulesoft.com/pdk/latest/policies-pdk-policy-templates)​も提供しています。 PDK の「Product Spotlight (製品スポットライト)」動画で PDK の概要を確認してください。 ![](https://play.vidyard.com/ibt7HZ8SByp9VCn88dNPx7.jpg) ## [](#関連情報)関連情報 - [アーキテクチャの確認](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-architecture) - [前提条件の確認](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-prerequisites) # Flex Gateway ポリシー開発キット (PDK) の概要 ポリシーは、セキュリティの管理、トラフィックの制御、API の適応性の向上に役立つ規制を適用します。Flex Gateway には多くの​[ポリシーが用意されています](https://docs.mulesoft.com/gateway/latest/policies-included-directory)​が、ビジネスニーズをすべてカバーできるとは限りません。 Flex Gateway ポリシー開発キット (PDK) は、カスタムポリシーを簡単に開発できるようにするソフトウェア開発キットです。 PDK は、Rust ソースコードの実装から Exchange でのポリシーのリリースまで、ポリシー開発のライフサイクルをガイドする手順を提供します。あらかじめ用意されているポリシーと同様に、接続モードで動作している Flex Gateway には API Manager を使用し、ローカルモードで動作している Flex Gateway には YAML 設定ファイルを使用して、カスタムポリシーを適用できます。 PDK は、ポリシー作成を始めるのに便利な​[ポリシー例](https://docs.mulesoft.com/pdk/latest/policies-pdk-policy-templates)​も提供しています。 PDK の「Product Spotlight (製品スポットライト)」動画で PDK の概要を確認してください。 Unresolved include directive in modules/ROOT/pages/policies-pdk-overview.adoc - include::\_partials/pdk-spotlight-video.html\[\] ## [](#関連情報)関連情報 - [アーキテクチャの確認](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-architecture) - [前提条件の確認](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-prerequisites) # Flex Gateway ポリシー開発キット (PDK) の概要 ポリシーは、セキュリティの管理、トラフィックの制御、API の適応性の向上に役立つ規制を適用します。Flex Gateway には多くの​[ポリシーが用意されています](https://docs.mulesoft.com/gateway/latest/policies-included-directory)​が、ビジネスニーズをすべてカバーできるとは限りません。 Flex Gateway ポリシー開発キット (PDK) は、カスタムポリシーを簡単に開発できるようにするソフトウェア開発キットです。 PDK は、Rust ソースコードの実装から Exchange でのポリシーのリリースまで、ポリシー開発のライフサイクルをガイドする手順を提供します。あらかじめ用意されているポリシーと同様に、接続モードで動作している Flex Gateway には API Manager を使用し、ローカルモードで動作している Flex Gateway には YAML 設定ファイルを使用して、カスタムポリシーを適用できます。 PDK は、ポリシー作成を始めるのに便利な​[ポリシー例](https://docs.mulesoft.com/pdk/latest/policies-pdk-policy-templates)​も提供しています。 PDK の「Product Spotlight (製品スポットライト)」動画で PDK の概要を確認してください。 Unresolved include directive in modules/ROOT/pages/policies-pdk-overview.adoc - include::\_partials/pdk-spotlight-video.html\[\] ## [](#関連情報)関連情報 - [アーキテクチャの確認](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-architecture) - [前提条件の確認](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-prerequisites) # HTTP コールの実行
HTTP コールを実行するポリシープロジェクトの例は、 「Simple OAuth 2.0 Validation Policy Example (簡単な OAuth 2.0 検証ポリシーの例)」​を参照してください。
外部サービスとやりとりするために、ポリシーで HTTP コールを使用できます。HTTP コールは、要求検索条件または応答検索条件からのみ実行できます。 ## [](#http-サービスの定義)HTTP サービスの定義 HTTP 要求を実行するには、スキーマ定義のパラメーターとしてサービスを定義します。パラメーターの定義の詳細については、[policy-pdk-create-schema-definition.adoc](#policy-pdk-create-schema-definition.adoc)を参照してください。 外部サービスのスキーマを定義するコードスニペットの例を示します。 ```yaml properties: externalService: type: string format: service endpointPath: type: string ``` ポリシーの Rust ソースコードでは、​`Config`​ 構造体で定義された外部サービスにアクセスできます。要求を実行するには、ポリシーで HTTP クライアントをコールします。例: ```rust let response = client .request(&config.external_service) .path(&config.endpoint_path) .headers(vec![("Content-Type", "application/json")]) .body(r#"{"key": "value"}"#.as_bytes()) .put().await?; ``` ## [](#要求の有効化するための-http-クライアントパラメーターの挿入)要求の有効化するための HTTP クライアントパラメーターの挿入 HTTP コールを実行するには、​`[entrypoint]`​ 関数またはラッパー関数に ​`HTTPClient`​ を挿入します。 - 要求検索条件と応答検索条件で要求を有効にするには、クライアントパラメーターを ​`#[entrypoint]`​ 関数に挿入します。 ```Rust #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration, client: HttpClient) -> Result<()> { let config: Config = serde_json::from_slice(&bytes).unwrap(); // Both request and the response handlers will use the client let filter = on_request(|request_state| request_filter(request_state, &config, &client)) .on_response(|response_state, request_data| { response_filter(response_state, request_data, &config, &client) }); launcher.launch(filter).await?; Ok(()) } ``` - 要求または応答でのみ要求を有効にするには、クライアントパラメーターを ​`on_request`​ または ​`on_response`​ ラッパー関数に挿入します。 ```Rust // Handler with the logic for incoming requests ​​async fn request_filter(state: RequestState, conf: &Config, client: HttpClient) { ... } #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&bytes).unwrap(); // For incoming request events, using the on_request wrapper, inject the client and pass it to the request_filter handler launcher .launch(on_request(|request, client| { request_filter(request, &config, client) })) .await?; Ok(()) } ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features) # HTTP コールの実行
HTTP コールを実行するポリシープロジェクトの例は、 「Simple OAuth 2.0 Validation Policy Example (簡単な OAuth 2.0 検証ポリシーの例)」​を参照してください。
外部サービスとやりとりするために、ポリシーで HTTP コールを使用できます。HTTP コールは、要求検索条件または応答検索条件からのみ実行できます。 ## [](#http-サービスの定義)HTTP サービスの定義 HTTP 要求を実行するには、スキーマ定義のパラメーターとしてサービスを定義します。パラメーターの定義の詳細については、[policy-pdk-create-schema-definition.adoc](#policy-pdk-create-schema-definition.adoc)を参照してください。 外部サービスのスキーマを定義するコードスニペットの例を示します。 ```yaml properties: externalService: type: string format: service endpointPath: type: string ``` ポリシーの Rust ソースコードでは、​`Config`​ 構造体で定義された外部サービスにアクセスできます。要求を実行するには、ポリシーで HTTP クライアントをコールします。例: ```rust let response = client .request(&config.external_service) .path(&config.endpoint_path) .headers(vec![("Content-Type", "application/json")]) .body(r#"{"key": "value"}"#.as_bytes()) .put().await?; ``` ## [](#要求の有効化するための-http-クライアントパラメーターの挿入)要求の有効化するための HTTP クライアントパラメーターの挿入 HTTP コールを実行するには、​`[entrypoint]`​ 関数またはラッパー関数に ​`HTTPClient`​ を挿入します。 - 要求検索条件と応答検索条件で要求を有効にするには、クライアントパラメーターを ​`#[entrypoint]`​ 関数に挿入します。 ```Rust #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration, client: HttpClient) -> Result<()> { let config: Config = serde_json::from_slice(&bytes).unwrap(); // Both request and the response handlers will use the client let filter = on_request(|request_state| request_filter(request_state, &config, &client)) .on_response(|response_state, request_data| { response_filter(response_state, request_data, &config, &client) }); launcher.launch(filter).await?; Ok(()) } ``` - 要求または応答でのみ要求を有効にするには、クライアントパラメーターを ​`on_request`​ または ​`on_response`​ ラッパー関数に挿入します。 ```Rust // Handler with the logic for incoming requests ​​async fn request_filter(state: RequestState, conf: &Config, client: HttpClient) { ... } #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&bytes).unwrap(); // For incoming request events, using the on_request wrapper, inject the client and pass it to the request_filter handler launcher .launch(on_request(|request, client| { request_filter(request, &config, client) })) .await?; Ok(()) } ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features) # HTTP コールの実行
HTTP コールを実行するポリシープロジェクトの例は、 「Simple OAuth 2.0 Validation Policy Example (簡単な OAuth 2.0 検証ポリシーの例)」​を参照してください。
外部サービスとやりとりするために、ポリシーで HTTP コールを使用できます。HTTP コールは、要求検索条件または応答検索条件からのみ実行できます。 ## [](#http-サービスの定義)HTTP サービスの定義 HTTP 要求を実行するには、スキーマ定義のパラメーターとしてサービスを定義します。パラメーターの定義の詳細については、[policy-pdk-create-schema-definition.adoc](#policy-pdk-create-schema-definition.adoc)を参照してください。 外部サービスのスキーマを定義するコードスニペットの例を示します。 ```yaml properties: externalService: type: string format: service endpointPath: type: string ``` ポリシーの Rust ソースコードでは、​`Config`​ 構造体で定義された外部サービスにアクセスできます。要求を実行するには、ポリシーで HTTP クライアントをコールします。例: ```rust let response = client .request(&config.external_service) .path(&config.endpoint_path) .headers(vec![("Content-Type", "application/json")]) .body(r#"{"key": "value"}"#.as_bytes()) .put().await?; ``` ## [](#要求の有効化するための-http-クライアントパラメーターの挿入)要求の有効化するための HTTP クライアントパラメーターの挿入 HTTP コールを実行するには、​`[entrypoint]`​ 関数またはラッパー関数に ​`HTTPClient`​ を挿入します。 - 要求検索条件と応答検索条件で要求を有効にするには、クライアントパラメーターを ​`#[entrypoint]`​ 関数に挿入します。 ```Rust #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration, client: HttpClient) -> Result<()> { let config: Config = serde_json::from_slice(&bytes).unwrap(); // Both request and the response handlers will use the client let filter = on_request(|request_state| request_filter(request_state, &config, &client)) .on_response(|response_state, request_data| { response_filter(response_state, request_data, &config, &client) }); launcher.launch(filter).await?; Ok(()) } ``` - 要求または応答でのみ要求を有効にするには、クライアントパラメーターを ​`on_request`​ または ​`on_response`​ ラッパー関数に挿入します。 ```Rust // Handler with the logic for incoming requests ​​async fn request_filter(state: RequestState, conf: &Config, client: HttpClient) { ... } #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&bytes).unwrap(); // For incoming request events, using the on_request wrapper, inject the client and pass it to the request_filter handler launcher .launch(on_request(|request, client| { request_filter(request, &config, client) })) .await?; Ok(()) } ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features) # JWT ライブラリ関数の使用
Flex Gateway ポリシー開発キット (PDK) の JWT ライブラリを使用したポリシープロジェクトの例は、 「JWT Validation Policy Example (JWT 検証ポリシーの例)」​を参照してください。
JSON Web Token (JWT) は、2 者間で転送されるクレームを表す URL セキュアな方法です。JWT トークンには、JSON Web Signature (JWS) のペイロードとして、またはプレーンテキストの JSON Web Encryption (JWE) 構造体として JSON オブジェクトでエンコードされたクレームが含まれており、これによりクレームはデジタル署名され、メッセージ認証コード (MAC) で保護されます。トークンは署名されるので、その情報と情報源を信頼できます。 PDK の JWT ライブラリには、JWT シグネチャーを検証し、すべての受信要求のクレームを抽出して検証するためのツールセットが用意されています。 ## [](#extract-a-jwt-token)JWT トークンの抽出 PDK は、認証ヘッダーにある ​`Bearer `​ という形式の JWT トークンを抽出するための ​`bearer`​ 関数を持つ ​`TokenProvider`​ 構造体を提供しています。次の例は、​`bearer`​ 関数の使い方を示しています。 ```Rust // [...] use pdk::jwt::*; // [...] async fn filter( state: RequestState, ) -> Flow<()> { let headers_state = state.into_headers_state().await; // Extract token let token = TokenProvider::bearer(headers_state.handler())?; // [...] ``` 異なるソースや異なる形式の JWT トークンを使用する場合は、要求の他の部分を取得する Rust ロジックを実装できます。DataWeave パラメーターを使用して抽出を構成し、JWT ソースを動的に変更できるポリシーを作成します。 ## [](#signature-validation)JWT トークンの検証 JWT ライブラリは、受信要求の認証トークンの署名検証を実行するためのヘルパーを提供しています。ポリシーで使用されるアルゴリズムに応じて、対応する設定で ​`SignatureValidator`​ を初期化します。 ```Rust pub fn new(algorithm: SigningAlgorithm, key_length: SigningKeyLength, key: String) -> Result ``` PDK は以下の署名アルゴリズムとキー長をサポートしています。

署名アルゴリズム

署名キーの長さ

RSA

256、384、512

HMAC

256、384、512

ES

256、384
`SigningAlgorithm`​ 列挙型は、利用可能な署名アルゴリズムを定義します。 ```Rust pub enum SigningAlgorithm { Rsa, Hmac, Es, } ``` `SigningKeyLength`​ 列挙型は、利用可能な署名キーの長さを定義します。 ```Rust pub enum SigningKeyLength { Len256, Len384, Len512, } ``` `SignatureValidator`​ インスタンスは ​`SignatureValidation`​ trait を実装します。この ​`SignatureValidation`​ trait は、トークンを​`文字列型`​のパラメーターとして受け取り、解析された ​`JWTClaims`​ を含む​`結果`​を返すか、エラーの場合は ​`JWTError`​ を返す ​`validate`​ 関数を提供します。 ```Rust pub trait SignatureValidation { fn validate(&self, token: String) -> Result; } ``` 次のコード例は、​`SignatureValidator`​ を初期化し、256 バイトの HMAC アルゴリズムで署名された受信トークンを検証する方法を示しています。 ```Rust use anyhow::Result; use pdk::hl::*; use pdk::jwt::*; // [...] async fn filter( state: RequestState, signature_validator: &SignatureValidator, ) -> Flow<()> { let headers_state = state.into_headers_state().await; // Extract token let token = TokenProvider::bearer(headers_state.handler())?; if token.is_err() { return Flow::Break(Response::new(401).with_body("Bearer not found")); } // Validating signature let claims = signature_validator.validate(token.unwrap()); if claims.is_err() { return Flow::Break(Response::new(401).with_body("Invalid token")); } // [...] } #[entrypoint] async fn configure(launcher: Launcher, Configuration(configuration): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&configuration)?; let signature_validator = SignatureValidator::new( model::SigningAlgorithm::Hmac, model::SigningKeyLength::Len256, config.secret.clone(), )?; launcher .launch(on_request(|request| { filter(request, &signature_validator) })) .await?; Ok(()) } ``` `SignatureValidator`​ は初期化時にポリシーの設定が正しいことを確認するため、​`#[entrypoint]`​ 関数で ​`SignatureValidator`​ を初期化すると、API が要求を受信したときではなく、ポリシーが適用されたときに早期にエラーがスローされます。 初期化後、ポリシーはラップされた関数の ​`on_request`​ に ​`SignatureValidator`​ を渡し、受信要求に対して ​`validate`​ メソッドを実行します。 ## [](#access-claims)クレームへのアクセスとヘッダーへの伝搬 [署名検証](#signature-validation)​の実行後、結果には JWT トークンから解析された JWT クレームが含まれます。 署名が無効な場合、または署名を検証しないことを選択した場合、PDK は ​`JWTClaimsParser`​ によってクレームを解析します。この構造体は、​`Result`​ を返す ​`parse`​ メソッドを提供します。 ```rust // Being "token" a String that contains a JWT token let parsed_claims = JWTClaimsParser::parse(token); if claims.is_err() { return Flow::Break(Response::new(401).with_body("Invalid token")); } ``` 署名検証または解析メソッドを実行したら、​`JWTClaims`​ 構造体が提供する以下のメソッドを使用して JWT クレームにアクセスします。 ```rust pub fn audience(&self) -> Option, JWTError>> pub fn not_before(&self) -> Option> pub fn expiration(&self) -> Option> pub fn issued_at(&self) -> Option> pub fn issuer(&self) -> Option pub fn jti(&self) -> Option pub fn nonce(&self) -> Option pub fn subject(&self) -> Option pub fn has_claim(&self, name: &str) -> bool pub fn get_claim(&self, name: &str) -> Option where T: ValueRetrieval, pub fn has_header(&self, name: &str) -> bool pub fn get_header(&self, name: &str) -> Option pub fn get_claims(&self) -> pdk_script::Value pub fn get_headers(&self) -> pdk_script::Value ``` 提供されているメソッドは、それぞれの標準 JWT クレームを返すように設計されています。 `get_claim`​ メソッドは、標準またはカスタムクレームを返します。​`get_claim`​ は異なる対象変数型をサポートしているため、ユーザーは出力種別を指定する必要があります。 `get_claim`​ は、出力種別として ​`String`​、​`f64`​、​`Vec`​、​`chrono::DateTime`​、​`serde_json::Value`​ をサポートしています。クレームがトークン中に存在しない場合に備えて、​`Option`​ で種別をラップする必要があります。例: ```rust let some_custom_claim: Option = claims.get_claim("username"); ``` 次の例では、ラップされた関数から JWT トークンを解析し、カスタムクレームを取得して、リクエストヘッダーに伝播する方法を示しています。 ```rust async fn filter( state: RequestState, ) -> Flow<()> { let headers_state = state.into_headers_state().await; // Extract token let token = TokenProvider::bearer(headers_state.handler())?; if token.is_err() { return Flow::Break(Response::new(401).with_body("Bearer not found")); } // Being "token" a String that contains a JWT token let parsed_claims = JWTClaimsParser::parse(token.unwrap()); if claims.is_err() { return Flow::Break(Response::new(401).with_body("Invalid token")); } let claims = claims.unwrap(); let username: Option = claims.get_claim("username"); if let Some(custom_claim) = some_custom_claim { headers_state .handler() .set_header("username", custom_claim.as_str()); } Flow::Continue(()) } ``` ## [](#validate-claims)クレームの検証 通常、JWT トークンには、検証可能な標準および非標準クレームが含まれています。JWT トークンのヘッダーまたはペイロードに存在するクレームを取得するには、​[クレームへのアクセスとヘッダーへの伝搬](#access-claims)​ のメソッドを使用します。取得したら、クレームの値を検証します。 次のコード例では、JWT トークンについて以下を検証しています。 - `exp`​ クレームによって期限切れではないことを検証。 - `aud`​ クレームによって正しいオーディエンス値を持っていることを検証。 - DataWeave 式ポリシーパラメーターとして設定されたカスタムバリデーターを使用して、正しいカスタム ​`role`​ クレームを持っていることを検証。 ```Rust use chrono::Utc; use pdk::hl::*; use pdk::jwt::*; use pdk::logger::info; use pdk::script::Evaluator; async fn filter( state: RequestState, mut custom_validator: Evaluator<'_>, ) -> Flow<()> { let headers_state = state.into_headers_state().await; let token = TokenProvider::bearer(headers_state.handler()); if token.is_err() { return Flow::Break(Response::new(400).with_body("Bearer not found")); } // Being "token" a String that contains a JWT token let parsed_claims = JWTClaimsParser::parse(token.unwrap()); if claims.is_err() { return Flow::Break(Response::new(401).with_body("Invalid token")); } let claims = claims.unwrap(); // Validating token expiration if let Some(exp) = claims.expiration() { if exp < Utc::now() { return Flow::Break(Response::new(400).with_body("token expired")); } } else { return Flow::Break(Response::new(400).with_body("token missing exp claim")); } // Validating audience if let Some(aud) = claims.audience() { if !aud_value.iter_mut().any(|a| a == "myAudience") { return Flow::Break(Response::new(400).with_body("token does not have the expected audience")); } } // Custom claim validation custom_validator.bind_vars("claimSet", claims.get_claims()); let result = custom_validator_role_claim.eval(); if !result.ok().and_then(|value| value.as_bool()).unwrap_or_default() { return Flow::Break(Response::new(400).with_body("custom token validations failed.")); } Flow::Continue(()) } #[entrypoint] async fn configure(launcher: Launcher, Configuration(configuration): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&configuration)?; launcher .launch(on_request(|request| { filter(request, config.custom_validator_role.evaluator()) })) .await?; Ok(()) } ``` 上の例では、​`gcl.yaml`​ スキーマ定義で次のように入力パラメーターとして設定されている DataWeave 式によってカスタム ​`role`​ クレームが定義されています。 ```yaml # [...] spec: extends: - name: extension-definition namespace: default properties: customValidatorRole: type: string format: dataweave default: "#[vars.claimSet.role == 'superRole']" # [...] required: - customValidatorRole ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features) # JWT ライブラリ関数の使用
Flex Gateway ポリシー開発キット (PDK) の JWT ライブラリを使用したポリシープロジェクトの例は、 「JWT Validation Policy Example (JWT 検証ポリシーの例)」​を参照してください。
JSON Web Token (JWT) は、2 者間で転送されるクレームを表す URL セキュアな方法です。JWT トークンには、JSON Web Signature (JWS) のペイロードとして、またはプレーンテキストの JSON Web Encryption (JWE) 構造体として JSON オブジェクトでエンコードされたクレームが含まれており、これによりクレームはデジタル署名され、メッセージ認証コード (MAC) で保護されます。トークンは署名されるので、その情報と情報源を信頼できます。 PDK の JWT ライブラリには、JWT シグネチャーを検証し、すべての受信要求のクレームを抽出して検証するためのツールセットが用意されています。 ## [](#extract-a-jwt-token)JWT トークンの抽出 PDK は、認証ヘッダーにある ​`Bearer `​ という形式の JWT トークンを抽出するための ​`bearer`​ 関数を持つ ​`TokenProvider`​ 構造体を提供しています。次の例は、​`bearer`​ 関数の使い方を示しています。 ```Rust // [...] use pdk::jwt::*; // [...] async fn filter( state: RequestState, ) -> Flow<()> { let headers_state = state.into_headers_state().await; // Extract token let token = TokenProvider::bearer(headers_state.handler())?; // [...] ``` 異なるソースや異なる形式の JWT トークンを使用する場合は、要求の他の部分を取得する Rust ロジックを実装できます。DataWeave パラメーターを使用して抽出を構成し、JWT ソースを動的に変更できるポリシーを作成します。 ## [](#signature-validation)JWT トークンの検証 JWT ライブラリは、受信要求の認証トークンの署名検証を実行するためのヘルパーを提供しています。ポリシーで使用されるアルゴリズムに応じて、対応する設定で ​`SignatureValidator`​ を初期化します。 ```Rust pub fn new(algorithm: SigningAlgorithm, key_length: SigningKeyLength, key: String) -> Result ``` PDK は以下の署名アルゴリズムとキー長をサポートしています。

署名アルゴリズム

署名キーの長さ

RSA

256、384、512

HMAC

256、384、512

ES

256、384
`SigningAlgorithm`​ 列挙型は、利用可能な署名アルゴリズムを定義します。 ```Rust pub enum SigningAlgorithm { Rsa, Hmac, Es, } ``` `SigningKeyLength`​ 列挙型は、利用可能な署名キーの長さを定義します。 ```Rust pub enum SigningKeyLength { Len256, Len384, Len512, } ``` `SignatureValidator`​ インスタンスは ​`SignatureValidation`​ trait を実装します。この ​`SignatureValidation`​ trait は、トークンを​`文字列型`​のパラメーターとして受け取り、解析された ​`JWTClaims`​ を含む​`結果`​を返すか、エラーの場合は ​`JWTError`​ を返す ​`validate`​ 関数を提供します。 ```Rust pub trait SignatureValidation { fn validate(&self, token: String) -> Result; } ``` 次のコード例は、​`SignatureValidator`​ を初期化し、256 バイトの HMAC アルゴリズムで署名された受信トークンを検証する方法を示しています。 ```Rust use anyhow::Result; use pdk::hl::*; use pdk::jwt::*; // [...] async fn filter( state: RequestState, signature_validator: &SignatureValidator, ) -> Flow<()> { let headers_state = state.into_headers_state().await; // Extract token let token = TokenProvider::bearer(headers_state.handler())?; if token.is_err() { return Flow::Break(Response::new(401).with_body("Bearer not found")); } // Validating signature let claims = signature_validator.validate(token.unwrap()); if claims.is_err() { return Flow::Break(Response::new(401).with_body("Invalid token")); } // [...] } #[entrypoint] async fn configure(launcher: Launcher, Configuration(configuration): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&configuration)?; let signature_validator = SignatureValidator::new( model::SigningAlgorithm::Hmac, model::SigningKeyLength::Len256, config.secret.clone(), )?; launcher .launch(on_request(|request| { filter(request, &signature_validator) })) .await?; Ok(()) } ``` `SignatureValidator`​ は初期化時にポリシーの設定が正しいことを確認するため、​`#[entrypoint]`​ 関数で ​`SignatureValidator`​ を初期化すると、API が要求を受信したときではなく、ポリシーが適用されたときに早期にエラーがスローされます。 初期化後、ポリシーはラップされた関数の ​`on_request`​ に ​`SignatureValidator`​ を渡し、受信要求に対して ​`validate`​ メソッドを実行します。 ## [](#access-claims)クレームへのアクセスとヘッダーへの伝搬 [署名検証](#signature-validation)​の実行後、結果には JWT トークンから解析された JWT クレームが含まれます。 署名が無効な場合、または署名を検証しないことを選択した場合、PDK は ​`JWTClaimsParser`​ によってクレームを解析します。この構造体は、​`Result`​ を返す ​`parse`​ メソッドを提供します。 ```rust // Being "token" a String that contains a JWT token let parsed_claims = JWTClaimsParser::parse(token); if claims.is_err() { return Flow::Break(Response::new(401).with_body("Invalid token")); } ``` 署名検証または解析メソッドを実行したら、​`JWTClaims`​ 構造体が提供する以下のメソッドを使用して JWT クレームにアクセスします。 ```rust pub fn audience(&self) -> Option, JWTError>> pub fn not_before(&self) -> Option> pub fn expiration(&self) -> Option> pub fn issued_at(&self) -> Option> pub fn issuer(&self) -> Option pub fn jti(&self) -> Option pub fn nonce(&self) -> Option pub fn subject(&self) -> Option pub fn has_claim(&self, name: &str) -> bool pub fn get_claim(&self, name: &str) -> Option where T: ValueRetrieval, pub fn has_header(&self, name: &str) -> bool pub fn get_header(&self, name: &str) -> Option pub fn get_claims(&self) -> pdk_script::Value pub fn get_headers(&self) -> pdk_script::Value ``` 提供されているメソッドは、それぞれの標準 JWT クレームを返すように設計されています。 `get_claim`​ メソッドは、標準またはカスタムクレームを返します。​`get_claim`​ は異なる対象変数型をサポートしているため、ユーザーは出力種別を指定する必要があります。 `get_claim`​ は、出力種別として ​`String`​、​`f64`​、​`Vec`​、​`chrono::DateTime`​、​`serde_json::Value`​ をサポートしています。クレームがトークン中に存在しない場合に備えて、​`Option`​ で種別をラップする必要があります。例: ```rust let some_custom_claim: Option = claims.get_claim("username"); ``` 次の例では、ラップされた関数から JWT トークンを解析し、カスタムクレームを取得して、リクエストヘッダーに伝播する方法を示しています。 ```rust async fn filter( state: RequestState, ) -> Flow<()> { let headers_state = state.into_headers_state().await; // Extract token let token = TokenProvider::bearer(headers_state.handler())?; if token.is_err() { return Flow::Break(Response::new(401).with_body("Bearer not found")); } // Being "token" a String that contains a JWT token let parsed_claims = JWTClaimsParser::parse(token.unwrap()); if claims.is_err() { return Flow::Break(Response::new(401).with_body("Invalid token")); } let claims = claims.unwrap(); let username: Option = claims.get_claim("username"); if let Some(custom_claim) = some_custom_claim { headers_state .handler() .set_header("username", custom_claim.as_str()); } Flow::Continue(()) } ``` ## [](#validate-claims)クレームの検証 通常、JWT トークンには、検証可能な標準および非標準クレームが含まれています。JWT トークンのヘッダーまたはペイロードに存在するクレームを取得するには、​[クレームへのアクセスとヘッダーへの伝搬](#access-claims)​ のメソッドを使用します。取得したら、クレームの値を検証します。 次のコード例では、JWT トークンについて以下を検証しています。 - `exp`​ クレームによって期限切れではないことを検証。 - `aud`​ クレームによって正しいオーディエンス値を持っていることを検証。 - DataWeave 式ポリシーパラメーターとして設定されたカスタムバリデーターを使用して、正しいカスタム ​`role`​ クレームを持っていることを検証。 ```Rust use chrono::Utc; use pdk::hl::*; use pdk::jwt::*; use pdk::logger::info; use pdk::script::Evaluator; async fn filter( state: RequestState, mut custom_validator: Evaluator<'_>, ) -> Flow<()> { let headers_state = state.into_headers_state().await; let token = TokenProvider::bearer(headers_state.handler()); if token.is_err() { return Flow::Break(Response::new(400).with_body("Bearer not found")); } // Being "token" a String that contains a JWT token let parsed_claims = JWTClaimsParser::parse(token.unwrap()); if claims.is_err() { return Flow::Break(Response::new(401).with_body("Invalid token")); } let claims = claims.unwrap(); // Validating token expiration if let Some(exp) = claims.expiration() { if exp < Utc::now() { return Flow::Break(Response::new(400).with_body("token expired")); } } else { return Flow::Break(Response::new(400).with_body("token missing exp claim")); } // Validating audience if let Some(aud) = claims.audience() { if !aud_value.iter_mut().any(|a| a == "myAudience") { return Flow::Break(Response::new(400).with_body("token does not have the expected audience")); } } // Custom claim validation custom_validator.bind_vars("claimSet", claims.get_claims()); let result = custom_validator_role_claim.eval(); if !result.ok().and_then(|value| value.as_bool()).unwrap_or_default() { return Flow::Break(Response::new(400).with_body("custom token validations failed.")); } Flow::Continue(()) } #[entrypoint] async fn configure(launcher: Launcher, Configuration(configuration): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&configuration)?; launcher .launch(on_request(|request| { filter(request, config.custom_validator_role.evaluator()) })) .await?; Ok(()) } ``` 上の例では、​`gcl.yaml`​ スキーマ定義で次のように入力パラメーターとして設定されている DataWeave 式によってカスタム ​`role`​ クレームが定義されています。 ```yaml # [...] spec: extends: - name: extension-definition namespace: default properties: customValidatorRole: type: string format: dataweave default: "#[vars.claimSet.role == 'superRole']" # [...] required: - customValidatorRole ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features) # JWT ライブラリ関数の使用
Flex Gateway ポリシー開発キット (PDK) の JWT ライブラリを使用したポリシープロジェクトの例は、 「JWT Validation Policy Example (JWT 検証ポリシーの例)」​を参照してください。
JSON Web Token (JWT) は、2 者間で転送されるクレームを表す URL セキュアな方法です。JWT トークンには、JSON Web Signature (JWS) のペイロードとして、またはプレーンテキストの JSON Web Encryption (JWE) 構造体として JSON オブジェクトでエンコードされたクレームが含まれており、これによりクレームはデジタル署名され、メッセージ認証コード (MAC) で保護されます。トークンは署名されるので、その情報と情報源を信頼できます。 PDK の JWT ライブラリには、JWT シグネチャーを検証し、すべての受信要求のクレームを抽出して検証するためのツールセットが用意されています。 ## [](#extract-a-jwt-token)JWT トークンの抽出 PDK は、認証ヘッダーにある ​`Bearer `​ という形式の JWT トークンを抽出するための ​`bearer`​ 関数を持つ ​`TokenProvider`​ 構造体を提供しています。次の例は、​`bearer`​ 関数の使い方を示しています。 ```Rust // [...] use pdk::jwt::*; // [...] async fn filter( state: RequestState, ) -> Flow<()> { let headers_state = state.into_headers_state().await; // Extract token let token = TokenProvider::bearer(headers_state.handler())?; // [...] ``` 異なるソースや異なる形式の JWT トークンを使用する場合は、要求の他の部分を取得する Rust ロジックを実装できます。DataWeave パラメーターを使用して抽出を構成し、JWT ソースを動的に変更できるポリシーを作成します。 ## [](#signature-validation)JWT トークンの検証 JWT ライブラリは、受信要求の認証トークンの署名検証を実行するためのヘルパーを提供しています。ポリシーで使用されるアルゴリズムに応じて、対応する設定で ​`SignatureValidator`​ を初期化します。 ```Rust pub fn new(algorithm: SigningAlgorithm, key_length: SigningKeyLength, key: String) -> Result ``` PDK は以下の署名アルゴリズムとキー長をサポートしています。

署名アルゴリズム

署名キーの長さ

RSA

256、384、512

HMAC

256、384、512

ES

256、384
`SigningAlgorithm`​ 列挙型は、利用可能な署名アルゴリズムを定義します。 ```Rust pub enum SigningAlgorithm { Rsa, Hmac, Es, } ``` `SigningKeyLength`​ 列挙型は、利用可能な署名キーの長さを定義します。 ```Rust pub enum SigningKeyLength { Len256, Len384, Len512, } ``` `SignatureValidator`​ インスタンスは ​`SignatureValidation`​ trait を実装します。この ​`SignatureValidation`​ trait は、トークンを​`文字列型`​のパラメーターとして受け取り、解析された ​`JWTClaims`​ を含む​`結果`​を返すか、エラーの場合は ​`JWTError`​ を返す ​`validate`​ 関数を提供します。 ```Rust pub trait SignatureValidation { fn validate(&self, token: String) -> Result; } ``` 次のコード例は、​`SignatureValidator`​ を初期化し、256 バイトの HMAC アルゴリズムで署名された受信トークンを検証する方法を示しています。 ```Rust use anyhow::Result; use pdk::hl::*; use pdk::jwt::*; // [...] async fn filter( state: RequestState, signature_validator: &SignatureValidator, ) -> Flow<()> { let headers_state = state.into_headers_state().await; // Extract token let token = TokenProvider::bearer(headers_state.handler())?; if token.is_err() { return Flow::Break(Response::new(401).with_body("Bearer not found")); } // Validating signature let claims = signature_validator.validate(token.unwrap()); if claims.is_err() { return Flow::Break(Response::new(401).with_body("Invalid token")); } // [...] } #[entrypoint] async fn configure(launcher: Launcher, Configuration(configuration): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&configuration)?; let signature_validator = SignatureValidator::new( model::SigningAlgorithm::Hmac, model::SigningKeyLength::Len256, config.secret.clone(), )?; launcher .launch(on_request(|request| { filter(request, &signature_validator) })) .await?; Ok(()) } ``` `SignatureValidator`​ は初期化時にポリシーの設定が正しいことを確認するため、​`#[entrypoint]`​ 関数で ​`SignatureValidator`​ を初期化すると、API が要求を受信したときではなく、ポリシーが適用されたときに早期にエラーがスローされます。 初期化後、ポリシーはラップされた関数の ​`on_request`​ に ​`SignatureValidator`​ を渡し、受信要求に対して ​`validate`​ メソッドを実行します。 ## [](#access-claims)クレームへのアクセスとヘッダーへの伝搬 [署名検証](#signature-validation)​の実行後、結果には JWT トークンから解析された JWT クレームが含まれます。 署名が無効な場合、または署名を検証しないことを選択した場合、PDK は ​`JWTClaimsParser`​ によってクレームを解析します。この構造体は、​`Result`​ を返す ​`parse`​ メソッドを提供します。 ```rust // Being "token" a String that contains a JWT token let parsed_claims = JWTClaimsParser::parse(token); if claims.is_err() { return Flow::Break(Response::new(401).with_body("Invalid token")); } ``` 署名検証または解析メソッドを実行したら、​`JWTClaims`​ 構造体が提供する以下のメソッドを使用して JWT クレームにアクセスします。 ```rust pub fn audience(&self) -> Option, JWTError>> pub fn not_before(&self) -> Option> pub fn expiration(&self) -> Option> pub fn issued_at(&self) -> Option> pub fn issuer(&self) -> Option pub fn jti(&self) -> Option pub fn nonce(&self) -> Option pub fn subject(&self) -> Option pub fn has_claim(&self, name: &str) -> bool pub fn get_claim(&self, name: &str) -> Option where T: ValueRetrieval, pub fn has_header(&self, name: &str) -> bool pub fn get_header(&self, name: &str) -> Option pub fn get_claims(&self) -> pdk_script::Value pub fn get_headers(&self) -> pdk_script::Value ``` 提供されているメソッドは、それぞれの標準 JWT クレームを返すように設計されています。 `get_claim`​ メソッドは、標準またはカスタムクレームを返します。​`get_claim`​ は異なる対象変数型をサポートしているため、ユーザーは出力種別を指定する必要があります。 `get_claim`​ は、出力種別として ​`String`​、​`f64`​、​`Vec`​、​`chrono::DateTime`​、​`serde_json::Value`​ をサポートしています。クレームがトークン中に存在しない場合に備えて、​`Option`​ で種別をラップする必要があります。例: ```rust let some_custom_claim: Option = claims.get_claim("username"); ``` 次の例では、ラップされた関数から JWT トークンを解析し、カスタムクレームを取得して、リクエストヘッダーに伝播する方法を示しています。 ```rust async fn filter( state: RequestState, ) -> Flow<()> { let headers_state = state.into_headers_state().await; // Extract token let token = TokenProvider::bearer(headers_state.handler())?; if token.is_err() { return Flow::Break(Response::new(401).with_body("Bearer not found")); } // Being "token" a String that contains a JWT token let parsed_claims = JWTClaimsParser::parse(token.unwrap()); if claims.is_err() { return Flow::Break(Response::new(401).with_body("Invalid token")); } let claims = claims.unwrap(); let username: Option = claims.get_claim("username"); if let Some(custom_claim) = some_custom_claim { headers_state .handler() .set_header("username", custom_claim.as_str()); } Flow::Continue(()) } ``` ## [](#validate-claims)クレームの検証 通常、JWT トークンには、検証可能な標準および非標準クレームが含まれています。JWT トークンのヘッダーまたはペイロードに存在するクレームを取得するには、​[クレームへのアクセスとヘッダーへの伝搬](#access-claims)​ のメソッドを使用します。取得したら、クレームの値を検証します。 次のコード例では、JWT トークンについて以下を検証しています。 - `exp`​ クレームによって期限切れではないことを検証。 - `aud`​ クレームによって正しいオーディエンス値を持っていることを検証。 - DataWeave 式ポリシーパラメーターとして設定されたカスタムバリデーターを使用して、正しいカスタム ​`role`​ クレームを持っていることを検証。 ```Rust use chrono::Utc; use pdk::hl::*; use pdk::jwt::*; use pdk::logger::info; use pdk::script::Evaluator; async fn filter( state: RequestState, mut custom_validator: Evaluator<'_>, ) -> Flow<()> { let headers_state = state.into_headers_state().await; let token = TokenProvider::bearer(headers_state.handler()); if token.is_err() { return Flow::Break(Response::new(400).with_body("Bearer not found")); } // Being "token" a String that contains a JWT token let parsed_claims = JWTClaimsParser::parse(token.unwrap()); if claims.is_err() { return Flow::Break(Response::new(401).with_body("Invalid token")); } let claims = claims.unwrap(); // Validating token expiration if let Some(exp) = claims.expiration() { if exp < Utc::now() { return Flow::Break(Response::new(400).with_body("token expired")); } } else { return Flow::Break(Response::new(400).with_body("token missing exp claim")); } // Validating audience if let Some(aud) = claims.audience() { if !aud_value.iter_mut().any(|a| a == "myAudience") { return Flow::Break(Response::new(400).with_body("token does not have the expected audience")); } } // Custom claim validation custom_validator.bind_vars("claimSet", claims.get_claims()); let result = custom_validator_role_claim.eval(); if !result.ok().and_then(|value| value.as_bool()).unwrap_or_default() { return Flow::Break(Response::new(400).with_body("custom token validations failed.")); } Flow::Continue(()) } #[entrypoint] async fn configure(launcher: Launcher, Configuration(configuration): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&configuration)?; launcher .launch(on_request(|request| { filter(request, config.custom_validator_role.evaluator()) })) .await?; Ok(()) } ``` 上の例では、​`gcl.yaml`​ スキーマ定義で次のように入力パラメーターとして設定されている DataWeave 式によってカスタム ​`role`​ クレームが定義されています。 ```yaml # [...] spec: extends: - name: extension-definition namespace: default properties: customValidatorRole: type: string format: dataweave default: "#[vars.claimSet.role == 'superRole']" # [...] required: - customValidatorRole ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features) # Mule ゲートウェイ PDK ポリシーの作成 Flex Gateway ポリシー開発キット (PDK) では、環境を強化する Mule ゲートウェイポリシーの作成がサポートされています。 - ポリシーの作成 - 設定スキーマの定義 - Exchange へのポリシーのデプロイ PDK Anypoint CLI プラグインでは、必要なすべてのポリシーファイルが含まれるカスタムポリシーフォルダーが生成されます。PDK のフォルダーには、ポリシー UI をビルドしたり、Exchange にデプロイしたりするコマンドと共に Makefile が含まれます。 Mule カスタムポリシーを作成する手順は、次のとおりです。 1. [始める前に](#before-you-begin)​の前提条件を満たしていることを確認する。 2. [カスタムポリシーを作成する](#create-policy)​。 3. [ポリシースキーマを定義する](#define-schema)​。 4. [ポリシーロジックを定義する](#define-policy-logic)​。 5. [ポリシーをパブリッシュおよびリリースする](#publish-policies)​。 ## [](#before-you-begin)始める前に 始める前に、次の前提条件を満たしていることを確認してください。 - PDK でサポートされていて、Make がインストールされているオペレーティングシステム [「サポートされているオペレーティングシステム」](https://docs.mulesoft.com/pdk/latest/policies-pdk-prerequisites#supported-operating-systems)​を参照してください。 - Anypoint CLI [「Anypoint CLI PDK Requirements (Anypoint CLI PDK の要件)」](https://docs.mulesoft.com/pdk/latest/policies-pdk-prerequisites#cli)​を参照してください。 - Java サポートされている Java バージョンについての詳細は、[Java サポート](https://docs.mulesoft.com/jp/general/java-support)を参照してください。 - [Apache Maven](https://maven.apache.org/) Apache Maven は ​[Mule Maven Plugin](https://docs.mulesoft.com/mule-runtime/latest/mmp-concept). PDK Mule Policy projects include an embedded Mule Maven Plugin so downloading the plugin is not required. To ensure your Maven version is compatible with the latest plugin, see [Mule Maven Plugin Release Notes](https://docs.mulesoft.com/jp/release-notes/mule-maven-plugin/mule-maven-plugin-release-notes)​の前提条件です。 - MuleSoft の Maven アーキタイプ Maven の ​`settings.xml`​ ファイルに次のコードセクションを追加して、MuleSoft の Maven アーキタイプを設定します。 ```xml archetype-repository archetype Mule Repository https://repository.mulesoft.org/nexus/content/repositories/public true fail true warn ``` ## [](#create-policy)PDK を使用して Mule カスタムポリシーを作成する カスタムポリシーを作成するには、次のコマンドを実行します。 ```cmd pdk policy-project create --name --implementation-technology mule4 ``` このコマンドを実行すると、ポリシー名でカスタムポリシーフォルダーが生成されます。フォルダーには、ポリシー開発ライフサイクルで必要になるすべての呼び出し可能なアクションを提供する makefile が含まれます。 ## [](#define-schema)ポリシースキーマを定義する ポリシープロジェクト内の ​`gcl.yaml`​ ファイルを使用して、ポリシーのスキーマを定義します。PDK では、スキーマ定義で定義されたパラメーターに基づいてポリシーの UI json が生成されます。これにより、これまで手動で行っていた ​`config.json`​ スキーマファイルの作成が不要になります。 スキーマの定義については、[ポリシースキーマ定義の作成](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-create-schema-definition)を参照してください。​`template.xml`​ ファイルで参照するスキーマにすべてのパラメーターを含めます。
Mule ゲートウェイカスタムポリシーでは、Dataweave 形式はサポートされますが、DataWeave バインドはサポートされません。詳細は、​「DataWeave 式」​を参照してください。
## [](#define-policy-logic)ポリシーロジックを定義する `template.xml`​ ファイルのポリシーロジックを定義します。 デフォルトでは、​`template.xml`​ ファイルには、返される HTTP 応答ペイロードを「Hello World!」メッセージに設定する基本的なポリシーのロジックが含まれます。ファイルを表示してロジックを確認します。 その他のポリシーロジックの例については、以下を参照してください。 - [カスタム応答ポリシーの開発](https://docs.mulesoft.com/jp/mule-gateway/policies-custom-response-example) - [イベント認証拡張機能を使用したカスタムポリシーの開発](https://docs.mulesoft.com/jp/mule-gateway/policies-custom-set-authentication-example) ## [](#publish-policies)ポリシーをパブリッシュおよびリリースする PDK では、Mule ゲートウェイと Flex Gateway のポリシーは同じ方法でパブリッシュされます。 ポリシーをパブリッシュおよびリリースするには、[Publishing Unified-Model Policies to Exchange](https://docs.mulesoft.com/pdk/latest/policies-pdk-publish-policies)を参照してください。 ## [](#関連情報)関連情報 - [Mule ゲートウェイカスタムポリシー](https://docs.mulesoft.com/jp/mule-gateway/policies-custom-overview) # Omni Gateway Policy Development Kit (PDK) Release Notes Omni Gateway Policy Development Kit (PDK) is a software development kit that enables you to develop Omni Gateway custom policies with ease. PDK provides instructions to guide you through the policy development lifecycle, from implementing your Rust source code to releasing your policy on Exchange. Like included policies, you can apply custom policies to Omni Gateway running in Connected Mode by using API Manager or to Omni Gateway running in Local Mode by using YAML configuration files. The following release notes are provided for PDK: - [Omni Gateway Policy Development Kit (PDK) Release Notes](https://docs.mulesoft.com/jp/release-notes/pdk/pdk-release-notes) ## [](#see-also)See Also - [Omni Gateway Policy Development Kit (PDK) Overview](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview) - [Omni Gateway Overview](https://docs.mulesoft.com/gateway/latest/) - [Known Issues](https://help.salesforce.com/s/issues) # Omni Gateway Policy Development Kit (PDK) Release Notes Omni Gateway Policy Development Kit (PDK) is a software development kit that enables you to develop Omni Gateway custom policies with ease. PDK provides instructions to guide you through the policy development lifecycle, from implementing your Rust source code to releasing your policy on Exchange. Like included policies, you can apply custom policies to Omni Gateway running in Connected Mode by using API Manager or to Omni Gateway running in Local Mode by using YAML configuration files. The following release notes are provided for PDK: - [Omni Gateway Policy Development Kit (PDK) Release Notes](https://docs.mulesoft.com/jp/release-notes/pdk/pdk-release-notes) ## [](#see-also)See Also - [Omni Gateway Policy Development Kit (PDK) Overview](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview) - [Omni Gateway Overview](https://docs.mulesoft.com/gateway/latest/) - [Known Issues](https://help.salesforce.com/s/issues) # Omni Gateway Policy Development Kit (PDK) Release Notes Omni Gateway Policy Development Kit (PDK) is a software development kit that enables you to develop Omni Gateway custom policies with ease. PDK provides instructions to guide you through the policy development lifecycle, from implementing your Rust source code to releasing your policy on Exchange. Like included policies, you can apply custom policies to Omni Gateway running in Connected Mode by using API Manager or to Omni Gateway running in Local Mode by using YAML configuration files. The following release notes are provided for PDK: - [Omni Gateway Policy Development Kit (PDK) Release Notes](https://docs.mulesoft.com/jp/release-notes/pdk/pdk-release-notes) ## [](#see-also)See Also - [Omni Gateway Policy Development Kit (PDK) Overview](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview) - [Omni Gateway Overview](https://docs.mulesoft.com/gateway/latest/) - [Known Issues](https://help.salesforce.com/s/issues) # PDK デバッグプレイグラウンドでのカスタムポリシーのデバッグ ポリシーの機能をテストできるように、Flex Gateway ポリシー開発キット (PDK) は ​`/playground/config`​ ディレクトリに設定済みの API インスタンスを用意しています。 PDK デバッグプレイグラウンドは、Docker コンテナのローカルモードで実行されている Flex Gateway のみをサポートします。接続モードで動作する Flex Gateway や別のプラットフォームにポリシーをデプロイする場合でも、まず Docker コンテナのローカルモードで実行されている Flex Gateway を使用して PDK でポリシーをテストしてください。
ポリシーの開発とテストのみが目的であれば、Windows の Docker で Flex Gateway をローカルモードで実行することもできます。ただし、Flex Gateway は本番環境では Windows をサポートしていません。
ポリシーをテストするには、次のタスクを実行します。 1. [\[before-you-begin\]](#before-you-begin) 2. [ローカルモードでの Flex Gateway インスタンスの登録](#register) 3. [\[configure-the-policy\]](#configure-the-policy) 4. [\[add-additional-policies\]](#add-additional-policies)​ (必要な場合) 5. [\[deploy-the-policy-with-pdk\]](#deploy-the-policy-with-pdk) ## [](#始める前に)始める前に 次の準備が整っていることを確認します。 - [Docker がインストールされている](https://www.docker.com/)​。 - [カスタムポリシーがコンパイルされている](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-compile-policies)​。 ## [](#register)ローカルモードでの Flex Gateway インスタンスの登録 `make run`​ コマンドを使用してカスタムポリシーのデバッグを開始するには、ローカルモードで Flex Gateway を登録します。 `run`​ コマンドが動作するためには、​`/playground/config`​ ディレクトリに Flex Gateway の ​`registration.yaml`​ ファイルが存在する必要があります。このディレクトリで登録コマンドを実行してこのファイルを作成するか、または以前に登録してある Flex Gateway の ​`registration.yaml`​ ファイルをこのディレクトリに移動します。 `make run`​ コマンドは Docker コンテナのローカルモードで動作する Flex Gateway のみをサポートします。Flex Gateway の登録については、以下を参照してください。 - [ユーザー名とパスワードを使用した Docker コンテナでの登録と実行](https://docs.mulesoft.com/gateway/latest/local-reg-run-up#docker) - [接続アプリケーションを使用した Docker コンテナでの登録と実行](https://docs.mulesoft.com/gateway/latest/local-reg-run-app#docker) - [トークンを使用した Docker コンテナでの登録と実行](https://docs.mulesoft.com/gateway/latest/local-reg-run-token#docker)
登録コマンドのみを実行してください。Docker の開始コマンドは、​make run​ コマンドがこのステップを完了するため、実行しないでください。
ポリシーをテストするデバイスごとに異なる登録ファイルを作成してください。 登録ファイルはリモートリポジトリへの保存では無視され、プロジェクトディレクトリのルートにある ​`.gitignore`​ ファイルにリストされます。 ## [](#ポリシーの設定)ポリシーの設定 [policy-pdk-create-schema-definition.adoc](#policy-pdk-create-schema-definition.adoc)で設定した ​`definition/gcl.yaml`​ ファイルにリストされている設定内容によっては、ポリシーをローカルで実行する前にいくつかのパラメーターを設定する必要があります。 たとえば、​`gcl.yaml`​ ファイルが次のようになっている場合: ```yaml apiVersion: gateway.mulesoft.com.v1alpha1 kind: Extension metadata: labels: title: my-custom-policy category: Security spec: extends: - name: extension-definition properties: user: type: string default: user1 password: type: string description: type: string required: - user - password ``` `/playground/config/api.yaml`​ ファイルを設定値で更新します。 ```yaml apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: ingress-http spec: address: http://0.0.0.0:8081 services: upstream: address: http://backend routes: - config: destinationPath: /anything/echo/ policies: - policyRef: name: my-custom-policy config: password: 12345678 ``` この例では、​`ユーザー名`​はデフォルト値の ​`user1`​、​`パスワード`​は ​`12345678`​ に設定され、説明は提供されません。 ## [](#ポリシーの追加)ポリシーの追加 テスト用の API インスタンスにポリシーを追加して、他のポリシーと一緒にカスタムポリシーの動作をテストすることもできます。 ただし、開発中のポリシーを最初に指定する必要があります。例: ```yaml policies: - policyRef: name: my-custom-policy config: password: 12345678 - policyRef: name: additional-policy config: ``` ## [](#pdk-によるポリシーのデプロイ)PDK によるポリシーのデプロイ これまでのステップを完了したら、ポリシーのルートディレクトリから ​`make run`​ コマンドを実行して、ポリシーをデプロイします。 ```cmd make run ``` このコマンドは、​`/playground/docker-compose.yaml`​ ファイルで 2 つの Docker コンテナを開始します。 - `Local-flex`​: カスタムポリシーを実行する Flex Gateway インスタンス Docker コンテナ。この Flex Gateway は ​`localhost:8081`​ への要求をリスンします。 - `Backend`​: Flex Gateway インスタンスのバックエンドサービスを実行する Docker コンテナ。このバックエンドサービスは、受信した要求をエコーします。
Docker コンテナを停止するには、コンテナを実行している端末から、使用しているデバイスに応じて ​Cmd+c​ または ​Ctrl+c​ を押します。
コンテナが動作を開始したら、API インスタンスへの要求を実行できます。例: ```cmd curl --location --request POST 'http://0.0.0.0:8081/some/route' \ --header 'Token: mytoken' ``` バックエンドのサービスは、要求のルート、ボディ、ヘッダーを含むエコー応答を、カスタムポリシーや追加ポリシーによって実行された修正とともに返します。カスタムポリシーのソースコードに含まれるすべてのログは、コンテナが実行されている端末で表示されます。 ## [](#loglevel-の設定)loglevel の設定 PDK のデバッグ環境のデフォルトでは、​`debug` ​`loglevel`​ (デバッグログレベル) が設定された状態でログが有効になっています。 `loglevel`​ を変更するには、​`/playground/config/logging.yaml`​ の ​`logging.runtimeLogs.logLevel`​ を編集します。 Flex Gateway のログ設定ファイルの編集についての詳細は、[Configuring External Logs for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-third-party-logs-config)を参照してください。 ## [](#rust-デバッガーの使用)Rust デバッガーの使用 Visual Studio Code (VS Code) には、ユニットテストを実行できる Rust デバッガーが含まれています。ポリシーが Flex Gateway にデプロイされている間は、VS Code Debugger を使用できません。API のモックを作成するには、デバッグが必要なロジックに対してユニットテストを使用する必要があります。 VS Code で Rust コードをデバッグするには、 [CodeLLDB Debugger Extension](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb)​ または同じ機能の他の VS Code 拡張機能をインストールする必要があります。VS Code での Rust のデバッグについての詳細は、 [「Rust in Visual Studio Code (Visual Studio Code の Rust)」](https://code.visualstudio.com/docs/languages/rust#_debugging)​を参照してください。 ## [](#関連情報)関連情報 - [インテグレーションテストの作成](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-integration-tests) - [PDK のトラブルシューティング](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-troubleshooting) # PDK デバッグプレイグラウンドでのカスタムポリシーのデバッグ ポリシーの機能をテストできるように、Flex Gateway ポリシー開発キット (PDK) は ​`/playground/config`​ ディレクトリに設定済みの API インスタンスを用意しています。 PDK デバッグプレイグラウンドは、Docker コンテナのローカルモードで実行されている Flex Gateway のみをサポートします。接続モードで動作する Flex Gateway や別のプラットフォームにポリシーをデプロイする場合でも、まず Docker コンテナのローカルモードで実行されている Flex Gateway を使用して PDK でポリシーをテストしてください。
ポリシーの開発とテストのみが目的であれば、Windows の Docker で Flex Gateway をローカルモードで実行することもできます。ただし、Flex Gateway は本番環境では Windows をサポートしていません。
ポリシーをテストするには、次のタスクを実行します。 1. [\[before-you-begin\]](#before-you-begin) 2. [ローカルモードでの Flex Gateway インスタンスの登録](#register) 3. [\[configure-the-policy\]](#configure-the-policy) 4. [\[add-additional-policies\]](#add-additional-policies)​ (必要な場合) 5. [\[deploy-the-policy-with-pdk\]](#deploy-the-policy-with-pdk) ## [](#始める前に)始める前に 次の準備が整っていることを確認します。 - [Docker がインストールされている](https://www.docker.com/)​。 - [カスタムポリシーがコンパイルされている](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-compile-policies)​。 ## [](#register)ローカルモードでの Flex Gateway インスタンスの登録 `make run`​ コマンドを使用してカスタムポリシーのデバッグを開始するには、ローカルモードで Flex Gateway を登録します。 `run`​ コマンドが動作するためには、​`/playground/config`​ ディレクトリに Flex Gateway の ​`registration.yaml`​ ファイルが存在する必要があります。このディレクトリで登録コマンドを実行してこのファイルを作成するか、または以前に登録してある Flex Gateway の ​`registration.yaml`​ ファイルをこのディレクトリに移動します。 `make run`​ コマンドは Docker コンテナのローカルモードで動作する Flex Gateway のみをサポートします。Flex Gateway の登録については、以下を参照してください。 - [ユーザー名とパスワードを使用した Docker コンテナでの登録と実行](https://docs.mulesoft.com/gateway/latest/local-reg-run-up#docker) - [接続アプリケーションを使用した Docker コンテナでの登録と実行](https://docs.mulesoft.com/gateway/latest/local-reg-run-app#docker) - [トークンを使用した Docker コンテナでの登録と実行](https://docs.mulesoft.com/gateway/latest/local-reg-run-token#docker)
登録コマンドのみを実行してください。Docker の開始コマンドは、​make run​ コマンドがこのステップを完了するため、実行しないでください。
ポリシーをテストするデバイスごとに異なる登録ファイルを作成してください。 登録ファイルはリモートリポジトリへの保存では無視され、プロジェクトディレクトリのルートにある ​`.gitignore`​ ファイルにリストされます。 ## [](#ポリシーの設定)ポリシーの設定 [policy-pdk-create-schema-definition.adoc](#policy-pdk-create-schema-definition.adoc)で設定した ​`definition/gcl.yaml`​ ファイルにリストされている設定内容によっては、ポリシーをローカルで実行する前にいくつかのパラメーターを設定する必要があります。 たとえば、​`gcl.yaml`​ ファイルが次のようになっている場合: ```yaml apiVersion: gateway.mulesoft.com.v1alpha1 kind: Extension metadata: labels: title: my-custom-policy category: Security spec: extends: - name: extension-definition properties: user: type: string default: user1 password: type: string description: type: string required: - user - password ``` `/playground/config/api.yaml`​ ファイルを設定値で更新します。 ```yaml apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: ingress-http spec: address: http://0.0.0.0:8081 services: upstream: address: http://backend routes: - config: destinationPath: /anything/echo/ policies: - policyRef: name: my-custom-policy config: password: 12345678 ``` この例では、​`ユーザー名`​はデフォルト値の ​`user1`​、​`パスワード`​は ​`12345678`​ に設定され、説明は提供されません。 ## [](#ポリシーの追加)ポリシーの追加 テスト用の API インスタンスにポリシーを追加して、他のポリシーと一緒にカスタムポリシーの動作をテストすることもできます。 ただし、開発中のポリシーを最初に指定する必要があります。例: ```yaml policies: - policyRef: name: my-custom-policy config: password: 12345678 - policyRef: name: additional-policy config: ``` ## [](#pdk-によるポリシーのデプロイ)PDK によるポリシーのデプロイ これまでのステップを完了したら、ポリシーのルートディレクトリから ​`make run`​ コマンドを実行して、ポリシーをデプロイします。 ```cmd make run ``` このコマンドは、​`/playground/docker-compose.yaml`​ ファイルで 2 つの Docker コンテナを開始します。 - `Local-flex`​: カスタムポリシーを実行する Flex Gateway インスタンス Docker コンテナ。この Flex Gateway は ​`localhost:8081`​ への要求をリスンします。 - `Backend`​: Flex Gateway インスタンスのバックエンドサービスを実行する Docker コンテナ。このバックエンドサービスは、受信した要求をエコーします。
Docker コンテナを停止するには、コンテナを実行している端末から、使用しているデバイスに応じて ​Cmd+c​ または ​Ctrl+c​ を押します。
コンテナが動作を開始したら、API インスタンスへの要求を実行できます。例: ```cmd curl --location --request POST 'http://0.0.0.0:8081/some/route' \ --header 'Token: mytoken' ``` バックエンドのサービスは、要求のルート、ボディ、ヘッダーを含むエコー応答を、カスタムポリシーや追加ポリシーによって実行された修正とともに返します。カスタムポリシーのソースコードに含まれるすべてのログは、コンテナが実行されている端末で表示されます。 ## [](#loglevel-の設定)loglevel の設定 PDK のデバッグ環境のデフォルトでは、​`debug` ​`loglevel`​ (デバッグログレベル) が設定された状態でログが有効になっています。 `loglevel`​ を変更するには、​`/playground/config/logging.yaml`​ の ​`logging.runtimeLogs.logLevel`​ を編集します。 Flex Gateway のログ設定ファイルの編集についての詳細は、[Configuring External Logs for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-third-party-logs-config)を参照してください。 ## [](#rust-デバッガーの使用)Rust デバッガーの使用 Visual Studio Code (VS Code) には、ユニットテストを実行できる Rust デバッガーが含まれています。ポリシーが Flex Gateway にデプロイされている間は、VS Code Debugger を使用できません。API のモックを作成するには、デバッグが必要なロジックに対してユニットテストを使用する必要があります。 VS Code で Rust コードをデバッグするには、 [CodeLLDB Debugger Extension](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb)​ または同じ機能の他の VS Code 拡張機能をインストールする必要があります。VS Code での Rust のデバッグについての詳細は、 [「Rust in Visual Studio Code (Visual Studio Code の Rust)」](https://code.visualstudio.com/docs/languages/rust#_debugging)​を参照してください。 ## [](#関連情報)関連情報 - [インテグレーションテストの作成](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-integration-tests) - [PDK のトラブルシューティング](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-troubleshooting) # PDK デバッグプレイグラウンドでのカスタムポリシーのデバッグ ポリシーの機能をテストできるように、Flex Gateway ポリシー開発キット (PDK) は ​`/playground/config`​ ディレクトリに設定済みの API インスタンスを用意しています。 PDK デバッグプレイグラウンドは、Docker コンテナのローカルモードで実行されている Flex Gateway のみをサポートします。接続モードで動作する Flex Gateway や別のプラットフォームにポリシーをデプロイする場合でも、まず Docker コンテナのローカルモードで実行されている Flex Gateway を使用して PDK でポリシーをテストしてください。
ポリシーの開発とテストのみが目的であれば、Windows の Docker で Flex Gateway をローカルモードで実行することもできます。ただし、Flex Gateway は本番環境では Windows をサポートしていません。
ポリシーをテストするには、次のタスクを実行します。 1. [\[before-you-begin\]](#before-you-begin) 2. [ローカルモードでの Flex Gateway インスタンスの登録](#register) 3. [\[configure-the-policy\]](#configure-the-policy) 4. [\[add-additional-policies\]](#add-additional-policies)​ (必要な場合) 5. [\[deploy-the-policy-with-pdk\]](#deploy-the-policy-with-pdk) ## [](#始める前に)始める前に 次の準備が整っていることを確認します。 - [Docker がインストールされている](https://www.docker.com/)​。 - [カスタムポリシーがコンパイルされている](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-compile-policies)​。 ## [](#register)ローカルモードでの Flex Gateway インスタンスの登録 `make run`​ コマンドを使用してカスタムポリシーのデバッグを開始するには、ローカルモードで Flex Gateway を登録します。 `run`​ コマンドが動作するためには、​`/playground/config`​ ディレクトリに Flex Gateway の ​`registration.yaml`​ ファイルが存在する必要があります。このディレクトリで登録コマンドを実行してこのファイルを作成するか、または以前に登録してある Flex Gateway の ​`registration.yaml`​ ファイルをこのディレクトリに移動します。 `make run`​ コマンドは Docker コンテナのローカルモードで動作する Flex Gateway のみをサポートします。Flex Gateway の登録については、以下を参照してください。 - [ユーザー名とパスワードを使用した Docker コンテナでの登録と実行](https://docs.mulesoft.com/gateway/latest/local-reg-run-up#docker) - [接続アプリケーションを使用した Docker コンテナでの登録と実行](https://docs.mulesoft.com/gateway/latest/local-reg-run-app#docker) - [トークンを使用した Docker コンテナでの登録と実行](https://docs.mulesoft.com/gateway/latest/local-reg-run-token#docker)
登録コマンドのみを実行してください。Docker の開始コマンドは、​make run​ コマンドがこのステップを完了するため、実行しないでください。
ポリシーをテストするデバイスごとに異なる登録ファイルを作成してください。 登録ファイルはリモートリポジトリへの保存では無視され、プロジェクトディレクトリのルートにある ​`.gitignore`​ ファイルにリストされます。 ## [](#ポリシーの設定)ポリシーの設定 [policy-pdk-create-schema-definition.adoc](#policy-pdk-create-schema-definition.adoc)で設定した ​`definition/gcl.yaml`​ ファイルにリストされている設定内容によっては、ポリシーをローカルで実行する前にいくつかのパラメーターを設定する必要があります。 たとえば、​`gcl.yaml`​ ファイルが次のようになっている場合: ```yaml apiVersion: gateway.mulesoft.com.v1alpha1 kind: Extension metadata: labels: title: my-custom-policy category: Security spec: extends: - name: extension-definition properties: user: type: string default: user1 password: type: string description: type: string required: - user - password ``` `/playground/config/api.yaml`​ ファイルを設定値で更新します。 ```yaml apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: ingress-http spec: address: http://0.0.0.0:8081 services: upstream: address: http://backend routes: - config: destinationPath: /anything/echo/ policies: - policyRef: name: my-custom-policy config: password: 12345678 ``` この例では、​`ユーザー名`​はデフォルト値の ​`user1`​、​`パスワード`​は ​`12345678`​ に設定され、説明は提供されません。 ## [](#ポリシーの追加)ポリシーの追加 テスト用の API インスタンスにポリシーを追加して、他のポリシーと一緒にカスタムポリシーの動作をテストすることもできます。 ただし、開発中のポリシーを最初に指定する必要があります。例: ```yaml policies: - policyRef: name: my-custom-policy config: password: 12345678 - policyRef: name: additional-policy config: ``` ## [](#pdk-によるポリシーのデプロイ)PDK によるポリシーのデプロイ これまでのステップを完了したら、ポリシーのルートディレクトリから ​`make run`​ コマンドを実行して、ポリシーをデプロイします。 ```cmd make run ``` このコマンドは、​`/playground/docker-compose.yaml`​ ファイルで 2 つの Docker コンテナを開始します。 - `Local-flex`​: カスタムポリシーを実行する Flex Gateway インスタンス Docker コンテナ。この Flex Gateway は ​`localhost:8081`​ への要求をリスンします。 - `Backend`​: Flex Gateway インスタンスのバックエンドサービスを実行する Docker コンテナ。このバックエンドサービスは、受信した要求をエコーします。
Docker コンテナを停止するには、コンテナを実行している端末から、使用しているデバイスに応じて ​Cmd+c​ または ​Ctrl+c​ を押します。
コンテナが動作を開始したら、API インスタンスへの要求を実行できます。例: ```cmd curl --location --request POST 'http://0.0.0.0:8081/some/route' \ --header 'Token: mytoken' ``` バックエンドのサービスは、要求のルート、ボディ、ヘッダーを含むエコー応答を、カスタムポリシーや追加ポリシーによって実行された修正とともに返します。カスタムポリシーのソースコードに含まれるすべてのログは、コンテナが実行されている端末で表示されます。 ## [](#loglevel-の設定)loglevel の設定 PDK のデバッグ環境のデフォルトでは、​`debug` ​`loglevel`​ (デバッグログレベル) が設定された状態でログが有効になっています。 `loglevel`​ を変更するには、​`/playground/config/logging.yaml`​ の ​`logging.runtimeLogs.logLevel`​ を編集します。 Flex Gateway のログ設定ファイルの編集についての詳細は、[Configuring External Logs for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-third-party-logs-config)を参照してください。 ## [](#rust-デバッガーの使用)Rust デバッガーの使用 Visual Studio Code (VS Code) には、ユニットテストを実行できる Rust デバッガーが含まれています。ポリシーが Flex Gateway にデプロイされている間は、VS Code Debugger を使用できません。API のモックを作成するには、デバッグが必要なロジックに対してユニットテストを使用する必要があります。 VS Code で Rust コードをデバッグするには、 [CodeLLDB Debugger Extension](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb)​ または同じ機能の他の VS Code 拡張機能をインストールする必要があります。VS Code での Rust のデバッグについての詳細は、 [「Rust in Visual Studio Code (Visual Studio Code の Rust)」](https://code.visualstudio.com/docs/languages/rust#_debugging)​を参照してください。 ## [](#関連情報)関連情報 - [インテグレーションテストの作成](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-integration-tests) - [PDK のトラブルシューティング](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-troubleshooting) # PDK のアップグレード カスタムポリシープロジェクトを更新するには、個別にバージョン管理された次の各 Flex Gateway ポリシー開発キット (PDK) コンポーネントを更新する必要があります。 - Anypoint CLI PDK プラグイン - PDK Rust ライブラリ - Anypoint Cargo プラグイン Anypoint CLI PDK プラグインをアップグレードする場合、PDK Rust ライブラリと Anypoint Cargo プラグインを手動でアップグレードして新しいプラグインバージョンとの互換性を確保する必要があります。デバイスのすべての PDK カスタムポリシーで同じ Anypoint CLI PDK プラグインを使用します。新しいカスタムポリシープロジェクトを作成すると、PDK Rust ライブラリと Anypoint Cargo プラグインのバージョンは、プロジェクトを作成するために使用された Anypoint CLI PDK プラグインと同じになりますが、他のポリシーオブジェクトとは関係がありません。 以前のバージョンの Anypoint CLI PDK プラグインで作成されたカスタムポリシープロジェクトをアップグレードする手順は、次のとおりです。 1. [Anypoint CLI PDK プラグインをアップグレードする](#anypoint-cli-pdk-plugin) 2. [PDK Rust ライブラリをアップグレードする](#pdk-rust-libraries) 3. [Anypoint Cargo プラグインをアップグレードする](#anypoint-cargo-plugin) ## [](#anypoint-cli-pdk-plugin)Anypoint CLI PDK プラグインをアップグレードする 以前のプラグインバージョンで作成されたカスタムポリシーを編集する場合、​[PDK Rust ライブラリ](#pdk-rust-libraries)​と ​[Anypoint Cargo プラグイン](#anypoint-cargo-plugin)​が Anypoint CLI PDK プラグインのバージョンと一致していることを確認します。 Anypoint CLI PDK プラグインを最新バージョンにアップグレードするには、次のコマンドを実行します。 ```ssh anypoint-cli-v4 plugins:install anypoint-cli-pdk-plugin ``` 現在のプラグインバージョンを確認するには、次のコマンドを実行します。 ```ssh anypoint-cli-v4 plugins ``` たとえば、次の PDK プラグインバージョンは ​`1.1.0`​ です。 ```ssh anypoint-cli-pdk-plugin 1.1.0 ├─ anypoint-cli-command 1.5.2 │ └─ @oclif/plugin-help 5.1.12 └─ @oclif/plugin-version 1.0.4 ``` ## [](#pdk-rust-libraries)PDK Rust ライブラリをアップグレードする PDK Rust ライブラリは、特定のカスタムポリシーで使用される Rust コードライブラリです。カスタムポリシーごとに異なる PDK ライブラリバージョンを使用できます。 PDK Rust コードライブラリをアップグレードするには、カスタムポリシーの ​`cargo.toml`​ ファイルの ​`pdk` ​`dependency`​ および ​`pdk-test` ​`dev-dependency`​ のバージョンを変更します。​`pdk`​ と ​`pdk-test`​ のバージョンが一致していて、指定されたバージョンが Anypoint CLI PDK プラグインでサポートされている必要があります。 次の例では、両方の連動関係バージョンが ​`1.0.0`​ です。これを必要なバージョンに変更します。 ```toml [dependencies] pdk = { version = "1.0.0", registry = "anypoint" } [dev-dependencies] pdk-test = { version = "1.0.0", registry = "anypoint" } ``` ## [](#anypoint-cargo-plugin)Anypoint Cargo プラグインをアップグレードする Anypoint Cargo プラグインは、PDK Rust ライブラリで使用する Cargo の機能を拡張します。 Anypoint Cargo プラグインをアップグレードする手順は、次のとおりです。 1. カスタムポリシーの ​`Makefile`​ を開きます。 2. `install-cargo-anypoint`​ 対象を見つけます。次に例を示します。 install-cargo-anypoint: cargo install cargo-anypoint@1.0.0 --registry anypoint --config .cargo/config.toml 3. `@`​ 文字の後のバージョンを必要なバージョンに変更します。 4. `Makefile`​ を保存します。 5. `make setup`​ コマンドを実行します。 ```ssh make setup ```
特定のポリシーの ​make setup​ コマンドを実行すると、そのポリシーの Anypoint Cargo プラグインバージョンがインストールされます。
6. 次のコマンドを実行して、適切なバージョンがインストールされていることを確認します。 ```ssh cargo anypoint --version ``` ## [](#関連情報)関連情報 - [PDK の前提条件の確認](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-prerequisites) # PDK のアップグレード カスタムポリシープロジェクトを更新するには、個別にバージョン管理された次の各 Flex Gateway ポリシー開発キット (PDK) コンポーネントを更新する必要があります。 - Anypoint CLI PDK プラグイン - PDK Rust ライブラリ - Anypoint Cargo プラグイン Anypoint CLI PDK プラグインをアップグレードする場合、PDK Rust ライブラリと Anypoint Cargo プラグインを手動でアップグレードして新しいプラグインバージョンとの互換性を確保する必要があります。デバイスのすべての PDK カスタムポリシーで同じ Anypoint CLI PDK プラグインを使用します。新しいカスタムポリシープロジェクトを作成すると、PDK Rust ライブラリと Anypoint Cargo プラグインのバージョンは、プロジェクトを作成するために使用された Anypoint CLI PDK プラグインと同じになりますが、他のポリシーオブジェクトとは関係がありません。 以前のバージョンの Anypoint CLI PDK プラグインで作成されたカスタムポリシープロジェクトをアップグレードする手順は、次のとおりです。 1. [Anypoint CLI PDK プラグインをアップグレードする](#anypoint-cli-pdk-plugin) 2. [PDK Rust ライブラリをアップグレードする](#pdk-rust-libraries) 3. [Anypoint Cargo プラグインをアップグレードする](#anypoint-cargo-plugin) ## [](#anypoint-cli-pdk-plugin)Anypoint CLI PDK プラグインをアップグレードする 以前のプラグインバージョンで作成されたカスタムポリシーを編集する場合、​[PDK Rust ライブラリ](#pdk-rust-libraries)​と ​[Anypoint Cargo プラグイン](#anypoint-cargo-plugin)​が Anypoint CLI PDK プラグインのバージョンと一致していることを確認します。 Anypoint CLI PDK プラグインを最新バージョンにアップグレードするには、次のコマンドを実行します。 ```ssh anypoint-cli-v4 plugins:install anypoint-cli-pdk-plugin ``` 現在のプラグインバージョンを確認するには、次のコマンドを実行します。 ```ssh anypoint-cli-v4 plugins ``` たとえば、次の PDK プラグインバージョンは ​`1.1.0`​ です。 ```ssh anypoint-cli-pdk-plugin 1.1.0 ├─ anypoint-cli-command 1.5.2 │ └─ @oclif/plugin-help 5.1.12 └─ @oclif/plugin-version 1.0.4 ``` ## [](#pdk-rust-libraries)PDK Rust ライブラリをアップグレードする PDK Rust ライブラリは、特定のカスタムポリシーで使用される Rust コードライブラリです。カスタムポリシーごとに異なる PDK ライブラリバージョンを使用できます。 PDK Rust コードライブラリをアップグレードするには、カスタムポリシーの ​`cargo.toml`​ ファイルの ​`pdk` ​`dependency`​ および ​`pdk-test` ​`dev-dependency`​ のバージョンを変更します。​`pdk`​ と ​`pdk-test`​ のバージョンが一致していて、指定されたバージョンが Anypoint CLI PDK プラグインでサポートされている必要があります。 次の例では、両方の連動関係バージョンが ​`1.0.0`​ です。これを必要なバージョンに変更します。 ```toml [dependencies] pdk = { version = "1.0.0", registry = "anypoint" } [dev-dependencies] pdk-test = { version = "1.0.0", registry = "anypoint" } ``` ## [](#anypoint-cargo-plugin)Anypoint Cargo プラグインをアップグレードする Anypoint Cargo プラグインは、PDK Rust ライブラリで使用する Cargo の機能を拡張します。 Anypoint Cargo プラグインをアップグレードする手順は、次のとおりです。 1. カスタムポリシーの ​`Makefile`​ を開きます。 2. `install-cargo-anypoint`​ 対象を見つけます。次に例を示します。 install-cargo-anypoint: cargo install cargo-anypoint@1.0.0 --registry anypoint --config .cargo/config.toml 3. `@`​ 文字の後のバージョンを必要なバージョンに変更します。 4. `Makefile`​ を保存します。 5. `make setup`​ コマンドを実行します。 ```ssh make setup ```
特定のポリシーの ​make setup​ コマンドを実行すると、そのポリシーの Anypoint Cargo プラグインバージョンがインストールされます。
6. 次のコマンドを実行して、適切なバージョンがインストールされていることを確認します。 ```ssh cargo anypoint --version ``` ## [](#関連情報)関連情報 - [Flex Gateway ポリシー開発キット (PDK) の前提条件](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-prerequisites) # PDK のアップグレード カスタムポリシープロジェクトを更新するには、個別にバージョン管理された次の各 Flex Gateway ポリシー開発キット (PDK) コンポーネントを更新する必要があります。 - Anypoint CLI PDK プラグイン - PDK Rust ライブラリ - Anypoint Cargo プラグイン - ポリシーの Rust バージョン - WASI クレート Anypoint CLI PDK プラグインをアップグレードする場合、PDK Rust ライブラリと Anypoint Cargo プラグインを手動でアップグレードして新しいプラグインバージョンとの互換性を確保する必要があります。デバイスのすべての PDK カスタムポリシーで同じ Anypoint CLI PDK プラグインを使用します。新しいカスタムポリシープロジェクトを作成すると、PDK Rust ライブラリと Anypoint Cargo プラグインのバージョンは、プロジェクトを作成するために使用された Anypoint CLI PDK プラグインと同じになりますが、他のポリシーオブジェクトとは関係がありません。 以前のバージョンの Anypoint CLI PDK プラグインで作成されたカスタムポリシープロジェクトをアップグレードする手順は、次のとおりです。 1. [Anypoint CLI PDK プラグインをアップグレードする](#anypoint-cli-pdk-plugin) 2. [PDK Rust ライブラリをアップグレードする](#pdk-rust-libraries) 3. [Anypoint Cargo プラグインをアップグレードする](#anypoint-cargo-plugin) 4. [ポリシーの Rust バージョンをアップグレードする](#anypoint-rust-version) 5. [ポリシーの WASI クレートをアップグレードする](#anypoint-wasi-crate) ## [](#anypoint-cli-pdk-plugin)Anypoint CLI PDK プラグインをアップグレードする 以前のプラグインバージョンで作成されたカスタムポリシーを編集する場合、​[PDK Rust ライブラリ](#pdk-rust-libraries)​と ​[Anypoint Cargo プラグイン](#anypoint-cargo-plugin)​が Anypoint CLI PDK プラグインのバージョンと一致していることを確認します。 Anypoint CLI PDK プラグインを最新バージョンにアップグレードするには、次のコマンドを実行します。 ```ssh anypoint-cli-v4 plugins:install anypoint-cli-pdk-plugin ``` 現在のプラグインバージョンを確認するには、次のコマンドを実行します。 ```ssh anypoint-cli-v4 plugins ``` たとえば、次の PDK プラグインバージョンは ​`1.4.1`​ です。 ```ssh anypoint-cli-pdk-plugin 1.4.1 ├─ anypoint-cli-command 1.5.2 │ └─ @oclif/plugin-help 5.1.12 └─ @oclif/plugin-version 1.0.4 ``` ## [](#pdk-rust-libraries)PDK Rust ライブラリをアップグレードする PDK Rust ライブラリは、特定のカスタムポリシーで使用される Rust コードライブラリです。カスタムポリシーごとに異なる PDK ライブラリバージョンを使用できます。 PDK Rust コードライブラリをアップグレードするには、カスタムポリシーの ​`cargo.toml`​ ファイルの ​`pdk` ​`dependency`​ および ​`pdk-test` ​`dev-dependency`​ のバージョンを変更します。​`pdk`​ と ​`pdk-test`​ のバージョンが一致していて、指定されたバージョンが Anypoint CLI PDK プラグインでサポートされている必要があります。 次の例では、両方の連動関係バージョンが ​`1.0.0`​ です。これを必要なバージョンに変更します。 ```toml [dependencies] pdk = { version = "1.0.0", registry = "anypoint" } [dev-dependencies] pdk-test = { version = "1.0.0", registry = "anypoint" } ``` ## [](#anypoint-cargo-plugin)Anypoint Cargo プラグインをアップグレードする Anypoint Cargo プラグインは、PDK Rust ライブラリで使用する Cargo の機能を拡張します。 Anypoint Cargo プラグインをアップグレードする手順は、次のとおりです。 1. カスタムポリシーの ​`Makefile`​ を開きます。 2. `install-cargo-anypoint`​ 対象を見つけます。次に例を示します。 install-cargo-anypoint: cargo install cargo-anypoint@1.0.0 --registry anypoint --config .cargo/config.toml 3. `@`​ 文字の後のバージョンを必要なバージョンに変更します。 4. `Makefile`​ を保存します。 5. `make setup`​ コマンドを実行します。 ```ssh make setup ```
特定のポリシーの ​make setup​ コマンドを実行すると、そのポリシーの Anypoint Cargo プラグインバージョンがインストールされます。
6. 次のコマンドを実行して、適切なバージョンがインストールされていることを確認します。 ```ssh cargo anypoint --version ``` ## [](#anypoint-rust-version)ポリシーの Rust バージョンをアップグレードする ポリシーの Rust バージョンをアップグレードする手順は、次のとおりです。 1. デバイスに Rust バージョンがダウンロードされていることを確認します。 Rust を更新するには、​[「PDK を使用するための Rust の要件」](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-prerequisites#rust-requirements)​を参照してください。 2. カスタムポリシーの ​`cargo.toml`​ を開きます。 3. Rust バージョンを見つけます。次に例を示します。 rust-version = "1.83.0" 4. Rust バージョンを更新します。次に例を示します。 rust-version = "1.87.0" 5. `cargo.toml`​ ファイルを保存します。 ## [](#anypoint-wasi-crate)ポリシーの WASI クレートをアップグレードする Rust WebAssembly システムインターフェース (WASI) クレートを ​`wasm32-wasi`​ から ​`wasm32-wasip1`​ にアップグレードする手順は、次のとおりです。 1. カスタムポリシーの ​`Makefile`​ を開きます。 2. 次の行を見つけます。 TARGET := wasm32-wasi 3. `wasm32-wasi`​ を ​`wasm32-wasip1`​ に置き換えます。 TARGET := wasm32-wasip1 4. `Makefile`​ を保存します。 5. カスタムポリシーの ​`tests/common/mod.rs`​ を開きます。 6. 次の行を見つけます。 pub const POLICY\_DIR: &str = concat!(env!("CARGO\_MANIFEST\_DIR"), "/target/wasm32-wasi/release"); 7. `wasm32-wasi`​ を ​`wasm32-wasip1`​ に置き換えます。 pub const POLICY\_DIR: &str = concat!(env!("CARGO\_MANIFEST\_DIR"), "/target/wasm32-wasip1/release"); 8. `mod.rs`​ ファイルを保存します。 ## [](#関連情報)関連情報 - [Flex Gateway ポリシー開発キット (PDK) の前提条件](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-prerequisites) # PDK のトラブルシューティング Flex Gateway ポリシー開発キット (PDK) の使用中に PDK 自身の問題が発生する場合があります。これらの問題を解決するための情報は、以下のセクションを参照してください。 - [Mac デバイスでの Cargo-Generate エラー](#cargo-generate) - [Anypoint CLI ログイン情報エラー](#cli-credential) - [ポリシープロジェクトの作成時のグループ ID エラー](#group-id-error) - [make setup の実行時の 401 認証エラー](#authorization-error) カスタムポリシーの問題をデバッグするには、以下を参照してください。 - [PDK デバッグプレイグラウンドでのカスタムポリシーのデバッグ](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-debug-local) - [デプロイ済みのカスタムポリシーのデバッグ](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-debug-deployed-policies) ## [](#cargo-generate)Mac デバイスでの Cargo-Generate エラー Mac デバイスで Rust を初めてコンパイルすると、次のエラーが発生する場合があります。 ```ssh $ cargo install cargo-generate error: linking with `cc` failed: exit status: 1 [...] ``` このエラーをトラブルシューティングする手順は、次のとおりです。 1. Xcode がインストールされていることを確認して、もう一度コンパイルします。 Xcode をインとするには、次のコマンドを実行します。 ```ssh xcode-select --install ``` 2. Xcode がインストールされているのに PDK がコンパイルできない場合は、以下を追加して ​`~/.cargo/config.toml`​ ファイルを作成または編集します。 ```toml [target.x86_64-apple-darwin] rustflags = [ "-C", "link-arg=-undefined", "-C", "link-arg=dynamic_lookup", ] [target.aarch64-apple-darwin] rustflags = [ "-C", "link-arg=-undefined", "-C", "link-arg=dynamic_lookup", ] ``` ## [](#cli-credential)Anypoint CLI ログイン情報エラー Anypoint CLI では、接続アプリケーションで多要素認証 (MFA) が必要です。接続アプリケーションのログイン情報を指定せずに PDK コマンドを使用すると、次のようなエラーが発生します。 ```ssh Error: Failed to launch the browser process! undefined [...]:ERROR:ozone_platform_x11.cc(239)] Missing X server or $DISPLAY [21921:21921:1103/113335.217708:ERROR:env.cc(255)] The platform failed to initialize. Exiting. TROUBLESHOOTING: https://pptr.dev/troubleshooting ``` 接続アプリケーションを使用した MFA で Anypoint CLI を設定するには、[Anypoint Platform CLI に対する認証](https://docs.mulesoft.com/jp/anypoint-cli/latest/auth)を参照してください。 ## [](#group-id-error)ポリシープロジェクトの作成時のグループ ID エラー Anypoint CLI は、​`ANYPOINT_ORG`​ 環境変数を使用します。この変数では、組織名または組織 ID を値として使用できます。この変数で組織名を設定すると、​[ポリシー作成コマンド](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-create-project)​は組織のグループ ID の推定に失敗します。 `ANYPOINT_ORG`​ の値としては組織 ID を使用してください。ただし、変数を変更できない場合は、以下のいずれかの方法でグループ ID を指定します。 - 作成コマンドで次のプロンプトが返された場合は ```ssh Please provide a valid group-id (the id of the organization that will own the asset): ``` グループ ID を入力してから Enter キーを押します。 - PDK プロジェクトの作成時に ​`-group-id`​ フラグを使用します。例: ```ssh anypoint-cli-v4 pdk policy-project create -n --group-id ``` ## [](#authorization-error)make setup の実行時の 401 認証エラー make setup コマンドを実行すると、次のエラーが返される場合があります。 ```ssh $ make setup Login token for `anypoint` saved [...] Caused by: failed to get successful HTTP response from `https://anypoint.mulesoft.com/crates[...]/download` [...], got 401 body: make: *** [install-cargo-anypoint] Error 101 ``` このエラーは、Rust のバージョンが v1.74.0 以降ではない場合に発生します。 このエラーを解決するには、​[「PDK を使用するための Rust の要件」](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-prerequisites#rust-requirements)​を参照して、必要なバージョンの Rust ソフトウェアを使用するようにしてください。 ## [](#関連情報)関連情報 - [ポリシー開発キットのアーキテクチャの概要](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-architecture) - [PDK の前提条件の確認](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-prerequisites) # PDK のトラブルシューティング Flex Gateway ポリシー開発キット (PDK) の使用中に PDK 自身の問題が発生する場合があります。これらの問題を解決するための情報は、以下のセクションを参照してください。 - [Mac デバイスでの Cargo-Generate エラー](#cargo-generate) - [Anypoint CLI ログイン情報エラー](#cli-credential) - [ポリシープロジェクトの作成時のグループ ID エラー](#group-id-error) - [make setup の実行時の 401 認証エラー](#authorization-error) カスタムポリシーの問題をデバッグするには、以下を参照してください。 - [PDK デバッグプレイグラウンドでのカスタムポリシーのデバッグ](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-debug-local) - [デプロイ済みのカスタムポリシーのデバッグ](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-debug-deployed-policies) ## [](#cargo-generate)Mac デバイスでの Cargo-Generate エラー Mac デバイスで Rust を初めてコンパイルすると、次のエラーが発生する場合があります。 ```ssh $ cargo install cargo-generate error: linking with `cc` failed: exit status: 1 [...] ``` このエラーをトラブルシューティングする手順は、次のとおりです。 1. Xcode がインストールされていることを確認して、もう一度コンパイルします。 Xcode をインとするには、次のコマンドを実行します。 ```ssh xcode-select --install ``` 2. Xcode がインストールされているのに PDK がコンパイルできない場合は、以下を追加して ​`~/.cargo/config.toml`​ ファイルを作成または編集します。 ```toml [target.x86_64-apple-darwin] rustflags = [ "-C", "link-arg=-undefined", "-C", "link-arg=dynamic_lookup", ] [target.aarch64-apple-darwin] rustflags = [ "-C", "link-arg=-undefined", "-C", "link-arg=dynamic_lookup", ] ``` ## [](#cli-credential)Anypoint CLI ログイン情報エラー Anypoint CLI では、接続アプリケーションで多要素認証 (MFA) が必要です。接続アプリケーションのログイン情報を指定せずに PDK コマンドを使用すると、次のようなエラーが発生します。 ```ssh Error: Failed to launch the browser process! undefined [...]:ERROR:ozone_platform_x11.cc(239)] Missing X server or $DISPLAY [21921:21921:1103/113335.217708:ERROR:env.cc(255)] The platform failed to initialize. Exiting. TROUBLESHOOTING: https://pptr.dev/troubleshooting ``` 接続アプリケーションを使用した MFA で Anypoint CLI を設定するには、[Anypoint Platform CLI に対する認証](https://docs.mulesoft.com/jp/anypoint-cli/latest/auth)を参照してください。 ## [](#group-id-error)ポリシープロジェクトの作成時のグループ ID エラー Anypoint CLI は、​`ANYPOINT_ORG`​ 環境変数を使用します。この変数では、組織名または組織 ID を値として使用できます。この変数で組織名を設定すると、​[ポリシー作成コマンド](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-create-project)​は組織のグループ ID の推定に失敗します。 `ANYPOINT_ORG`​ の値としては組織 ID を使用してください。ただし、変数を変更できない場合は、以下のいずれかの方法でグループ ID を指定します。 - 作成コマンドで次のプロンプトが返された場合は ```ssh Please provide a valid group-id (the id of the organization that will own the asset): ``` グループ ID を入力してから Enter キーを押します。 - PDK プロジェクトの作成時に ​`-group-id`​ フラグを使用します。例: ```ssh anypoint-cli-v4 pdk policy-project create -n --group-id ``` ## [](#authorization-error)make setup の実行時の 401 認証エラー make setup コマンドを実行すると、次のエラーが返される場合があります。 ```ssh $ make setup Login token for `anypoint` saved [...] Caused by: failed to get successful HTTP response from `https://anypoint.mulesoft.com/crates[...]/download` [...], got 401 body: make: *** [install-cargo-anypoint] Error 101 ``` このエラーは、Rust のバージョンが v1.74.0 以降ではない場合に発生します。 このエラーを解決するには、​[「PDK を使用するための Rust の要件」](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-prerequisites#rust-requirements)​を参照して、必要なバージョンの Rust ソフトウェアを使用するようにしてください。 ## [](#関連情報)関連情報 - [ポリシー開発キットのアーキテクチャの概要](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-architecture) - [Flex Gateway ポリシー開発キット (PDK) の前提条件](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-prerequisites) # PDK のトラブルシューティング Flex Gateway ポリシー開発キット (PDK) の使用中に PDK 自身の問題が発生する場合があります。これらの問題を解決するための情報は、以下のセクションを参照してください。 - [Mac デバイスでの Cargo-Generate エラー](#cargo-generate) - [Anypoint CLI ログイン情報エラー](#cli-credential) - [ポリシープロジェクトの作成時のグループ ID エラー](#group-id-error) - [make setup の実行時の 401 認証エラー](#authorization-error) カスタムポリシーの問題をデバッグするには、以下を参照してください。 - [PDK デバッグプレイグラウンドでのカスタムポリシーのデバッグ](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-debug-local) - [デプロイ済みのカスタムポリシーのデバッグ](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-debug-deployed-policies) ## [](#cargo-generate)Mac デバイスでの Cargo-Generate エラー Mac デバイスで Rust を初めてコンパイルすると、次のエラーが発生する場合があります。 ```ssh $ cargo install cargo-generate error: linking with `cc` failed: exit status: 1 [...] ``` このエラーをトラブルシューティングする手順は、次のとおりです。 1. Xcode がインストールされていることを確認して、もう一度コンパイルします。 Xcode をインとするには、次のコマンドを実行します。 ```ssh xcode-select --install ``` 2. Xcode がインストールされているのに PDK がコンパイルできない場合は、以下を追加して ​`~/.cargo/config.toml`​ ファイルを作成または編集します。 ```toml [target.x86_64-apple-darwin] rustflags = [ "-C", "link-arg=-undefined", "-C", "link-arg=dynamic_lookup", ] [target.aarch64-apple-darwin] rustflags = [ "-C", "link-arg=-undefined", "-C", "link-arg=dynamic_lookup", ] ``` ## [](#cli-credential)Anypoint CLI ログイン情報エラー Anypoint CLI では、接続アプリケーションで多要素認証 (MFA) が必要です。接続アプリケーションのログイン情報を指定せずに PDK コマンドを使用すると、次のようなエラーが発生します。 ```ssh Error: Failed to launch the browser process! undefined [...]:ERROR:ozone_platform_x11.cc(239)] Missing X server or $DISPLAY [21921:21921:1103/113335.217708:ERROR:env.cc(255)] The platform failed to initialize. Exiting. TROUBLESHOOTING: https://pptr.dev/troubleshooting ``` 接続アプリケーションを使用した MFA で Anypoint CLI を設定するには、[Anypoint Platform CLI に対する認証](https://docs.mulesoft.com/jp/anypoint-cli/latest/auth)を参照してください。 ## [](#group-id-error)ポリシープロジェクトの作成時のグループ ID エラー Anypoint CLI は、​`ANYPOINT_ORG`​ 環境変数を使用します。この変数では、組織名または組織 ID を値として使用できます。この変数で組織名を設定すると、​[ポリシー作成コマンド](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-create-project)​は組織のグループ ID の推定に失敗します。 `ANYPOINT_ORG`​ の値としては組織 ID を使用してください。ただし、変数を変更できない場合は、以下のいずれかの方法でグループ ID を指定します。 - 作成コマンドで次のプロンプトが返された場合は ```ssh Please provide a valid group-id (the id of the organization that will own the asset): ``` グループ ID を入力してから Enter キーを押します。 - PDK プロジェクトの作成時に ​`-group-id`​ フラグを使用します。例: ```ssh anypoint-cli-v4 pdk policy-project create -n --group-id ``` ## [](#authorization-error)make setup の実行時の 401 認証エラー make setup コマンドを実行すると、次のエラーが返される場合があります。 ```ssh $ make setup Login token for `anypoint` saved [...] Caused by: failed to get successful HTTP response from `https://anypoint.mulesoft.com/crates[...]/download` [...], got 401 body: make: *** [install-cargo-anypoint] Error 101 ``` このエラーは、Rust のバージョンが v1.87.0 以降ではない場合に発生します。 このエラーを解決するには、​[「PDK を使用するための Rust の要件」](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-prerequisites#rust-requirements)​を参照して、必要なバージョンの Rust ソフトウェアを使用するようにしてください。 ## [](#関連情報)関連情報 - [ポリシー開発キットのアーキテクチャの概要](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-architecture) - [Flex Gateway ポリシー開発キット (PDK) の前提条件](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-prerequisites) # PDK のネットワークプロキシの設定 ネットワークプロキシを使用してインターネットに接続する場合、Flex Gateway ポリシー開発キット (PDK) で使用するソフトウェアツールのネットワークプロキシの定義が必要な場合があります。Docker 以外にも、​[PDK の前提条件](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-prerequisites)​でダウンロードされるすべてのツールは、​`HTTP_PROXY`​ および ​`HTTPS_PROXY`​ 環境変数を受け入れます。 環境変数の設定は、​[ネットワークプロキシの設定](#configure-a-network-proxy)​を参照してください。 でネットワークプロキシを使用するには、​[Docker のネットワークプロキシの設定](#configure-a-network-proxy-for-docker)​を参照してください。
使用するネットワークプロキシによっては、PDK ツールがアクセスするドメインをプロキシの許可リストで定義する必要があります。
## [](#configure-a-network-proxy)ネットワークプロキシの設定 `HTTP_PROXY`​ または ​`HTTPS_PROXY`​ 環境変数を設定するには、次のいずれかのコマンドを、変数値を自分の情報に置き換えて実行します。 - `HTTP_PROXY`​: ```ssh export HTTP_PROXY=://: ``` - `HTTPS_PROXY`​: ```ssh export HTTPS_PROXY=://: ``` - ネットワークプロキシで認証が必要な場合は、次のコマンドを使用します。 ```ssh export HTTPS_PROXY=://:@: ``` ## [](#configure-a-network-proxy-for-docker)Docker のネットワークプロキシの設定 [インテグレーションテスト](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-integration-tests)​と​[デバッグ環境](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-debug-local)​では Docker が必要です。 Docker は、Docker イメージを取得するためにインターネットにアクセスする必要があります。Docker のネットワークプロキシの設定方法は、自分のユースケースに関連した Docker ドキュメントを参照してください。 - [Docker CLI クライアント](https://docs.docker.com/network/proxy/) - [Docker Desktop on Mac](https://docs.docker.com/desktop/settings/mac/#proxies) - [Docker Desktop on Windows](https://docs.docker.com/desktop/settings/windows/#proxies) - [Docker Desktop on Linux](https://docs.docker.com/desktop/settings/linux/#proxies) # PDK のネットワークプロキシの設定 ネットワークプロキシを使用してインターネットに接続する場合、Flex Gateway ポリシー開発キット (PDK) で使用するソフトウェアツールのネットワークプロキシの定義が必要な場合があります。Docker 以外にも、​[PDK の前提条件](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-prerequisites)​でダウンロードされるすべてのツールは、​`HTTP_PROXY`​ および ​`HTTPS_PROXY`​ 環境変数を受け入れます。 環境変数の設定は、​[ネットワークプロキシの設定](#configure-a-network-proxy)​を参照してください。 でネットワークプロキシを使用するには、​[Docker のネットワークプロキシの設定](#configure-a-network-proxy-for-docker)​を参照してください。
使用するネットワークプロキシによっては、PDK ツールがアクセスするドメインをプロキシの許可リストで定義する必要があります。
## [](#configure-a-network-proxy)ネットワークプロキシの設定 `HTTP_PROXY`​ または ​`HTTPS_PROXY`​ 環境変数を設定するには、次のいずれかのコマンドを、変数値を自分の情報に置き換えて実行します。 - `HTTP_PROXY`​: ```ssh export HTTP_PROXY=://: ``` - `HTTPS_PROXY`​: ```ssh export HTTPS_PROXY=://: ``` - ネットワークプロキシで認証が必要な場合は、次のコマンドを使用します。 ```ssh export HTTPS_PROXY=://:@: ``` ## [](#configure-a-network-proxy-for-docker)Docker のネットワークプロキシの設定 [インテグレーションテスト](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-integration-tests)​と​[デバッグ環境](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-debug-local)​では Docker が必要です。 Docker は、Docker イメージを取得するためにインターネットにアクセスする必要があります。Docker のネットワークプロキシの設定方法は、自分のユースケースに関連した Docker ドキュメントを参照してください。 - [Docker CLI クライアント](https://docs.docker.com/network/proxy/) - [Docker Desktop on Mac](https://docs.docker.com/desktop/settings/mac/#proxies) - [Docker Desktop on Windows](https://docs.docker.com/desktop/settings/windows/#proxies) - [Docker Desktop on Linux](https://docs.docker.com/desktop/settings/linux/#proxies) # PDK のネットワークプロキシの設定 ネットワークプロキシを使用してインターネットに接続する場合、Flex Gateway ポリシー開発キット (PDK) で使用するソフトウェアツールのネットワークプロキシの定義が必要な場合があります。Docker 以外にも、​[PDK の前提条件](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-prerequisites)​でダウンロードされるすべてのツールは、​`HTTP_PROXY`​ および ​`HTTPS_PROXY`​ 環境変数を受け入れます。 環境変数の設定は、​[ネットワークプロキシの設定](#configure-a-network-proxy)​を参照してください。 でネットワークプロキシを使用するには、​[Docker のネットワークプロキシの設定](#configure-a-network-proxy-for-docker)​を参照してください。
使用するネットワークプロキシによっては、PDK ツールがアクセスするドメインをプロキシの許可リストで定義する必要があります。
## [](#configure-a-network-proxy)ネットワークプロキシの設定 `HTTP_PROXY`​ または ​`HTTPS_PROXY`​ 環境変数を設定するには、次のいずれかのコマンドを、変数値を自分の情報に置き換えて実行します。 - `HTTP_PROXY`​: ```ssh export HTTP_PROXY=://: ``` - `HTTPS_PROXY`​: ```ssh export HTTPS_PROXY=://: ``` - ネットワークプロキシで認証が必要な場合は、次のコマンドを使用します。 ```ssh export HTTPS_PROXY=://:@: ``` ## [](#configure-a-network-proxy-for-docker)Docker のネットワークプロキシの設定 [インテグレーションテスト](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-integration-tests)​と​[デバッグ環境](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-debug-local)​では Docker が必要です。 Docker は、Docker イメージを取得するためにインターネットにアクセスする必要があります。Docker のネットワークプロキシの設定方法は、自分のユースケースに関連した Docker ドキュメントを参照してください。 - [Docker CLI クライアント](https://docs.docker.com/network/proxy/) - [Docker Desktop on Mac](https://docs.docker.com/desktop/settings/mac/#proxies) - [Docker Desktop on Windows](https://docs.docker.com/desktop/settings/windows/#proxies) - [Docker Desktop on Linux](https://docs.docker.com/desktop/settings/linux/#proxies) # PDK の前提条件の確認 Flex Gateway ポリシー開発キット (PDK) の使用を開始するには、以下の前提条件がインストールされていることを確認します。 ## [](#flex-gateway)Flex Gateway PDK のチュートリアルでは、​[Flex Gateway がダウンロード済み](https://docs.mulesoft.com/gateway/latest/)​で、製品に関する予備知識があることを前提としています。 Policies created with PDK might be compatible with Omni Gateway versions that aren’t compatible with PDK’s integration testing framework. The Omni Gateway version used for testing doesn’t affect the functionality of the policy when deployed to a different Omni Gateway version. See the following table to ensure your Omni Gateway’s compatibility:
Component Minimum Omni Gateway Version Maximum Omni Gateway Version

Policies

1.6.1

Latest

Testing Framework

1.6.1

Latest
## [](#rust-requirements)PDK を使用するための Rust の要件 1. Git ダウンロードとインストールの方法は、 [「Installing Git (Git のインストール)」](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)​を参照してください。 2. Rust プログラミング言語バージョン v1.74.0 ～ v1.83.0: 1. Rust をインストールまたは更新するには、次の curl コマンドを実行します。 ```ssh curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ```
curl がインストールされていない場合は、 「Install curl (curl のインストール)」​を参照してください。
2. PDK で使用される ​`wasm32-wasi`​ コンパイルターゲットは Rust v1.84.0 で非推奨になるため、Rust を最新の互換性のある最新バージョンにダウングレードします。 ```ssh rustup default 1.83.0 ``` 3. Rust WebAssembly システムインターフェース (WASI) クレート Rust WASI をインストールまたは更新するには、次のコマンドを実行します。 ```ssh rustup target add wasm32-wasi ``` 4. Cargo Generate Cargo Generate をインストールまたは更新するには、次のコマンドを実行します。 ```ssh cargo install --locked cargo-generate ``` ## [](#サポートされているオペレーティングシステム)サポートされているオペレーティングシステム - macOS - Ubuntu Ubuntu を使用するには、​[PDK を使用するための Rust の要件](#rust-requirements)​ をインストールした後で、以下のコマンドを使用して必要なパッケージをインストールします。 ```ssh sudo apt install -y build-essential sudo apt install -y pkg-config sudo apt install -y libssl-dev ``` - Windows
PDK では、カスタムポリシーの開発とテストでのみ Windows をサポートしています。ただし、Flex Gateway は本番環境では Windows をサポートしていません。
PDK で提供されている ​`make`​ コマンドを実行するには、以下をインストールします。 1. [Windows の PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.3) 2. 次のいずれかの Make: - [Make for Windows](https://gnuwin32.sourceforge.net/packages/make.htm) - Chocolatey: ```ssh choco install make ``` ## [](#cli)Anypoint CLI PDK 用の Anypoint CLI を設定する手順は、次のとおりです。 1. [Anypoint CLI 4.x v1.4.4 以降をインストールします](https://docs.mulesoft.com/jp/anypoint-cli/latest/install)​。
自分の Anypoint CLI 4.x バージョンを確認するには、​「Verify the Core Package Version (コアパッケージバージョンを確認する)」​を参照してください。
2. [接続アプリケーション](https://docs.mulesoft.com/jp/access-management/connected-apps-overview)​を使用して、​[Anypoint Platform CLI に対して認証します](https://docs.mulesoft.com/jp/anypoint-cli/latest/auth)​。 接続アプリケーションで認証を行うには、アプリケーションのクライアント ID とクライアントシークレットを提供します。
Anypoint Platform に対する認証では、​[View Organization (組織の表示)]​ および ​[View Environment (環境の表示)]​ スコープに加えて、Exchange へのカスタムポリシーのアップロードを完了するために、接続アプリケーションに ​[Exchange Contributor (Exchange コントリビュータ)]​ スコープを適用しておく必要があります。
3. Anypoint CLI PDK プラグインをインストールまたは更新するには、次のコマンドを実行します。 ```ssh anypoint-cli-v4 plugins:install anypoint-cli-pdk-plugin ``` ## [](#docker)Docker Docker は、PDK で用意されている​[ローカルデバッグ環境](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-debug-local)​と​[インテグレーションテストフレームワーク](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-integration-tests)​を使用するために必要です。Docker がなくてもポリシーのビルドとパブリッシュは可能です。 Docker をインストールするには、 [「Install Docker (Docker のインストール)」](https://docs.docker.com/get-docker/)​を参照してください。
ポリシーの開発とテストのみが目的であれば、Windows の Docker で Flex Gateway をローカルモードで実行することもできます。ただし、Flex Gateway は本番環境では Windows をサポートしていません。
## [](#visual-studio-推奨-ide)Visual Studio (推奨 IDE) PDK は、 [Rust in Visual Studio Code プラグイン](https://code.visualstudio.com/docs/languages/rust)​がインストールされていれば、 [Microsoft Visual Studio](https://code.visualstudio.com/)​ など、どの IDE やテキストエディターでも使用できます。 ## [](#関連情報)関連情報 - [PDK のアップグレード](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-upgrade-pdk) - [ポリシー開発キットのアーキテクチャの概要](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-architecture) - [カスタムポリシーの開発](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-develop-custom-policies) # Rust でのカスタムポリシー機能の実装 以降のページでは、さまざまなポリシータスクを完了するための Rust コード例を示します。ポリシーの Rust コードは ​`src/lib.rs`​ ファイルで実装します。 コード例は、Rust プログラミング言語に関する基礎知識があることを前提としています。Rust のプログラミングに関する詳細は、以下を参照してください。 - [Rust プログラミング言語ドキュメント](https://doc.rust-lang.org/book/) - [Rust クックブック](https://rust-lang-nursery.github.io/rust-cookbook/intro.html) ## [](#始める前に)始める前に - [新規プロジェクトを作成する](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-create-project) - [スキーマの定義](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-create-schema-definition)
ポリシーを実装する際に、設定パラメーターの追加または再定義が必要になる場合もあります。
- [追加のポリシー機能](#provided-rust-source-code)​を定義する前に、「​[ポリシーテンプレート](#policy-template)​」、「​[ラップされた関数](#wrapped-functions)​」、「​[フローのキャンセル](#flow-cancellation)​」でポリシーのソースコード構造について確認してください。 ## [](#policy-template)ポリシーテンプレート Flex Gateway ポリシー開発キット (PDK) には、ポリシーの実装を開始するためのテンプレートとして、ポリシープロジェクトの最初の ​`src/lib.rs`​ ファイルが用意されています。 ```Rust // Copyright 2024 Salesforce, Inc. All rights reserved. mod generated; use anyhow::{anyhow, Result}; use pdk::hl::*; use pdk::logger; use crate::generated::config::Config; // This filter shows how to log a specific request header. // You can extend the function and use the configurations exposed in config.rs file async fn request_filter(request_state: RequestState, _config: &Config) { let headers_state = request_state.into_headers_state().await; let token = headers_state.handler().header("Token").unwrap_or_default(); // Log the header value logger::info!("Header value: {token}"); } #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&bytes).map_err(|err| { anyhow!( "Failed to parse configuration '{}'. Cause: {}", String::from_utf8_lossy(&bytes), err ) })?; let filter = on_request(|rs| request_filter(rs, &config)); launcher.launch(filter).await?; Ok(()) } ``` ポリシーは簡単なログを実行します。受信した要求ごとに、ポリシーは ​`INFO`​ ログレベルでヘッダー​`トークン`​を記録します。 以下の要素でポリシーを設定します。 - `use pdk::api::hl::*;`​: PDK のすべてのコンポーネントを ​`lib.rs`​ ソースコードにインポートします。 - `#[entrypoint]`​ 関数: ポリシーが適用されたときに実行され、​`request_filter`​ 関数を呼び出します。この関数の内部で定義された変数は、ポリシーが適用されている間は有効です。 `#[entrypoint]`​ 関数は、以下のパラメーターを受け取ります。 - `Launcher`​: 検索条件関数を設定します。 - `Configuration`​: [policy-pdk-create-schema-definition.adoc](#policy-pdk-create-schema-definition.adoc)で定義されている設定パラメーターを提供します。 - `request_filter`​: ポリシーが適用される API インスタンスに送信される要求ごとに 1 回実行されます。この関数は、ポリシー例で実行される検索条件を実装します。この関数の中で定義されている変数は、要求の実行中に利用できます。 `request_filter`​ は、ラップされた関数の例です。 `#[entrypoint]`​ 関数はラップされた関数を実行します。 ```Rust let filter = on_request(|rs| request_filter(rs, &config)); launcher.launch(filter).await?; ``` ## [](#wrapped-functions)ラップされた関数 `on_response`​ または ​`on_request`​ ラッパーは、検索条件関数が実行されるタイミングを定義します。 `#[entrypoint]`​ 関数では、提供されている ​`requests_filter`​ と ​`response_filter`​ 以外のカスタム関数を定義することができます。​`requests_filter`​ と ​`response_filter`​ は例に過ぎません。 前の例で示したように、受信要求を絞り込む代わりに、​`on_response`​ ラッパーを使用して送信応答を処理することができます。 ```Rust async fn response_filter(response_state: ResponseState, _config: &Config) { ... } #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&bytes).map_err(|err| { anyhow!( "Failed to parse configuration '{}'. Cause: {}", String::from_utf8_lossy(&bytes), err ) })?; let filter = on_response(|rs| response_filter(rs, &config)); launcher.launch(filter).await?; Ok(()) } ```
request_filter​ 関数は ​response_filter​ 関数になりました。
要求と応答の両方を絞り込むには、両方のラッパーを使用します。 ```Rust async fn request_filter(request_state: RequestState,_config: &Config) { ... } async fn response_filter(response_state: ResponseState,_config: &Config) { ... } #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&bytes).map_err(|err| { anyhow!( "Failed to parse configuration '{}'. Cause: {}", String::from_utf8_lossy(&bytes), err ) })?; let filter = on_request(|rs| request_filter(rs, &config)) .on_response(|rs| response_filter(rs, &config)); launcher.launch(filter).await?; Ok(()) } ``` ## [](#flow-cancellation)フローのキャンセル カスタムポリシーはシングルスレッド環境で実行されます。ただし、ラップされた関数 (​`非同期`​関数の ​`on_request`​ と ​`on_response`​) のすべてのセットは同時タスクとして実行されるため、単一ポリシーのインスタンスが複数の要求を同時に処理することになります。 この動作をサポートするために、すべての ​`.await`​ が潜在的なタスク中断ポイントとなります。​`.await`​ が呼び出されると、基盤となる非同期ランタイムは現在のタスクをしばらくスリープさせて、まだ完了していない別のタスクを目覚めさせることができます。非同期ランタイムはタスクをキャンセルすることができ、最後の ​`.await`​ 呼び出しの後にあるコードを実行することはありません。 `on_request`​ 関数と ​`on_response`​ 関数は、​`.await`​ 呼び出しが潜在的なキャンセルポイントであることを想定しています。 次のコード例に示すように、タスクキャンセルの最も一般的な状況は、要求関数がボディを待っている途中でアップストリームポリシーが応答を早期に返した場合です。 ```Rust // Request function for upstream policy async fn upstream_request(state: RequestState) -> Response { Response::new(404) } // Request function for downstream policy async fn downstream_request(state: RequestState) { // Request function will be cancelled after this .await point. let body_state = state.into_body_state().await; // Code here will never be executed } ``` ## [](#provided-rust-source-code)PDK の機能を体験するために用意されている Rust ソースコード PDK では、以下のポリシー機能のコード例が用意されています。追加のポリシー機能を定義する前に、​[ポリシーテンプレート](#policy-template)​と​[ラップされた関数](#wrapped-functions)​を確認してください。 - [ポリシーログの設定](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-logging) - [リクエストヘッダーとリクエストボディの読み取りと書き込み](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-headers) - [パラメーターの挿入](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-inject-parameters) - [HTTP コールの実行](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-http-request) - [CORS ライブラリ関数の使用](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-cors) - [JWT ライブラリ関数の使用](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-jwt) - [DataWeave 式の使用](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-dataweave) - [要求と応答でのデータの共有](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-share-data) - [サードパーティライブラリの使用](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-libraries) - [ワーカー間でのデータ共有とキャッシュの設定](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-caching) - [ポリシーのメタデータへのアクセス](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-metadata) - [ポリシー間のデータ共有](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-streamproperties) - [要求認証情報へのアクセス](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-authentication) - [遅延関数、周期関数、同期関数の設定](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-timer) - [要求実行の停止](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-stop) # Rust でのカスタムポリシー機能の実装 以降のページでは、さまざまなポリシータスクを完了するための Rust コード例を示します。ポリシーの Rust コードは ​`src/lib.rs`​ ファイルで実装します。 コード例は、Rust プログラミング言語に関する基礎知識があることを前提としています。Rust のプログラミングに関する詳細は、以下を参照してください。 - [Rust プログラミング言語ドキュメント](https://doc.rust-lang.org/book/) - [Rust クックブック](https://rust-lang-nursery.github.io/rust-cookbook/intro.html) ## [](#始める前に)始める前に - [新規プロジェクトを作成する](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-create-project) - [スキーマの定義](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-create-schema-definition)
ポリシーを実装する際に、設定パラメーターの追加または再定義が必要になる場合もあります。
- [追加のポリシー機能](#provided-rust-source-code)​を定義する前に、「​[ポリシーテンプレート](#policy-template)​」、「​[ラップされた関数](#wrapped-functions)​」、「​[フローのキャンセル](#flow-cancellation)​」でポリシーのソースコード構造について確認してください。 ## [](#policy-template)ポリシーテンプレート Flex Gateway ポリシー開発キット (PDK) には、ポリシーの実装を開始するためのテンプレートとして、ポリシープロジェクトの最初の ​`src/lib.rs`​ ファイルが用意されています。 ```Rust // Copyright 2024 Salesforce, Inc. All rights reserved. mod generated; use anyhow::{anyhow, Result}; use pdk::hl::*; use pdk::logger; use crate::generated::config::Config; // This filter shows how to log a specific request header. // You can extend the function and use the configurations exposed in config.rs file async fn request_filter(request_state: RequestState, _config: &Config) { let headers_state = request_state.into_headers_state().await; let token = headers_state.handler().header("Token").unwrap_or_default(); // Log the header value logger::info!("Header value: {token}"); } #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&bytes).map_err(|err| { anyhow!( "Failed to parse configuration '{}'. Cause: {}", String::from_utf8_lossy(&bytes), err ) })?; let filter = on_request(|rs| request_filter(rs, &config)); launcher.launch(filter).await?; Ok(()) } ``` ポリシーは簡単なログを実行します。受信した要求ごとに、ポリシーは ​`INFO`​ ログレベルでヘッダー​`トークン`​を記録します。 以下の要素でポリシーを設定します。 - `use pdk::api::hl::*;`​: PDK のすべてのコンポーネントを ​`lib.rs`​ ソースコードにインポートします。 - `#[entrypoint]`​ 関数: ポリシーが適用されたときに実行され、​`request_filter`​ 関数を呼び出します。この関数の内部で定義された変数は、ポリシーが適用されている間は有効です。 `#[entrypoint]`​ 関数は、以下のパラメーターを受け取ります。 - `Launcher`​: 検索条件関数を設定します。 - `Configuration`​: [policy-pdk-create-schema-definition.adoc](#policy-pdk-create-schema-definition.adoc)で定義されている設定パラメーターを提供します。 - `request_filter`​: ポリシーが適用される API インスタンスに送信される要求ごとに 1 回実行されます。この関数は、ポリシー例で実行される検索条件を実装します。この関数の中で定義されている変数は、要求の実行中に利用できます。 `request_filter`​ は、ラップされた関数の例です。 `#[entrypoint]`​ 関数はラップされた関数を実行します。 ```Rust let filter = on_request(|rs| request_filter(rs, &config)); launcher.launch(filter).await?; ``` ## [](#wrapped-functions)ラップされた関数 `on_response`​ または ​`on_request`​ ラッパーは、検索条件関数が実行されるタイミングを定義します。 `#[entrypoint]`​ 関数では、提供されている ​`requests_filter`​ と ​`response_filter`​ 以外のカスタム関数を定義することができます。​`requests_filter`​ と ​`response_filter`​ は例に過ぎません。 前の例で示したように、受信要求を絞り込む代わりに、​`on_response`​ ラッパーを使用して送信応答を処理することができます。 ```Rust async fn response_filter(response_state: ResponseState, _config: &Config) { ... } #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&bytes).map_err(|err| { anyhow!( "Failed to parse configuration '{}'. Cause: {}", String::from_utf8_lossy(&bytes), err ) })?; let filter = on_response(|rs| response_filter(rs, &config)); launcher.launch(filter).await?; Ok(()) } ```
request_filter​ 関数は ​response_filter​ 関数になりました。
要求と応答の両方を絞り込むには、両方のラッパーを使用します。 ```Rust async fn request_filter(request_state: RequestState,_config: &Config) { ... } async fn response_filter(response_state: ResponseState,_config: &Config) { ... } #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&bytes).map_err(|err| { anyhow!( "Failed to parse configuration '{}'. Cause: {}", String::from_utf8_lossy(&bytes), err ) })?; let filter = on_request(|rs| request_filter(rs, &config)) .on_response(|rs| response_filter(rs, &config)); launcher.launch(filter).await?; Ok(()) } ``` ## [](#flow-cancellation)フローのキャンセル カスタムポリシーはシングルスレッド環境で実行されます。ただし、ラップされた関数 (​`非同期`​関数の ​`on_request`​ と ​`on_response`​) のすべてのセットは同時タスクとして実行されるため、単一ポリシーのインスタンスが複数の要求を同時に処理することになります。 この動作をサポートするために、すべての ​`.await`​ が潜在的なタスク中断ポイントとなります。​`.await`​ が呼び出されると、基盤となる非同期ランタイムは現在のタスクをしばらくスリープさせて、まだ完了していない別のタスクを目覚めさせることができます。非同期ランタイムはタスクをキャンセルすることができ、最後の ​`.await`​ 呼び出しの後にあるコードを実行することはありません。 `on_request`​ 関数と ​`on_response`​ 関数は、​`.await`​ 呼び出しが潜在的なキャンセルポイントであることを想定しています。 次のコード例に示すように、タスクキャンセルの最も一般的な状況は、要求関数がボディを待っている途中でアップストリームポリシーが応答を早期に返した場合です。 ```Rust // Request function for upstream policy async fn upstream_request(state: RequestState) -> Response { Response::new(404) } // Request function for downstream policy async fn downstream_request(state: RequestState) { // Request function will be cancelled after this .await point. let body_state = state.into_body_state().await; // Code here will never be executed } ``` ## [](#provided-rust-source-code)PDK の機能を体験するために用意されている Rust ソースコード PDK では、以下のポリシー機能のコード例が用意されています。追加のポリシー機能を定義する前に、​[ポリシーテンプレート](#policy-template)​と​[ラップされた関数](#wrapped-functions)​を確認してください。 - [ポリシーログの設定](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-logging) - [リクエストヘッダーとリクエストボディの読み取りと書き込み](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-headers) - [パラメーターの挿入](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-inject-parameters) - [HTTP コールの実行](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-http-request) - [コントラクト検証ライブラリ関数の使用](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-contracts) - [CORS ライブラリ関数の使用](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-cors) - [JWT ライブラリ関数の使用](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-jwt) - [DataWeave 式の使用](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-dataweave) - [要求と応答でのデータの共有](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-share-data) - [サードパーティライブラリの使用](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-libraries) - [ワーカー間でのデータ共有とキャッシュの設定](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-caching) - [ポリシーのメタデータへのアクセス](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-metadata) - [ポリシー間のデータ共有](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-streamproperties) - [要求認証情報へのアクセス](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-authentication) - [遅延関数、周期関数、同期関数の設定](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-timer) - [要求実行の停止](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-stop) # Rust でのカスタムポリシー機能の実装 以降のページでは、さまざまなポリシータスクを完了するための Rust コード例を示します。ポリシーの Rust コードは ​`src/lib.rs`​ ファイルで実装します。 コード例は、Rust プログラミング言語に関する基礎知識があることを前提としています。Rust のプログラミングに関する詳細は、以下を参照してください。 - [Rust プログラミング言語ドキュメント](https://doc.rust-lang.org/book/) - [Rust クックブック](https://rust-lang-nursery.github.io/rust-cookbook/intro.html) ## [](#始める前に)始める前に - [新規プロジェクトを作成する](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-create-project) - [スキーマの定義](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-create-schema-definition)
ポリシーを実装する際に、設定パラメーターの追加または再定義が必要になる場合もあります。
- [追加のポリシー機能](#provided-rust-source-code)​を定義する前に、「​[ポリシーテンプレート](#policy-template)​」、「​[ラップされた関数](#wrapped-functions)​」、「​[フローのキャンセル](#flow-cancellation)​」でポリシーのソースコード構造について確認してください。 ## [](#policy-template)ポリシーテンプレート Flex Gateway ポリシー開発キット (PDK) には、ポリシーの実装を開始するためのテンプレートとして、ポリシープロジェクトの最初の ​`src/lib.rs`​ ファイルが用意されています。 ```Rust // Copyright 2024 Salesforce, Inc. All rights reserved. mod generated; use anyhow::{anyhow, Result}; use pdk::hl::*; use pdk::logger; use crate::generated::config::Config; // This filter shows how to log a specific request header. // You can extend the function and use the configurations exposed in config.rs file async fn request_filter(request_state: RequestState, _config: &Config) { let headers_state = request_state.into_headers_state().await; let token = headers_state.handler().header("Token").unwrap_or_default(); // Log the header value logger::info!("Header value: {token}"); } #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&bytes).map_err(|err| { anyhow!( "Failed to parse configuration '{}'. Cause: {}", String::from_utf8_lossy(&bytes), err ) })?; let filter = on_request(|rs| request_filter(rs, &config)); launcher.launch(filter).await?; Ok(()) } ``` ポリシーは簡単なログを実行します。受信した要求ごとに、ポリシーは ​`INFO`​ ログレベルでヘッダー​`トークン`​を記録します。 以下の要素でポリシーを設定します。 - `use pdk::api::hl::*;`​: PDK のすべてのコンポーネントを ​`lib.rs`​ ソースコードにインポートします。 - `#[entrypoint]`​ 関数: ポリシーが適用されたときに実行され、​`request_filter`​ 関数を呼び出します。この関数の内部で定義された変数は、ポリシーが適用されている間は有効です。 `#[entrypoint]`​ 関数は、以下のパラメーターを受け取ります。 - `Launcher`​: 検索条件関数を設定します。 - `Configuration`​: [policy-pdk-create-schema-definition.adoc](#policy-pdk-create-schema-definition.adoc)で定義されている設定パラメーターを提供します。 - `request_filter`​: ポリシーが適用される API インスタンスに送信される要求ごとに 1 回実行されます。この関数は、ポリシー例で実行される検索条件を実装します。この関数の中で定義されている変数は、要求の実行中に利用できます。 `request_filter`​ は、ラップされた関数の例です。 `#[entrypoint]`​ 関数はラップされた関数を実行します。 ```Rust let filter = on_request(|rs| request_filter(rs, &config)); launcher.launch(filter).await?; ``` ## [](#wrapped-functions)ラップされた関数 `on_response`​ または ​`on_request`​ ラッパーは、検索条件関数が実行されるタイミングを定義します。 `#[entrypoint]`​ 関数では、提供されている ​`requests_filter`​ と ​`response_filter`​ 以外のカスタム関数を定義することができます。​`requests_filter`​ と ​`response_filter`​ は例に過ぎません。 前の例で示したように、受信要求を絞り込む代わりに、​`on_response`​ ラッパーを使用して送信応答を処理することができます。 ```Rust async fn response_filter(response_state: ResponseState, _config: &Config) { ... } #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&bytes).map_err(|err| { anyhow!( "Failed to parse configuration '{}'. Cause: {}", String::from_utf8_lossy(&bytes), err ) })?; let filter = on_response(|rs| response_filter(rs, &config)); launcher.launch(filter).await?; Ok(()) } ```
request_filter​ 関数は ​response_filter​ 関数になりました。
要求と応答の両方を絞り込むには、両方のラッパーを使用します。 ```Rust async fn request_filter(request_state: RequestState,_config: &Config) { ... } async fn response_filter(response_state: ResponseState,_config: &Config) { ... } #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration) -> Result<()> { let config: Config = serde_json::from_slice(&bytes).map_err(|err| { anyhow!( "Failed to parse configuration '{}'. Cause: {}", String::from_utf8_lossy(&bytes), err ) })?; let filter = on_request(|rs| request_filter(rs, &config)) .on_response(|rs| response_filter(rs, &config)); launcher.launch(filter).await?; Ok(()) } ``` ## [](#flow-cancellation)フローのキャンセル カスタムポリシーはシングルスレッド環境で実行されます。ただし、ラップされた関数 (​`非同期`​関数の ​`on_request`​ と ​`on_response`​) のすべてのセットは同時タスクとして実行されるため、単一ポリシーのインスタンスが複数の要求を同時に処理することになります。 この動作をサポートするために、すべての ​`.await`​ が潜在的なタスク中断ポイントとなります。​`.await`​ が呼び出されると、基盤となる非同期ランタイムは現在のタスクをしばらくスリープさせて、まだ完了していない別のタスクを目覚めさせることができます。非同期ランタイムはタスクをキャンセルすることができ、最後の ​`.await`​ 呼び出しの後にあるコードを実行することはありません。 `on_request`​ 関数と ​`on_response`​ 関数は、​`.await`​ 呼び出しが潜在的なキャンセルポイントであることを想定しています。 次のコード例に示すように、タスクキャンセルの最も一般的な状況は、要求関数がボディを待っている途中でアップストリームポリシーが応答を早期に返した場合です。 ```Rust // Request function for upstream policy async fn upstream_request(state: RequestState) -> Response { Response::new(404) } // Request function for downstream policy async fn downstream_request(state: RequestState) { // Request function will be cancelled after this .await point. let body_state = state.into_body_state().await; // Code here will never be executed } ``` ## [](#provided-rust-source-code)PDK の機能を体験するために用意されている Rust ソースコード PDK では、以下のポリシー機能のコード例が用意されています。追加のポリシー機能を定義する前に、​[ポリシーテンプレート](#policy-template)​と​[ラップされた関数](#wrapped-functions)​を確認してください。 - [ポリシーログの設定](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-logging) - [リクエストヘッダーとリクエストボディの読み取りと書き込み](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-headers) - [パラメーターの挿入](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-inject-parameters) - [HTTP コールの実行](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-http-request) - [コントラクト検証ライブラリ関数の使用](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-contracts) - [CORS ライブラリ関数の使用](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-cors) - [JWT ライブラリ関数の使用](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-jwt) - [DataWeave 式の使用](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-dataweave) - [要求と応答でのデータの共有](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-share-data) - [サードパーティライブラリの使用](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-libraries) - [ワーカー間でのデータ共有とキャッシュの設定](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-caching) - [ポリシーのメタデータへのアクセス](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-metadata) - [ポリシー間のデータ共有](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-streamproperties) - [要求認証情報へのアクセス](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-authentication) - [遅延関数、周期関数、同期関数の設定](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-timer) - [ポリシー違反のレポート](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-violations) - [要求実行の停止](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-stop) # インテグレーションテストの作成 Flex Gateway ポリシー開発キット (PDK) には、カスタムポリシーのインテグレーション回帰を検出するための自動化テストフレームワークが用意されています。 PDK が提供するインテグレーションテストフレームワークは、Docker コンテナのローカルモードで実行されている Flex Gateway のみをサポートします。接続モードで動作する Flex Gateway や別のプラットフォームにポリシーをデプロイする場合でも、まず Docker コンテナのローカルモードで実行されている Flex Gateway を使用して PDK でポリシーをテストしてください。
ポリシーの開発とテストのみが目的であれば、Windows の Docker で Flex Gateway をローカルモードで実行することもできます。ただし、Flex Gateway は本番環境では Windows をサポートしていません。
ポリシーをテストするには、次のタスクを実行します。 1. [始める前に](#before-you-begin)​を確認します。 2. [インテグレーションテストのディレクトリ構造](#structure)​を確認します。 3. [ローカルモードでの Flex Gateway インスタンスの登録](#register)​。 4. [カスタムポリシーを設定する](#configure-your-custom-policy)​。 5. [テスト関数を作成する](#create-a-test-function)​。 6. [インテグレーションテストを実行する](#run-integration-test)​。 7. [インテグレーションテスト用にサービスを設定する](#configure-services-for-integration-testing)​。 8. [サービスログを確認する](#review-service-logs)​。 ## [](#before-you-begin)始める前に 次の準備が整っていることを確認します。 - [Docker がインストールされている](https://www.docker.com/) ## [](#structure)インテグレーションテストのディレクトリ構造 デフォルトでは、​`/tests`​ ディレクトリには以下のファイルが保存されます。 tests ├── common.rs ├── requests.rs └── common └── logging.yaml └── registration.yaml `/tests`​ ディレクトリにはインテグレーションテストが保存されます。デフォルトでは以下のファイルが保存されます。 - `requests.rs`​ ファイル: 個別のテストモジュールと実行ファイル。 - `commons.rs`​ ファイル: すべてのインテグレーションテストモジュールに含める必要がある機能、API 設定、ポリシー設定が含まれたテストモジュール。 ## [](#register)ローカルモードでの Flex Gateway インスタンスの登録 `make test`​ コマンドを使用してカスタムポリシーのデバッグを開始するには、ローカルモードで Flex Gateway を登録します。 `make test`​ コマンドが動作するためには、​`/tests/common`​ ディレクトリに Flex Gateway の ​`registration.yaml`​ ファイルが存在する必要があります。このディレクトリで登録コマンドを実行してこのファイルを作成するか、または以前に登録してある Flex Gateway の ​`registration.yaml`​ ファイルをこのディレクトリに移動します。 Flex Gateway の登録については、以下を参照してください。 - [ユーザー名とパスワードを使用した Docker コンテナでの登録と実行](https://docs.mulesoft.com/gateway/latest/local-reg-run-up#docker) - [接続アプリケーションを使用した Docker コンテナでの登録と実行](https://docs.mulesoft.com/gateway/latest/local-reg-run-app#docker) - [トークンを使用した Docker コンテナでの登録と実行](https://docs.mulesoft.com/gateway/latest/local-reg-run-token#docker)
登録コマンドのみを実行してください。Docker の開始コマンドは、​make test​ コマンドがこのステップを完了するため、実行しないでください。
ポリシーをテストするデバイスごとに異なる登録ファイルを作成してください。 登録ファイルはリモートリポジトリへの保存では無視され、プロジェクトディレクトリのルートにある ​`.gitignore`​ ファイルにリストされます。 ## [](#configure-your-custom-policy)カスタムポリシーを設定する 各テスト関数では、その要求の API とポリシーの設定が必要です。 カスタムポリシーを設定する手順は、次のとおりです。 1. `show-policy-ref-name`​ を実行してポリシー ID を表示します。 ```ssh make show-policy-ref-name ``` 2. 結果をコピーします。 3. `commons.rs`​ の ​`{{project-name}}`​ を自分のポリシー ID で上書きします。例: ```rust pub const POLICY_NAME: &str = ""; ``` 4. ポリシーの設定パラメーターを定義します。 設定パラメーターは、​`definition/gcl.yaml`​ ファイルにあります。 ## [](#create-a-test-function)テスト関数を作成する 既存のテストモジュール (​`/tests/requests.rs`​ など) に新しいテスト関数を配置して、新しいテストモジュールを追加します。 PDK テスト関数は、​`#[pdk_test]`​ 属性がつけられた​`非同期`​関数です。 ```rust use pdk_test::pdk_test; #[pdk_test] async fn say_hello() { } ```
ボディが空であるため、この関数がエラーとなることはありません。​make test​ を実行してすべてが正常に動作することを確認します。
## [](#run-integration-test)インテグレーションテストを実行する `/tests`​ フォルダーのインテグレーションテストを実行するには、​`make test`​ コマンドを実行します。 ```ssh make test ``` インテグレーションテストに機能を追加するたびにこのテストを実行して、正しく設定されていることを確認してください。
make test​ コマンドは、インテグレーションテストを実行する前にポリシーをコンパイルします。
## [](#configure-services-for-integration-testing)インテグレーションテスト用にサービスを設定する PDK インテグレーションテストには、Docker ネットワーク内で実行されるサービスの複合体が含まれます。サービスインスタンスは ​`TestComposite`​ オブジェクトに登録できます。すべてのサービスには、設定、ホスト名、インスタンスがあります。 `Cargo.toml`​ ファイルの ​`[dev-dependencies]`​ セクションにある ​`pdk-test`​ クレートは PDK のカスタムポリシーのインテグレーションテストを作成するためのすべての機能を提供します。 ### [](#supported-services)サポートされるサービス PDK のテストライブラリは以下のサービスをサポートします。
サービス 説明

Flex

Flex Gateway サービスインスタンス。

httpmock

Rust の httpmock​ サーバーへのサービスバインド。
サポートされるサービスにより、インテグレーションテストの大半のユースケースがカバーされます。異なる種別のサービスを定義することはできません。 ### [](#httpmock-service)httpmock サービス `httpmock`​ は、Rust で要求のモックを作成できるようにするモックサーバーです。 [httpmock](https://crates.io/crates/httpmock)​ サービスは、​`HttpMockConfig`​ 値を使用して設定します。テスト関数から​`結果`​を返すようにするのがベストプラクティスです。Rust の [anyhow](https://crates.io/crates/anyhow)​ クレートは、異なるデフォルトエラー種別を返せるようにします。 `httpmock`​ サービスの設定は、次のコード例を参照してください。 ```rust use pdk_test::{pdk_test, TestComposite}; use pdk_test::services::httpmock::HttpMockConfig; #[pdk_test] async fn say_hello() -> anyhow::Result<()> { // Configure HttpMock service let backend_config = HttpMockConfig::builder() .hostname("backend") .port(80) // Port where the service will accept requests .build(); // Register HTTPBin service and start the docker network let composite = TestComposite::builder() .with_service(backend_config) .build() .await?; Ok(()) } ```
Docker エンジンが正しく設定されていれば、このテストは合格します。​make test​ を実行して設定が正しいことを確認してください。
### [](#get-a-services-hande)サービスのハンドルを取得する サービスの複合体で設定されているすべてのサービスインスタンスには、カスタムインタラクション用のハンドルがあります。このハンドルはサービスエンドポイントを使用できるようにするためのソケットを返します。 サービスのハンドルを見つけるには、次のコード例を参照してください。 ```rust use pdk_test::{pdk_test, TestComposite}; use pdk_test::services::httpmock::{HttpMock, HttpMockConfig}; #[pdk_test] async fn say_hello() -> anyhow::Result<()> { // Configure HTTPMock service let backend_config = HttpMockConfig::builder() .hostname("backend") .build(); // Register HTTPMock service and start the docker network let composite = TestComposite::builder() .with_service(backend_config) .port(80) // Port where the service accepts requests .build() .await?; // Get the httpmock handle let httpmock: HttpMock = composite.service()?; Ok(()) } ```
httpmock​ インスタンスが正しく設定されていれば、このテストは合格します。​make test​ を実行して設定が正しいことを確認してください。
### [](#http-entpoint-requests)HTTP エンドポイント要求 エンドポイントをモックするには [httpmock When/Then API](https://docs.rs/httpmock/latest/httpmock/#whenthen-api)​ を使用します。 エンドポイントをモックしたら、HTTP クライアントを使用してエンドポイント要求を実行します。 [reqwest](https://crates.io/crates/reqwest/)​ クレートは、最も包括的で柔軟な Rust HTTP クライアントを提供します。 エンドポイントをモックして要求を実行するには、次のコード例を参照してください。 ```rust use pdk_test::{pdk_test, TestComposite}; use pdk_test::services::httpmock::{HttpMock, HttpMockConfig}; #[pdk_test] async fn say_hello() -> anyhow::Result<()> { // Configure HttpMock service let backend_config = HttpMockConfig::builder() .hostname("backend") .port(80) // Port where the service will accept requests .build(); // Register HTTPBin service and start the docker network let composite = TestComposite::builder() .with_service(backend_config) .build() .await?; // Get the httpmock handle let httpmock: HttpMock = composite.service()?; // Connect the mock server let mock_server = httpmock::MockServer::connect_async(httpmock.socket()).await; // Configure the endpoint mocks mock_server.mock_async(|when, then| { when.path_contains("/hello"); then.status(202).body("World!"); }).await; let base_url = mock_server.base_url(); // Hit the endpoint let response = reqwest::get(format!("{base_url}/hello")).await?; // Assert on response assert_eq!(response.status(), 202); assert_eq!(response.text().await?, "World!"); Ok(()) } ```
make test​ を実行して設定が正しいことを確認してください。
### [](#configure-a-flex-service-instance)Flex サービスインスタンスを設定する `Flex`​ サービスは、​`TestComposite`​ で ​`FlexConfig`​ 構造のインスタンスを登録して設定します。​`FlexConfig`​ インスタンスを完了するには、​`ApiConfig`​ および ​`PolicyConfig`​ インスタンスも定義する必要があります。 `FlexConfig`​ 構造には次のプロパティがあります。
プロパティ コンテンツ

version

テストする Flex Gateway バージョン。

hostname

Flex​ サービスのホスト名。デフォルトでは、「local-flex」です。

config_mounts

Flex​ サービスが設定ファイルを見つけるためのローカルディレクトリのマップ。 POLICY_DIR​ 定数と ​COMMON_CONFIG_DIR​ 定数は、デフォルトでは ​common.rs​ モジュールで定義されます。テストで追加の設定が必要な場合、テスト関数の特定の設定が含まれるディレクトリを追加します。

with_api

Flex​ サービスインスタンスにデプロイされた API の ​ApiConfiguration​。複数の API を設定するには、複数回コールします。

ports

Flex​ サービスが要求をリスンするポートのリスト。​config_mount​ ディレクトリに含まれるいずれかの設定ディレクトリで API を公開する場合、そのポートと ​spec.address​ プロパティで設定されたポートが一致している必要があります。
`ApiConfig`​ には次のプロパティがあります。
プロパティ コンテンツ

name

API の名前。

upstream

アップストリームサービスへの参照。

path

アップストリーム要求の送信先パス。

port

API が要求をリスンするポート。

policies

API に適用される ​PolicyConfig​ インスタンスのリスト。
`PolicyConfig`​ には次のプロパティがあります。
プロパティ コンテンツ

name

適用するポリシー。

configuration

ポリシーのパラメーター。
次のコード例では、完全な ​`Flex`​ サービスを定義しています。 ```rust mod common; use common::*; use pdk_test::{pdk_test, TestComposite}; use pdk_test::port::Port; use pdk_test::services::flex::FlexConfig; // Port where Flex listens for requests const FLEX_PORT: Port = 8081; #[pdk_test] async fn say_hello() -> anyhow::Result<()> { // Configure an upstream service for the API let httpmock_config = HttpMockConfig::builder() .port(80) .version("latest") .hostname("backend") .build(); // Configure a policy for the API let policy_config = PolicyConfig::builder() .name(POLICY_NAME) .configuration(serde_json::json!({"source": "http://backend/blocked", "frequency": 60})) .build(); // Configure the API to deploy to the Flex let api_config = ApiConfig::builder() .name("ingress-http") .upstream(&httpmock_config) .path("/anything/echo/") .port(FLEX_PORT) .policies([policy_config]) .build(); // Configure the Flex service let flex_config = FlexConfig::builder() .version("1.6.1") .hostname("local-flex") .config_mounts([ (POLICY_DIR, "policy"), (COMMON_CONFIG_DIR, "common") ]) .with_api(api_config) .build(); let composite = TestComposite::builder() .with_service(flex_config) .with_service(httpmock_config) .build() .await?; } ```

make test​ を実行して設定が正しいことを確認してください。
### [](#flex-service-endpoint-requests)Flex サービスエンドポイント要求 `Flex`​ サービスは、ポートに応じた外部ベース URL でエンドポイントを表示します。これらの URL にアクセスするには、ポートごとにインデックス付けされた ​`external_url()`​ メソッドを Flex サービスインスタンスハンドルで指定する必要があります。例: ```rust use pdk_test::{pdk_test, TestComposite, port::Port}; use pdk_test::services::flex::Flex; const FLEX_PORT: Port = 8081; async fn build_composite() -> anyhow::Result { todo!("Configuration stuff comes here") } #[pdk_test] async fn say_hello() -> anyhow::Result<()> { // Invoke a helper composite builder function for simplicity let composite = build_composite().await?; // Get the Flex service handle let flex: Flex = composite.service()?; // Get the URL for our configured port let flex_url = flex.external_url(FLEX_PORT).unwrap(); let response = reqwest::get(format!("{flex_url}/hello")).await?; // Make assertions Ok(()) } ``` ### [](#combine-multiple-services)複数サービスの組み合わせ 通常、PDK のインテグレーションテストには、​`Flex`​ サービスと、1 つ以上のバックエンドサービスが含まれます。 次のコードは、カスタムポリシーの作成時に生成されるデフォルトのテストです。 ```rust mod common; use httpmock::MockServer; use pdk_test::{pdk_test, TestComposite}; use pdk_test::port::Port; use pdk_test::services::flex::{FlexConfig, Flex}; use pdk_test::services::httpmock::{HttpMockConfig, HttpMock}; use common::*; // Directory with the configurations for the `hello` test. const HELLO_CONFIG_DIR: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/requests/hello"); // Flex port for the internal test network const FLEX_PORT: Port = 8081; // This integration test shows how to build a test to compose a local-flex instance // with a MockServer backend #[pdk_test] async fn hello() -> anyhow::Result<()> { // Configure an HttpMock service let httpmock_config = HttpMockConfig::builder() .port(80) .version("latest") .hostname("backend") .build(); // Configure a policy for the API let policy_config = PolicyConfig::builder() .name(POLICY_NAME) .configuration(serde_json::json!({"source": "http://backend/blocked", "frequency": 60})) .build(); // Configure the API to deploy to the Flex let api_config = ApiConfig::builder() .name("ingress-http") .upstream(&httpmock_config) .path("/anything/echo/") .port(FLEX_PORT) .policies([policy_config]) .build(); // Configure the Flex service let flex_config = FlexConfig::builder() .version("1.6.1") .hostname("local-flex") .config_mounts([ (POLICY_DIR, "policy"), (COMMON_CONFIG_DIR, "common") ]) .with_api(api_config) .build(); // Compose the services let composite = TestComposite::builder() .with_service(flex_config) .with_service(httpmock_config) .build() .await?; // Get a handle to the Flex service let flex: Flex = composite.service()?; // Get an external URL to point the Flex service let flex_url = flex.external_url(FLEX_PORT).unwrap(); // Get a handle to the HttpMock service let httpmock: HttpMock = composite.service()?; // Create a MockServer let mock_server = MockServer::connect_async(httpmock.socket()).await; // Mock a /hello request mock_server.mock_async(|when, then| { when.path_contains("/hello"); then.status(202).body("World!"); }).await; // Perform an actual request let response = reqwest::get(format!("{flex_url}/hello")).await?; // Assert on the response assert_eq!(response.status(), 202); Ok(()) } ``` ## [](#review-service-logs)サービスログを確認する インテグレーションテストでエラーが発生した場合は、サービスログで原因を特定します。効率的にデバッグできるように、各テストフォルダーに専用のサービスログ (​`/target/pdk-test///.log`​) があります。 たとえば、​`say_hello`​ テストには次のサービスログがあります。 ```none ├── Cargo.lock ├── Cargo.toml ├── playground ├── src ├── tests └── target └── pdk-test └── requests └── say_hello └── .log ``` ## [](#関連情報)関連情報 - [PDK デバッグプレイグラウンドでのカスタムポリシーのデバッグ](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-debug-local) - [PDK のトラブルシューティング](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-troubleshooting) # インテグレーションテストの作成 Flex Gateway ポリシー開発キット (PDK) には、カスタムポリシーのインテグレーション回帰を検出するための自動化テストフレームワークが用意されています。 PDK が提供するインテグレーションテストフレームワークは、Docker コンテナのローカルモードで実行されている Flex Gateway のみをサポートします。接続モードで動作する Flex Gateway や別のプラットフォームにポリシーをデプロイする場合でも、まず Docker コンテナのローカルモードで実行されている Flex Gateway を使用して PDK でポリシーをテストしてください。
ポリシーの開発とテストのみが目的であれば、Windows の Docker で Flex Gateway をローカルモードで実行することもできます。ただし、Flex Gateway は本番環境では Windows をサポートしていません。
ポリシーをテストするには、次のタスクを実行します。 1. [始める前に](#before-you-begin)​を確認します。 2. [インテグレーションテストのディレクトリ構造](#structure)​を確認します。 3. [ローカルモードでの Flex Gateway インスタンスの登録](#register)​。 4. [カスタムポリシーを設定する](#configure-your-custom-policy)​。 5. [テスト関数を作成する](#create-a-test-function)​。 6. [インテグレーションテストを実行する](#run-integration-test)​。 7. [インテグレーションテスト用にサービスを設定する](#configure-services-for-integration-testing)​。 8. [サービスログを確認する](#review-service-logs)​。 ## [](#before-you-begin)始める前に 次の準備が整っていることを確認します。 - [Docker がインストールされている](https://www.docker.com/) ## [](#structure)インテグレーションテストのディレクトリ構造 デフォルトでは、​`/tests`​ ディレクトリには以下のファイルが保存されます。 tests ├── common.rs ├── requests.rs └── common └── logging.yaml └── registration.yaml `/tests`​ ディレクトリにはインテグレーションテストが保存されます。デフォルトでは以下のファイルが保存されます。 - `requests.rs`​ ファイル: 個別のテストモジュールと実行ファイル。 - `commons.rs`​ ファイル: すべてのインテグレーションテストモジュールに含める必要がある機能、API 設定、ポリシー設定が含まれたテストモジュール。 ## [](#register)ローカルモードでの Flex Gateway インスタンスの登録 `make test`​ コマンドを使用してカスタムポリシーのデバッグを開始するには、ローカルモードで Flex Gateway を登録します。 `make test`​ コマンドが動作するためには、​`/tests/common`​ ディレクトリに Flex Gateway の ​`registration.yaml`​ ファイルが存在する必要があります。このディレクトリで登録コマンドを実行してこのファイルを作成するか、または以前に登録してある Flex Gateway の ​`registration.yaml`​ ファイルをこのディレクトリに移動します。 Flex Gateway の登録については、以下を参照してください。 - [ユーザー名とパスワードを使用した Docker コンテナでの登録と実行](https://docs.mulesoft.com/gateway/latest/local-reg-run-up#docker) - [接続アプリケーションを使用した Docker コンテナでの登録と実行](https://docs.mulesoft.com/gateway/latest/local-reg-run-app#docker) - [トークンを使用した Docker コンテナでの登録と実行](https://docs.mulesoft.com/gateway/latest/local-reg-run-token#docker)
登録コマンドのみを実行してください。Docker の開始コマンドは、​make test​ コマンドがこのステップを完了するため、実行しないでください。
ポリシーをテストするデバイスごとに異なる登録ファイルを作成してください。 登録ファイルはリモートリポジトリへの保存では無視され、プロジェクトディレクトリのルートにある ​`.gitignore`​ ファイルにリストされます。 ## [](#configure-your-custom-policy)カスタムポリシーを設定する 各テスト関数では、その要求の API とポリシーの設定が必要です。 カスタムポリシーを設定する手順は、次のとおりです。 1. `show-policy-ref-name`​ を実行してポリシー ID を表示します。 ```ssh make show-policy-ref-name ``` 2. 結果をコピーします。 3. `commons.rs`​ の ​`{{project-name}}`​ を自分のポリシー ID で上書きします。例: ```rust pub const POLICY_NAME: &str = ""; ``` 4. ポリシーの設定パラメーターを定義します。 設定パラメーターは、​`definition/gcl.yaml`​ ファイルにあります。 ## [](#create-a-test-function)テスト関数を作成する 既存のテストモジュール (​`/tests/requests.rs`​ など) に新しいテスト関数を配置して、新しいテストモジュールを追加します。 PDK テスト関数は、​`#[pdk_test]`​ 属性がつけられた​`非同期`​関数です。 ```rust use pdk_test::pdk_test; #[pdk_test] async fn say_hello() { } ```
ボディが空であるため、この関数がエラーとなることはありません。​make test​ を実行してすべてが正常に動作することを確認します。
## [](#run-integration-test)インテグレーションテストを実行する `/tests`​ フォルダーのインテグレーションテストを実行するには、​`make test`​ コマンドを実行します。 ```ssh make test ``` インテグレーションテストに機能を追加するたびにこのテストを実行して、正しく設定されていることを確認してください。
make test​ コマンドは、インテグレーションテストを実行する前にポリシーをコンパイルします。
## [](#configure-services-for-integration-testing)インテグレーションテスト用にサービスを設定する PDK インテグレーションテストには、Docker ネットワーク内で実行されるサービスの複合体が含まれます。サービスインスタンスは ​`TestComposite`​ オブジェクトに登録できます。すべてのサービスには、設定、ホスト名、インスタンスがあります。 `Cargo.toml`​ ファイルの ​`[dev-dependencies]`​ セクションにある ​`pdk-test`​ クレートは PDK のカスタムポリシーのインテグレーションテストを作成するためのすべての機能を提供します。 ### [](#supported-services)サポートされるサービス PDK のテストライブラリは以下のサービスをサポートします。
サービス 説明

Flex

Flex Gateway サービスインスタンス。

httpmock

Rust の httpmock​ サーバーへのサービスバインド。
サポートされるサービスにより、インテグレーションテストの大半のユースケースがカバーされます。異なる種別のサービスを定義することはできません。 ### [](#httpmock-service)httpmock サービスを設定する `httpmock`​ は、Rust で要求のモックを作成できるようにするモックサーバーです。 [httpmock](https://crates.io/crates/httpmock)​ サービスは、​`HttpMockConfig`​ 値を使用して設定します。テスト関数から​`結果`​を返すようにするのがベストプラクティスです。Rust の [anyhow](https://crates.io/crates/anyhow)​ クレートは、異なるデフォルトエラー種別を返せるようにします。 `httpmock`​ サービスの設定は、次のコード例を参照してください。 ```rust use pdk_test::{pdk_test, TestComposite}; use pdk_test::services::httpmock::HttpMockConfig; #[pdk_test] async fn say_hello() -> anyhow::Result<()> { // Configure HttpMock service let backend_config = HttpMockConfig::builder() .hostname("backend") .port(80) // Port where the service will accept requests .build(); // Register HTTPBin service and start the docker network let composite = TestComposite::builder() .with_service(backend_config) .build() .await?; Ok(()) } ```
Docker エンジンが正しく設定されていれば、このテストは合格します。​make test​ を実行して設定が正しいことを確認してください。
### [](#alternative-httpmock-docker-images)代替 httpmock Docker イメージを設定する 提供されるデフォルトの代わりに別のソースの ​`httpmock`​ Docker イメージを使用するには、設定ビルダーで提供される ​`image_name()`​ メソッドを使用して明示的に定義します。 代替 ​`httpmock`​ Docker イメージを設定するには、次の例のように ​`HttpMockConfig::builder()`​ 定義を更新します。 ```rust // Configure HttpMock service let backend_config = HttpMockConfig::builder() .image_name("myrepo/httpmock") // Custom image name setting .hostname("backend") .port(80) // Port where the service will accept requests .build(); ``` ### [](#get-a-services-hande)サービスのハンドルを取得する サービスの複合体で設定されているすべてのサービスインスタンスには、カスタムインタラクション用のハンドルがあります。このハンドルはサービスエンドポイントを使用できるようにするためのソケットを返します。 サービスのハンドルを見つけるには、次のコード例を参照してください。 ```rust use pdk_test::{pdk_test, TestComposite}; use pdk_test::services::httpmock::{HttpMock, HttpMockConfig}; #[pdk_test] async fn say_hello() -> anyhow::Result<()> { // Configure HTTPMock service let backend_config = HttpMockConfig::builder() .hostname("backend") .build(); // Register HTTPMock service and start the docker network let composite = TestComposite::builder() .with_service(backend_config) .port(80) // Port where the service accepts requests .build() .await?; // Get the httpmock handle let httpmock: HttpMock = composite.service()?; Ok(()) } ```
httpmock​ インスタンスが正しく設定されていれば、このテストは合格します。​make test​ を実行して設定が正しいことを確認してください。
### [](#http-entpoint-requests)HTTP エンドポイント要求 エンドポイントをモックするには [httpmock When/Then API](https://docs.rs/httpmock/latest/httpmock/#whenthen-api)​ を使用します。 エンドポイントをモックしたら、HTTP クライアントを使用してエンドポイント要求を実行します。 [reqwest](https://crates.io/crates/reqwest/)​ クレートは、最も包括的で柔軟な Rust HTTP クライアントを提供します。 エンドポイントをモックして要求を実行するには、次のコード例を参照してください。 ```rust use pdk_test::{pdk_test, TestComposite}; use pdk_test::services::httpmock::{HttpMock, HttpMockConfig}; #[pdk_test] async fn say_hello() -> anyhow::Result<()> { // Configure HttpMock service let backend_config = HttpMockConfig::builder() .hostname("backend") .port(80) // Port where the service will accept requests .build(); // Register HTTPBin service and start the docker network let composite = TestComposite::builder() .with_service(backend_config) .build() .await?; // Get the httpmock handle let httpmock: HttpMock = composite.service()?; // Connect the mock server let mock_server = httpmock::MockServer::connect_async(httpmock.socket()).await; // Configure the endpoint mocks mock_server.mock_async(|when, then| { when.path_contains("/hello"); then.status(202).body("World!"); }).await; let base_url = mock_server.base_url(); // Hit the endpoint let response = reqwest::get(format!("{base_url}/hello")).await?; // Assert on response assert_eq!(response.status(), 202); assert_eq!(response.text().await?, "World!"); Ok(()) } ```
make test​ を実行して設定が正しいことを確認してください。
### [](#configure-a-flex-service-instance)Flex サービスインスタンスを設定する `Flex`​ サービスは、​`TestComposite`​ で ​`FlexConfig`​ 構造のインスタンスを登録して設定します。​`FlexConfig`​ インスタンスを完了するには、​`ApiConfig`​ および ​`PolicyConfig`​ インスタンスも定義する必要があります。 `FlexConfig`​ 構造には次のプロパティがあります。
プロパティ コンテンツ

version

テストする Flex Gateway バージョン。

image_name

Flex Gateway Docker イメージ名 (デフォルトは「mulesoft/flex-gateway」)。

hostname

Flex​ サービスのホスト名。デフォルトでは、「local-flex」です。

config_mounts

Flex​ サービスが設定ファイルを見つけるためのローカルディレクトリのマップ。 POLICY_DIR​ 定数と ​COMMON_CONFIG_DIR​ 定数は、デフォルトでは ​common.rs​ モジュールで定義されます。テストで追加の設定が必要な場合、テスト関数の特定の設定が含まれるディレクトリを追加します。

with_api

Flex​ サービスインスタンスにデプロイされた API の ​ApiConfiguration​。複数の API を設定するには、複数回コールします。

ports

Flex​ サービスが要求をリスンするポートのリスト。​config_mount​ ディレクトリに含まれるいずれかの設定ディレクトリで API を公開する場合、そのポートと ​spec.address​ プロパティで設定されたポートが一致している必要があります。
`ApiConfig`​ には次のプロパティがあります。
プロパティ コンテンツ

name

API の名前。

upstream

アップストリームサービスへの参照。

path

アップストリーム要求の送信先パス。

port

API が要求をリスンするポート。

policies

API に適用される ​PolicyConfig​ インスタンスのリスト。
`PolicyConfig`​ には次のプロパティがあります。
プロパティ コンテンツ

name

適用するポリシー。

configuration

ポリシーのパラメーター。
次のコード例では、完全な ​`Flex`​ サービスを定義しています。 ```rust mod common; use common::*; use pdk_test::{pdk_test, TestComposite}; use pdk_test::port::Port; use pdk_test::services::flex::FlexConfig; // Port where Flex listens for requests const FLEX_PORT: Port = 8081; #[pdk_test] async fn say_hello() -> anyhow::Result<()> { // Configure an upstream service for the API let httpmock_config = HttpMockConfig::builder() .port(80) .version("latest") .hostname("backend") .build(); // Configure a policy for the API let policy_config = PolicyConfig::builder() .name(POLICY_NAME) .configuration(serde_json::json!({"source": "http://backend/blocked", "frequency": 60})) .build(); // Configure the API to deploy to the Flex let api_config = ApiConfig::builder() .name("ingress-http") .upstream(&httpmock_config) .path("/anything/echo/") .port(FLEX_PORT) .policies([policy_config]) .build(); // Configure the Flex service let flex_config = FlexConfig::builder() .version("1.6.1") .hostname("local-flex") .config_mounts([ (POLICY_DIR, "policy"), (COMMON_CONFIG_DIR, "common") ]) .with_api(api_config) .build(); let composite = TestComposite::builder() .with_service(flex_config) .with_service(httpmock_config) .build() .await?; } ``` ### [](#alternative-flex-docker-images)代替 Flex Docker イメージを設定する 提供されるデフォルトの代わりに別のソースの ​`flex`​ Docker イメージを使用するには、設定ビルダーで提供される ​`image_name()`​ メソッドを使用して明示的に定義します。 代替 Flex Docker イメージを設定するには、次の例のように ​`FlexConfig::builder()`​ 定義を更新します。 ```rust // Configure the Flex service let flex_config = FlexConfig::builder() .image_name("myrepo/flex-gateway") // Custom image name setting .version("1.6.1") .hostname("local-flex") .config_mounts([ (POLICY_DIR, "policy"), (COMMON_CONFIG_DIR, "common") ]) .with_api(api_config) .build(); ```

make test​ を実行して設定が正しいことを確認してください。
### [](#flex-service-endpoint-requests)Flex サービスエンドポイント要求 `Flex`​ サービスは、ポートに応じた外部ベース URL でエンドポイントを表示します。これらの URL にアクセスするには、ポートごとにインデックス付けされた ​`external_url()`​ メソッドを Flex サービスインスタンスハンドルで指定する必要があります。例: ```rust use pdk_test::{pdk_test, TestComposite, port::Port}; use pdk_test::services::flex::Flex; const FLEX_PORT: Port = 8081; async fn build_composite() -> anyhow::Result { todo!("Configuration stuff comes here") } #[pdk_test] async fn say_hello() -> anyhow::Result<()> { // Invoke a helper composite builder function for simplicity let composite = build_composite().await?; // Get the Flex service handle let flex: Flex = composite.service()?; // Get the URL for our configured port let flex_url = flex.external_url(FLEX_PORT).unwrap(); let response = reqwest::get(format!("{flex_url}/hello")).await?; // Make assertions Ok(()) } ``` ### [](#combine-multiple-services)複数サービスの組み合わせ 通常、PDK のインテグレーションテストには、​`Flex`​ サービスと、1 つ以上のバックエンドサービスが含まれます。 次のコードは、カスタムポリシーの作成時に生成されるデフォルトのテストです。 ```rust mod common; use httpmock::MockServer; use pdk_test::{pdk_test, TestComposite}; use pdk_test::port::Port; use pdk_test::services::flex::{FlexConfig, Flex}; use pdk_test::services::httpmock::{HttpMockConfig, HttpMock}; use common::*; // Directory with the configurations for the `hello` test. const HELLO_CONFIG_DIR: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/requests/hello"); // Flex port for the internal test network const FLEX_PORT: Port = 8081; // This integration test shows how to build a test to compose a local-flex instance // with a MockServer backend #[pdk_test] async fn hello() -> anyhow::Result<()> { // Configure an HttpMock service let httpmock_config = HttpMockConfig::builder() .port(80) .version("latest") .hostname("backend") .build(); // Configure a policy for the API let policy_config = PolicyConfig::builder() .name(POLICY_NAME) .configuration(serde_json::json!({"source": "http://backend/blocked", "frequency": 60})) .build(); // Configure the API to deploy to the Flex let api_config = ApiConfig::builder() .name("ingress-http") .upstream(&httpmock_config) .path("/anything/echo/") .port(FLEX_PORT) .policies([policy_config]) .build(); // Configure the Flex service let flex_config = FlexConfig::builder() .version("1.6.1") .hostname("local-flex") .config_mounts([ (POLICY_DIR, "policy"), (COMMON_CONFIG_DIR, "common") ]) .with_api(api_config) .build(); // Compose the services let composite = TestComposite::builder() .with_service(flex_config) .with_service(httpmock_config) .build() .await?; // Get a handle to the Flex service let flex: Flex = composite.service()?; // Get an external URL to point the Flex service let flex_url = flex.external_url(FLEX_PORT).unwrap(); // Get a handle to the HttpMock service let httpmock: HttpMock = composite.service()?; // Create a MockServer let mock_server = MockServer::connect_async(httpmock.socket()).await; // Mock a /hello request mock_server.mock_async(|when, then| { when.path_contains("/hello"); then.status(202).body("World!"); }).await; // Perform an actual request let response = reqwest::get(format!("{flex_url}/hello")).await?; // Assert on the response assert_eq!(response.status(), 202); Ok(()) } ``` ## [](#review-service-logs)サービスログを確認する インテグレーションテストでエラーが発生した場合は、サービスログで原因を特定します。効率的にデバッグできるように、各テストフォルダーに専用のサービスログ (​`/target/pdk-test///.log`​) があります。 たとえば、​`say_hello`​ テストには次のサービスログがあります。 ```none ├── Cargo.lock ├── Cargo.toml ├── playground ├── src ├── tests └── target └── pdk-test └── requests └── say_hello └── .log ``` ## [](#関連情報)関連情報 - [PDK デバッグプレイグラウンドでのカスタムポリシーのデバッグ](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-debug-local) - [PDK のトラブルシューティング](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-troubleshooting) # インテグレーションテストの作成 Flex Gateway ポリシー開発キット (PDK) には、カスタムポリシーのインテグレーション回帰を検出するための自動化テストフレームワークが用意されています。 PDK が提供するインテグレーションテストフレームワークは、Docker コンテナのローカルモードで実行されている Flex Gateway のみをサポートします。接続モードで動作する Flex Gateway や別のプラットフォームにポリシーをデプロイする場合でも、まず Docker コンテナのローカルモードで実行されている Flex Gateway を使用して PDK でポリシーをテストしてください。
ポリシーの開発とテストのみが目的であれば、Windows の Docker で Flex Gateway をローカルモードで実行することもできます。ただし、Flex Gateway は本番環境では Windows をサポートしていません。
ポリシーをテストするには、次のタスクを実行します。 1. [始める前に](#before-you-begin)​を確認します。 2. [インテグレーションテストのディレクトリ構造](#structure)​を確認します。 3. [ローカルモードでの Flex Gateway インスタンスの登録](#register)​。 4. [カスタムポリシーを設定する](#configure-your-custom-policy)​。 5. [テスト関数を作成する](#create-a-test-function)​。 6. [インテグレーションテストを実行する](#run-integration-test)​。 7. [インテグレーションテスト用にサービスを設定する](#configure-services-for-integration-testing)​。 8. [サービスログを確認する](#review-service-logs)​。 ## [](#before-you-begin)始める前に 次の準備が整っていることを確認します。 - [Docker がインストールされている](https://www.docker.com/) ## [](#structure)インテグレーションテストのディレクトリ構造 デフォルトでは、​`/tests`​ ディレクトリには以下のファイルが保存されます。 tests ├── common.rs ├── requests.rs └── common └── logging.yaml └── registration.yaml `/tests`​ ディレクトリにはインテグレーションテストが保存されます。デフォルトでは以下のファイルが保存されます。 - `requests.rs`​ ファイル: 個別のテストモジュールと実行ファイル。 - `commons.rs`​ ファイル: すべてのインテグレーションテストモジュールに含める必要がある機能、API 設定、ポリシー設定が含まれたテストモジュール。 ## [](#register)ローカルモードでの Flex Gateway インスタンスの登録 `make test`​ コマンドを使用してカスタムポリシーのデバッグを開始するには、ローカルモードで Flex Gateway を登録します。 `make test`​ コマンドが動作するためには、​`/tests/common`​ ディレクトリに Flex Gateway の ​`registration.yaml`​ ファイルが存在する必要があります。このディレクトリで登録コマンドを実行してこのファイルを作成するか、または以前に登録してある Flex Gateway の ​`registration.yaml`​ ファイルをこのディレクトリに移動します。 Flex Gateway の登録については、以下を参照してください。 - [ユーザー名とパスワードを使用した Docker コンテナでの登録と実行](https://docs.mulesoft.com/gateway/latest/local-reg-run-up#docker) - [接続アプリケーションを使用した Docker コンテナでの登録と実行](https://docs.mulesoft.com/gateway/latest/local-reg-run-app#docker) - [トークンを使用した Docker コンテナでの登録と実行](https://docs.mulesoft.com/gateway/latest/local-reg-run-token#docker)
登録コマンドのみを実行してください。Docker の開始コマンドは、​make test​ コマンドがこのステップを完了するため、実行しないでください。
ポリシーをテストするデバイスごとに異なる登録ファイルを作成してください。 登録ファイルはリモートリポジトリへの保存では無視され、プロジェクトディレクトリのルートにある ​`.gitignore`​ ファイルにリストされます。 ## [](#configure-your-custom-policy)カスタムポリシーを設定する 各テスト関数では、その要求の API とポリシーの設定が必要です。 カスタムポリシーを設定する手順は、次のとおりです。 1. `show-policy-ref-name`​ を実行してポリシー ID を表示します。 ```ssh make show-policy-ref-name ``` 2. 結果をコピーします。 3. `commons.rs`​ の ​`{{project-name}}`​ を自分のポリシー ID で上書きします。例: ```rust pub const POLICY_NAME: &str = ""; ``` 4. ポリシーの設定パラメーターを定義します。 設定パラメーターは、​`definition/gcl.yaml`​ ファイルにあります。 ## [](#create-a-test-function)テスト関数を作成する 既存のテストモジュール (​`/tests/requests.rs`​ など) に新しいテスト関数を配置して、新しいテストモジュールを追加します。 PDK テスト関数は、​`#[pdk_test]`​ 属性がつけられた​`非同期`​関数です。 ```rust use pdk_test::pdk_test; #[pdk_test] async fn say_hello() { } ```
ボディが空であるため、この関数がエラーとなることはありません。​make test​ を実行してすべてが正常に動作することを確認します。
## [](#run-integration-test)インテグレーションテストを実行する `/tests`​ フォルダーのインテグレーションテストを実行するには、​`make test`​ コマンドを実行します。 ```ssh make test ``` インテグレーションテストに機能を追加するたびにこのテストを実行して、正しく設定されていることを確認してください。
make test​ コマンドは、インテグレーションテストを実行する前にポリシーをコンパイルします。
## [](#configure-services-for-integration-testing)インテグレーションテスト用にサービスを設定する PDK インテグレーションテストには、Docker ネットワーク内で実行されるサービスの複合体が含まれます。サービスインスタンスは ​`TestComposite`​ オブジェクトに登録できます。すべてのサービスには、設定、ホスト名、インスタンスがあります。 `Cargo.toml`​ ファイルの ​`[dev-dependencies]`​ セクションにある ​`pdk-test`​ クレートは PDK のカスタムポリシーのインテグレーションテストを作成するためのすべての機能を提供します。 ### [](#supported-services)サポートされるサービス PDK のテストライブラリは以下のサービスをサポートします。
サービス 説明

Flex

Flex Gateway サービスインスタンス。

httpmock

Rust の httpmock​ サーバーへのサービスバインド。
サポートされるサービスにより、インテグレーションテストの大半のユースケースがカバーされます。異なる種別のサービスを定義することはできません。 ### [](#httpmock-service)httpmock サービスを設定する `httpmock`​ は、Rust で要求のモックを作成できるようにするモックサーバーです。 [httpmock](https://crates.io/crates/httpmock)​ サービスは、​`HttpMockConfig`​ 値を使用して設定します。テスト関数から​`結果`​を返すようにするのがベストプラクティスです。Rust の [anyhow](https://crates.io/crates/anyhow)​ クレートは、異なるデフォルトエラー種別を返せるようにします。 `httpmock`​ サービスの設定は、次のコード例を参照してください。 ```rust use pdk_test::{pdk_test, TestComposite}; use pdk_test::services::httpmock::HttpMockConfig; #[pdk_test] async fn say_hello() -> anyhow::Result<()> { // Configure HttpMock service let backend_config = HttpMockConfig::builder() .hostname("backend") .port(80) // Port where the service will accept requests .build(); // Register HTTPBin service and start the docker network let composite = TestComposite::builder() .with_service(backend_config) .build() .await?; Ok(()) } ```
Docker エンジンが正しく設定されていれば、このテストは合格します。​make test​ を実行して設定が正しいことを確認してください。
### [](#alternative-httpmock-docker-images)代替 httpmock Docker イメージを設定する 提供されるデフォルトの代わりに別のソースの ​`httpmock`​ Docker イメージを使用するには、設定ビルダーで提供される ​`image_name()`​ メソッドを使用して明示的に定義します。 代替 ​`httpmock`​ Docker イメージを設定するには、次の例のように ​`HttpMockConfig::builder()`​ 定義を更新します。 ```rust // Configure HttpMock service let backend_config = HttpMockConfig::builder() .image_name("myrepo/httpmock") // Custom image name setting .hostname("backend") .port(80) // Port where the service will accept requests .build(); ``` ### [](#get-a-services-hande)サービスのハンドルを取得する サービスの複合体で設定されているすべてのサービスインスタンスには、カスタムインタラクション用のハンドルがあります。このハンドルはサービスエンドポイントを使用できるようにするためのソケットを返します。 サービスのハンドルを見つけるには、次のコード例を参照してください。 ```rust use pdk_test::{pdk_test, TestComposite}; use pdk_test::services::httpmock::{HttpMock, HttpMockConfig}; #[pdk_test] async fn say_hello() -> anyhow::Result<()> { // Configure HTTPMock service let backend_config = HttpMockConfig::builder() .hostname("backend") .build(); // Register HTTPMock service and start the docker network let composite = TestComposite::builder() .with_service(backend_config) .port(80) // Port where the service accepts requests .build() .await?; // Get the httpmock handle let httpmock: HttpMock = composite.service()?; Ok(()) } ```
httpmock​ インスタンスが正しく設定されていれば、このテストは合格します。​make test​ を実行して設定が正しいことを確認してください。
### [](#http-entpoint-requests)HTTP エンドポイント要求 エンドポイントをモックするには [httpmock When/Then API](https://docs.rs/httpmock/latest/httpmock/#whenthen-api)​ を使用します。 エンドポイントをモックしたら、HTTP クライアントを使用してエンドポイント要求を実行します。 [reqwest](https://crates.io/crates/reqwest/)​ クレートは、最も包括的で柔軟な Rust HTTP クライアントを提供します。 エンドポイントをモックして要求を実行するには、次のコード例を参照してください。 ```rust use pdk_test::{pdk_test, TestComposite}; use pdk_test::services::httpmock::{HttpMock, HttpMockConfig}; #[pdk_test] async fn say_hello() -> anyhow::Result<()> { // Configure HttpMock service let backend_config = HttpMockConfig::builder() .hostname("backend") .port(80) // Port where the service will accept requests .build(); // Register HTTPBin service and start the docker network let composite = TestComposite::builder() .with_service(backend_config) .build() .await?; // Get the httpmock handle let httpmock: HttpMock = composite.service()?; // Connect the mock server let mock_server = httpmock::MockServer::connect_async(httpmock.socket()).await; // Configure the endpoint mocks mock_server.mock_async(|when, then| { when.path_contains("/hello"); then.status(202).body("World!"); }).await; let base_url = mock_server.base_url(); // Hit the endpoint let response = reqwest::get(format!("{base_url}/hello")).await?; // Assert on response assert_eq!(response.status(), 202); assert_eq!(response.text().await?, "World!"); Ok(()) } ```
make test​ を実行して設定が正しいことを確認してください。
### [](#configure-a-flex-service-instance)Flex サービスインスタンスを設定する `Flex`​ サービスは、​`TestComposite`​ で ​`FlexConfig`​ 構造のインスタンスを登録して設定します。​`FlexConfig`​ インスタンスを完了するには、​`ApiConfig`​ および ​`PolicyConfig`​ インスタンスも定義する必要があります。 `FlexConfig`​ 構造には次のプロパティがあります。
プロパティ コンテンツ

version

テストする Flex Gateway バージョン。

image_name

Flex Gateway Docker イメージ名 (デフォルトは「mulesoft/flex-gateway」)。

hostname

Flex​ サービスのホスト名。デフォルトでは、「local-flex」です。

config_mounts

Flex​ サービスが設定ファイルを見つけるためのローカルディレクトリのマップ。 POLICY_DIR​ 定数と ​COMMON_CONFIG_DIR​ 定数は、デフォルトでは ​common.rs​ モジュールで定義されます。テストで追加の設定が必要な場合、テスト関数の特定の設定が含まれるディレクトリを追加します。

with_api

Flex​ サービスインスタンスにデプロイされた API の ​ApiConfiguration​。複数の API を設定するには、複数回コールします。

ports

Flex​ サービスが要求をリスンするポートのリスト。​config_mount​ ディレクトリに含まれるいずれかの設定ディレクトリで API を公開する場合、そのポートと ​spec.address​ プロパティで設定されたポートが一致している必要があります。
`ApiConfig`​ には次のプロパティがあります。
プロパティ コンテンツ

name

API の名前。

upstream

アップストリームサービスへの参照。

path

アップストリーム要求の送信先パス。

port

API が要求をリスンするポート。

policies

API に適用される ​PolicyConfig​ インスタンスのリスト。
`PolicyConfig`​ には次のプロパティがあります。
プロパティ コンテンツ

name

適用するポリシー。

configuration

ポリシーのパラメーター。
次のコード例では、完全な ​`Flex`​ サービスを定義しています。 ```rust mod common; use common::*; use pdk_test::{pdk_test, TestComposite}; use pdk_test::port::Port; use pdk_test::services::flex::FlexConfig; // Port where Flex listens for requests const FLEX_PORT: Port = 8081; #[pdk_test] async fn say_hello() -> anyhow::Result<()> { // Configure an upstream service for the API let httpmock_config = HttpMockConfig::builder() .port(80) .version("latest") .hostname("backend") .build(); // Configure a policy for the API let policy_config = PolicyConfig::builder() .name(POLICY_NAME) .configuration(serde_json::json!({"source": "http://backend/blocked", "frequency": 60})) .build(); // Configure the API to deploy to the Flex let api_config = ApiConfig::builder() .name("ingress-http") .upstream(&httpmock_config) .path("/anything/echo/") .port(FLEX_PORT) .policies([policy_config]) .build(); // Configure the Flex service let flex_config = FlexConfig::builder() .version("1.6.1") .hostname("local-flex") .config_mounts([ (POLICY_DIR, "policy"), (COMMON_CONFIG_DIR, "common") ]) .with_api(api_config) .build(); let composite = TestComposite::builder() .with_service(flex_config) .with_service(httpmock_config) .build() .await?; } ``` ### [](#alternative-flex-docker-images)代替 Flex Docker イメージを設定する 提供されるデフォルトの代わりに別のソースの ​`flex`​ Docker イメージを使用するには、設定ビルダーで提供される ​`image_name()`​ メソッドを使用して明示的に定義します。 代替 Flex Docker イメージを設定するには、次の例のように ​`FlexConfig::builder()`​ 定義を更新します。 ```rust // Configure the Flex service let flex_config = FlexConfig::builder() .image_name("myrepo/flex-gateway") // Custom image name setting .version("1.6.1") .hostname("local-flex") .config_mounts([ (POLICY_DIR, "policy"), (COMMON_CONFIG_DIR, "common") ]) .with_api(api_config) .build(); ```

make test​ を実行して設定が正しいことを確認してください。
### [](#flex-service-endpoint-requests)Flex サービスエンドポイント要求 `Flex`​ サービスは、ポートに応じた外部ベース URL でエンドポイントを表示します。これらの URL にアクセスするには、ポートごとにインデックス付けされた ​`external_url()`​ メソッドを Flex サービスインスタンスハンドルで指定する必要があります。例: ```rust use pdk_test::{pdk_test, TestComposite, port::Port}; use pdk_test::services::flex::Flex; const FLEX_PORT: Port = 8081; async fn build_composite() -> anyhow::Result { todo!("Configuration stuff comes here") } #[pdk_test] async fn say_hello() -> anyhow::Result<()> { // Invoke a helper composite builder function for simplicity let composite = build_composite().await?; // Get the Flex service handle let flex: Flex = composite.service()?; // Get the URL for our configured port let flex_url = flex.external_url(FLEX_PORT).unwrap(); let response = reqwest::get(format!("{flex_url}/hello")).await?; // Make assertions Ok(()) } ``` ### [](#combine-multiple-services)複数サービスの組み合わせ 通常、PDK のインテグレーションテストには、​`Flex`​ サービスと、1 つ以上のバックエンドサービスが含まれます。 次のコードは、カスタムポリシーの作成時に生成されるデフォルトのテストです。 ```rust mod common; use httpmock::MockServer; use pdk_test::{pdk_test, TestComposite}; use pdk_test::port::Port; use pdk_test::services::flex::{FlexConfig, Flex}; use pdk_test::services::httpmock::{HttpMockConfig, HttpMock}; use common::*; // Directory with the configurations for the `hello` test. const HELLO_CONFIG_DIR: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/requests/hello"); // Flex port for the internal test network const FLEX_PORT: Port = 8081; // This integration test shows how to build a test to compose a local-flex instance // with a MockServer backend #[pdk_test] async fn hello() -> anyhow::Result<()> { // Configure an HttpMock service let httpmock_config = HttpMockConfig::builder() .port(80) .version("latest") .hostname("backend") .build(); // Configure a policy for the API let policy_config = PolicyConfig::builder() .name(POLICY_NAME) .configuration(serde_json::json!({"source": "http://backend/blocked", "frequency": 60})) .build(); // Configure the API to deploy to the Flex let api_config = ApiConfig::builder() .name("ingress-http") .upstream(&httpmock_config) .path("/anything/echo/") .port(FLEX_PORT) .policies([policy_config]) .build(); // Configure the Flex service let flex_config = FlexConfig::builder() .version("1.6.1") .hostname("local-flex") .config_mounts([ (POLICY_DIR, "policy"), (COMMON_CONFIG_DIR, "common") ]) .with_api(api_config) .build(); // Compose the services let composite = TestComposite::builder() .with_service(flex_config) .with_service(httpmock_config) .build() .await?; // Get a handle to the Flex service let flex: Flex = composite.service()?; // Get an external URL to point the Flex service let flex_url = flex.external_url(FLEX_PORT).unwrap(); // Get a handle to the HttpMock service let httpmock: HttpMock = composite.service()?; // Create a MockServer let mock_server = MockServer::connect_async(httpmock.socket()).await; // Mock a /hello request mock_server.mock_async(|when, then| { when.path_contains("/hello"); then.status(202).body("World!"); }).await; // Perform an actual request let response = reqwest::get(format!("{flex_url}/hello")).await?; // Assert on the response assert_eq!(response.status(), 202); Ok(()) } ``` ## [](#review-service-logs)サービスログを確認する インテグレーションテストでエラーが発生した場合は、サービスログで原因を特定します。効率的にデバッグできるように、各テストフォルダーに専用のサービスログ (​`/target/pdk-test///.log`​) があります。 たとえば、​`say_hello`​ テストには次のサービスログがあります。 ```none ├── Cargo.lock ├── Cargo.toml ├── playground ├── src ├── tests └── target └── pdk-test └── requests └── say_hello └── .log ``` ## [](#関連情報)関連情報 - [PDK デバッグプレイグラウンドでのカスタムポリシーのデバッグ](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-debug-local) - [PDK のトラブルシューティング](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-troubleshooting) # カスタムポリシーのコンパイル `make build`​ コマンドを使用して、カスタムポリシーをコンパイルし、ポリシーのバイナリターゲットファイルを作成します。ポリシーのソースコードを編集したら、Flex Gateway にポリシーをデプロイする前に必ずカスタムポリシーをコンパイルする必要があります。 ## [](#始める前に)始める前に [policy-pdk-create-project.adoc](#policy-pdk-create-project.adoc) のすべての手順を完了していることを確認してください。 ## [](#ビルドコマンドによるコンパイル)ビルドコマンドによるコンパイル ポリシーをコンパイルするには、ポリシーのルートフォルダーから ​`make build`​ コマンドを実行します。 ```ssh make build ``` `make build`​ コマンドは以下のアクションを実行します。 1. `make build-asset-files`​ スクリプトを実行します。 2. `make build`​ コマンドを実行して、ポリシーを ​`WebAssembly`​ バイナリファイルにコンパイルします。 3. `make build-asset-files`​ スクリプトでは生成されない、ポリシーの実行に必要な追加設定ファイルを生成します。 `make build`​ コマンドは、生成されたファイルを​`ターゲット`​ディレクトリに出力します。 `make build`​ コマンドは、コンパイルされたアーティファクトを生成するために必要な回数だけ実行できます。カスタムポリシーをコンパイルして、ソースコードと設定の編集内容をコンパイルしたアーティファクトに含める必要があります。

ポリシーを初めてコンパイルするとき、Rust で最新バージョンの連動関係が取得されます。連動関係で v1.83.0 以降の Rust バージョンが必要な場合、次のコマンドを使用して、連動関係の互換性のある最新バージョンを固定します。

cargo update -p <conflicting_crate> --precise <major.minor.patch>
## [](#関連情報)関連情報 - [PDK デバッグプレイグラウンドでのカスタムポリシーのデバッグ](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-debug-local) - [カスタムポリシーの適用](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-apply-policies) - [PDK のトラブルシューティング](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-troubleshooting) # カスタムポリシーのコンパイル `make build`​ コマンドを使用して、カスタムポリシーをコンパイルし、ポリシーのバイナリターゲットファイルを作成します。ポリシーのソースコードを編集したら、Flex Gateway にポリシーをデプロイする前に必ずカスタムポリシーをコンパイルする必要があります。 ## [](#始める前に)始める前に [policy-pdk-create-project.adoc](#policy-pdk-create-project.adoc) のすべての手順を完了していることを確認してください。 ## [](#ビルドコマンドによるコンパイル)ビルドコマンドによるコンパイル ポリシーをコンパイルするには、ポリシーのルートフォルダーから ​`make build`​ コマンドを実行します。 ```ssh make build ``` `make build`​ コマンドは以下のアクションを実行します。 1. `make build-asset-files`​ スクリプトを実行します。 2. `make build`​ コマンドを実行して、ポリシーを ​`WebAssembly`​ バイナリファイルにコンパイルします。 3. `make build-asset-files`​ スクリプトでは生成されない、ポリシーの実行に必要な追加設定ファイルを生成します。 `make build`​ コマンドは、生成されたファイルを​`ターゲット`​ディレクトリに出力します。 `make build`​ コマンドは、コンパイルされたアーティファクトを生成するために必要な回数だけ実行できます。カスタムポリシーをコンパイルして、ソースコードと設定の編集内容をコンパイルしたアーティファクトに含める必要があります。

ポリシーを初めてコンパイルするとき、Rust で最新バージョンの連動関係が取得されます。連動関係で v1.83.0 以降の Rust バージョンが必要な場合、次のコマンドを使用して、連動関係の互換性のある最新バージョンを固定します。

cargo update -p <conflicting_crate> --precise <major.minor.patch>
## [](#関連情報)関連情報 - [PDK デバッグプレイグラウンドでのカスタムポリシーのデバッグ](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-debug-local) - [カスタムポリシーの適用](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-apply-policies) - [PDK のトラブルシューティング](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-troubleshooting) # カスタムポリシーのコンパイル `make build`​ コマンドを使用して、カスタムポリシーをコンパイルし、ポリシーのバイナリターゲットファイルを作成します。ポリシーのソースコードを編集したら、Flex Gateway にポリシーをデプロイする前に必ずカスタムポリシーをコンパイルする必要があります。 ## [](#始める前に)始める前に [policy-pdk-create-project.adoc](#policy-pdk-create-project.adoc) のすべての手順を完了していることを確認してください。 ## [](#ビルドコマンドによるコンパイル)ビルドコマンドによるコンパイル ポリシーをコンパイルするには、ポリシーのルートフォルダーから ​`make build`​ コマンドを実行します。 ```ssh make build ``` `make build`​ コマンドは以下のアクションを実行します。 1. `make build-asset-files`​ スクリプトを実行します。 2. `make build`​ コマンドを実行して、ポリシーを ​`WebAssembly`​ バイナリファイルにコンパイルします。 3. `make build-asset-files`​ スクリプトでは生成されない、ポリシーの実行に必要な追加設定ファイルを生成します。 `make build`​ コマンドは、生成されたファイルを​`ターゲット`​ディレクトリに出力します。 `make build`​ コマンドは、コンパイルされたアーティファクトを生成するために必要な回数だけ実行できます。カスタムポリシーをコンパイルして、ソースコードと設定の編集内容をコンパイルしたアーティファクトに含める必要があります。

ポリシーを初めてコンパイルするとき、Rust で最新バージョンの連動関係が取得されます。連動関係で {rust-ver-max-var} 以降の Rust バージョンが必要な場合、次のコマンドを使用して、連動関係の互換性のある最新バージョンを固定します。

cargo update -p <conflicting_crate> --precise <major.minor.patch>
## [](#関連情報)関連情報 - [PDK デバッグプレイグラウンドでのカスタムポリシーのデバッグ](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-debug-local) - [カスタムポリシーの適用](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-apply-policies) - [PDK のトラブルシューティング](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-troubleshooting) # カスタムポリシーの例 Flex Gateway ポリシー開発キット (PDK) は、Rust ソースコードの設定を開始するためのポリシープロジェクトの例を提供しています。 すべてのポリシー例と関連ドキュメントは [PDK カスタムポリシー GitHub リポジトリ](https://github.com/mulesoft/pdk-custom-policy-examples)​ にあります。 PDK が提供するポリシー例は次のとおりです。 - [ブロックポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/block/README.md)​: [周期関数](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-timer)​と ​[HTTP コール](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-http-request)​を実装して IP 範囲をブロックする方法の例として、ブロックポリシーを使用します。 - [証明書ポリシー例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/certs/README.md)​: 証明書ポリシーは、接続の証明書に関するデータを取得する方法の例として使用します。 - [CORS 検証ポリシー例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/cors-validation/README.md)​: CORS 検証ポリシーは、​[CORS ライブラリ](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-cors)​をカスタムポリシーで使用する方法の例として使用します。 - [暗号化ポリシー例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/crypto/README.md)​: 暗号化ポリシーは、暗号化機能を提供する​[サードパーティライブラリ](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-libraries)​をカスタムポリシーで使用する方法の例として使用します。 - [データキャッシュポリシー例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/data-caching/README.md)​: データキャッシュポリシーは、​[データキャッシュ](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-caching)​をカスタムポリシーで使用する方法の例として使用します。 - [JWT 検証ポリシー例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/jwt-validation/README.md)​: JWT 検証ポリシーは、​[JWT ライブラリ](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-jwt)​をカスタムポリシーで使用する方法の例として使用します。 - [メトリクスポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/metrics/README.md)​: [周期関数](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-timer)​と ​[HTTP コール](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-http-request)​を実装してメトリクス取り込みサービスに定期的にデータを送信する方法の例として、メトリクスポリシーを使用します。 - [クエリポリシー例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/query/README.md)​: クエリポリシー例は、​[DataWeave 式](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-dataweave)​をカスタムポリシーで処理する方法の例として使用します。 - [簡単な OAuth 2.0 検証ポリシー例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/simple-oauth-2-validation/README.md)​: 簡単な OAuth 2.0 検証ポリシーは、​[HTTP コール](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-http-request)​をカスタムポリシーで実装する方法の例として使用します。 - [スパイクポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/spike/README.md)​: [周期関数](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-timer)​を実装してワーカーのスパイク制御を設定する方法の例として、スパイクポリシーを使用します。 - [TLS コールポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/tls-calls/README.md)​: Flex Gateway が実行されているオペレーティングシステムに証明書をインストールせずにポリシーで HTTPS コールを実行する方法の例として、TLS コールポリシーを使用します。 ## [](#ポリシープロジェクト例をセットアップする)ポリシープロジェクト例をセットアップする ポリシープロジェクト例の使用を開始する手順は、次のとおりです。 1. [PDK 前提条件](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-prerequisites)​をすべてインストールしてあることを確認します。 2. 次のコマンドまたは好きな GitHub インターフェースを使用して、 [PDK カスタムポリシー GitHub リポジトリ](https://github.com/mulesoft/pdk-custom-policy-examples)​をコピーします。 ```ssh git clone https://github.com/mulesoft/pdk-custom-policy-examples.git ``` 3. コピーしたディレクトリに移動して、使用するポリシー例のディレクトリをコピーして新しい場所に貼り付けます。 4. コピーしたポリシー例の ​`cargo.toml`​ ファイルで、​`group-id`​ をプロジェクトのグループ ID に置き換えます。例: ```toml group_id = "" ``` 5. `make setup`​ コマンドを実行します。 ```ssh make setup ``` 6. ポリシー例の ​`README.md`​ ファイルを開いて、ポリシーの詳細やテスト方法を確認します。 ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features) # カスタムポリシーの例 Flex Gateway ポリシー開発キット (PDK) は、Rust ソースコードの設定を開始するためのポリシープロジェクトの例を提供しています。 すべてのポリシー例と関連ドキュメントは [PDK カスタムポリシー GitHub リポジトリ](https://github.com/mulesoft/pdk-custom-policy-examples)​にあります。 ## [](#api-ポリシーの例)API ポリシーの例 PDK には、次の API ポリシーの例が含まれています。 - [ブロックポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/block/README.md)​: [周期関数](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-timer)​と ​[HTTP コール](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-http-request)​を実装して IP 範囲をブロックする方法の例として、ブロックポリシーを使用します。 - [証明書ポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/certs/README.md)​: 証明書ポリシーは、接続の証明書に関するデータを取得する方法の例として使用します。 - [CORS 検証ポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/cors-validation/README.md)​: CORS 検証ポリシーは、​[CORS ライブラリ](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-cors)​の関数をカスタムポリシーで使用する方法の例として使用します。 - [暗号化ポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/crypto/README.md)​: 暗号化ポリシーは、暗号化機能を提供する​[サードパーティライブラリ](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-libraries)​をカスタムポリシーで使用する方法の例として使用します。 - [データキャッシュポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/data-caching/README.md)​: データキャッシュポリシーは、​[データキャッシュ](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-caching)​をカスタムポリシーに実装する方法の例として使用します。 - [JWT 検証ポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/jwt-validation/README.md)​: JWT 検証ポリシーは、​[JWT ライブラリ](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-jwt)​の関数をカスタムポリシーで使用する方法の例として使用します。 - [メトリクスポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/metrics/README.md)​: [周期関数](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-timer)​と ​[HTTP コール](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-http-request)​を実装してメトリクス取り込みサービスに定期的にデータを送信する方法の例として、メトリクスポリシーを使用します。 - [クエリポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/query/README.md)​: クエリポリシーの例は、​[DataWeave 式](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-dataweave)​をカスタムポリシーで処理する方法の例として使用します。 - [簡単な OAuth 2.0 検証ポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/simple-oauth-2-validation/README.md)​: 簡単な OAuth 2.0 検証ポリシーは、​[HTTP コール](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-http-request)​をカスタムポリシーで実装する方法の例として使用します。 - [スパイクポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/spike/README.md)​: [周期関数](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-timer)​を実装してワーカーのスパイク制御を設定する方法の例として、スパイクポリシーを使用します。 - [TLS コールポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.2.0/tls-calls/README.md)​: Flex Gateway が実行されているオペレーティングシステムに証明書をインストールせずにポリシーで HTTPS コールを実行する方法の例として、TLS コールポリシーを使用します。 ## [](#a2a-および-mcp-サーバーポリシーの例)A2A および MCP サーバーポリシーの例 PDK には、次の A2A および MCP ポリシーの例が含まれています。 - [A2A サポートポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/main/agent-policies/a2a-support-policy/README.md)​: A2A サポートを追加する方法を示しています。 - [MCP サポートポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/main/agent-policies/mcp-support-policy/README.md)​: MCP サポートを追加する方法を示しています。 - [A2A PII 検出ポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/main/agent-policies/a2a-pii-detector-policy/README.md)​: A2A エージェントインタラクションの機密情報を記録またはブロックする方法を示しています。 - [A2A PII デコレーターポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/main/agent-policies/a2a-prompt-decorator-policy/README.md)​: A2A エージェントに送信されるプロンプトを変更する方法を示しています。 ## [](#ポリシープロジェクト例をセットアップする)ポリシープロジェクト例をセットアップする ポリシープロジェクト例を使用する手順は、次のとおりです。 1. [PDK 前提条件](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-prerequisites)​をすべてインストールしてあることを確認します。 2. 次のコマンドまたは好きな GitHub インターフェースを使用して、 [PDK カスタムポリシー GitHub リポジトリ](https://github.com/mulesoft/pdk-custom-policy-examples)​をコピーします。 ```ssh git clone https://github.com/mulesoft/pdk-custom-policy-examples.git ``` 3. コピーしたディレクトリに移動して、使用するポリシー例のディレクトリをコピーして新しい場所に貼り付けます。 4. コピーしたポリシー例の ​`cargo.toml`​ ファイルで、​`group-id`​ をプロジェクトのグループ ID に置き換えます。例: ```toml group_id = "" ``` 5. `make setup`​ コマンドを実行します。 ```ssh make setup ``` 6. ポリシー例の ​`README.md`​ ファイルを開いて、ポリシーの詳細やテスト方法を確認します。 ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features) # カスタムポリシーの例 Flex Gateway ポリシー開発キット (PDK) は、Rust ソースコードの設定を開始するためのポリシープロジェクトの例を提供しています。 すべてのポリシー例と関連ドキュメントは [PDK カスタムポリシー GitHub リポジトリ](https://github.com/mulesoft/pdk-custom-policy-examples)​にあります。 ## [](#api-ポリシーの例)API ポリシーの例 PDK には、次の API ポリシーの例が含まれています。 - [ブロックポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.4.0/block/README.md)​: [周期関数](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-timer)​と ​[HTTP コール](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-http-request)​を実装して IP 範囲をブロックする方法の例として、ブロックポリシーを使用します。 - [証明書ポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.4.0/certs/README.md)​: 証明書ポリシーは、接続の証明書に関するデータを取得する方法の例として使用します。 - [CORS 検証ポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.4.0/cors-validation/README.md)​: CORS 検証ポリシーは、​[CORS ライブラリ](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-cors)​の関数をカスタムポリシーで使用する方法の例として使用します。 - [暗号化ポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.4.0/crypto/README.md)​: 暗号化ポリシーは、暗号化機能を提供する​[サードパーティライブラリ](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-libraries)​をカスタムポリシーで使用する方法の例として使用します。 - [データキャッシュポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.4.0/data-caching/README.md)​: データキャッシュポリシーは、​[データキャッシュ](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-caching)​をカスタムポリシーに実装する方法の例として使用します。 - [DataWeave ポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.4.0/dataweave/README.md)​: DataWeave ポリシーの例は、​[DataWeave 式](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-dataweave)​をカスタムポリシーで処理する方法の例として使用します。 - [JWT 検証ポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.4.0/jwt-validation/README.md)​: JWT 検証ポリシーは、​[JWT ライブラリ](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-jwt)​の関数をカスタムポリシーで使用する方法の例として使用します。 - [メトリクスポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.4.0/metrics/README.md)​: [周期関数](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-timer)​と ​[HTTP コール](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-http-request)​を実装してメトリクス取り込みサービスに定期的にデータを送信する方法の例として、メトリクスポリシーを使用します。 - [クエリポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.4.0/query/README.md)​: クエリポリシーの例は、クエリパラメーターをカスタムポリシーで処理する方法の例として使用します。 - [簡単な OAuth 2.0 検証ポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.4.0/simple-oauth-2-validation/README.md)​: 簡単な OAuth 2.0 検証ポリシーは、​[HTTP コール](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-http-request)​をカスタムポリシーで実装する方法の例として使用します。 - [スパイクポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.4.0/spike/README.md)​: [周期関数](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-timer)​を実装してワーカーのスパイク制御を設定する方法の例として、スパイクポリシーを使用します。 - [ストリームペイロードポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.4.0/stream-payload/README.md)​: ストリームペイロードポリシーは、​[1MB より大きいペイロードボディを読み取る](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-headers#streaming-bodies)​方法の例として使用します。 - [TLS コールポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.4.0/tls-calls/README.md)​: Flex Gateway が実行されているオペレーティングシステムに証明書をインストールせずにポリシーで HTTPS コールを実行する方法の例として、TLS コールポリシーを使用します。 ## [](#a2a-および-mcp-サーバーポリシーの例)A2A および MCP サーバーポリシーの例 PDK には、次の A2A および MCP ポリシーの例が含まれています。 - [A2A サポートポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/main/agent-policies/a2a-support-policy/README.md)​: A2A サポートを追加する方法を示しています。 - [MCP サポートポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/main/agent-policies/mcp-support-policy/README.md)​: MCP サポートを追加する方法を示しています。 - [A2A PII 検出ポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/main/agent-policies/a2a-pii-detector-policy/README.md)​: A2A エージェントインタラクションの機密情報を記録またはブロックする方法を示しています。 - [A2A PII デコレーターポリシーの例](https://github.com/mulesoft/pdk-custom-policy-examples/blob/main/agent-policies/a2a-prompt-decorator-policy/README.md)​: A2A エージェントに送信されるプロンプトを変更する方法を示しています。 ## [](#ポリシープロジェクト例をセットアップする)ポリシープロジェクト例をセットアップする ポリシープロジェクト例を使用する手順は、次のとおりです。 1. [PDK 前提条件](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-prerequisites)​をすべてインストールしてあることを確認します。 2. 次のコマンドまたは好きな GitHub インターフェースを使用して、 [PDK カスタムポリシー GitHub リポジトリ](https://github.com/mulesoft/pdk-custom-policy-examples)​をコピーします。 ```ssh git clone https://github.com/mulesoft/pdk-custom-policy-examples.git ``` 3. コピーしたディレクトリに移動して、使用するポリシー例のディレクトリをコピーして新しい場所に貼り付けます。 4. コピーしたポリシー例の ​`cargo.toml`​ ファイルで、​`group-id`​ をプロジェクトのグループ ID に置き換えます。例: ```toml group_id = "" ``` 5. `make setup`​ コマンドを実行します。 ```ssh make setup ``` 6. ポリシー例の ​`README.md`​ ファイルを開いて、ポリシーの詳細やテスト方法を確認します。 ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features) # カスタムポリシーの適用 カスタムポリシーの適用は、​[内部ポリシー](https://docs.mulesoft.com/gateway/latest/policies-included-directory)​と同じように適用します。 カスタムポリシーを適用する場合、設定パラメーターは ​`definition/gcl.yaml`​ で定義されます。 構成パラメーターの定義の詳細については、[policy-pdk-create-schema-definition.adoc](#policy-pdk-create-schema-definition.adoc)を参照してください。 ## [](#始める前に)始める前に - [カスタムポリシーをコンパイルします](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-compile-policies)​。 - カスタムポリシーを接続モードで実行されている Flex Gateway に適用する場合は、​[カスタムポリシーを Exchange にアップロードします](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-publish-policies)​。 ## [](#接続モードでのポリシーの適用)接続モードでのポリシーの適用 接続モードでカスタムポリシーを適用すると、​`gcl.yaml`​ で定義された設定パラメーターとメタデータが API Manager UI に表示されます。 接続モードでカスタムポリシーを適用するには、[Applying Policies for Managed Omni Gateways and Connected Mode](https://docs.mulesoft.com/gateway/latest/gateway-secure-conn)を参照してください。 ### [](#接続モードでのポリシーの更新)接続モードでのポリシーの更新 API Manager でカスタムポリシーを適用する手順は、次のとおりです 1. **\[Anypoint Platform\] > \[API Manager\]**​ に移動します。 2. **\[API Administration (API 管理)\]**​ で、ポリシーを適用する API の名前をクリックします。 3. 左側のナビゲーションメニューから、​**\[Policies (ポリシー)\]**​ をクリックします。 4. 更新するポリシーのその他のオプションボタン (​![1%](/mulesoft/current/ja-jp/pdk/1.2/_images/more-options-menu.png)​) をクリックし、​**\[Edit configuration (設定を編集)\]**​ をクリックします。 5. **\[Policy version (ポリシーバージョン)\]**​ 設定パラメーターで​**最新**​バージョンを選択します。 6. **\[Save (保存)\]**​ をクリックします。 7. 更新するポリシーのその他のオプションボタン (​![1%](/mulesoft/current/ja-jp/pdk/1.2/_images/more-options-menu.png)​) をクリックし、​**\[Check for implementation updates (実装の更新を確認)\]**​ をクリックします。 実装の更新の詳細は、​[「ポリシー実装を更新する」](https://docs.mulesoft.com/jp/exchange/manage-versions#update-policy-implementations)​を参照してください。 8. 確認用のダイアログボックスで ​**\[Update all (すべて更新)\]**​ をクリックします。 ## [](#apply-policies-in-local-mode)ローカルモードでのポリシーの適用 ローカルモードで実行されている Flex Gateway では、​[ローカルの宣言型設定ファイル](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide)​を使用してカスタムポリシーを適用します。最初に Flex Gateway を実行するときに、この設定ファイルの場所を指定します。 ローカル宣言ファイルを作成する手順は、次のとおりです。 1. `target/wasm32-wasi/release`​ の PDK ディレクトリに、次の 2 つのファイルをコピーします。 - `_definition.yaml` - `_implementation.yaml` 2. この 2 つのファイルを ​`/etc/mulesoft/flex-gateway/conf.d/`​ Flex Gateway 設定ディレクトリに貼り付けます。 3. ポリシーを API インスタンスにバインドするために、​`.yaml`​ というファイル拡張子を持つポリシーバインディング設定ファイルを作成します。 - ファイルにカスタム名を付けます。 - ファイルを Flex Gateway の設定ディレクトリ ​`/etc/mulesoft/flex-gateway/conf.d/custom`​ に保存します。このディレクトリには複数の設定ファイルを保存できます。 4. 次の YAML スニペットをコピーしてファイルに貼り付け、必要な箇所を適切な値に変更します。 ```yaml apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: spec: targetRef: kind: ApiInstance name: policyRef: kind: Extension name: --impl config: : "your parameter" ``` - `Metadata.name:`​: カスタムポリシーインスタンス名。 - `spec.targetRef.name`​: カスタムポリシーを適用する API インスタンスの名前。API インスタンスはすでに定義済みで、適用されている必要があります。 - `spec.policyRef.name`​: カスタムポリシーの実装 ID。ポリシー ID を取得するには、ポリシーのルートディレクトリで ​`make show-policy-ref-name`​ コマンドを実行します。 - `spec.config`​: ポリシーの設定データ。 5. ファイルを保存します。ゲートウェイによって設定が自動的に更新されます。 ### [](#ローカルモードでのポリシーの更新)ローカルモードでのポリシーの更新 ローカルモードで Flex Gateway のカスタムポリシーを更新する手順は、次のとおりです。 - 設定パラメーターを編集していない場合は、Flex Gateway 設定ディレクトリの古い ​`_implementation.yaml`​ を ​`target/wasm32-wasi/release`​ PDK ディレクトリの実装ファイルに置き換えます。 - 設定パラメーターを編集した場合は、​[ローカルモードでのポリシーの適用](#apply-policies-in-local-mode)​の手順を繰り返して設定パラメーターを更新します。 ## [](#カスタムポリシーの並び替え)カスタムポリシーの並び替え カスタムポリシーの並び替えは、内部ポリシーと同じように行います。 ポリシーを並び替えるには、[Ordering Policies](https://docs.mulesoft.com/gateway/latest/policies-reorder)を参照してください。 ポリシーは、要求では順序どおりに、応答では逆の順序で実行されます。ただし、要求と応答のどちらでも実行されないポリシーもあります。 たとえば、次の順序で並んでいるポリシーがあるとします。 1. ポリシー X 2. ポリシー Y 要求ではポリシー X、ポリシー Y の順に実行され、応答ではポリシー Y、ポリシー X の順に実行されます。 ## [](#関連情報)関連情報 - [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide) # カスタムポリシーの適用 カスタムポリシーの適用は、​[内部ポリシー](https://docs.mulesoft.com/gateway/latest/policies-included-directory)​と同じように適用します。 カスタムポリシーを適用する場合、設定パラメーターは ​`definition/gcl.yaml`​ で定義されます。 構成パラメーターの定義の詳細については、[policy-pdk-create-schema-definition.adoc](#policy-pdk-create-schema-definition.adoc)を参照してください。 ## [](#始める前に)始める前に - [カスタムポリシーをコンパイルします](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-compile-policies)​。 - カスタムポリシーを接続モードで実行されている Flex Gateway に適用する場合は、​[カスタムポリシーを Exchange にアップロードします](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-publish-policies)​。 ## [](#接続モードでのポリシーの適用)接続モードでのポリシーの適用 接続モードでカスタムポリシーを適用すると、​`gcl.yaml`​ で定義された設定パラメーターとメタデータが API Manager UI に表示されます。 接続モードでカスタムポリシーを適用するには、[Applying Policies for Managed Omni Gateways and Connected Mode](https://docs.mulesoft.com/gateway/latest/gateway-secure-conn)を参照してください。 ### [](#接続モードでのポリシーの更新)接続モードでのポリシーの更新 API Manager でカスタムポリシーを適用する手順は、次のとおりです 1. **\[Anypoint Platform\] > \[API Manager\]**​ に移動します。 2. **\[API Administration (API 管理)\]**​ で、ポリシーを適用する API の名前をクリックします。 3. 左側のナビゲーションメニューから、​**\[Policies (ポリシー)\]**​ をクリックします。 4. 更新するポリシーのその他のオプションボタン (​![1%](/mulesoft/current/ja-jp/pdk/1.3/_images/more-options-menu.png)​) をクリックし、​**\[Edit configuration (設定を編集)\]**​ をクリックします。 5. **\[Policy version (ポリシーバージョン)\]**​ 設定パラメーターで​**最新**​バージョンを選択します。 6. **\[Save (保存)\]**​ をクリックします。 7. 更新するポリシーのその他のオプションボタン (​![1%](/mulesoft/current/ja-jp/pdk/1.3/_images/more-options-menu.png)​) をクリックし、​**\[Check for implementation updates (実装の更新を確認)\]**​ をクリックします。 実装の更新の詳細は、​[「ポリシー実装を更新する」](https://docs.mulesoft.com/jp/exchange/manage-versions#update-policy-implementations)​を参照してください。 8. 確認用のダイアログボックスで ​**\[Update all (すべて更新)\]**​ をクリックします。 ## [](#apply-policies-in-local-mode)ローカルモードでのポリシーの適用 ローカルモードで実行されている Flex Gateway では、​[ローカルの宣言型設定ファイル](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide)​を使用してカスタムポリシーを適用します。最初に Flex Gateway を実行するときに、この設定ファイルの場所を指定します。 ローカル宣言ファイルを作成する手順は、次のとおりです。 1. `target/wasm32-wasi/release`​ の PDK ディレクトリに、次の 2 つのファイルをコピーします。 - `_definition.yaml` - `_implementation.yaml` 2. この 2 つのファイルを ​`/etc/mulesoft/flex-gateway/conf.d/`​ Flex Gateway 設定ディレクトリに貼り付けます。 3. ポリシーを API インスタンスにバインドするために、​`.yaml`​ というファイル拡張子を持つポリシーバインディング設定ファイルを作成します。 - ファイルにカスタム名を付けます。 - ファイルを Flex Gateway の設定ディレクトリ ​`/etc/mulesoft/flex-gateway/conf.d/custom`​ に保存します。このディレクトリには複数の設定ファイルを保存できます。 4. 次の YAML スニペットをコピーしてファイルに貼り付け、必要な箇所を適切な値に変更します。 ```yaml apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: spec: targetRef: kind: ApiInstance name: policyRef: kind: Extension name: --impl config: : "your parameter" ``` - `Metadata.name:`​: カスタムポリシーインスタンス名。 - `spec.targetRef.name`​: カスタムポリシーを適用する API インスタンスの名前。API インスタンスはすでに定義済みで、適用されている必要があります。 - `spec.policyRef.name`​: カスタムポリシーの実装 ID。ポリシー ID を取得するには、ポリシーのルートディレクトリで ​`make show-policy-ref-name`​ コマンドを実行します。 - `spec.config`​: ポリシーの設定データ。 5. ファイルを保存します。ゲートウェイによって設定が自動的に更新されます。 ### [](#ローカルモードでのポリシーの更新)ローカルモードでのポリシーの更新 ローカルモードで Flex Gateway のカスタムポリシーを更新する手順は、次のとおりです。 - 設定パラメーターを編集していない場合は、Flex Gateway 設定ディレクトリの古い ​`_implementation.yaml`​ を ​`target/wasm32-wasi/release`​ PDK ディレクトリの実装ファイルに置き換えます。 - 設定パラメーターを編集した場合は、​[ローカルモードでのポリシーの適用](#apply-policies-in-local-mode)​の手順を繰り返して設定パラメーターを更新します。 ## [](#カスタムポリシーの並び替え)カスタムポリシーの並び替え カスタムポリシーの並び替えは、内部ポリシーと同じように行います。 ポリシーを並び替えるには、[Ordering Policies](https://docs.mulesoft.com/gateway/latest/policies-reorder)を参照してください。 ポリシーは、要求では順序どおりに、応答では逆の順序で実行されます。ただし、要求と応答のどちらでも実行されないポリシーもあります。 たとえば、次の順序で並んでいるポリシーがあるとします。 1. ポリシー X 2. ポリシー Y 要求ではポリシー X、ポリシー Y の順に実行され、応答ではポリシー Y、ポリシー X の順に実行されます。 ## [](#関連情報)関連情報 - [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide) # カスタムポリシーの適用 カスタムポリシーの適用は、​[内部ポリシー](https://docs.mulesoft.com/gateway/latest/policies-included-directory)​と同じように適用します。 カスタムポリシーを適用する場合、設定パラメーターは ​`definition/gcl.yaml`​ で定義されます。 構成パラメーターの定義の詳細については、[policy-pdk-create-schema-definition.adoc](#policy-pdk-create-schema-definition.adoc)を参照してください。 ## [](#始める前に)始める前に - [カスタムポリシーをコンパイルします](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-compile-policies)​。 - カスタムポリシーを接続モードで実行されている Flex Gateway に適用する場合は、​[カスタムポリシーを Exchange にアップロードします](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-publish-policies)​。 ## [](#接続モードでのポリシーの適用)接続モードでのポリシーの適用 接続モードでカスタムポリシーを適用すると、​`gcl.yaml`​ で定義された設定パラメーターとメタデータが API Manager UI に表示されます。 接続モードでカスタムポリシーを適用するには、[Applying Policies for Managed Omni Gateways and Connected Mode](https://docs.mulesoft.com/gateway/latest/gateway-secure-conn)を参照してください。 ### [](#接続モードでのポリシーの更新)接続モードでのポリシーの更新 API Manager でカスタムポリシーを適用する手順は、次のとおりです 1. **\[Anypoint Platform\] > \[API Manager\]**​ に移動します。 2. **\[API Administration (API 管理)\]**​ で、ポリシーを適用する API の名前をクリックします。 3. 左側のナビゲーションメニューから、​**\[Policies (ポリシー)\]**​ をクリックします。 4. 更新するポリシーのその他のオプションボタン (​![1%](/mulesoft/current/ja-jp/pdk/1.4/_images/more-options-menu.png)​) をクリックし、​**\[Edit configuration (設定を編集)\]**​ をクリックします。 5. **\[Policy version (ポリシーバージョン)\]**​ 設定パラメーターで​**最新**​バージョンを選択します。 6. **\[Save (保存)\]**​ をクリックします。 7. 更新するポリシーのその他のオプションボタン (​![1%](/mulesoft/current/ja-jp/pdk/1.4/_images/more-options-menu.png)​) をクリックし、​**\[Check for implementation updates (実装の更新を確認)\]**​ をクリックします。 実装の更新の詳細は、​[「ポリシー実装を更新する」](https://docs.mulesoft.com/jp/exchange/manage-versions#update-policy-implementations)​を参照してください。 8. 確認用のダイアログボックスで ​**\[Update all (すべて更新)\]**​ をクリックします。 ## [](#apply-policies-in-local-mode)ローカルモードでのポリシーの適用 ローカルモードで実行されている Flex Gateway では、​[ローカルの宣言型設定ファイル](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide)​を使用してカスタムポリシーを適用します。最初に Flex Gateway を実行するときに、この設定ファイルの場所を指定します。 ローカル宣言ファイルを作成する手順は、次のとおりです。 1. `target/wasm32-wasip1/release`​ の PDK ディレクトリに、次の 2 つのファイルをコピーします。 - `_definition.yaml` - `_implementation.yaml` 2. この 2 つのファイルを ​`/etc/mulesoft/flex-gateway/conf.d/`​ Flex Gateway 設定ディレクトリに貼り付けます。 3. ポリシーを API インスタンスにバインドするために、​`.yaml`​ というファイル拡張子を持つポリシーバインディング設定ファイルを作成します。 - ファイルにカスタム名を付けます。 - ファイルを Flex Gateway の設定ディレクトリ ​`/etc/mulesoft/flex-gateway/conf.d/custom`​ に保存します。このディレクトリには複数の設定ファイルを保存できます。 4. 次の YAML スニペットをコピーしてファイルに貼り付け、必要な箇所を適切な値に変更します。 ```yaml apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: spec: targetRef: kind: ApiInstance name: policyRef: kind: Extension name: --impl config: : "your parameter" ``` - `Metadata.name:`​: カスタムポリシーインスタンス名。 - `spec.targetRef.name`​: カスタムポリシーを適用する API インスタンスの名前。API インスタンスはすでに定義済みで、適用されている必要があります。 - `spec.policyRef.name`​: カスタムポリシーの実装 ID。ポリシー ID を取得するには、ポリシーのルートディレクトリで ​`make show-policy-ref-name`​ コマンドを実行します。 - `spec.config`​: ポリシーの設定データ。 5. ファイルを保存します。ゲートウェイによって設定が自動的に更新されます。 ### [](#ローカルモードでのポリシーの更新)ローカルモードでのポリシーの更新 ローカルモードで Flex Gateway のカスタムポリシーを更新する手順は、次のとおりです。 - 設定パラメーターを編集していない場合は、Flex Gateway 設定ディレクトリの古い ​`_implementation.yaml`​ を ​`target/wasm32-wasip1/release`​ PDK ディレクトリの実装ファイルに置き換えます。 - 設定パラメーターを編集した場合は、​[ローカルモードでのポリシーの適用](#apply-policies-in-local-mode)​の手順を繰り返して設定パラメーターを更新します。 ## [](#カスタムポリシーの並び替え)カスタムポリシーの並び替え カスタムポリシーの並び替えは、内部ポリシーと同じように行います。 ポリシーを並び替えるには、[Ordering Policies](https://docs.mulesoft.com/gateway/latest/policies-reorder)を参照してください。 ポリシーは、要求では順序どおりに、応答では逆の順序で実行されます。ただし、要求と応答のどちらでも実行されないポリシーもあります。 たとえば、次の順序で並んでいるポリシーがあるとします。 1. ポリシー X 2. ポリシー Y 要求ではポリシー X、ポリシー Y の順に実行され、応答ではポリシー Y、ポリシー X の順に実行されます。 ## [](#関連情報)関連情報 - [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide) # カスタムポリシーの開発 [前提条件](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-prerequisites)​のインストールが終わったら、Flex Gateway ポリシー開発キット (PDK) を使用してカスタムポリシーを開発できます。 カスタムポリシーのライフサイクルは、PDK で実行するすべてのカスタムポリシー開発ステップで構成されます。下記の手順には、PDK の外部で実行され、すべての Flex Gateway ポリシーに共通するステップ (​[ポリシーの適用](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-apply-policies)​など) は含まれません。 [新しいプロジェクトを作成](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-create-project)​した後は、いくつかのステップを繰り返し実行します。たとえば、ポリシーのソースコードを書いている間に一度戻って​[パラメーターを追加](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-create-schema-definition)​したり、ソースコードをデバッグしてからポリシーを再コンパイルしたりする場合などです。 PDK でカスタムポリシーを作成する手順は、次のとおりです。 1. [新しいプロジェクトを作成します](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-create-project)​。 2. [スキーマ定義を作成します](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-create-schema-definition)​。 `definition/gcl.yaml`​ ファイルを修正して、カスタムポリシーのメタデータと設定パラメーターを定義します。 3. [Rust でカスタムポリシー機能を設定します](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features)​。 Rust のコード例を使用して、​`src/lib.rs`​ ファイルでカスタムロジックを実装します。 4. [カスタムポリシーをコンパイルします](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-compile-policies)​。 ポリシーをコンパイルすると、ポリシーを Exchange にアップロードして Flex Gateway にデプロイするために必要な ​`WebAssembly`​ バイナリファイルと設定ファイルが作成されます。 5. [PDK デバッグプレイグラウンドでポリシーをデバッグします](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-debug-local)​。 PDK に用意されているプレイグラウンドを使用して、カスタムポリシーの機能をローカルにデバッグします。 6. [インテグレーションテストを作成します](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-integration-tests)​。 カスタムポリシーが他のサービスと互換性があることを確認し、新しいポリシーのバージョンごとに回帰エラーが発生しないことを確認するために、インテグレーションテストを作成します。 7. [ポリシーを Exchange でパブリッシュ](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-publish-policies#publish)​します。 ポリシーを Exchange でパブリッシュし、Flex Gateway 設定でテストするためのポリシーのベータ版を配布します。ポリシーを Flex Gateway にデプロイするには、ステップ 9 を参照してください。 8. [ポリシーを Exchange でリリース](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-publish-policies#release)​します。 Exchange でポリシーをリリースして、本番対応のポリシーを配布します。 9. カスタムポリシーを本番環境にデプロイするには、Flex Gateway にデプロイされている ​[API インスタンスにポリシーを適用](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-apply-policies)​します。 10. ステップ 2 に戻って、この API インスタンスの新しいバージョンを設定します。 # カスタムポリシーの開発 [前提条件](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-prerequisites)​のインストールが終わったら、Flex Gateway ポリシー開発キット (PDK) を使用してカスタムポリシーを開発できます。 カスタムポリシーのライフサイクルは、PDK で実行するすべてのカスタムポリシー開発ステップで構成されます。下記の手順には、PDK の外部で実行され、すべての Flex Gateway ポリシーに共通するステップ (​[ポリシーの適用](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-apply-policies)​など) は含まれません。 [新しいプロジェクトを作成](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-create-project)​した後は、いくつかのステップを繰り返し実行します。たとえば、ポリシーのソースコードを書いている間に一度戻って​[パラメーターを追加](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-create-schema-definition)​したり、ソースコードをデバッグしてからポリシーを再コンパイルしたりする場合などです。 PDK でカスタムポリシーを作成する手順は、次のとおりです。 1. [新しいプロジェクトを作成します](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-create-project)​。 2. [スキーマ定義を作成します](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-create-schema-definition)​。 `definition/gcl.yaml`​ ファイルを修正して、カスタムポリシーのメタデータと設定パラメーターを定義します。 3. [Rust でカスタムポリシー機能を設定します](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features)​。 Rust のコード例を使用して、​`src/lib.rs`​ ファイルでカスタムロジックを実装します。 4. [カスタムポリシーをコンパイルします](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-compile-policies)​。 ポリシーをコンパイルすると、ポリシーを Exchange にアップロードして Flex Gateway にデプロイするために必要な ​`WebAssembly`​ バイナリファイルと設定ファイルが作成されます。 5. [PDK デバッグプレイグラウンドでポリシーをデバッグします](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-debug-local)​。 PDK に用意されているプレイグラウンドを使用して、カスタムポリシーの機能をローカルにデバッグします。 6. [インテグレーションテストを作成します](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-integration-tests)​。 カスタムポリシーが他のサービスと互換性があることを確認し、新しいポリシーのバージョンごとに回帰エラーが発生しないことを確認するために、インテグレーションテストを作成します。 7. [ポリシーを Exchange でパブリッシュ](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-publish-policies#publish)​します。 ポリシーを Exchange でパブリッシュし、Flex Gateway 設定でテストするためのポリシーのベータ版を配布します。ポリシーを Flex Gateway にデプロイするには、ステップ 9 を参照してください。 8. [ポリシーを Exchange でリリース](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-publish-policies#release)​します。 Exchange でポリシーをリリースして、本番対応のポリシーを配布します。 9. カスタムポリシーを本番環境にデプロイするには、Flex Gateway にデプロイされている ​[API インスタンスにポリシーを適用](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-apply-policies)​します。 10. ステップ 2 に戻って、この API インスタンスの新しいバージョンを設定します。 # カスタムポリシーの開発 [前提条件](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-prerequisites)​のインストールが終わったら、Flex Gateway ポリシー開発キット (PDK) を使用してカスタムポリシーを開発できます。 カスタムポリシーのライフサイクルは、PDK で実行するすべてのカスタムポリシー開発ステップで構成されます。下記の手順には、PDK の外部で実行され、すべての Flex Gateway ポリシーに共通するステップ (​[ポリシーの適用](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-apply-policies)​など) は含まれません。 [新しいプロジェクトを作成](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-create-project)​した後は、いくつかのステップを繰り返し実行します。たとえば、ポリシーのソースコードを書いている間に一度戻って​[パラメーターを追加](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-create-schema-definition)​したり、ソースコードをデバッグしてからポリシーを再コンパイルしたりする場合などです。 PDK でカスタムポリシーを作成する手順は、次のとおりです。 1. [新しいプロジェクトを作成します](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-create-project)​。 2. [スキーマ定義を作成します](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-create-schema-definition)​。 `definition/gcl.yaml`​ ファイルを修正して、カスタムポリシーのメタデータと設定パラメーターを定義します。 3. [Rust でカスタムポリシー機能を設定します](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features)​。 Rust のコード例を使用して、​`src/lib.rs`​ ファイルでカスタムロジックを実装します。 4. [カスタムポリシーをコンパイルします](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-compile-policies)​。 ポリシーをコンパイルすると、ポリシーを Exchange にアップロードして Flex Gateway にデプロイするために必要な ​`WebAssembly`​ バイナリファイルと設定ファイルが作成されます。 5. [PDK デバッグプレイグラウンドでポリシーをデバッグします](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-debug-local)​。 PDK に用意されているプレイグラウンドを使用して、カスタムポリシーの機能をローカルにデバッグします。 6. [インテグレーションテストを作成します](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-integration-tests)​。 カスタムポリシーが他のサービスと互換性があることを確認し、新しいポリシーのバージョンごとに回帰エラーが発生しないことを確認するために、インテグレーションテストを作成します。 7. [ポリシーを Exchange でパブリッシュ](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-publish-policies#publish)​します。 ポリシーを Exchange でパブリッシュし、Flex Gateway 設定でテストするためのポリシーのベータ版を配布します。ポリシーを Flex Gateway にデプロイするには、ステップ 9 を参照してください。 8. [ポリシーを Exchange でリリース](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-publish-policies#release)​します。 Exchange でポリシーをリリースして、本番対応のポリシーを配布します。 9. カスタムポリシーを本番環境にデプロイするには、Flex Gateway にデプロイされている ​[API インスタンスにポリシーを適用](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-apply-policies)​します。 10. ステップ 2 に戻って、この API インスタンスの新しいバージョンを設定します。 # コントラクト検証ライブラリ関数の使用 API インスタンスとアプリケーション間の​[コントラクト](https://docs.mulesoft.com/jp/api-manager/latest/api-contracts-landing-page)​により、アプリケーションは SLA 層に基づいてインスタンスにアクセスできます。クライアントアプリケーションは、クライアント ID とクライアントシークレットで構成されるログイン情報を提供してコントラクトを検証できます。PDK コントラクト検証ライブラリでは、クライアントログイン情報を検証してカスタムクライアント ID 適用ポリシーを実装する関数が提供されます。 API インスタンスとアプリケーション間に同時に存在できるコントラクトはコントラクトは 1 つのみです。
Flex Gateway ポリシー開発キット (PDK) コントラクト検証ライブラリを使用するポリシープロジェクトの例については、 「Client ID Enforcement Policy Example (クライアント ID 適用ポリシーの例)」​を参照してください。
## [](#contracts-module)クライアントログイン情報を抽出する コントラクト検証ライブラリは、​`pdk::cors`​ モジュールから使用できます。 このモジュールで提供される ​`ContractValidator`​ は、​`ClientId`​ オブジェクトと ​`ClientSecret`​ オブジェクトで表されるクライアントログイン情報を検証します。​`ContractValidator::authenticate()`​ メソッドと ​`ContractValidator::authorize()`​ メソッドを使用して、認証および承認ログイン情報を検証します。 ```Rust impl ContractValidator { pub fn authenticate(client_id: &ClientId, client_secret: &ClientSecret) -> Result; pub fn authorize(client_id: &ClientId, client_secret: &ClientSecret) -> Result; } ``` どちらのメソッドでも、クライアント ID、クライアント名、SLA ID 項目が含まれる ​`ClientData`​ 構造体が返されます。 ```Rust pub struct ClientData { pub client_id: String, pub client_name: String, pub sla_id: Option, } ``` ## [](#request-validation)要求の認証および承認ヘッダーを検証する 要求からクライアントログイン情報を抽出して要求を認証し、​`ClientValidation::authenticate()`​ メソッドを呼び出します。​`pdk::contracts`​ モジュールで提供される ​`basic_auth_credentials()`​ ヘルパー関数は、リクエストヘッダーから基本認証ログイン情報を抽出します。 ```Rust pub fn basic_auth_credentials(request_headers_state: &RequestHeadersState) -> Result<(ClientId, ClientSecret), BasicAuthError>; ``` 次のコードスニペットでは、認証要求のシンプルな検索条件が提供されます。 ```Rust async fn my_authentication_filter( state: RequestHeadersState, authentication: Authentication, validator: &ContractValidator, ) -> Flow<()> { // Extract credentials let (client_id, client_secret) = match basic_auth_credentials(&state) { Ok(credentials) => credentials, Err(e) => { logger::info!("Invalid credentials: {e}"); // For simplicity, we are using a user-defined `unathorized_response()` // helper function for building responses. return Flow::Break(unauthorized_response("Invalid credentials", 401)); } }; // Validate authentication let validation = validator.authenticate(&client_id, &client_secret); let client_data = match validation { Ok(client_data) => client_data, Err(e) => { logger::info!("Invalid authentication: {e}"); return Flow::Break(unauthorized_response("Invalid authentication", 403)); } }; // Update the current authentication if let Some(mut auth) = authentication.authentication() { auth.client_id = Some(client_data.client_id); auth.client_name = Some(client_data.client_name); authentication.set_authentication(Some(&auth)); } Flow::Continue(()) } ``` 次のコードスニペットでは、承認要求のシンプルな検索条件が提供されます。 ```Rust async fn my_authorization_filter( state: RequestHeadersState, validator: &ContractValidator, ) -> Flow<()> { // Extract client id with a user defined helper `extract_client_id()` function, let client_id = match extract_client_id(&state) { Ok(credentials) => credentials, Err(e) => { logger::info!("Invalid credentials: {e}"); // For simplicity, we are using a user-defined `unathorized_response()` // helper function for building responses. return Flow::Break(unauthorized_response("Invalid credentials", 401)); } }; // Validate authorization let validation = validator.authorize(&client_id); if let Err(e) = validation { logger::info!("Invalid authentication: {e}"); return Flow::Break(unauthorized_response("Invalid authentication", 403)); } Flow::Continue(()) } ``` ## [](#custom-credentials-extraction)クライアントログイン情報のカスタム抽出を実装する `ClientId::new()`​ および ​`ClientSecret::new()`​ メソッドを呼び出して、ログイン情報を抽出します。 ```Rust impl ClientId { pub fn new(client_id: String) -> Self; } impl ClientSecret { pub fn new(client_secret: String) -> Self; } ``` ログイン情報を抽出したら、一連のログイン情報を初期化します。 ```Rust fn initialize_credentials(raw_client_id: String, raw_client_secret) -> (ClientId, ClientSecret) { let client_id = ClientId::new(raw_client_id); let client_secret = ClientSecret::new(raw_client_secret); (client_id, client_secret) } ```
セキュリティ上の理由により、​ClientSecret​ のコンテンツは使用後に削除され、​Debug​ trait に ​ClientSecret​ のコンテンツは表示されません。
## [](#contract-validator-injection)ContractValidator オブジェクトを挿入する `ContractValidator`​ オブジェクトを ​`#[entrypoint]`​ 関数に挿入し、要求検索条件への参照を共有します。 ```Rust #[entrypoint] async fn configure(launcher: Launcher, validator: ContractValidator) -> Result<(), LaunchError> { let filter = on_request(|state, authentication| my_authentication_filter(state, authentication, &validator)); launcher.launch(filter).await?; OK(()) } ``` ### [](#contract-database-polling)ローカルコントラクトデータベースをポーリングする `ContractValidator`​ オブジェクトには、コントラクトデータベースのローカルコピーが保持されます。ローカルコピーをポーリングして、コントラクトの有効なコピーを保持する必要があります。​`ContractValidator::update_contracts()`​ メソッドを呼び出して、ローカルコピーをポーリングします。 ```Rust impl ContractValidator { pub async fn update_contracts(&self) -> Result<(), UpdateError>; } ``` `ContractValidator::update_contracts()`​ メソッドでコントラクトデータベースのポーリング中に接続の問題が発生したことを示すエラーが返された場合、再試行およびエラー処理ヒューリスティックを実装する必要があります。これを行うには、​`ContractValidator::UPDATE_PERIOD`​ 定数で指定された期間に ​`ContractValidator::update_contracts()`​ を呼び出します。 ```Rust async fn update_my_contracts(validator: &ContractValidator, clock: Clock) { // Configure a new timer let timer = clock.period(ContractValidator::UPDATE_PERIOD); loop { // Update result handling should be customized by the programmer let update_result = validator.update_contracts().await; // Wait for the next tick if !timer.next_tick().await { // If no more ticks are available, finish the task. return; } } } ``` コントラクトデータベース初期化期間では、更新期間よりも高い頻度でコントラクトデータベースをポーリングする期間を指定します。​`ContractValidator::INITIALIZATION_PERIOD`​ では、最初のポーリングに必要な間隔を指定します。 ```Rust async fn initialize_my_contracts(validator: &ContractValidator, clock: Clock) { // Configure a new timer let timer = clock.period(ContractValidator::UPDATE_PERIOD); loop { // Update result handling should be customized by the programmer let update_result = validator.update_contracts().await; // Wait for the next tick if !timer.next_tick().await { // If no more ticks are available, finish the task. return; } } } ``` 次のスニペットは、初期化と更新のポーリング期間が含まれる完全なコントラクトポーリングタスクを示しています。 ```Rust async fn update_my_contracts(validator: &ContractValidator, clock: Clock) { let initialization_timer = clock.period(ContractValidator::INITIALIZATION_PERIOD); loop { if validator.update_contracts().await.is_ok() { logger::info!("Contracts storage initialized."); break; } if !initialization_timer.next_tick().await { logger::info!("Tick event suspended."); break; } } let update_timer = initialization_timer .release() .period(ContractValidator::UPDATE_PERIOD); loop { let _ = validator.update_contracts().await; if !update_timer.next_tick().await { logger::info!("Tick event suspended."); break; } logger::info!("Retrying contracts storage initialization."); } } ``` コントラクトデータベースポーリングタスクは ​`Launcher::launch()`​ タスクと同時に実行する必要があるため、 [futures](https://crates.io/crates/futures)​ クレートの ​`join!()`​ マクロを使用して両方のタスクを結合します。次のスニペットでは、ポーリングと起動が含まれる完全な ​`#[entrypoint]`​ 関数を実装します。 ```Rust #[entrypoint] async fn configure(launcher: Launcher, clock: Clock,validator: ContractValidator) -> Result<(), LauncherError> { let filter = on_request(|state, authentication| my_authentication_filter(state, authentication, &validator)); let (_, launcher_result) = join! { update_my_contracts(&validator, clock), launcher.launch(filter), }; launcher_result } ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features) - [遅延関数、周期関数、同期関数の設定](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-timer) - [クライアントアプリケーション、コントラクト、ログイン情報](https://docs.mulesoft.com/jp/api-manager/latest/api-contracts-landing-page) # コントラクト検証ライブラリ関数の使用 API インスタンスとアプリケーション間の​[コントラクト](https://docs.mulesoft.com/jp/api-manager/latest/api-contracts-landing-page)​により、アプリケーションは SLA 層に基づいてインスタンスにアクセスできます。クライアントアプリケーションは、クライアント ID とクライアントシークレットで構成されるログイン情報を提供してコントラクトを検証できます。PDK コントラクト検証ライブラリでは、クライアントログイン情報を検証してカスタムクライアント ID 適用ポリシーを実装する関数が提供されます。 API インスタンスとアプリケーション間に同時に存在できるコントラクトはコントラクトは 1 つのみです。
Flex Gateway ポリシー開発キット (PDK) コントラクト検証ライブラリを使用するポリシープロジェクトの例については、 「Client ID Enforcement Policy Example (クライアント ID 適用ポリシーの例)」​を参照してください。
## [](#contracts-module)クライアントログイン情報を抽出する コントラクト検証ライブラリは、​`pdk::cors`​ モジュールから使用できます。 このモジュールで提供される ​`ContractValidator`​ は、​`ClientId`​ オブジェクトと ​`ClientSecret`​ オブジェクトで表されるクライアントログイン情報を検証します。​`ContractValidator::authenticate()`​ メソッドと ​`ContractValidator::authorize()`​ メソッドを使用して、認証および承認ログイン情報を検証します。 ```Rust impl ContractValidator { pub fn authenticate(client_id: &ClientId, client_secret: &ClientSecret) -> Result; pub fn authorize(client_id: &ClientId, client_secret: &ClientSecret) -> Result; } ``` どちらのメソッドでも、クライアント ID、クライアント名、SLA ID 項目が含まれる ​`ClientData`​ 構造体が返されます。 ```Rust pub struct ClientData { pub client_id: String, pub client_name: String, pub sla_id: Option, } ``` ## [](#request-validation)要求の認証および承認ヘッダーを検証する 要求からクライアントログイン情報を抽出して要求を認証し、​`ClientValidation::authenticate()`​ メソッドを呼び出します。​`pdk::contracts`​ モジュールで提供される ​`basic_auth_credentials()`​ ヘルパー関数は、リクエストヘッダーから基本認証ログイン情報を抽出します。 ```Rust pub fn basic_auth_credentials(request_headers_state: &RequestHeadersState) -> Result<(ClientId, ClientSecret), BasicAuthError>; ``` 次のコードスニペットでは、認証要求のシンプルな検索条件が提供されます。 ```Rust async fn my_authentication_filter( state: RequestHeadersState, authentication: Authentication, validator: &ContractValidator, ) -> Flow<()> { // Extract credentials let (client_id, client_secret) = match basic_auth_credentials(&state) { Ok(credentials) => credentials, Err(e) => { logger::info!("Invalid credentials: {e}"); // For simplicity, we are using a user-defined `unathorized_response()` // helper function for building responses. return Flow::Break(unauthorized_response("Invalid credentials", 401)); } }; // Validate authentication let validation = validator.authenticate(&client_id, &client_secret); let client_data = match validation { Ok(client_data) => client_data, Err(e) => { logger::info!("Invalid authentication: {e}"); return Flow::Break(unauthorized_response("Invalid authentication", 403)); } }; // Update the current authentication if let Some(mut auth) = authentication.authentication() { auth.client_id = Some(client_data.client_id); auth.client_name = Some(client_data.client_name); authentication.set_authentication(Some(&auth)); } Flow::Continue(()) } ``` 次のコードスニペットでは、承認要求のシンプルな検索条件が提供されます。 ```Rust async fn my_authorization_filter( state: RequestHeadersState, validator: &ContractValidator, ) -> Flow<()> { // Extract client id with a user defined helper `extract_client_id()` function, let client_id = match extract_client_id(&state) { Ok(credentials) => credentials, Err(e) => { logger::info!("Invalid credentials: {e}"); // For simplicity, we are using a user-defined `unathorized_response()` // helper function for building responses. return Flow::Break(unauthorized_response("Invalid credentials", 401)); } }; // Validate authorization let validation = validator.authorize(&client_id); if let Err(e) = validation { logger::info!("Invalid authentication: {e}"); return Flow::Break(unauthorized_response("Invalid authentication", 403)); } Flow::Continue(()) } ``` ## [](#custom-credentials-extraction)クライアントログイン情報のカスタム抽出を実装する `ClientId::new()`​ および ​`ClientSecret::new()`​ メソッドを呼び出して、ログイン情報を抽出します。 ```Rust impl ClientId { pub fn new(client_id: String) -> Self; } impl ClientSecret { pub fn new(client_secret: String) -> Self; } ``` ログイン情報を抽出したら、一連のログイン情報を初期化します。 ```Rust fn initialize_credentials(raw_client_id: String, raw_client_secret) -> (ClientId, ClientSecret) { let client_id = ClientId::new(raw_client_id); let client_secret = ClientSecret::new(raw_client_secret); (client_id, client_secret) } ```
セキュリティ上の理由により、​ClientSecret​ のコンテンツは使用後に削除され、​Debug​ trait に ​ClientSecret​ のコンテンツは表示されません。
## [](#contract-validator-injection)ContractValidator オブジェクトを挿入する `ContractValidator`​ オブジェクトを ​`#[entrypoint]`​ 関数に挿入し、要求検索条件への参照を共有します。 ```Rust #[entrypoint] async fn configure(launcher: Launcher, validator: ContractValidator) -> Result<(), LaunchError> { let filter = on_request(|state, authentication| my_authentication_filter(state, authentication, &validator)); launcher.launch(filter).await?; OK(()) } ``` ### [](#contract-database-polling)ローカルコントラクトデータベースをポーリングする `ContractValidator`​ オブジェクトには、コントラクトデータベースのローカルコピーが保持されます。ローカルコピーをポーリングして、コントラクトの有効なコピーを保持する必要があります。​`ContractValidator::update_contracts()`​ メソッドを呼び出して、ローカルコピーをポーリングします。 ```Rust impl ContractValidator { pub async fn update_contracts(&self) -> Result<(), UpdateError>; } ``` `ContractValidator::update_contracts()`​ メソッドでコントラクトデータベースのポーリング中に接続の問題が発生したことを示すエラーが返された場合、再試行およびエラー処理ヒューリスティックを実装する必要があります。これを行うには、​`ContractValidator::UPDATE_PERIOD`​ 定数で指定された期間に ​`ContractValidator::update_contracts()`​ を呼び出します。 ```Rust async fn update_my_contracts(validator: &ContractValidator, clock: Clock) { // Configure a new timer let timer = clock.period(ContractValidator::UPDATE_PERIOD); loop { // Update result handling should be customized by the programmer let update_result = validator.update_contracts().await; // Wait for the next tick if !timer.next_tick().await { // If no more ticks are available, finish the task. return; } } } ``` コントラクトデータベース初期化期間では、更新期間よりも高い頻度でコントラクトデータベースをポーリングする期間を指定します。​`ContractValidator::INITIALIZATION_PERIOD`​ では、最初のポーリングに必要な間隔を指定します。 ```Rust async fn initialize_my_contracts(validator: &ContractValidator, clock: Clock) { // Configure a new timer let timer = clock.period(ContractValidator::UPDATE_PERIOD); loop { // Update result handling should be customized by the programmer let update_result = validator.update_contracts().await; // Wait for the next tick if !timer.next_tick().await { // If no more ticks are available, finish the task. return; } } } ``` 次のスニペットは、初期化と更新のポーリング期間が含まれる完全なコントラクトポーリングタスクを示しています。 ```Rust async fn update_my_contracts(validator: &ContractValidator, clock: Clock) { let initialization_timer = clock.period(ContractValidator::INITIALIZATION_PERIOD); loop { if validator.update_contracts().await.is_ok() { logger::info!("Contracts storage initialized."); break; } if !initialization_timer.next_tick().await { logger::info!("Tick event suspended."); break; } } let update_timer = initialization_timer .release() .period(ContractValidator::UPDATE_PERIOD); loop { let _ = validator.update_contracts().await; if !update_timer.next_tick().await { logger::info!("Tick event suspended."); break; } logger::info!("Retrying contracts storage initialization."); } } ``` コントラクトデータベースポーリングタスクは ​`Launcher::launch()`​ タスクと同時に実行する必要があるため、 [futures](https://crates.io/crates/futures)​ クレートの ​`join!()`​ マクロを使用して両方のタスクを結合します。次のスニペットでは、ポーリングと起動が含まれる完全な ​`#[entrypoint]`​ 関数を実装します。 ```Rust #[entrypoint] async fn configure(launcher: Launcher, clock: Clock,validator: ContractValidator) -> Result<(), LauncherError> { let filter = on_request(|state, authentication| my_authentication_filter(state, authentication, &validator)); let (_, launcher_result) = join! { update_my_contracts(&validator, clock), launcher.launch(filter), }; launcher_result } ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features) - [遅延関数、周期関数、同期関数の設定](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-timer) - [クライアントアプリケーション、コントラクト、ログイン情報](https://docs.mulesoft.com/jp/api-manager/latest/api-contracts-landing-page) # サードパーティライブラリの使用
サードパーティライブラリを使用するポリシープロジェクトの例は、 「Crypto Policy Example (暗号化ポリシーの例)」​を参照してください。
Proxy Wasm は、低レベルのバイナリアプリケーションインターフェース (abi) を定義し、ライブラリが実行できるシステムコールを制限します。ポリシーに含まれるすべてのサードパーティライブラリは、​`wasm32-wasi`​ Rust コンパイルターゲットと互換性がある必要があります。 `serde_urlencoded`​ などのライブラリを定義するには、​`cargo.toml`​ の連動関係リストに追加します。 ```toml [dependencies] ... serde_urlencoded = "0.7.0" ``` ライブラリを定義すると、​`lib.rs`​ にある以下のような関数を使用できるようになります。 ```Rust serde_urlencoded::to_string([("token", "myToken")]) ``` データベースのような外部サービスとやりとりするライブラリや、ファイルの読み取りのようなシステムコールを実行するライブラリは、通常は ​`wasm32-wasi`​ ターゲットとの互換性がありません。 ポリシーが外部サービスとやりとりする場合は、Flex Gateway で提供されている ​`HttpClient`​ を使用してください。HTTP コールの実行に関する詳細は、[policy-pdk-configure-features-http-request.adoc](#policy-pdk-configure-features-http-request.adoc)を参照してください。 一部のライブラリは ​`wasm32-wasi`​ ターゲットに適切にコンパイルできても、Flex Gateway にデプロイすると適切に動作しないことがあります。次のようなエラーがあります。 - `Failed to load Wasm module due to a missing import: …​ (インポートが欠落しているため Wasm モジュールの読み込みに失敗しました: …​)` - `Wasm VM failed to initialize Wasm code (Wasm VM が Wasm コードの初期化に失敗しました)` - `Plugin configured to fail closed failed to load (フェールクローズに設定されたプラグインの読み込みに失敗しました)` これらのエラーが発生した場合には、サードパーティライブラリのオーナーに問い合わせるか、別のライブラリを使用してください。 ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features) # サードパーティライブラリの使用
サードパーティライブラリを使用するポリシープロジェクトの例は、 「Crypto Policy Example (暗号化ポリシーの例)」​を参照してください。
Proxy Wasm は、低レベルのバイナリアプリケーションインターフェース (abi) を定義し、ライブラリが実行できるシステムコールを制限します。ポリシーに含まれるすべてのサードパーティライブラリは、​`wasm32-wasi`​ Rust コンパイルターゲットと互換性がある必要があります。 `serde_urlencoded`​ などのライブラリを定義するには、​`cargo.toml`​ の連動関係リストに追加します。 ```toml [dependencies] ... serde_urlencoded = "0.7.0" ``` ライブラリを定義すると、​`lib.rs`​ にある以下のような関数を使用できるようになります。 ```Rust serde_urlencoded::to_string([("token", "myToken")]) ``` データベースのような外部サービスとやりとりするライブラリや、ファイルの読み取りのようなシステムコールを実行するライブラリは、通常は ​`wasm32-wasi`​ ターゲットとの互換性がありません。 ポリシーが外部サービスとやりとりする場合は、Flex Gateway で提供されている ​`HttpClient`​ を使用してください。HTTP コールの実行に関する詳細は、[policy-pdk-configure-features-http-request.adoc](#policy-pdk-configure-features-http-request.adoc)を参照してください。 一部のライブラリは ​`wasm32-wasi`​ ターゲットに適切にコンパイルできても、Flex Gateway にデプロイすると適切に動作しないことがあります。次のようなエラーがあります。 - `Failed to load Wasm module due to a missing import: …​ (インポートが欠落しているため Wasm モジュールの読み込みに失敗しました: …​)` - `Wasm VM failed to initialize Wasm code (Wasm VM が Wasm コードの初期化に失敗しました)` - `Plugin configured to fail closed failed to load (フェールクローズに設定されたプラグインの読み込みに失敗しました)` これらのエラーが発生した場合には、サードパーティライブラリのオーナーに問い合わせるか、別のライブラリを使用してください。 ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features) # サードパーティライブラリの使用
サードパーティライブラリを使用するポリシープロジェクトの例は、 「Crypto Policy Example (暗号化ポリシーの例)」​を参照してください。
Proxy Wasm は、低レベルのバイナリアプリケーションインターフェース (abi) を定義し、ライブラリが実行できるシステムコールを制限します。ポリシーに含まれるすべてのサードパーティライブラリは、​`wasm32-wasip1`​ Rust コンパイルターゲットと互換性がある必要があります。 `serde_urlencoded`​ などのライブラリを定義するには、​`cargo.toml`​ の連動関係リストに追加します。 ```toml [dependencies] ... serde_urlencoded = "0.7.0" ``` ライブラリを定義すると、​`lib.rs`​ にある以下のような関数を使用できるようになります。 ```Rust serde_urlencoded::to_string([("token", "myToken")]) ``` データベースのような外部サービスとやりとりするライブラリや、ファイルの読み取りのようなシステムコールを実行するライブラリは、通常は ​`wasm32-wasip1`​ ターゲットとの互換性がありません。 ポリシーが外部サービスとやりとりする場合は、Flex Gateway で提供されている ​`HttpClient`​ を使用してください。HTTP コールの実行に関する詳細は、[policy-pdk-configure-features-http-request.adoc](#policy-pdk-configure-features-http-request.adoc)を参照してください。 一部のライブラリは ​`wasm32-wasip1`​ ターゲットに適切にコンパイルできても、Flex Gateway にデプロイすると適切に動作しないことがあります。次のようなエラーがあります。 - `Failed to load Wasm module due to a missing import: …​ (インポートが欠落しているため Wasm モジュールの読み込みに失敗しました: …​)` - `Wasm VM failed to initialize Wasm code (Wasm VM が Wasm コードの初期化に失敗しました)` - `Plugin configured to fail closed failed to load (フェールクローズに設定されたプラグインの読み込みに失敗しました)` これらのエラーが発生した場合には、サードパーティライブラリのオーナーに問い合わせるか、別のライブラリを使用してください。 ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features) # デプロイ済みのカスタムポリシーのデバッグ PDK のデバッグプレイグラウンドや PDK の統合環境では存在しなかったエラーが、ポリシーを本番環境の ​[API インスタンスに適用](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-apply-policies)​した時点で見つかることがあります。 本番環境でデバッグログを使用する方法は、[Troubleshooting Self-Managed Gateway with Debug Logs](https://docs.mulesoft.com/gateway/latest/troubleshoot-debug-logs)を参照してください。 Flex Gateway ログの監視に関する詳細は、[Monitoring Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-monitor)を参照してください。 ## [](#関連情報)関連情報 - [PDK デバッグプレイグラウンドでのカスタムポリシーのデバッグ](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-debug-local) - [インテグレーションテストの作成](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-integration-tests) # デプロイ済みのカスタムポリシーのデバッグ PDK のデバッグプレイグラウンドや PDK の統合環境では存在しなかったエラーが、ポリシーを本番環境の ​[API インスタンスに適用](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-apply-policies)​した時点で見つかることがあります。 本番環境でデバッグログを使用する方法は、[Troubleshooting Self-Managed Gateway with Debug Logs](https://docs.mulesoft.com/gateway/latest/troubleshoot-debug-logs)を参照してください。 Flex Gateway ログの監視に関する詳細は、[Monitoring Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-monitor)を参照してください。 ## [](#関連情報)関連情報 - [PDK デバッグプレイグラウンドでのカスタムポリシーのデバッグ](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-debug-local) - [インテグレーションテストの作成](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-integration-tests) # デプロイ済みのカスタムポリシーのデバッグ PDK のデバッグプレイグラウンドや PDK の統合環境では存在しなかったエラーが、ポリシーを本番環境の ​[API インスタンスに適用](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-apply-policies)​した時点で見つかることがあります。 本番環境でデバッグログを使用する方法は、[Troubleshooting Self-Managed Gateway with Debug Logs](https://docs.mulesoft.com/gateway/latest/troubleshoot-debug-logs)を参照してください。 Flex Gateway ログの監視に関する詳細は、[Monitoring Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-monitor)を参照してください。 ## [](#関連情報)関連情報 - [PDK デバッグプレイグラウンドでのカスタムポリシーのデバッグ](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-debug-local) - [インテグレーションテストの作成](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-integration-tests) # パラメーターの挿入 Flex Gateway ポリシー開発キット (PDK) は、​`#[entrypoint]`​ 設定関数に挿入できる以下のパラメーターを提供します。 - `Configuration`​: ポリシーの設定パラメーターを提供します。設定パラメーターの定義方法については、[ポリシースキーマ定義の作成](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-create-schema-definition)を参照してください。 - `Metadata`​: ポリシー、Flex Gateway インスタンス、API インスタンス、および Anypoint 組織に関するメタデータを提供します。提供されるメタデータの詳細については、[ポリシーのメタデータへのアクセス](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-metadata)を参照してください。 - `HttpClient`​: ポリシーで HTTP コールを有効にします。ポリシーから HTTP コールを実行する方法の詳細については、[HTTP コールの実行](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-http-request)を参照してください。 - `CacheBuilder`​: ポリシーのキャッシュ機能を提供します。キャッシュの詳細については、[ワーカー間でのデータ共有とキャッシュの設定](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-caching)を参照してください。 - `StreamProperties`​: 同じ要求を処理する他のポリシーとプロパティを共有するための構造体を提供します。ポリシー間の情報共有の詳細については、[ポリシー間のデータ共有](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-streamproperties)を参照してください。 また、​`HttpClient`​ および ​`StreamProperties`​ パラメーターをラップされた関数の ​`on_request`​ または ​`on_response`​ に直接挿入することもできます。たとえば、​`on_request`​ 関数の内部で HTTP コールを実行する必要がある場合は、​`HTTPClient`​ をその関数に直接挿入します。 ベストプラクティスとして、パラメーターは必ず使用する場所にのみ挿入するようにしてください。ただし、ポリシーの適用時に一度だけ実行する初期化ステップがパラメーターに必要な場合は、ラップされた関数のパフォーマンスを向上させるために、パラメーターを ​`#[entrypoint]`​ に挿入して設定ステップを完了させるのが最善です。 ## [](#ラップされた関数の-on_request-と-on_response-へのパラメーターの挿入)ラップされた関数の on\_request と on\_response へのパラメーターの挿入 ラップされた関数は以下のパラメーターを受け入れます。 - `HttpClient`​: ポリシーで HTTP コールを有効にします。ポリシーから HTTP コールを実行する方法の詳細については、[HTTP コールの実行](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-http-request)を参照してください。 - `StreamProperties`​: 同じ要求を処理する他のポリシーとプロパティを共有するための構造体を提供します。ポリシー間の情報共有の詳細については、[ポリシー間のデータ共有](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-streamproperties)を参照してください。 - `RequestState`​: 受信したリクエストヘッダーとリクエストボディを操作するための、要求検索条件のさまざまなフェーズへのアクセスを提供します。 `RequestState`​ は ​`on_request`​ 関数でのみ使用できます。​`RequestState`​ のヘッダーとボディの読み取りと書き込みについては、[リクエストヘッダーとリクエストボディの読み取りと書き込み](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-headers)を参照してください。 - `ResponseState`​: アップストリームのレスポンスヘッダーとレスポンスボディを操作するための、要求検索条件のさまざまなフェーズへのアクセスを提供します。 `ResponseState`​ は ​`on_response`​ 関数でのみ使用できます。​`ResponseState`​ のヘッダーとボディの読み取りと書き込みについては、[リクエストヘッダーとリクエストボディの読み取りと書き込み](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-headers)を参照してください。 - `RequestData`​: `on_request`​ 関数と ​`on_response`​ 関数の間でデータを共有します。 `RequestData`​ は ​`on_response`​ 関数でのみ使用できます。​`RequestData`​ の詳細については、[要求と応答でのデータの共有](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-share-data)を参照してください。 - `Authentication`​: 認証データの読み取りまたは他のポリシーとの共有のためのアクセスを提供します。​`Authentication`​ の詳細については、[要求認証情報へのアクセス](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-authentication)を参照してください。 ラップされた関数がこれらのパラメーターを受け取るだけであれば、ラッパーにラムダは必要ありません。たとえば、関数のシグネチャーが次のように定義されているとします。 ```Rust async fn request_filter(state: RequestState) -> RequestData; async fn response_filter(state: ResponseState, path: RequestData); ``` 次の例では、関数定義のラムダを定義しています。 ```Rust let filter = on_request(|request_state| request_filter(request_state)) .on_response(|response_state, request_data| response_filter(response_state, request_data)); ``` ラムダを定義する代わりに、次の関数定義を使うことができます。 ```Rust let filter = on_request(request_filter) .on_response(response_filter); ``` ラップされた関数が、他のパラメーター (​`#[entrypoint]`​ 関数で定義された設定パラメーターなど) を必要とする場合は、そのパラメーターをラップされた関数に挿入します。パラメーターを渡すには、ラムダを定義して変数参照を送信します。例: ```Rust async fn request_filter(state: RequestState, conf: &Config, tuple: &(u32, u32)) { ... } #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration) -> Result<()> { let config = serde_json::from_slice(&bytes)?; let tuple: (u32, u32) = (10, 10); let filter = on_request(|request_state| request_filter(request_state, &config, &tuple)); launcher .launch(filter) .await?; Ok(()) } ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features) # パラメーターの挿入 Flex Gateway ポリシー開発キット (PDK) は、​`#[entrypoint]`​ 設定関数に挿入できる以下のパラメーターを提供します。 - `Configuration`​: ポリシーの設定パラメーターを提供します。設定パラメーターの定義方法については、[ポリシースキーマ定義の作成](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-create-schema-definition)を参照してください。 - `Metadata`​: ポリシー、Flex Gateway インスタンス、API インスタンス、および Anypoint 組織に関するメタデータを提供します。提供されるメタデータの詳細については、[ポリシーのメタデータへのアクセス](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-metadata)を参照してください。 - `HttpClient`​: ポリシーで HTTP コールを有効にします。ポリシーから HTTP コールを実行する方法の詳細については、[HTTP コールの実行](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-http-request)を参照してください。 - `CacheBuilder`​: ポリシーのキャッシュ機能を提供します。キャッシュの詳細については、[ワーカー間でのデータ共有とキャッシュの設定](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-caching)を参照してください。 - `StreamProperties`​: 同じ要求を処理する他のポリシーとプロパティを共有するための構造体を提供します。ポリシー間の情報共有の詳細については、[ポリシー間のデータ共有](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-streamproperties)を参照してください。 また、​`HttpClient`​ および ​`StreamProperties`​ パラメーターをラップされた関数の ​`on_request`​ または ​`on_response`​ に直接挿入することもできます。たとえば、​`on_request`​ 関数の内部で HTTP コールを実行する必要がある場合は、​`HTTPClient`​ をその関数に直接挿入します。 ベストプラクティスとして、パラメーターは必ず使用する場所にのみ挿入するようにしてください。ただし、ポリシーの適用時に一度だけ実行する初期化ステップがパラメーターに必要な場合は、ラップされた関数のパフォーマンスを向上させるために、パラメーターを ​`#[entrypoint]`​ に挿入して設定ステップを完了させるのが最善です。 ## [](#ラップされた関数の-on_request-と-on_response-へのパラメーターの挿入)ラップされた関数の on\_request と on\_response へのパラメーターの挿入 ラップされた関数は以下のパラメーターを受け入れます。 - `HttpClient`​: ポリシーで HTTP コールを有効にします。ポリシーから HTTP コールを実行する方法の詳細については、[HTTP コールの実行](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-http-request)を参照してください。 - `StreamProperties`​: 同じ要求を処理する他のポリシーとプロパティを共有するための構造体を提供します。ポリシー間の情報共有の詳細については、[ポリシー間のデータ共有](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-streamproperties)を参照してください。 - `RequestState`​: 受信したリクエストヘッダーとリクエストボディを操作するための、要求検索条件のさまざまなフェーズへのアクセスを提供します。 `RequestState`​ は ​`on_request`​ 関数でのみ使用できます。​`RequestState`​ のヘッダーとボディの読み取りと書き込みについては、[リクエストヘッダーとリクエストボディの読み取りと書き込み](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-headers)を参照してください。 - `ResponseState`​: アップストリームのレスポンスヘッダーとレスポンスボディを操作するための、要求検索条件のさまざまなフェーズへのアクセスを提供します。 `ResponseState`​ は ​`on_response`​ 関数でのみ使用できます。​`ResponseState`​ のヘッダーとボディの読み取りと書き込みについては、[リクエストヘッダーとリクエストボディの読み取りと書き込み](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-headers)を参照してください。 - `RequestData`​: `on_request`​ 関数と ​`on_response`​ 関数の間でデータを共有します。 `RequestData`​ は ​`on_response`​ 関数でのみ使用できます。​`RequestData`​ の詳細については、[要求と応答でのデータの共有](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-share-data)を参照してください。 - `Authentication`​: 認証データの読み取りまたは他のポリシーとの共有のためのアクセスを提供します。​`Authentication`​ の詳細については、[要求認証情報へのアクセス](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-authentication)を参照してください。 ラップされた関数がこれらのパラメーターを受け取るだけであれば、ラッパーにラムダは必要ありません。たとえば、関数のシグネチャーが次のように定義されているとします。 ```Rust async fn request_filter(state: RequestState) -> RequestData; async fn response_filter(state: ResponseState, path: RequestData); ``` 次の例では、関数定義のラムダを定義しています。 ```Rust let filter = on_request(|request_state| request_filter(request_state)) .on_response(|response_state, request_data| response_filter(response_state, request_data)); ``` ラムダを定義する代わりに、次の関数定義を使うことができます。 ```Rust let filter = on_request(request_filter) .on_response(response_filter); ``` ラップされた関数が、他のパラメーター (​`#[entrypoint]`​ 関数で定義された設定パラメーターなど) を必要とする場合は、そのパラメーターをラップされた関数に挿入します。パラメーターを渡すには、ラムダを定義して変数参照を送信します。例: ```Rust async fn request_filter(state: RequestState, conf: &Config, tuple: &(u32, u32)) { ... } #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration) -> Result<()> { let config = serde_json::from_slice(&bytes)?; let tuple: (u32, u32) = (10, 10); let filter = on_request(|request_state| request_filter(request_state, &config, &tuple)); launcher .launch(filter) .await?; Ok(()) } ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features) # パラメーターの挿入 Flex Gateway ポリシー開発キット (PDK) は、​`#[entrypoint]`​ 設定関数に挿入できる以下のパラメーターを提供します。 - `Configuration`​: ポリシーの設定パラメーターを提供します。設定パラメーターの定義方法については、[ポリシースキーマ定義の作成](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-create-schema-definition)を参照してください。 - `Metadata`​: ポリシー、Flex Gateway インスタンス、API インスタンス、および Anypoint 組織に関するメタデータを提供します。提供されるメタデータの詳細については、[ポリシーのメタデータへのアクセス](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-metadata)を参照してください。 - `HttpClient`​: ポリシーで HTTP コールを有効にします。ポリシーから HTTP コールを実行する方法の詳細については、[HTTP コールの実行](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-http-request)を参照してください。 - `CacheBuilder`​: ポリシーのキャッシュ機能を提供します。キャッシュの詳細については、[ワーカー間でのデータ共有とキャッシュの設定](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-caching)を参照してください。 - `StreamProperties`​: 同じ要求を処理する他のポリシーとプロパティを共有するための構造体を提供します。ポリシー間の情報共有の詳細については、[ポリシー間のデータ共有](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-streamproperties)を参照してください。 - `` PolicyViolations` ``​: ダッシュボードの監視に関するポリシー違反をレポートするメカニズムを提供します。ポリシー違反についての詳細、[ポリシー違反のレポート](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-violations)を参照してください。 また、​`HttpClient`​ および ​`StreamProperties`​ パラメーターをラップされた関数の ​`on_request`​ または ​`on_response`​ に直接挿入することもできます。たとえば、​`on_request`​ 関数の内部で HTTP コールを実行する必要がある場合は、​`HTTPClient`​ をその関数に直接挿入します。 ベストプラクティスとして、パラメーターは必ず使用する場所にのみ挿入するようにしてください。ただし、ポリシーの適用時に一度だけ実行する初期化ステップがパラメーターに必要な場合は、ラップされた関数のパフォーマンスを向上させるために、パラメーターを ​`#[entrypoint]`​ に挿入して設定ステップを完了させるのが最善です。 ## [](#ラップされた関数の-on_request-と-on_response-へのパラメーターの挿入)ラップされた関数の on\_request と on\_response へのパラメーターの挿入 ラップされた関数は以下のパラメーターを受け入れます。 - `HttpClient`​: ポリシーで HTTP コールを有効にします。ポリシーから HTTP コールを実行する方法の詳細については、[HTTP コールの実行](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-http-request)を参照してください。 - `StreamProperties`​: 同じ要求を処理する他のポリシーとプロパティを共有するための構造体を提供します。ポリシー間の情報共有の詳細については、[ポリシー間のデータ共有](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-streamproperties)を参照してください。 - `RequestState`​: 受信したリクエストヘッダーとリクエストボディを操作するための、要求検索条件のさまざまなフェーズへのアクセスを提供します。 `RequestState`​ は ​`on_request`​ 関数でのみ使用できます。​`RequestState`​ のヘッダーとボディの読み取りと書き込みについては、[リクエストヘッダーとリクエストボディの読み取りと書き込み](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-headers)を参照してください。 - `ResponseState`​: アップストリームのレスポンスヘッダーとレスポンスボディを操作するための、要求検索条件のさまざまなフェーズへのアクセスを提供します。 `ResponseState`​ は ​`on_response`​ 関数でのみ使用できます。​`ResponseState`​ のヘッダーとボディの読み取りと書き込みについては、[リクエストヘッダーとリクエストボディの読み取りと書き込み](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-headers)を参照してください。 - `RequestData`​: `on_request`​ 関数と ​`on_response`​ 関数の間でデータを共有します。 `RequestData`​ は ​`on_response`​ 関数でのみ使用できます。​`RequestData`​ の詳細については、[要求と応答でのデータの共有](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-share-data)を参照してください。 - `Authentication`​: 認証データの読み取りまたは他のポリシーとの共有のためのアクセスを提供します。​`Authentication`​ の詳細については、[要求認証情報へのアクセス](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-authentication)を参照してください。 ラップされた関数がこれらのパラメーターを受け取るだけであれば、ラッパーにラムダは必要ありません。たとえば、関数のシグネチャーが次のように定義されているとします。 ```Rust async fn request_filter(state: RequestState) -> RequestData; async fn response_filter(state: ResponseState, path: RequestData); ``` 次の例では、関数定義のラムダを定義しています。 ```Rust let filter = on_request(|request_state| request_filter(request_state)) .on_response(|response_state, request_data| response_filter(response_state, request_data)); ``` ラムダを定義する代わりに、次の関数定義を使うことができます。 ```Rust let filter = on_request(request_filter) .on_response(response_filter); ``` ラップされた関数が、他のパラメーター (​`#[entrypoint]`​ 関数で定義された設定パラメーターなど) を必要とする場合は、そのパラメーターをラップされた関数に挿入します。パラメーターを渡すには、ラムダを定義して変数参照を送信します。例: ```Rust async fn request_filter(state: RequestState, conf: &Config, tuple: &(u32, u32)) { ... } #[entrypoint] async fn configure(launcher: Launcher, Configuration(bytes): Configuration) -> Result<()> { let config = serde_json::from_slice(&bytes)?; let tuple: (u32, u32) = (10, 10); let filter = on_request(|request_state| request_filter(request_state, &config, &tuple)); launcher .launch(filter) .await?; Ok(()) } ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features) # ポリシースキーマ定義の作成 [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.2/_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`​ のどちらかに定義することで、ペイロードの読み取り方法を設定します。デフォルトでは、​`mimeType`​ は ​`text`​ に設定されます。​`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.2/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.2/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.2/policies-pdk-troubleshooting) # ポリシースキーマ定義の作成 [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.3/_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`​ のどちらかに定義することで、ペイロードの読み取り方法を設定します。デフォルトでは、​`mimeType`​ は ​`text`​ に設定されます。​`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.3/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.3/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.3/policies-pdk-troubleshooting) # ポリシースキーマ定義の作成 [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) # ポリシーのメタデータへのアクセス PDK は、ポリシー、Flex インスタンス、API インスタンス、および Anypoint Organization に関するメタデータを提供する ​`Metadata`​ Injectable を提供します。​`Metadata`​ 構造体は次のようになります。 ```Rust pub struct Metadata { pub flex_metadata: FlexMetadata, pub policy_metadata: PolicyMetadata, pub api_metadata: ApiMetadata, pub platform_metadata: PlatformMetadata, } ``` `Metadata`​ 構造体は、以下の構造体を参照しています。 - `FlexMetadata`​: ```Rust pub struct FlexMetadata { pub flex_name: String, pub flex_version: String, } ``` - `PolicyMetadata`​: ```Rust pub struct PolicyMetadata { pub policy_name: String, pub policy_namespace: String, } ``` - `ApiMetadata`​: ```Rust pub struct ApiMetadata { pub id: Option, pub name: Option, pub version: Option, pub slas: Option>, // API SLA tiers in the platform } // Each ApiSla contains the limits for each SLA. pub struct ApiSla { pub id: String, pub tiers: Vec, // Limits within an API SLA tier in the platform } ``` - `PlatformMetadata`​: ```Rust pub struct PlatformMetadata { pub organization_id: String, pub environment_id: String, pub root_organization_id: String, } ``` ## [](#entrypoint-へのメタデータの挿入)#\[entrypoint\] へのメタデータの挿入 メタデータを ​`#[entrypoint]`​ 設定関数に挿入するには、以下のコードスニペットを参照してください。 ```Rust #[entrypoint] async fn configure(launcher: Launcher, metadata: Metadata) -> Result<()> { logger::info!("Flex instance name is: {}", metadata.flex_metadata.flex_name.to_string()); launcher .launch(on_request(filter)) .await?; Ok(()) } ``` ## [](#ラップされた関数へのメタデータの挿入)ラップされた関数へのメタデータの挿入 ラップされた関数にメタデータを直接挿入することはできません。ラップされた関数でメタデータを使用するには、まず ​`#[entrypoint]`​ 関数にデータを挿入してから、ラップされた関数にデータを挿入します。 ```Rust #[entrypoint] async fn configure(launcher: Launcher, metadata: Metadata) -> Result<()> { launcher .launch(on_request(|r| request_filter(r, &metadata))) .await?; Ok(()) } async fn request_filter(_: RequestState, metadata: &Metadata) -> Flow<()> { let mut vec = Vec::new(); let headers = &mut vec; headers.push(( "flex_name".to_string(), metadata.flex_metadata.flex_name.to_string(), )); headers.push(( "policy_name".to_string(), metadata.policy_metadata.policy_name.to_string(), )); Flow::Break(Response::new(201).with_headers(vec)) } ``` ## [](#関連情報)関連情報 - [パラメーターの挿入](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-inject-parameters) # ポリシーのメタデータへのアクセス PDK は、ポリシー、Flex インスタンス、API インスタンス、および Anypoint Organization に関するメタデータを提供する ​`Metadata`​ Injectable を提供します。​`Metadata`​ 構造体は次のようになります。 ```Rust pub struct Metadata { pub flex_metadata: FlexMetadata, pub policy_metadata: PolicyMetadata, pub api_metadata: ApiMetadata, pub platform_metadata: PlatformMetadata, } ``` `Metadata`​ 構造体は、以下の構造体を参照しています。 - `FlexMetadata`​: ```Rust pub struct FlexMetadata { pub flex_name: String, pub flex_version: String, } ``` - `PolicyMetadata`​: ```Rust pub struct PolicyMetadata { pub policy_name: String, pub policy_namespace: String, } ``` - `ApiMetadata`​: ```Rust pub struct ApiMetadata { pub id: Option, pub name: Option, pub version: Option, pub slas: Option>, // API SLA tiers in the platform } // Each ApiSla contains the limits for each SLA. pub struct ApiSla { pub id: String, pub tiers: Vec, // Limits within an API SLA tier in the platform } ``` - `PlatformMetadata`​: ```Rust pub struct PlatformMetadata { pub organization_id: String, pub environment_id: String, pub root_organization_id: String, } ``` ## [](#entrypoint-へのメタデータの挿入)#\[entrypoint\] へのメタデータの挿入 メタデータを ​`#[entrypoint]`​ 設定関数に挿入するには、以下のコードスニペットを参照してください。 ```Rust #[entrypoint] async fn configure(launcher: Launcher, metadata: Metadata) -> Result<()> { logger::info!("Flex instance name is: {}", metadata.flex_metadata.flex_name.to_string()); launcher .launch(on_request(filter)) .await?; Ok(()) } ``` ## [](#ラップされた関数へのメタデータの挿入)ラップされた関数へのメタデータの挿入 ラップされた関数にメタデータを直接挿入することはできません。ラップされた関数でメタデータを使用するには、まず ​`#[entrypoint]`​ 関数にデータを挿入してから、ラップされた関数にデータを挿入します。 ```Rust #[entrypoint] async fn configure(launcher: Launcher, metadata: Metadata) -> Result<()> { launcher .launch(on_request(|r| request_filter(r, &metadata))) .await?; Ok(()) } async fn request_filter(_: RequestState, metadata: &Metadata) -> Flow<()> { let mut vec = Vec::new(); let headers = &mut vec; headers.push(( "flex_name".to_string(), metadata.flex_metadata.flex_name.to_string(), )); headers.push(( "policy_name".to_string(), metadata.policy_metadata.policy_name.to_string(), )); Flow::Break(Response::new(201).with_headers(vec)) } ``` ## [](#関連情報)関連情報 - [パラメーターの挿入](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-inject-parameters) # ポリシーのメタデータへのアクセス PDK は、ポリシー、Flex インスタンス、API インスタンス、および Anypoint Organization に関するメタデータを提供する ​`Metadata`​ Injectable を提供します。​`Metadata`​ 構造体は次のようになります。 ```Rust pub struct Metadata { pub flex_metadata: FlexMetadata, pub policy_metadata: PolicyMetadata, pub api_metadata: ApiMetadata, pub platform_metadata: PlatformMetadata, } ``` `Metadata`​ 構造体は、以下の構造体を参照しています。 - `FlexMetadata`​: ```Rust pub struct FlexMetadata { pub flex_name: String, pub flex_version: String, } ``` - `PolicyMetadata`​: ```Rust pub struct PolicyMetadata { pub policy_name: String, pub policy_namespace: String, } ``` - `ApiMetadata`​: ```Rust pub struct ApiMetadata { pub id: Option, pub name: Option, pub version: Option, pub slas: Option>, // API SLA tiers in the platform } // Each ApiSla contains the limits for each SLA. pub struct ApiSla { pub id: String, pub tiers: Vec, // Limits within an API SLA tier in the platform } ``` - `PlatformMetadata`​: ```Rust pub struct PlatformMetadata { pub organization_id: String, pub environment_id: String, pub root_organization_id: String, } ``` ## [](#entrypoint-へのメタデータの挿入)#\[entrypoint\] へのメタデータの挿入 メタデータを ​`#[entrypoint]`​ 設定関数に挿入するには、以下のコードスニペットを参照してください。 ```Rust #[entrypoint] async fn configure(launcher: Launcher, metadata: Metadata) -> Result<()> { logger::info!("Flex instance name is: {}", metadata.flex_metadata.flex_name.to_string()); launcher .launch(on_request(filter)) .await?; Ok(()) } ``` ## [](#ラップされた関数へのメタデータの挿入)ラップされた関数へのメタデータの挿入 ラップされた関数にメタデータを直接挿入することはできません。ラップされた関数でメタデータを使用するには、まず ​`#[entrypoint]`​ 関数にデータを挿入してから、ラップされた関数にデータを挿入します。 ```Rust #[entrypoint] async fn configure(launcher: Launcher, metadata: Metadata) -> Result<()> { launcher .launch(on_request(|r| request_filter(r, &metadata))) .await?; Ok(()) } async fn request_filter(_: RequestState, metadata: &Metadata) -> Flow<()> { let mut vec = Vec::new(); let headers = &mut vec; headers.push(( "flex_name".to_string(), metadata.flex_metadata.flex_name.to_string(), )); headers.push(( "policy_name".to_string(), metadata.policy_metadata.policy_name.to_string(), )); Flow::Break(Response::new(201).with_headers(vec)) } ``` ## [](#関連情報)関連情報 - [パラメーターの挿入](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-inject-parameters) # ポリシーログの設定 Flex Gateway ポリシー開発キット (PDK) は、API インスタンス ID、ポリシー ID、要求 ID を含むログメッセージを生成するログメカニズムを提供します。 `Pdk::logger;`​ パッケージを使用して、以下のマクロでカスタムログを挿入します。 - `logger::debug!` - `logger::info!` - `logger::warn!` - `logger::error!` マクロは [Rust std::format! macro](https://doc.rust-lang.org/std/macro.format.html)​ と同じ動作をします。最初のパラメーターは形式文字列リテラルである必要があります。リテラルでは ​`{}`​ を使用してパラメーターを渡します。例: ```Rust use pdk::logger; // [...] let value = "there!"; logger::debug!("Hello there!"); logger::info!("Hello {}", value); logger::warn!("Hello {value}"); logger::error!("Hello {}", "there!"); ``` すべての例は、次の形式で Flex Gateway のログに表示されます。 \[flex-gateway-envoy\]\[\] wasm log . main: \[policy: \]\[api: \]\[req: \] Hello there! Flex Gateway ログの表示に関する詳細は、[Monitoring Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-monitor)を参照してください。 # ポリシーログの設定 Flex Gateway ポリシー開発キット (PDK) は、API インスタンス ID、ポリシー ID、要求 ID を含むログメッセージを生成するログメカニズムを提供します。 `Pdk::logger;`​ パッケージを使用して、以下のマクロでカスタムログを挿入します。 - `logger::debug!` - `logger::info!` - `logger::warn!` - `logger::error!` マクロは [Rust std::format! macro](https://doc.rust-lang.org/std/macro.format.html)​ と同じ動作をします。最初のパラメーターは形式文字列リテラルである必要があります。リテラルでは ​`{}`​ を使用してパラメーターを渡します。例: ```Rust use pdk::logger; // [...] let value = "there!"; logger::debug!("Hello there!"); logger::info!("Hello {}", value); logger::warn!("Hello {value}"); logger::error!("Hello {}", "there!"); ``` すべての例は、次の形式で Flex Gateway のログに表示されます。 \[flex-gateway-envoy\]\[\] wasm log . main: \[policy: \]\[api: \]\[req: \] Hello there! Flex Gateway ログの表示に関する詳細は、[Monitoring Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-monitor)を参照してください。 # ポリシーログの設定 Flex Gateway ポリシー開発キット (PDK) は、API インスタンス ID、ポリシー ID、要求 ID を含むログメッセージを生成するログメカニズムを提供します。 `Pdk::logger;`​ パッケージを使用して、以下のマクロでカスタムログを挿入します。 - `logger::debug!` - `logger::info!` - `logger::warn!` - `logger::error!` マクロは [Rust std::format! macro](https://doc.rust-lang.org/std/macro.format.html)​ と同じ動作をします。最初のパラメーターは形式文字列リテラルである必要があります。リテラルでは ​`{}`​ を使用してパラメーターを渡します。例: ```Rust use pdk::logger; // [...] let value = "there!"; logger::debug!("Hello there!"); logger::info!("Hello {}", value); logger::warn!("Hello {value}"); logger::error!("Hello {}", "there!"); ``` すべての例は、次の形式で Flex Gateway のログに表示されます。 \[flex-gateway-envoy\]\[\] wasm log . main: \[policy: \]\[api: \]\[req: \] Hello there! Flex Gateway ログの表示に関する詳細は、[Monitoring Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-monitor)を参照してください。 # ポリシー違反のレポート
ポリシー違反のレポートの例については、 「Stream Payload Policy (ストリームペイロードポリシーの収集)」​を参照してください。
PDK には、ポリシー違反をレポートする関数があります。レポートされたポリシー違反は、Anypoint Monitoring に表示されます。 要求に対して一度に 1 つのポリシー違反のみがアクティブになります。新しい違反が発生すると、既存の違反が上書きされます。複数のポリシーで 1 つの要求の違反が生成されても、Anypoint Monitoring には 1 つの違反のみが表示されます。 ポリシー違反がレポートされても、要求は拒否されません。要求を拒否するには、[要求実行の停止](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-stop)を参照してください。 現在のポリシー違反を表示したり、新しいポリシー違反を生成するには、次の PDK 関数を使用します。 ```Rust /// Returns the existing policy violation of the current request. Returns None if no violation exists. pub fn policy_violation(&self) -> Option; /// Generates a new policy violation for the current request. If a violation was previously generated, the previous violation is overridden. pub fn generate_policy_violation(&self); /// Generates a new policy violation with the client application details for the current request. This overwrites any previous policy violations. pub fn generate_policy_violation_for_client_app, K: Into>( &self, client_name: T, client_id: K, ); ``` 現在のポリシー違反に関する情報を取得するには、次の PDK 関数を使用します。 ```Rust /// The name of the policy that generated the violation pub fn get_policy_name(&self) -> &str; /// Client name associated with the violation, only available if a previous policy reported the client ID pub fn get_client_name(&self) -> Option<&str>; /// Client ID associated with the violation, only available if a previous policy reported the client ID pub fn get_client_id(&self) -> Option<&str>; ``` ## [](#関連情報)関連情報 - [パラメーターの挿入](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-inject-parameters) # ポリシー開発キットのアーキテクチャの概要 Flex Gateway ポリシー開発キット (PDK) は次のコンポーネントから構成されています。 - [\[anypoint-cli-pdk-plugin\]](#anypoint-cli-pdk-plugin)​: ポリシーを生成して Exchange に配布する - [\[policy-template\]](#policy-template)​: 新しいカスタムポリシーをスキャフォールディングする - [SDK ビルドツール](#sdk-building-tools)​: 開発プロセスを簡素化する ## [](#anypoint-cli-pdk-プラグイン)Anypoint CLI PDK プラグイン Anypoint CLI PDK プラグインは PDK プロジェクトを作成し、ポリシーアセットを Exchange にアップロードします (接続モードのみ)。プロジェクトの作成後、PDK は以降のすべての開発ステップを完了するための簡易コマンドセットを ​`Makefile`​ で提供します。 ## [](#ポリシーテンプレート)ポリシーテンプレート PDK はポリシーを作成する際に、いくつかの簡易スキャフォールディングを生成します。 生成されたすべてのファイルには、ポリシーを適切にコンパイルするために必要な情報が含まれています。 内部についての詳細は、​[「プロジェクト構造」](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-create-project#project-structure)​を参照してください。 ## [](#sdk-ビルドツール)SDK ビルドツール Flex Gateway は Envoy 上に構築されており、開発されるポリシーは、イベント駆動型の [proxy-wasm](https://github.com/proxy-wasm/spec)​ アーキテクチャとの互換性を持っている必要があります。 `proxy-wasm`​ のイベント駆動型アーキテクチャでは、1 つの要求を処理するさまざまなイベントをユーザーが管理する必要があります。そのため、次のような問題が生じ、イベント駆動型コードの開発や保守にコストがかかってしまいます。 - ビジネスロジックとエントリポイントの結合によるコードの複雑化 - 共通のロジックをモジュール化できないことに起因するモノリシックなコード - 関数のコールバックとエラー伝搬を困難にする、冗長な非線形の制御フロー PDK は、Reactor パターンと Executor パターンを使用することで、イベント指向のコーディングアプローチを抽象化するビルドツールを提供します。PDK は開発者に、受信要求をリニア方式でコーディングする方法を提供することで、以下を実現します。 - 正しくないコンテキストでのメソッドの使用によるコンパイルエラーやランタイムエラーを減少 - 学習曲線を短縮 - コールスタックの最小化によりデバッグ性を向上 - コードの重複を削減 - パラメーターインジェクションを改善 - 動的メモリの使用を削減し、不確定性とカスタムメモリ管理の必要性を低減 ## [](#関連情報)関連情報 - [PDK の前提条件の確認](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-prerequisites) # ポリシー開発キットのアーキテクチャの概要 Flex Gateway ポリシー開発キット (PDK) は次のコンポーネントから構成されています。 - [\[anypoint-cli-pdk-plugin\]](#anypoint-cli-pdk-plugin)​: ポリシーを生成して Exchange に配布する - [\[policy-template\]](#policy-template)​: 新しいカスタムポリシーをスキャフォールディングする - [SDK ビルドツール](#sdk-building-tools)​: 開発プロセスを簡素化する ## [](#anypoint-cli-pdk-プラグイン)Anypoint CLI PDK プラグイン Anypoint CLI PDK プラグインは PDK プロジェクトを作成し、ポリシーアセットを Exchange にアップロードします (接続モードのみ)。プロジェクトの作成後、PDK は以降のすべての開発ステップを完了するための簡易コマンドセットを ​`Makefile`​ で提供します。 ## [](#ポリシーテンプレート)ポリシーテンプレート PDK はポリシーを作成する際に、いくつかの簡易スキャフォールディングを生成します。 生成されたすべてのファイルには、ポリシーを適切にコンパイルするために必要な情報が含まれています。 内部についての詳細は、​[「プロジェクト構造」](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-create-project#project-structure)​を参照してください。 ## [](#sdk-ビルドツール)SDK ビルドツール Flex Gateway は Envoy 上に構築されており、開発されるポリシーは、イベント駆動型の [proxy-wasm](https://github.com/proxy-wasm/spec)​ アーキテクチャとの互換性を持っている必要があります。 `proxy-wasm`​ のイベント駆動型アーキテクチャでは、1 つの要求を処理するさまざまなイベントをユーザーが管理する必要があります。そのため、次のような問題が生じ、イベント駆動型コードの開発や保守にコストがかかってしまいます。 - ビジネスロジックとエントリポイントの結合によるコードの複雑化 - 共通のロジックをモジュール化できないことに起因するモノリシックなコード - 関数のコールバックとエラー伝搬を困難にする、冗長な非線形の制御フロー PDK は、Reactor パターンと Executor パターンを使用することで、イベント指向のコーディングアプローチを抽象化するビルドツールを提供します。PDK は開発者に、受信要求をリニア方式でコーディングする方法を提供することで、以下を実現します。 - 正しくないコンテキストでのメソッドの使用によるコンパイルエラーやランタイムエラーを減少 - 学習曲線を短縮 - コールスタックの最小化によりデバッグ性を向上 - コードの重複を削減 - パラメーターインジェクションを改善 - 動的メモリの使用を削減し、不確定性とカスタムメモリ管理の必要性を低減 ## [](#関連情報)関連情報 - [Flex Gateway ポリシー開発キット (PDK) の前提条件](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-prerequisites) # ポリシー開発キットのアーキテクチャの概要 Flex Gateway ポリシー開発キット (PDK) は次のコンポーネントから構成されています。 - [\[anypoint-cli-pdk-plugin\]](#anypoint-cli-pdk-plugin)​: ポリシーを生成して Exchange に配布する - [\[policy-template\]](#policy-template)​: 新しいカスタムポリシーをスキャフォールディングする - [SDK ビルドツール](#sdk-building-tools)​: 開発プロセスを簡素化する ## [](#anypoint-cli-pdk-プラグイン)Anypoint CLI PDK プラグイン Anypoint CLI PDK プラグインは PDK プロジェクトを作成し、ポリシーアセットを Exchange にアップロードします (接続モードのみ)。プロジェクトの作成後、PDK は以降のすべての開発ステップを完了するための簡易コマンドセットを ​`Makefile`​ で提供します。 ## [](#ポリシーテンプレート)ポリシーテンプレート PDK はポリシーを作成する際に、いくつかの簡易スキャフォールディングを生成します。 生成されたすべてのファイルには、ポリシーを適切にコンパイルするために必要な情報が含まれています。 内部についての詳細は、​[「プロジェクト構造」](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-create-project#project-structure)​を参照してください。 ## [](#sdk-ビルドツール)SDK ビルドツール Flex Gateway は Envoy 上に構築されており、開発されるポリシーは、イベント駆動型の [proxy-wasm](https://github.com/proxy-wasm/spec)​ アーキテクチャとの互換性を持っている必要があります。 `proxy-wasm`​ のイベント駆動型アーキテクチャでは、1 つの要求を処理するさまざまなイベントをユーザーが管理する必要があります。そのため、次のような問題が生じ、イベント駆動型コードの開発や保守にコストがかかってしまいます。 - ビジネスロジックとエントリポイントの結合によるコードの複雑化 - 共通のロジックをモジュール化できないことに起因するモノリシックなコード - 関数のコールバックとエラー伝搬を困難にする、冗長な非線形の制御フロー PDK は、Reactor パターンと Executor パターンを使用することで、イベント指向のコーディングアプローチを抽象化するビルドツールを提供します。PDK は開発者に、受信要求をリニア方式でコーディングする方法を提供することで、以下を実現します。 - 正しくないコンテキストでのメソッドの使用によるコンパイルエラーやランタイムエラーを減少 - 学習曲線を短縮 - コールスタックの最小化によりデバッグ性を向上 - コードの重複を削減 - パラメーターインジェクションを改善 - 動的メモリの使用を削減し、不確定性とカスタムメモリ管理の必要性を低減 ## [](#関連情報)関連情報 - [Flex Gateway ポリシー開発キット (PDK) の前提条件](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-prerequisites) # ポリシー間のデータ共有 `StreamProperties`​ Injectable は、以下の目的のインターフェースを提供しています。 - 同じ要求を処理している他のポリシーによって設定されたプロパティをコンシュームする。 - プロパティをブロードキャストして、他のポリシーがコンシュームできるようにする。 データを共有するためには、​`StreamProperties`​ で ​`PropertyAccessor`​ trait を実装します。 ```Rust pub trait PropertyAccessor { fn read_property(&self, path: &[&str]) -> Option; fn set_property(&self, path: &[&str], value: Option<&[u8]>); } ``` 次の例は、ストリームからプロパティを読み取り、別のパラメーターを書き込む単純な検索条件を示しています。 ```Rust async fn request_filter(stream: StreamProperties) -> Flow<()> { let incoming = String::from_utf8(stream.read_property(&["incoming_property"]).unwrap_or_default()).unwrap_or_default(); logger::info!("Recieved incoming prop {}", incoming); let outgoing = "outgoing".as_bytes(); stream.set_property(&["outgoing_property"], Some(outgoing)); Flow::Continue(()) } #[entrypoint] async fn configure(launcher: Launcher) -> Result<()> { let filter = on_request(|stream| request_filter(stream)); launcher.launch(filter).await?; Ok(()) } ``` ## [](#関連情報)関連情報 - [パラメーターの挿入](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-inject-parameters) # ポリシー間のデータ共有 `StreamProperties`​ Injectable は、以下の目的のインターフェースを提供しています。 - 同じ要求を処理している他のポリシーによって設定されたプロパティをコンシュームする。 - プロパティをブロードキャストして、他のポリシーがコンシュームできるようにする。 データを共有するためには、​`StreamProperties`​ で ​`PropertyAccessor`​ trait を実装します。 ```Rust pub trait PropertyAccessor { fn read_property(&self, path: &[&str]) -> Option; fn set_property(&self, path: &[&str], value: Option<&[u8]>); } ``` 次の例は、ストリームからプロパティを読み取り、別のパラメーターを書き込む単純な検索条件を示しています。 ```Rust async fn request_filter(stream: StreamProperties) -> Flow<()> { let incoming = String::from_utf8(stream.read_property(&["incoming_property"]).unwrap_or_default()).unwrap_or_default(); logger::info!("Recieved incoming prop {}", incoming); let outgoing = "outgoing".as_bytes(); stream.set_property(&["outgoing_property"], Some(outgoing)); Flow::Continue(()) } #[entrypoint] async fn configure(launcher: Launcher) -> Result<()> { let filter = on_request(|stream| request_filter(stream)); launcher.launch(filter).await?; Ok(()) } ``` ## [](#関連情報)関連情報 - [パラメーターの挿入](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-inject-parameters) # ポリシー間のデータ共有 `StreamProperties`​ Injectable は、以下の目的のインターフェースを提供しています。 - 同じ要求を処理している他のポリシーによって設定されたプロパティをコンシュームする。 - プロパティをブロードキャストして、他のポリシーがコンシュームできるようにする。 データを共有するためには、​`StreamProperties`​ で ​`PropertyAccessor`​ trait を実装します。 ```Rust pub trait PropertyAccessor { fn read_property(&self, path: &[&str]) -> Option; fn set_property(&self, path: &[&str], value: Option<&[u8]>); } ``` 次の例は、ストリームからプロパティを読み取り、別のパラメーターを書き込む単純な検索条件を示しています。 ```Rust async fn request_filter(stream: StreamProperties) -> Flow<()> { let incoming = String::from_utf8(stream.read_property(&["incoming_property"]).unwrap_or_default()).unwrap_or_default(); logger::info!("Recieved incoming prop {}", incoming); let outgoing = "outgoing".as_bytes(); stream.set_property(&["outgoing_property"], Some(outgoing)); Flow::Continue(()) } #[entrypoint] async fn configure(launcher: Launcher) -> Result<()> { let filter = on_request(|stream| request_filter(stream)); launcher.launch(filter).await?; Ok(()) } ``` ## [](#関連情報)関連情報 - [パラメーターの挿入](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-inject-parameters) # リクエストヘッダーとリクエストボディの読み取りと書き込み Flex Gateway ポリシー開発キット (PDK) を使用すると、リクエスト/レスポンスヘッダーおよびボディの読み取りと書き込みを行うことができます。 ## [](#event-flow)イベントフロー 要求および応答を絞り込むときに、Proxy Wasm はヘッダーとボディの処理を必ず特定の順序で発生する 2 つのメインイベントに分割します。ポリシーでボディを処理する前に、すべてのポリシーでヘッダーイベントが完全に伝播されている必要があります。たとえば、2 つのポリシーが適用される API のイベントフローは次のようになります。 1. ポリシー 1 はリクエストヘッダーイベントを処理します。 2. ポリシー 2 はリクエストヘッダーイベントを処理します。 3. バックエンドサービスはリクエストヘッダーを受信します。 4. ポリシー 1 はリクエストボディイベントを処理します。 5. ポリシー 2 はリクエストボディイベントを処理します。 6. バックエンドはリクエストボディを受信します。 7. バックエンドは応答を送信します。 8. ポリシー 2 はレスポンスヘッダーイベントを処理します。 9. ポリシー 1 はレスポンスヘッダーイベントを処理します。 10. クライアントはレスポンスヘッダーを受信します。 11. ポリシー 2 はレスポンスボディイベントを処理します。 12. ポリシー 1 はレスポンスボディイベントを処理します。 13. クライアントはレスポンスボディを受信します。 この順序では、次の制限が生じます。 - ポリシーはボディを読み取った後にヘッダーを変更できない。 - すべてのポリシーはボディを読み取る前にヘッダーイベントを完全に処理する必要がある。ボディのデータをあるポリシーに保存し、別のポリシーのボディデータを使用してヘッダーを変更することはできません。 - すべてのポリシーはヘッダーイベントを処理するときにバックエンドサービスに到達する。拒否された要求からのデータがバックエンドサービスに到達しないようにするには、リクエストヘッダーのみに基づいてヘッダーを拒否する必要があります。ボディに基づいて要求を拒否すると、大部分のサーバーおよびクライアントは中断された要求を検出して、リクエストヘッダーを破棄できます。 ポリシーソースコードでボディを読み取ると、ヘッダーとボディのイベントが分割されます。たとえば、ボディを読み取るために宣言 ​`let body_state = headers_state.into_body_state().await;`​ が使用されている場合、宣言前のすべてがヘッダーイベントで発生し、宣言後のすべてがボディイベントで発生します。 ## [](#read-and-write-headers)リクエストヘッダーの読み取りと書き込み リクエストヘッダーとレスポンスヘッダーの両方にアクセスするには、​`into_headers_state()`​ メソッドを呼び出して、​`RequestState`​ または ​`ResponseState`​ をヘッダー状態に変換して、処理が完了するのを待ちます。メソッドを呼び出したら、​`HeadersHandler`​ trait の関数を呼び出してヘッダーにアクセスして操作します。 ```Rust pub trait HeadersHandler { fn headers(&self) -> Vec<(String, String)>; fn header(&self, name: &str) -> Option; fn add_header(&self, name: &str, value: &str); fn set_header(&self, name: &str, value: &str); fn set_headers(&self, headers: Vec<(&str, &str)>); fn remove_header(&self, name: &str); } ``` 以下のコードを実装することで、ラップされた関数の ​`on_request`​ または ​`on_response`​ でヘッダーにアクセスすることができます。 ```Rust async fn request_filter(request_state: RequestState, _config: &Config) { let headers_state = request_state.into_headers_state().await; let headers_handler = headers_state.handler(); let old_value = headers_handler.header("request-header").unwrap_or_default(); let new_value = "--replaced--"; logger::info!("Old request header value: {old_value}, New value: {new_value}"); headers_handler.set_header("request-header", new_value); } async fn response_filter(response_state: ResponseState, _config: &Config) { let headers_state = response_state.into_headers_state().await; let headers_handler = headers_state.handler(); let old_headers = headers_handler.header("request-header").unwrap_or_default(); let new_headers = vec![("response-header1", "--replaced--"), ("response-header2", "--replaced--")]; logger::info!("Old request header value: {old_headers:?}, New value: {new_headers:?}"); headers_handler.set_headers(new_headers); } ``` Envoy はメソッド、スキーム、パス、承認、状況コードをヘッダーとして扱います。PDK は要求の Envoy ヘッダーである ​`:method`​、​`:scheme`​、​`:path`​、​`:authority`​、​`:status`​ にアクセスして変更するために以下のメソッドを提供しています。 ```Rust async fn request_filter(request_state: RequestState, _config: &Config) { let headers_state = request_state.into_headers_state().await; let method = headers_state.method(); let scheme = headers_state.scheme(); let authority = headers_state.authority(); let path = headers_state.path(); ... } async fn response_filter(response_state: ResponseState, _config: &Config) { let headers_state = response_state.into_headers_state().await; let status = headers_state.status_code(); } ``` ## [](#read-and-write-request-bodies)リクエストボディの読み取りと書き込み
ボディの読み取りと書き込みのペイロードサイズは 1MB 未満に制限されています。
リクエストボディとレスポンスボディの両方にアクセスするには、​`into_body_state()`​ メソッドを呼び出して、​`RequestState`​ または ​`ResponseState`​ をボディ状態に変換して、処理が完了するのを待ちます。 ```Rust let body_state = request_state.into_body_state().await; ```
前の ​.await​ は、キャンセルポイントになります。要求中に​フローがキャンセル​されると、​.await​ が再開されない可能性があります。
元の状態がすでにヘッダー状態に変換されている場合は、同じ関数を呼び出してボディ状態に変換します。例: ```Rust let headers_state = request_state.into_headers_state().await; let body_state = headers_state.into_body_state().await; ``` `into_body_state()`​ を呼び出したら、​`BodyHandler`​ trait の関数を呼び出してヘッダーにアクセスして操作します。 ```Rust pub trait BodyHandler { fn body(&self) -> Vec; fn set_body(&self, body: &[u8]) -> Result<(), BodyError>; } ``` Envoy はヘッダーとボディのデータを共有するために同じバッファを使用するため、ポリシーはヘッダーとボディに同時にアクセスすることはできません。もしポリシーが両方を読み取る必要がある場合は、次の手順に従ってください。 1. ヘッダーを読み取り、必要な値を変数に保存します。 2. ボディを読み取ります。 応答と要求の両方で、ヘッダーとボディを読み取ることができます。ただし、ボディを読み取った後でヘッダーを変更することはできません。ボディを読み取る前にすべてのヘッダーの修正を完了してください。例: ```Rust async fn request_filter(request_state: RequestState) { let headers_state = request_state.into_headers_state().await; let headers_handler = headers_state.handler(); let agent = headers_handler.header("User-Agent").unwrap_or_else(|| "Undefined".to_string()); // Removing old content length header before manipulating body headers_handler.remove_header("content-length"); let body_state = headers_state.into_body_state().await; let body_handler = body_state.handler(); let body = body_handler.body(); logger::info!("User: {agent} sent: {}", String::from_utf8_lossy(body.as_slice())); let new_body = "new body".as_bytes(); match body_handler.set_body(&new_body) { Ok(_) => logger::info!("Body updated"), Err(e) => logger::info!("Unable to set body. Reason: {e:?}), } } ```
このコードでは ​content-length​ ヘッダーを削除します。これはボディを修正するために必要です。
`BodyHandler::set_body()`​ メソッドは、​`Result<(), BodyError>`​ オブジェクトを返します。ボディの更新は、以下が原因で失敗する可能性があります。 - `BodyError::BodyNotSent`​: 現在の HTTP フローにボディ (​`GET`​ 要求など) がありません。 - `BodyError::ExceededBodySize`​: 新しいボディが Envoy でサポートされる最大ボディバッファサイズを超えています。 ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features) # リクエストヘッダーとリクエストボディの読み取りと書き込み Flex Gateway ポリシー開発キット (PDK) を使用すると、リクエスト/レスポンスヘッダーおよびボディの読み取りと書き込みを行うことができます。 ## [](#event-flow)イベントフロー 要求および応答を絞り込むときに、Proxy Wasm はヘッダーとボディの処理を必ず特定の順序で発生する 2 つのメインイベントに分割します。ポリシーでボディを処理する前に、すべてのポリシーでヘッダーイベントが完全に伝播されている必要があります。たとえば、2 つのポリシーが適用される API のイベントフローは次のようになります。 1. ポリシー 1 はリクエストヘッダーイベントを処理します。 2. ポリシー 2 はリクエストヘッダーイベントを処理します。 3. バックエンドサービスはリクエストヘッダーを受信します。 4. ポリシー 1 はリクエストボディイベントを処理します。 5. ポリシー 2 はリクエストボディイベントを処理します。 6. バックエンドはリクエストボディを受信します。 7. バックエンドは応答を送信します。 8. ポリシー 2 はレスポンスヘッダーイベントを処理します。 9. ポリシー 1 はレスポンスヘッダーイベントを処理します。 10. クライアントはレスポンスヘッダーを受信します。 11. ポリシー 2 はレスポンスボディイベントを処理します。 12. ポリシー 1 はレスポンスボディイベントを処理します。 13. クライアントはレスポンスボディを受信します。 この順序では、次の制限が生じます。 - ポリシーはボディを読み取った後にヘッダーを変更できない。 - すべてのポリシーはボディを読み取る前にヘッダーイベントを完全に処理する必要がある。ボディのデータをあるポリシーに保存し、別のポリシーのボディデータを使用してヘッダーを変更することはできません。 - すべてのポリシーはヘッダーイベントを処理するときにバックエンドサービスに到達する。拒否された要求からのデータがバックエンドサービスに到達しないようにするには、リクエストヘッダーのみに基づいてヘッダーを拒否する必要があります。ボディに基づいて要求を拒否すると、大部分のサーバーおよびクライアントは中断された要求を検出して、リクエストヘッダーを破棄できます。 ポリシーソースコードでボディを読み取ると、ヘッダーとボディのイベントが分割されます。たとえば、ボディを読み取るために宣言 ​`let body_state = headers_state.into_body_state().await;`​ が使用されている場合、宣言前のすべてがヘッダーイベントで発生し、宣言後のすべてがボディイベントで発生します。 ## [](#read-and-write-headers)リクエストヘッダーの読み取りと書き込み リクエストヘッダーとレスポンスヘッダーの両方にアクセスするには、​`into_headers_state()`​ メソッドを呼び出して、​`RequestState`​ または ​`ResponseState`​ をヘッダー状態に変換して、処理が完了するのを待ちます。メソッドを呼び出したら、​`HeadersHandler`​ trait の関数を呼び出してヘッダーにアクセスして操作します。 ```Rust pub trait HeadersHandler { fn headers(&self) -> Vec<(String, String)>; fn header(&self, name: &str) -> Option; fn add_header(&self, name: &str, value: &str); fn set_header(&self, name: &str, value: &str); fn set_headers(&self, headers: Vec<(&str, &str)>); fn remove_header(&self, name: &str); } ``` 以下のコードを実装することで、ラップされた関数の ​`on_request`​ または ​`on_response`​ でヘッダーにアクセスすることができます。 ```Rust async fn request_filter(request_state: RequestState, _config: &Config) { let headers_state = request_state.into_headers_state().await; let headers_handler = headers_state.handler(); let old_value = headers_handler.header("request-header").unwrap_or_default(); let new_value = "--replaced--"; logger::info!("Old request header value: {old_value}, New value: {new_value}"); headers_handler.set_header("request-header", new_value); } async fn response_filter(response_state: ResponseState, _config: &Config) { let headers_state = response_state.into_headers_state().await; let headers_handler = headers_state.handler(); let old_headers = headers_handler.header("request-header").unwrap_or_default(); let new_value = vec![("response-header1", "--replaced--"), ("response-header2", "--replaced--")]; logger::info!("Old request header value: {old_headers:?}, New value: {new_value:?}"); headers_handler.set_headers(new_value); } ``` Envoy はメソッド、スキーム、パス、承認、状況コードをヘッダーとして扱います。PDK は要求の Envoy ヘッダーである ​`:method`​、​`:scheme`​、​`:path`​、​`:authority`​、​`:status`​ にアクセスして変更するために以下のメソッドを提供しています。 ```Rust async fn request_filter(request_state: RequestState, _config: &Config) { let headers_state = request_state.into_headers_state().await; let method = headers_state.method(); let scheme = headers_state.scheme(); let authority = headers_state.authority(); let path = headers_state.path(); ... } async fn response_filter(response_state: ResponseState, _config: &Config) { let headers_state = response_state.into_headers_state().await; let status = headers_state.status_code(); } ``` ## [](#read-and-write-request-bodies)リクエストボディの読み取りと書き込み
ボディの読み取りと書き込みのペイロードサイズは 1MB 未満に制限されています。
リクエストボディとレスポンスボディの両方にアクセスするには、​`into_body_state()`​ メソッドを呼び出して、​`RequestState`​ または ​`ResponseState`​ をボディ状態に変換して、処理が完了するのを待ちます。 ```Rust let body_state = request_state.into_body_state().await; ```
前の ​.await​ は、キャンセルポイントになります。要求中に​フローがキャンセル​されると、​.await​ が再開されない可能性があります。
元の状態がすでにヘッダー状態に変換されている場合は、同じ関数を呼び出してボディ状態に変換します。例: ```Rust let headers_state = request_state.into_headers_state().await; let body_state = headers_state.into_body_state().await; ``` `into_body_state()`​ を呼び出したら、​`BodyHandler`​ trait の関数を呼び出してヘッダーにアクセスして操作します。 ```Rust pub trait BodyHandler { fn body(&self) -> Vec; fn set_body(&self, body: &[u8]) -> Result<(), BodyError>; } ``` Envoy はヘッダーとボディのデータを共有するために同じバッファを使用するため、ポリシーはヘッダーとボディに同時にアクセスすることはできません。もしポリシーが両方を読み取る必要がある場合は、次の手順に従ってください。 1. ヘッダーを読み取り、必要な値を変数に保存します。 2. ボディを読み取ります。 応答と要求の両方で、ヘッダーとボディを読み取ることができます。ただし、ボディを読み取った後でヘッダーを変更することはできません。ボディを読み取る前にすべてのヘッダーの修正を完了してください。例: ```Rust async fn request_filter(request_state: RequestState) { let headers_state = request_state.into_headers_state().await; let headers_handler = headers_state.handler(); let agent = headers_handler.header("User-Agent").unwrap_or_else(|| "Undefined".to_string()); // Removing old content length header before manipulating body headers_handler.remove_header("content-length"); let body_state = headers_state.into_body_state().await; let body_handler = body_state.handler(); let body = body_handler.body(); logger::info!("User: {agent} sent: {}", String::from_utf8_lossy(body.as_slice())); let new_body = "new body".as_bytes(); match body_handler.set_body(&new_body) { Ok(_) => logger::info!("Body updated"), Err(e) => logger::info!("Unable to set body. Reason: {e:?}), } } ```
このコードでは ​content-length​ ヘッダーを削除します。これはボディを修正するために必要です。
`BodyHandler::set_body()`​ メソッドは、​`Result<(), BodyError>`​ オブジェクトを返します。ボディの更新は、以下が原因で失敗する可能性があります。 - `BodyError::BodyNotSent`​: 現在の HTTP フローにボディ (​`GET`​ 要求など) がありません。 - `BodyError::ExceededBodySize`​: 新しいボディが Envoy でサポートされる最大ボディバッファサイズを超えています。 ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features) # リクエストヘッダーとリクエストボディの読み取りと書き込み Flex Gateway ポリシー開発キット (PDK) を使用すると、リクエスト/レスポンスヘッダーおよびボディの読み取りと書き込み、ストリーミングされたボディの読み取りを行うことができます。 ## [](#event-flow)イベントフロー 要求および応答を絞り込むときに、Proxy Wasm はヘッダーとボディの処理を必ず特定の順序で発生する 2 つのメインイベントに分割します。ポリシーでボディを処理する前に、すべてのポリシーでヘッダーイベントが完全に伝播されている必要があります。たとえば、2 つのポリシーが適用される API のイベントフローは次のようになります。 1. ポリシー 1 はリクエストヘッダーイベントを処理します。 2. ポリシー 2 はリクエストヘッダーイベントを処理します。 3. バックエンドサービスはリクエストヘッダーを受信します。 4. ポリシー 1 はリクエストボディイベントを処理します。 5. ポリシー 2 はリクエストボディイベントを処理します。 6. バックエンドはリクエストボディを受信します。 7. バックエンドは応答を送信します。 8. ポリシー 2 はレスポンスヘッダーイベントを処理します。 9. ポリシー 1 はレスポンスヘッダーイベントを処理します。 10. クライアントはレスポンスヘッダーを受信します。 11. ポリシー 2 はレスポンスボディイベントを処理します。 12. ポリシー 1 はレスポンスボディイベントを処理します。 13. クライアントはレスポンスボディを受信します。 この順序では、次の制限が生じます。 - ポリシーはボディを読み取った後にヘッダーを変更できない。 - すべてのポリシーはボディを読み取る前にヘッダーイベントを完全に処理する必要がある。ボディのデータをあるポリシーに保存し、別のポリシーのボディデータを使用してヘッダーを変更することはできません。 - すべてのポリシーはヘッダーイベントを処理するときにバックエンドサービスに到達する。拒否された要求からのデータがバックエンドサービスに到達しないようにするには、リクエストヘッダーのみに基づいてヘッダーを拒否する必要があります。ボディに基づいて要求を拒否すると、大部分のサーバーおよびクライアントは中断された要求を検出して、リクエストヘッダーを破棄できます。 ポリシーソースコードでボディを読み取ると、ヘッダーとボディのイベントが分割されます。たとえば、ボディを読み取るために宣言 ​`let body_state = headers_state.into_body_state().await;`​ が使用されている場合、宣言前のすべてがヘッダーイベントで発生し、宣言後のすべてがボディイベントで発生します。 ## [](#read-and-write-headers)リクエストヘッダーの読み取りと書き込み リクエストヘッダーとレスポンスヘッダーの両方にアクセスするには、​`into_headers_state()`​ メソッドを呼び出して、​`RequestState`​ または ​`ResponseState`​ をヘッダー状態に変換して、処理が完了するのを待ちます。メソッドを呼び出したら、​`HeadersHandler`​ trait の関数を呼び出してヘッダーにアクセスして操作します。 ```Rust pub trait HeadersHandler { fn headers(&self) -> Vec<(String, String)>; fn header(&self, name: &str) -> Option; fn add_header(&self, name: &str, value: &str); fn set_header(&self, name: &str, value: &str); fn set_headers(&self, headers: Vec<(&str, &str)>); fn remove_header(&self, name: &str); } ``` 以下のコードを実装することで、ラップされた関数の ​`on_request`​ または ​`on_response`​ でヘッダーにアクセスすることができます。 ```Rust async fn request_filter(request_state: RequestState, _config: &Config) { let headers_state = request_state.into_headers_state().await; let headers_handler = headers_state.handler(); let old_value = headers_handler.header("request-header").unwrap_or_default(); let new_value = "--replaced--"; logger::info!("Old request header value: {old_value}, New value: {new_value}"); headers_handler.set_header("request-header", new_value); } async fn response_filter(response_state: ResponseState, _config: &Config) { let headers_state = response_state.into_headers_state().await; let headers_handler = headers_state.handler(); let old_headers = headers_handler.header("request-header").unwrap_or_default(); let new_value = vec![("response-header1", "--replaced--"), ("response-header2", "--replaced--")]; logger::info!("Old request header value: {old_headers:?}, New value: {new_value:?}"); headers_handler.set_headers(new_value); } ``` Envoy はメソッド、スキーム、パス、承認、状況コードをヘッダーとして扱います。PDK は要求の Envoy ヘッダーである ​`:method`​、​`:scheme`​、​`:path`​、​`:authority`​、​`:status`​ にアクセスして変更するために以下のメソッドを提供しています。 ```Rust async fn request_filter(request_state: RequestState, _config: &Config) { let headers_state = request_state.into_headers_state().await; let method = headers_state.method(); let scheme = headers_state.scheme(); let authority = headers_state.authority(); let path = headers_state.path(); ... } async fn response_filter(response_state: ResponseState, _config: &Config) { let headers_state = response_state.into_headers_state().await; let status = headers_state.status_code(); } ``` ## [](#read-and-write-request-bodies)リクエストボディの読み取りと書き込み
ボディの読み取りと書き込みのペイロードサイズは 1MB 未満に制限されています。より大きなペイロードについては、​ボディのストリーミング​を参照してください。
リクエストボディとレスポンスボディの両方にアクセスするには、​`into_body_state()`​ メソッドを呼び出して、​`RequestState`​ または ​`ResponseState`​ をボディ状態に変換して、処理が完了するのを待ちます。 ```Rust let body_state = request_state.into_body_state().await; ```
前の ​.await​ は、キャンセルポイントになります。要求中に​フローがキャンセル​されると、​.await​ が再開されない可能性があります。
元の状態がすでにヘッダー状態に変換されている場合は、同じ関数を呼び出してボディ状態に変換します。例: ```Rust let headers_state = request_state.into_headers_state().await; let body_state = headers_state.into_body_state().await; ``` `into_body_state()`​ を呼び出したら、​`BodyHandler`​ trait の関数を呼び出してヘッダーにアクセスして操作します。 ```Rust pub trait BodyHandler { fn body(&self) -> Vec; fn set_body(&self, body: &[u8]) -> Result<(), BodyError>; } ``` Envoy はヘッダーとボディのデータを共有するために同じバッファを使用するため、ポリシーはヘッダーとボディに同時にアクセスすることはできません。もしポリシーが両方を読み取る必要がある場合は、次の手順に従ってください。 1. ヘッダーを読み取り、必要な値を変数に保存します。 2. ボディを読み取ります。 応答と要求の両方で、ヘッダーとボディを読み取ることができます。ただし、ボディを読み取った後でヘッダーを変更することはできません。ボディを読み取る前にすべてのヘッダーの修正を完了してください。例: ```Rust async fn request_filter(request_state: RequestState) { let headers_state = request_state.into_headers_state().await; let headers_handler = headers_state.handler(); let agent = headers_handler.header("User-Agent").unwrap_or_else(|| "Undefined".to_string()); // Removing old content length header before manipulating body headers_handler.remove_header("content-length"); let body_state = headers_state.into_body_state().await; let body_handler = body_state.handler(); let body = body_handler.body(); logger::info!("User: {agent} sent: {}", String::from_utf8_lossy(body.as_slice())); let new_body = "new body".as_bytes(); match body_handler.set_body(&new_body) { Ok(_) => logger::info!("Body updated"), Err(e) => logger::info!("Unable to set body. Reason: {e:?}), } } ```
このコードでは ​content-length​ ヘッダーを削除します。これはボディを修正するために必要です。
`BodyHandler::set_body()`​ メソッドは、​`Result<(), BodyError>`​ オブジェクトを返します。ボディの更新は、以下が原因で失敗する可能性があります。 - `BodyError::BodyNotSent`​: 現在の HTTP フローにボディ (​`GET`​ 要求など) がありません。 - `BodyError::ExceededBodySize`​: 新しいボディが Envoy でサポートされる最大ボディバッファサイズを超えています。 ## [](#streaming-bodies)ボディのストリーミング
ストリーミングボディ状態を使用するポリシーの例については、 「Stream Payload Policy (ストリームペイロードポリシー)」​を参照してください。
1MB より大きいリクエストボディまたはレスポンスボディを処理するには、ストリーミングボディ状態を使用します。ストリーミングボディ状態により、データの受信時にボディをチャンクとして処理できます。ストリーミングボディ状態を使用すると、ボディに書き込みできなくなります。ストリームボディ状態を使用しても、ヘッダーの読み取りおよび書き込みには影響しません。 ストリーミングボディ状態を使用するには、​`into_body_stream_state()`​ メソッドを呼び出して、​`RequestState`​ または ​`ResponseState`​ をボディ状態に変換して、処理が完了するのを待ちます。 ```Rust let body_stream_state = request_state.into_body_stream_state().await; ``` 変換後、​`stream()`​ メソッドを使用して受信チャンクにアクセスします。 ```Rust let mut stream = body_stream_state.stream(); while let Some(chunk) = stream.next().await { // Process each chunk as it arrives let chunk_bytes = chunk.into_bytes(); // ... process chunk_bytes ... } ```
チャンク処理の例については、 「Stream Payload Policy Chunks (ストリームペイロードポリシーのチャンク)」​を参照してください。
ペイロードを処理する前に完全なボディが必要な場合は、​`collect()`​ メソッドを使用してすべてのチャンクを収集します。 ```Rust let collect = stream.collect().await; ```
ペイロード全体を収集および処理する方法の例については、 「Stream Payload Policy Collect (ストリームペイロードポリシーの収集)」​を参照してください。
## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features) # ワーカー間でのデータ共有とキャッシュの設定
キャッシングを使用するポリシープロジェクトの例は、 「データキャッシングポリシーの例」​を参照してください。
Envoy は、ポリシーの要求処理能力を高めるために多くのワーカーを生成します。1 つのワーカーが、発信接続や応答フローなど、特定の要求のすべてのフェーズを処理します。これにより、特定の要求の内部ステータスを追跡したり、基盤となるイベント駆動型の実装には関係なく、逐次的な実行フローを作成したりできます。 各ワーカーは与えられた時間内に 1 つの要求を処理します。特定のワーカーでグローバルな状態を共有するには、同時変更のリスクがない ​`RefCell`​ を使用します。 用意されている​`キャッシュ`​メカニズムを使用して、すべてのワーカーで共有されるグローバル状態を作成します。 キャッシュビルダーを挿入したら、キャッシュの ID とキャッシュがサポートする要素の最大数を指定します。 次の例では、10 個の要素を保持できるキャッシュを設定しています。 ```Rust #[entrypoint] async fn configure( launcher: Launcher, cache_builder: CacheBuilder, ) -> Result<()> { let cache = cache_builder.new(String::from("caching")).max_entries(10); ... ``` キャッシュは以下のインターフェースを持ちます。 ```Rust pub trait Cache { fn save(&self, key: &str, value: Vec) -> Result<(), CacheError>; fn get(&self, key: &str) -> Option>; fn delete(&self, key: &str) -> Option>; fn purge(&self); } ```
異なるワーカーが同時にキャッシュに書き込むため、キャッシュを保存するときに上書きされる値が、取得したときと同じであるという保証はありません。
## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features) # ワーカー間でのデータ共有とキャッシュの設定
キャッシングを使用するポリシープロジェクトの例は、 「データキャッシングポリシーの例」​を参照してください。
Envoy は、ポリシーの要求処理能力を高めるために多くのワーカーを生成します。1 つのワーカーが、発信接続や応答フローなど、特定の要求のすべてのフェーズを処理します。これにより、特定の要求の内部ステータスを追跡したり、基盤となるイベント駆動型の実装には関係なく、逐次的な実行フローを作成したりできます。 各ワーカーは与えられた時間内に 1 つの要求を処理します。特定のワーカーでグローバルな状態を共有するには、同時変更のリスクがない ​`RefCell`​ を使用します。 用意されている​`キャッシュ`​メカニズムを使用して、すべてのワーカーで共有されるグローバル状態を作成します。 キャッシュビルダーを挿入したら、キャッシュの ID とキャッシュがサポートする要素の最大数を指定します。 次の例では、10 個の要素を保持できるキャッシュを設定しています。 ```Rust #[entrypoint] async fn configure( launcher: Launcher, cache_builder: CacheBuilder, ) -> Result<()> { let cache = cache_builder.new(String::from("caching")).max_entries(10); ... ``` キャッシュは以下のインターフェースを持ちます。 ```Rust pub trait Cache { fn save(&self, key: &str, value: Vec) -> Result<(), CacheError>; fn get(&self, key: &str) -> Option>; fn delete(&self, key: &str) -> Option>; fn purge(&self); } ```
異なるワーカーが同時にキャッシュに書き込むため、キャッシュを保存するときに上書きされる値が、取得したときと同じであるという保証はありません。
## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features) # ワーカー間でのデータ共有とキャッシュの設定
キャッシングを使用するポリシープロジェクトの例は、 「データキャッシングポリシーの例」​を参照してください。
Envoy は、ポリシーの要求処理能力を高めるために多くのワーカーを生成します。1 つのワーカーが、発信接続や応答フローなど、特定の要求のすべてのフェーズを処理します。これにより、特定の要求の内部ステータスを追跡したり、基盤となるイベント駆動型の実装には関係なく、逐次的な実行フローを作成したりできます。 各ワーカーは与えられた時間内に 1 つの要求を処理します。特定のワーカーでグローバルな状態を共有するには、同時変更のリスクがない ​`RefCell`​ を使用します。 用意されている​`キャッシュ`​メカニズムを使用して、すべてのワーカーで共有されるグローバル状態を作成します。 キャッシュビルダーを挿入したら、キャッシュの ID とキャッシュがサポートする要素の最大数を指定します。 次の例では、10 個の要素を保持できるキャッシュを設定しています。 ```Rust #[entrypoint] async fn configure( launcher: Launcher, cache_builder: CacheBuilder, ) -> Result<()> { let cache = cache_builder.new(String::from("caching")).max_entries(10); ... ``` キャッシュは以下のインターフェースを持ちます。 ```Rust pub trait Cache { fn save(&self, key: &str, value: Vec) -> Result<(), CacheError>; fn get(&self, key: &str) -> Option>; fn delete(&self, key: &str) -> Option>; fn purge(&self); } ```
異なるワーカーが同時にキャッシュに書き込むため、キャッシュを保存するときに上書きされる値が、取得したときと同じであるという保証はありません。
## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features) # 新規プロジェクトの作成 Flex Gateway ポリシー開発キット (PDK) を使用して新しいカスタムポリシーの開発を開始するには、新しいカスタムポリシープロジェクトを生成します。 新しいプロジェクトを作成するには、次のタスクを完了します。 1. [始める前に](#before-you-begin) 2. [新しいポリシープロジェクトを作成する](#create-a-new-policy-project) 3. [PDK ビルド環境のセットアップ](#setup-the-pdk-build-environment) 4. [プロジェクト構造](#project-structure)​を確認します。 ## [](#before-you-begin)始める前に カスタムポリシープロジェクトを作成する前に、すべての ​[PDK 前提条件](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-prerequisites)​がインストール済みであることを確認してください。 ## [](#create-a-new-policy-project)新しいポリシープロジェクトを作成する カスタムポリシープロジェクトを作成するには、PDK CLI ​`create`​ コマンドを実行します。​``​ には新しいポリシー名を指定してください ```ssh anypoint-cli-v4 pdk policy-project create --name ```
グループ ID が要求された場合は、​「グループ ID のトラブルシューティング」​を参照してください。
`create`​ コマンドを実行すると指定した名前でカスタムポリシープロジェクトが作成されます。プロジェクトは、ポリシーと同じ名前の新しいディレクトリか、または ​`--output-dir`​ フラグで指定したディレクトリに保存されます。以下のチュートリアルでは、このディレクトリをプロジェクトのルートディレクトリと呼びます。 新しいポリシーの ​`assetID`​ は、ポリシーの名前を小文字にしてスペースを ​`-`​ に置き換えた文字列になります。たとえば、​`My Header Injection Policy`​ という名前のポリシーの ​`assetID`​ は、​`my-header-injection-policy`​ になります。 新しいポリシーの ​`groupID`​ は、Anypoint CLI で設定した組織の ID です。 `create`​ コマンドは、次のフラグをサポートします。
フラグ デフォルト値 必須 説明

--name=<value>​ または ​-n

なし

はい

新しいポリシーの名前。

--description=<value>​ または ​-d

なし

いいえ

新しいポリシーの説明。

--output-dir=<value>​ または ​-o

assetID

いいえ

新しいポリシーが作成されるディレクトリ。
指定したディレクトリが存在しない場合は新たに作成されます。ディレクトリが指定されていない場合は、ポリシーの ​assetID​ がディレクトリ名になります。

--version=<value>

1.0.0

いいえ

新しいポリシーのバージョン。
バージョンの形式は ​<major-release>.<minor-release>.<patch-release>​ です。

--group-id=<value>

なし

いいえ

ポリシーを所有する組織の組織 ID。
このフラグの詳細は、​「グループ ID のトラブルシューティング」​を参照してください。
## [](#setup-the-pdk-build-environment)PDK ビルド環境のセットアップ [新しいポリシープロジェクトを作成](#create-a-new-policy-project)​したら、​`make setup`​ コマンドを実行して、追加のソフトウェア連動関係をダウンロードする必要があります。 ```ssh make setup ``` ## [](#project-structure)プロジェクト構造 `make setup`​ コマンドを実行すると、ポリシーのルートディレクトリに、次のディレクトリツリーに示すディレクトリとファイルが作成されます。 ├─ definition/ # Contains the files that describe the policy Definition │ ├── target/ # Contains the build definition asset files │ └── gcl.yaml # GCL file managed by the developer that describes the policy Definition ├─ target/ # Contains the implementation asset files and the output of the policy build ├─ src/ # Contains the implementation source code ├─ playground/ # Contains the artifacts required for running the policy locally ├─ tests/ # Contains the source and configuration files to write and run integration tests ├─ Makefile # Provides all the callable actions required during the policy development lifecycle ├─ Cargo.toml # Rust language standard file that contains the metadata required to build the policy └─.project.yaml # Project manifest used by PDK ### [](#target-および-definitiontarget)target/ および definition/target/ 2 つの別々の​`ターゲット`​ディレクトリです。 - `definition/target/`​: Exchange にパブリッシュされたポリシーアセット定義が保存されます。 - `target/`​: ポリシーの Exchange アセット実装用のファイルとプロジェクトビルドの出力が保存されます。 両方のターゲットディレクトリとそのコンテンツは ​`.gitignore`​ ファイルに保存されます。​`make build`​ コマンドを使用して、各デバイス上でターゲットをコンパイルする必要があります。たとえば、チームでポリシーを開発する場合は、チームとしてポリシーとソースコードをリモートリポジトリにパブリッシュできますが、各チームメンバーがポリシーの作業に取り掛かるためには、自分のデバイス上でターゲットをビルドする必要があります。 ### [](#definition)definition/ `definition`​ ディレクトリには、ポリシーのメタデータと設定プロパティを定義する ​`gcl.yaml`​ ファイルが保存されます。 `gcl.yaml`​ の設定については、[policy-pdk-create-schema-definition.adoc](#policy-pdk-create-schema-definition.adoc)を参照してください。 ### [](#cargo-toml)Cargo.toml Flex Gateway のカスタムポリシーは Rust プログラミング言語で開発され、WebAssembly バイナリにコンパイルされます。 `Cargo.toml`​ は、Rust プロジェクトのマニフェストファイルです。​`[package]`​ セクションには、ポリシーの実装に関する基本情報が含まれています。​`Cargo.toml`​ で指定されたバージョンは、ポリシーアセットのバージョンと一致します。ポリシーのバージョンは、​`Cargo.toml`​ のバージョン番号を編集することで管理できます。バージョンの形式は ​`..`​ です。 ### [](#src)src/ `src`​ ディレクトリにはポリシーのソースコードが保存されます。 - `lib.rs`​: ポリシーの動作を実装するメソッドのセットが保存されます。PDK は、これらのメソッドをインクルードしてカスタムポリシーの動作を実装します。これらのメソッドについての詳細は、​[Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features). For complete policy examples, see [カスタムポリシーの例](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-policy-templates)​を参照してください。 - `generated/config.rs`​ および ​`generated/mod.rs`​: `gcl.yaml`​ で定義されているポリシーの設定を、​`lib.rs`​ やポリシーのソースファイルで使用できるようにする自動生成モジュールです。 ### [](#makefile)Makefile Makefile には、​`make`​ コマンドなど、ポリシー開発のライフサイクルに必要な呼び出し可能なアクションがすべて含まれています。すべての ​`make`​ コマンドは、カスタムポリシーディレクトリのルートレベルで実行します。 - `make setup`​: Makefile の残りのゴールに必要な PDK の内部連動関係をインストールします。 プロジェクトの設定についての詳細は、​[PDK ビルド環境のセットアップ](#setup-the-pdk-build-environment)​を参照してください。 - `make build-asset-files`​: ポリシーのビルド、実行、パブリッシュに必要なすべてのポリシーアセットファイルを生成します。このコマンドは、​`gcl.yaml`​ ファイルで定義されている最新の設定で ​`config.rs`​ ソースコードファイルを更新します。 ポリシーのコンパイルの詳細については、[カスタムポリシーのコンパイル](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-compile-policies)を参照してください。 - `make build`​: `make build-asset-files`​ コマンドを実行して、ポリシーの WebAssembly バイナリをコンパイルします。 ポリシーのコンパイルの詳細については、[カスタムポリシーのコンパイル](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-compile-policies)を参照してください。 - `make run`​: コンテナ化された Docker 環境でポリシーの現在のビルドを簡単に実行する方法を提供します。 ポリシーの実行とデバッグの詳細については、[PDK デバッグプレイグラウンドでのカスタムポリシーのデバッグ](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-debug-local)を参照してください。 - `make test`​: PDK が提供するテストフレームワークを使用して、​`tests/`​ に保存されているテストを実行します。 ポリシーのテストの詳細については、[インテグレーションテストの作成](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-integration-tests)を参照してください。 - `make publish`​: ポリシーアセットを Exchange でパブリッシュします。 Exchange でのポリシーのパブリッシュについての詳細は、[Exchange へのカスタムポリシーのアップロード](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-publish-policies)を参照してください。 - `make release`​: ポリシーアセットを Exchange でリリースします。 Exchange でのポリシーのリリースについての詳細は、[Exchange へのカスタムポリシーのアップロード](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-publish-policies)を参照してください。 - `make help`​: PDK が提供するすべての ​`make`​ コマンドをリスト表示します。 ## [](#関連情報)関連情報 - [PDK のトラブルシューティング](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-troubleshooting) # 新規プロジェクトの作成 Flex Gateway ポリシー開発キット (PDK) を使用して新しいカスタムポリシーの開発を開始するには、新しいカスタムポリシープロジェクトを生成します。 新しいプロジェクトを作成するには、次のタスクを完了します。 1. [始める前に](#before-you-begin) 2. [新しいポリシープロジェクトを作成する](#create-a-new-policy-project) 3. [PDK ビルド環境のセットアップ](#setup-the-pdk-build-environment) 4. [プロジェクト構造](#project-structure)​を確認します。 ## [](#before-you-begin)始める前に カスタムポリシープロジェクトを作成する前に、すべての ​[PDK 前提条件](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-prerequisites)​がインストール済みであることを確認してください。 ## [](#create-a-new-policy-project)新しいポリシープロジェクトを作成する カスタムポリシープロジェクトを作成するには、PDK CLI ​`create`​ コマンドを実行します。​``​ には新しいポリシー名を指定してください ```ssh anypoint-cli-v4 pdk policy-project create --name ```
グループ ID が要求された場合は、​「グループ ID のトラブルシューティング」​を参照してください。
`create`​ コマンドを実行すると指定した名前でカスタムポリシープロジェクトが作成されます。プロジェクトは、ポリシーと同じ名前の新しいディレクトリか、または ​`--output-dir`​ フラグで指定したディレクトリに保存されます。以下のチュートリアルでは、このディレクトリをプロジェクトのルートディレクトリと呼びます。 新しいポリシーの ​`assetID`​ は、ポリシーの名前を小文字にしてスペースを ​`-`​ に置き換えた文字列になります。たとえば、​`My Header Injection Policy`​ という名前のポリシーの ​`assetID`​ は、​`my-header-injection-policy`​ になります。 新しいポリシーの ​`groupID`​ は、Anypoint CLI で設定した組織の ID です。 `create`​ コマンドは、次のフラグをサポートします。
フラグ デフォルト値 必須 説明

--name=<value>​ または ​-n

なし

はい

新しいポリシーの名前。

--description=<value>​ または ​-d

なし

いいえ

新しいポリシーの説明。

--output-dir=<value>​ または ​-o

assetID

いいえ

新しいポリシーが作成されるディレクトリ。
指定したディレクトリが存在しない場合は新たに作成されます。ディレクトリが指定されていない場合は、ポリシーの ​assetID​ がディレクトリ名になります。

--version=<value>

1.0.0

いいえ

新しいポリシーのバージョン。
バージョンの形式は ​<major-release>.<minor-release>.<patch-release>​ です。

--group-id=<value>

なし

いいえ

ポリシーを所有する組織の組織 ID。
このフラグの詳細は、​「グループ ID のトラブルシューティング」​を参照してください。
## [](#setup-the-pdk-build-environment)PDK ビルド環境のセットアップ [新しいポリシープロジェクトを作成](#create-a-new-policy-project)​したら、​`make setup`​ コマンドを実行して、追加のソフトウェア連動関係をダウンロードする必要があります。 ```ssh make setup ``` ## [](#project-structure)プロジェクト構造 `make setup`​ コマンドを実行すると、ポリシーのルートディレクトリに、次のディレクトリツリーに示すディレクトリとファイルが作成されます。 ├─ definition/ # Contains the files that describe the policy Definition │ ├── target/ # Contains the build definition asset files │ └── gcl.yaml # GCL file managed by the developer that describes the policy Definition ├─ target/ # Contains the implementation asset files and the output of the policy build ├─ src/ # Contains the implementation source code ├─ playground/ # Contains the artifacts required for running the policy locally ├─ tests/ # Contains the source and configuration files to write and run integration tests ├─ Makefile # Provides all the callable actions required during the policy development lifecycle ├─ Cargo.toml # Rust language standard file that contains the metadata required to build the policy └─.project.yaml # Project manifest used by PDK ### [](#target-および-definitiontarget)target/ および definition/target/ 2 つの別々の​`ターゲット`​ディレクトリです。 - `definition/target/`​: Exchange にパブリッシュされたポリシーアセット定義が保存されます。 - `target/`​: ポリシーの Exchange アセット実装用のファイルとプロジェクトビルドの出力が保存されます。 両方のターゲットディレクトリとそのコンテンツは ​`.gitignore`​ ファイルに保存されます。​`make build`​ コマンドを使用して、各デバイス上でターゲットをコンパイルする必要があります。たとえば、チームでポリシーを開発する場合は、チームとしてポリシーとソースコードをリモートリポジトリにパブリッシュできますが、各チームメンバーがポリシーの作業に取り掛かるためには、自分のデバイス上でターゲットをビルドする必要があります。 ### [](#definition)definition/ `definition`​ ディレクトリには、ポリシーのメタデータと設定プロパティを定義する ​`gcl.yaml`​ ファイルが保存されます。 `gcl.yaml`​ の設定については、[policy-pdk-create-schema-definition.adoc](#policy-pdk-create-schema-definition.adoc)を参照してください。 ### [](#cargo-toml)Cargo.toml Flex Gateway のカスタムポリシーは Rust プログラミング言語で開発され、WebAssembly バイナリにコンパイルされます。 `Cargo.toml`​ は、Rust プロジェクトのマニフェストファイルです。​`[package]`​ セクションには、ポリシーの実装に関する基本情報が含まれています。​`Cargo.toml`​ で指定されたバージョンは、ポリシーアセットのバージョンと一致します。ポリシーのバージョンは、​`Cargo.toml`​ のバージョン番号を編集することで管理できます。バージョンの形式は ​`..`​ です。 ### [](#src)src/ `src`​ ディレクトリにはポリシーのソースコードが保存されます。 - `lib.rs`​: ポリシーの動作を実装するメソッドのセットが保存されます。PDK は、これらのメソッドをインクルードしてカスタムポリシーの動作を実装します。これらのメソッドについての詳細は、​[Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features). For complete policy examples, see [カスタムポリシーの例](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-policy-templates)​を参照してください。 - `generated/config.rs`​ および ​`generated/mod.rs`​: `gcl.yaml`​ で定義されているポリシーの設定を、​`lib.rs`​ やポリシーのソースファイルで使用できるようにする自動生成モジュールです。 ### [](#makefile)Makefile Makefile には、​`make`​ コマンドなど、ポリシー開発のライフサイクルに必要な呼び出し可能なアクションがすべて含まれています。すべての ​`make`​ コマンドは、カスタムポリシーディレクトリのルートレベルで実行します。 - `make setup`​: Makefile の残りのゴールに必要な PDK の内部連動関係をインストールします。 プロジェクトの設定についての詳細は、​[PDK ビルド環境のセットアップ](#setup-the-pdk-build-environment)​を参照してください。 - `make build-asset-files`​: ポリシーのビルド、実行、パブリッシュに必要なすべてのポリシーアセットファイルを生成します。このコマンドは、​`gcl.yaml`​ ファイルで定義されている最新の設定で ​`config.rs`​ ソースコードファイルを更新します。 ポリシーのコンパイルの詳細については、[カスタムポリシーのコンパイル](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-compile-policies)を参照してください。 - `make build`​: `make build-asset-files`​ コマンドを実行して、ポリシーの WebAssembly バイナリをコンパイルします。 ポリシーのコンパイルの詳細については、[カスタムポリシーのコンパイル](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-compile-policies)を参照してください。 - `make run`​: コンテナ化された Docker 環境でポリシーの現在のビルドを簡単に実行する方法を提供します。 ポリシーの実行とデバッグの詳細については、[PDK デバッグプレイグラウンドでのカスタムポリシーのデバッグ](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-debug-local)を参照してください。 - `make test`​: PDK が提供するテストフレームワークを使用して、​`tests/`​ に保存されているテストを実行します。 ポリシーのテストの詳細については、[インテグレーションテストの作成](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-integration-tests)を参照してください。 - `make publish`​: ポリシーアセットを Exchange でパブリッシュします。 Exchange でのポリシーのパブリッシュについての詳細は、[Exchange へのカスタムポリシーのアップロード](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-publish-policies)を参照してください。 - `make release`​: ポリシーアセットを Exchange でリリースします。 Exchange でのポリシーのリリースについての詳細は、[Exchange へのカスタムポリシーのアップロード](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-publish-policies)を参照してください。 - `make help`​: PDK が提供するすべての ​`make`​ コマンドをリスト表示します。 ## [](#関連情報)関連情報 - [PDK のトラブルシューティング](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-troubleshooting) # 新規プロジェクトの作成 Flex Gateway ポリシー開発キット (PDK) を使用して新しいカスタムポリシーの開発を開始するには、新しいカスタムポリシープロジェクトを生成します。 新しいプロジェクトを作成するには、次のタスクを完了します。 1. [始める前に](#before-you-begin) 2. [新しいポリシープロジェクトを作成する](#create-a-new-policy-project) 3. [PDK ビルド環境のセットアップ](#setup-the-pdk-build-environment) 4. [プロジェクト構造](#project-structure)​を確認します。 ## [](#before-you-begin)始める前に カスタムポリシープロジェクトを作成する前に、すべての ​[PDK 前提条件](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-prerequisites)​がインストール済みであることを確認してください。 ## [](#create-a-new-policy-project)新しいポリシープロジェクトを作成する カスタムポリシープロジェクトを作成するには、PDK CLI ​`create`​ コマンドを実行します。​``​ には新しいポリシー名を指定してください ```ssh anypoint-cli-v4 pdk policy-project create --name ```
グループ ID が要求された場合は、​「グループ ID のトラブルシューティング」​を参照してください。
`create`​ コマンドを実行すると指定した名前でカスタムポリシープロジェクトが作成されます。プロジェクトは、ポリシーと同じ名前の新しいディレクトリか、または ​`--output-dir`​ フラグで指定したディレクトリに保存されます。以下のチュートリアルでは、このディレクトリをプロジェクトのルートディレクトリと呼びます。 新しいポリシーの ​`assetID`​ は、ポリシーの名前を小文字にしてスペースを ​`-`​ に置き換えた文字列になります。たとえば、​`My Header Injection Policy`​ という名前のポリシーの ​`assetID`​ は、​`my-header-injection-policy`​ になります。 新しいポリシーの ​`groupID`​ は、Anypoint CLI で設定した組織の ID です。 `create`​ コマンドは、次のフラグをサポートします。
フラグ デフォルト値 必須 説明

--name=<value>​ または ​-n

なし

はい

新しいポリシーの名前。

--description=<value>​ または ​-d

なし

いいえ

新しいポリシーの説明。

--output-dir=<value>​ または ​-o

assetID

いいえ

新しいポリシーが作成されるディレクトリ。
指定したディレクトリが存在しない場合は新たに作成されます。ディレクトリが指定されていない場合は、ポリシーの ​assetID​ がディレクトリ名になります。

--version=<value>

1.0.0

いいえ

新しいポリシーのバージョン。
バージョンの形式は ​<major-release>.<minor-release>.<patch-release>​ です。

--group-id=<value>

なし

いいえ

ポリシーを所有する組織の組織 ID。
このフラグの詳細は、​「グループ ID のトラブルシューティング」​を参照してください。
## [](#setup-the-pdk-build-environment)PDK ビルド環境のセットアップ [新しいポリシープロジェクトを作成](#create-a-new-policy-project)​したら、​`make setup`​ コマンドを実行して、追加のソフトウェア連動関係をダウンロードする必要があります。 ```ssh make setup ``` ## [](#project-structure)プロジェクト構造 `make setup`​ コマンドを実行すると、ポリシーのルートディレクトリに、次のディレクトリツリーに示すディレクトリとファイルが作成されます。 ├─ definition/ # Contains the files that describe the policy Definition │ ├── target/ # Contains the build definition asset files │ └── gcl.yaml # GCL file managed by the developer that describes the policy Definition ├─ target/ # Contains the implementation asset files and the output of the policy build ├─ src/ # Contains the implementation source code ├─ playground/ # Contains the artifacts required for running the policy locally ├─ tests/ # Contains the source and configuration files to write and run integration tests ├─ Makefile # Provides all the callable actions required during the policy development lifecycle ├─ Cargo.toml # Rust language standard file that contains the metadata required to build the policy └─.project.yaml # Project manifest used by PDK ### [](#target-および-definitiontarget)target/ および definition/target/ 2 つの別々の​`ターゲット`​ディレクトリです。 - `definition/target/`​: Exchange にパブリッシュされたポリシーアセット定義が保存されます。 - `target/`​: ポリシーの Exchange アセット実装用のファイルとプロジェクトビルドの出力が保存されます。 両方のターゲットディレクトリとそのコンテンツは ​`.gitignore`​ ファイルに保存されます。​`make build`​ コマンドを使用して、各デバイス上でターゲットをコンパイルする必要があります。たとえば、チームでポリシーを開発する場合は、チームとしてポリシーとソースコードをリモートリポジトリにパブリッシュできますが、各チームメンバーがポリシーの作業に取り掛かるためには、自分のデバイス上でターゲットをビルドする必要があります。 ### [](#definition)definition/ `definition`​ ディレクトリには、ポリシーのメタデータと設定プロパティを定義する ​`gcl.yaml`​ ファイルが保存されます。 `gcl.yaml`​ の設定については、[policy-pdk-create-schema-definition.adoc](#policy-pdk-create-schema-definition.adoc)を参照してください。 ### [](#cargo-toml)Cargo.toml Flex Gateway のカスタムポリシーは Rust プログラミング言語で開発され、WebAssembly バイナリにコンパイルされます。 `Cargo.toml`​ は、Rust プロジェクトのマニフェストファイルです。​`[package]`​ セクションには、ポリシーの実装に関する基本情報が含まれています。​`Cargo.toml`​ で指定されたバージョンは、ポリシーアセットのバージョンと一致します。ポリシーのバージョンは、​`Cargo.toml`​ のバージョン番号を編集することで管理できます。バージョンの形式は ​`..`​ です。 ### [](#src)src/ `src`​ ディレクトリにはポリシーのソースコードが保存されます。 - `lib.rs`​: ポリシーの動作を実装するメソッドのセットが保存されます。PDK は、これらのメソッドをインクルードしてカスタムポリシーの動作を実装します。これらのメソッドについての詳細は、​[Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features). For complete policy examples, see [カスタムポリシーの例](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-policy-templates)​を参照してください。 - `generated/config.rs`​ および ​`generated/mod.rs`​: `gcl.yaml`​ で定義されているポリシーの設定を、​`lib.rs`​ やポリシーのソースファイルで使用できるようにする自動生成モジュールです。 ### [](#makefile)Makefile Makefile には、​`make`​ コマンドなど、ポリシー開発のライフサイクルに必要な呼び出し可能なアクションがすべて含まれています。すべての ​`make`​ コマンドは、カスタムポリシーディレクトリのルートレベルで実行します。 - `make setup`​: Makefile の残りのゴールに必要な PDK の内部連動関係をインストールします。 プロジェクトの設定についての詳細は、​[PDK ビルド環境のセットアップ](#setup-the-pdk-build-environment)​を参照してください。 - `make build-asset-files`​: ポリシーのビルド、実行、パブリッシュに必要なすべてのポリシーアセットファイルを生成します。このコマンドは、​`gcl.yaml`​ ファイルで定義されている最新の設定で ​`config.rs`​ ソースコードファイルを更新します。 ポリシーのコンパイルの詳細については、[カスタムポリシーのコンパイル](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-compile-policies)を参照してください。 - `make build`​: `make build-asset-files`​ コマンドを実行して、ポリシーの WebAssembly バイナリをコンパイルします。 ポリシーのコンパイルの詳細については、[カスタムポリシーのコンパイル](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-compile-policies)を参照してください。 - `make run`​: コンテナ化された Docker 環境でポリシーの現在のビルドを簡単に実行する方法を提供します。 ポリシーの実行とデバッグの詳細については、[PDK デバッグプレイグラウンドでのカスタムポリシーのデバッグ](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-debug-local)を参照してください。 - `make test`​: PDK が提供するテストフレームワークを使用して、​`tests/`​ に保存されているテストを実行します。 ポリシーのテストの詳細については、[インテグレーションテストの作成](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-integration-tests)を参照してください。 - `make publish`​: ポリシーアセットを Exchange でパブリッシュします。 Exchange でのポリシーのパブリッシュについての詳細は、[Exchange へのカスタムポリシーのアップロード](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-publish-policies)を参照してください。 - `make release`​: ポリシーアセットを Exchange でリリースします。 Exchange でのポリシーのリリースについての詳細は、[Exchange へのカスタムポリシーのアップロード](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-publish-policies)を参照してください。 - `make help`​: PDK が提供するすべての ​`make`​ コマンドをリスト表示します。 ## [](#関連情報)関連情報 - [PDK のトラブルシューティング](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-troubleshooting) # 要求と応答でのデータの共有 Flex Gateway ポリシー開発キット (PDK) は、要求と応答の間でデータを受け渡すための ​`RequestData`​ 列挙型を提供しています。 要求関数と応答関数の間で状況を共有するには、要求関数が、応答関数に渡すデータパラメーターが格納された ​`Flow::Continue`​ 列挙型変数を返す必要があります。応答関数は、要求関数の最終状況と渡されたデータパラメーターを含む ​`RequestData`​ パラメーターを受け取る必要があります。 `RequestData`​ 列挙型に格納される最終状況は次のとおりです。 - `RequestData::Continue(data)`​: 要求関数は ​`Flow::Continue(data)`​ で終了しました。 - `RequestData::Break`​ : 要求関数は ​`Flow::Break`​ で終了しました。 - `RequestData::Cancel`​: 要求機能は​[キャンセル](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features#flow-cancellation)​されました。 要求関数が ​`Flow::Continue`​ で終了し、アップストリームポリシーによってキャンセルされなかった場合、​`RequestData::Continue`​ 変数には要求関数によって送信された値が格納されます。 これを実装するには、[policy-pdk-configure-features-stop.adoc](#policy-pdk-configure-features-stop.adoc) で使用されている​`フロー`​の例にラップされる関数の ​`on_response`​ を追加します。 ```Rust async fn request_filter(state: RequestState) -> Flow { let state = state.into_headers_state().await; let handler = state.handler(); if handler.header("authorization").is_some() { Flow::Continue(state.path()) } else { Flow::Break( Response::new(401) .with_headers(vec![( "WWW-Authenticate".to_string(), "Bearer realm=\"oauth2\"".to_string(), )]) .with_body(r#"{ "error": "token was not present"}"#), ) } } async fn response_filter(state: ResponseState, request_data: RequestData) { // Handle only completed requests if let RequestData::Continue(path) = request_data else { return; }; let state = state.into_headers_state().await; logger::info!("Path: {path}, Status: {}", state.status_code()); } ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features) # 要求と応答でのデータの共有 Flex Gateway ポリシー開発キット (PDK) は、要求と応答の間でデータを受け渡すための ​`RequestData`​ 列挙型を提供しています。 要求関数と応答関数の間で状況を共有するには、要求関数が、応答関数に渡すデータパラメーターが格納された ​`Flow::Continue`​ 列挙型変数を返す必要があります。応答関数は、要求関数の最終状況と渡されたデータパラメーターを含む ​`RequestData`​ パラメーターを受け取る必要があります。 `RequestData`​ 列挙型に格納される最終状況は次のとおりです。 - `RequestData::Continue(data)`​: 要求関数は ​`Flow::Continue(data)`​ で終了しました。 - `RequestData::Break`​ : 要求関数は ​`Flow::Break`​ で終了しました。 - `RequestData::Cancel`​: 要求機能は​[キャンセル](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features#flow-cancellation)​されました。 要求関数が ​`Flow::Continue`​ で終了し、アップストリームポリシーによってキャンセルされなかった場合、​`RequestData::Continue`​ 変数には要求関数によって送信された値が格納されます。 これを実装するには、[policy-pdk-configure-features-stop.adoc](#policy-pdk-configure-features-stop.adoc) で使用されている​`フロー`​の例にラップされる関数の ​`on_response`​ を追加します。 ```Rust async fn request_filter(state: RequestState) -> Flow { let state = state.into_headers_state().await; let handler = state.handler(); if handler.header("authorization").is_some() { Flow::Continue(state.path()) } else { Flow::Break( Response::new(401) .with_headers(vec![( "WWW-Authenticate".to_string(), "Bearer realm=\"oauth2\"".to_string(), )]) .with_body(r#"{ "error": "token was not present"}"#), ) } } async fn response_filter(state: ResponseState, request_data: RequestData) { // Handle only completed requests if let RequestData::Continue(path) = request_data else { return; }; let state = state.into_headers_state().await; logger::info!("Path: {path}, Status: {}", state.status_code()); } ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features) # 要求と応答でのデータの共有 Flex Gateway ポリシー開発キット (PDK) は、要求と応答の間でデータを受け渡すための ​`RequestData`​ 列挙型を提供しています。 要求関数と応答関数の間で状況を共有するには、要求関数が、応答関数に渡すデータパラメーターが格納された ​`Flow::Continue`​ 列挙型変数を返す必要があります。応答関数は、要求関数の最終状況と渡されたデータパラメーターを含む ​`RequestData`​ パラメーターを受け取る必要があります。 `RequestData`​ 列挙型に格納される最終状況は次のとおりです。 - `RequestData::Continue(data)`​: 要求関数は ​`Flow::Continue(data)`​ で終了しました。 - `RequestData::Break`​ : 要求関数は ​`Flow::Break`​ で終了しました。 - `RequestData::Cancel`​: 要求機能は​[キャンセル](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features#flow-cancellation)​されました。 要求関数が ​`Flow::Continue`​ で終了し、アップストリームポリシーによってキャンセルされなかった場合、​`RequestData::Continue`​ 変数には要求関数によって送信された値が格納されます。 これを実装するには、[policy-pdk-configure-features-stop.adoc](#policy-pdk-configure-features-stop.adoc) で使用されている​`フロー`​の例にラップされる関数の ​`on_response`​ を追加します。 ```Rust async fn request_filter(state: RequestState) -> Flow { let state = state.into_headers_state().await; let handler = state.handler(); if handler.header("authorization").is_some() { Flow::Continue(state.path()) } else { Flow::Break( Response::new(401) .with_headers(vec![( "WWW-Authenticate".to_string(), "Bearer realm=\"oauth2\"".to_string(), )]) .with_body(r#"{ "error": "token was not present"}"#), ) } } async fn response_filter(state: ResponseState, request_data: RequestData) { // Handle only completed requests if let RequestData::Continue(path) = request_data else { return; }; let state = state.into_headers_state().await; logger::info!("Path: {path}, Status: {}", state.status_code()); } ``` ## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features) # 要求実行の停止 要求を捕捉して停止するには、ラップされる関数の ​`on_request`​ から ​`Response`​ オブジェクトを返します。 ```Rust Response::new(401) .with_headers(vec![("WWW-Authenticate".to_string(), "Bearer realm=\"oauth2\"".to_string())]) .with_body(r#"{ "error": "token was not present"}"#) ``` `フロー`​を使用して、アップストリームサービスへの要求の到達をブロックまたは許可できます。​`フロー`​は、次の 2 つの可能な値を持つ​`列挙型`​の値です。 - `Continue`​: 応答に転送されるオブジェクトを定義します。 - `Break`​: 要求を中止し、指定された応答を返します。 `フロー`​は次のように作成します。 ```Rust async fn request_filter(request_state: RequestState) -> Flow<()> { let header_state = request_state.into_headers_state().await; let handler = header_state.handler(); if handler.header("authorization").is_some() { Flow::Continue(()) } else { Flow::Break(Response::new(401) .with_headers(vec![("WWW-Authenticate".to_string(), "Bearer realm=\"oauth2\"".to_string())]) .with_body(r#"{ "error": "token was not present"}"#)) } } ```

proxy wasm​ のストリーミングの性質により、​headers_state.into_body_state​ 関数を待っている間に、要求の一部がアップストリームサービスに早期に到達する可能性があります。これを避けるには、ボディの読み取りを待たないことです。しかし、この方法はすべてのポリシーで可能であるとは限りません。ポリシーがボディを読み取る必要がある場合は、部分的な要求を無視するようにアップストリームを設定してください。

応答がクライアントに早期に返されないようにするには、要求と応答でのデータの共有を参照してください。
## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features) # 要求実行の停止 要求を捕捉して停止するには、ラップされる関数の ​`on_request`​ から ​`Response`​ オブジェクトを返します。 ```Rust Response::new(401) .with_headers(vec![("WWW-Authenticate".to_string(), "Bearer realm=\"oauth2\"".to_string())]) .with_body(r#"{ "error": "token was not present"}"#) ``` `フロー`​を使用して、アップストリームサービスへの要求の到達をブロックまたは許可できます。​`フロー`​は、次の 2 つの可能な値を持つ​`列挙型`​の値です。 - `Continue`​: 応答に転送されるオブジェクトを定義します。 - `Break`​: 要求を中止し、指定された応答を返します。 `フロー`​は次のように作成します。 ```Rust async fn request_filter(request_state: RequestState) -> Flow<()> { let header_state = request_state.into_headers_state().await; let handler = header_state.handler(); if handler.header("authorization").is_some() { Flow::Continue(()) } else { Flow::Break(Response::new(401) .with_headers(vec![("WWW-Authenticate".to_string(), "Bearer realm=\"oauth2\"".to_string())]) .with_body(r#"{ "error": "token was not present"}"#)) } } ```

proxy wasm​ のストリーミングの性質により、​headers_state.into_body_state​ 関数を待っている間に、要求の一部がアップストリームサービスに早期に到達する可能性があります。これを避けるには、ボディの読み取りを待たないことです。しかし、この方法はすべてのポリシーで可能であるとは限りません。ポリシーがボディを読み取る必要がある場合は、部分的な要求を無視するようにアップストリームを設定してください。

応答がクライアントに早期に返されないようにするには、要求と応答でのデータの共有を参照してください。
## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features) # 要求実行の停止 要求を捕捉して停止するには、ラップされる関数の ​`on_request`​ から ​`Response`​ オブジェクトを返します。 ```Rust Response::new(401) .with_headers(vec![("WWW-Authenticate".to_string(), "Bearer realm=\"oauth2\"".to_string())]) .with_body(r#"{ "error": "token was not present"}"#) ``` `フロー`​を使用して、アップストリームサービスへの要求の到達をブロックまたは許可できます。​`フロー`​は、次の 2 つの可能な値を持つ​`列挙型`​の値です。 - `Continue`​: 応答に転送されるオブジェクトを定義します。 - `Break`​: 要求を中止し、指定された応答を返します。 `フロー`​は次のように作成します。 ```Rust async fn request_filter(request_state: RequestState) -> Flow<()> { let header_state = request_state.into_headers_state().await; let handler = header_state.handler(); if handler.header("authorization").is_some() { Flow::Continue(()) } else { Flow::Break(Response::new(401) .with_headers(vec![("WWW-Authenticate".to_string(), "Bearer realm=\"oauth2\"".to_string())]) .with_body(r#"{ "error": "token was not present"}"#)) } } ```

proxy wasm​ のストリーミングの性質により、​headers_state.into_body_state​ 関数を待っている間に、要求の一部がアップストリームサービスに早期に到達する可能性があります。これを避けるには、ボディの読み取りを待たないことです。しかし、この方法はすべてのポリシーで可能であるとは限りません。ポリシーがボディを読み取る必要がある場合は、部分的な要求を無視するようにアップストリームを設定してください。

応答がクライアントに早期に返されないようにするには、要求と応答でのデータの共有を参照してください。
## [](#関連情報)関連情報 - [Rust でのカスタムポリシー機能の実装](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features) # 要求認証情報へのアクセス `Authentication`​ Injectable は、以下のインターフェースを提供します。 - 他のポリシーによって消費される認証データを伝播します。 - 別のポリシーで設定済みの認証データをコンシュームします。 データを共有するために、​`Authentication`​ は ​`AuthenticationHandler`​ という trait を実装します。 ```Rust pub trait AuthenticationHandler { fn authentication(&self) -> Option; fn set_authentication(&self, authentication: Option<&AuthenticationData>); } ``` `AuthenticationData`​ 構造体には、以下の認証データが含まれます。 ```Rust pub struct AuthenticationData { pub principal: Option, pub client_id: Option, pub client_name: Option, pub properties: Value, } ``` たとえば、次のコードは ​`Authentication`​ データを読み込み、​`client_id`​ と ​`client_name`​ を上書きして変更します。 ```Rust async fn request_filter(state: RequestState, authentication: Authentication) -> Flow<()> { let state = state.into_headers_state().await; let header_handler = state.handler(); let auth = authentication.authentication().unwrap_or_default(); let properties = auth.properties.as_object().cloned().unwrap_or_default(); let client_id = header_handler .header("custom_client_id_header") .unwrap_or_default(); let client_name = header_handler .header("custom_client_name_header") .unwrap_or_default(); let auth = AuthenticationData::new( auth.principal, Some(client_id), Some(client_name), properties ); authentication.set_authentication(Some(&auth)); Flow::Continue(()) } #[entrypoint] async fn configure(launcher: Launcher) -> Result<()> { let filter = on_request(|rs, auth| request_filter(rs, auth)); launcher.launch(filter).await?; Ok(()) } ``` ## [](#関連情報)関連情報 - [パラメーターの挿入](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-inject-parameters) # 要求認証情報へのアクセス `Authentication`​ Injectable は、以下のインターフェースを提供します。 - 他のポリシーによって消費される認証データを伝播します。 - 別のポリシーで設定済みの認証データをコンシュームします。 データを共有するために、​`Authentication`​ は ​`AuthenticationHandler`​ という trait を実装します。 ```Rust pub trait AuthenticationHandler { fn authentication(&self) -> Option; fn set_authentication(&self, authentication: Option<&AuthenticationData>); } ``` `AuthenticationData`​ 構造体には、以下の認証データが含まれます。 ```Rust pub struct AuthenticationData { pub principal: Option, pub client_id: Option, pub client_name: Option, pub properties: Value, } ``` たとえば、次のコードは ​`Authentication`​ データを読み込み、​`client_id`​ と ​`client_name`​ を上書きして変更します。 ```Rust async fn request_filter(state: RequestState, authentication: Authentication) -> Flow<()> { let state = state.into_headers_state().await; let header_handler = state.handler(); let auth = authentication.authentication().unwrap_or_default(); let properties = auth.properties.as_object().cloned().unwrap_or_default(); let client_id = header_handler .header("custom_client_id_header") .unwrap_or_default(); let client_name = header_handler .header("custom_client_name_header") .unwrap_or_default(); let auth = AuthenticationData::new( auth.principal, Some(client_id), Some(client_name), properties ); authentication.set_authentication(Some(&auth)); Flow::Continue(()) } #[entrypoint] async fn configure(launcher: Launcher) -> Result<()> { let filter = on_request(|rs, auth| request_filter(rs, auth)); launcher.launch(filter).await?; Ok(()) } ``` ## [](#関連情報)関連情報 - [パラメーターの挿入](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-inject-parameters) # 要求認証情報へのアクセス `Authentication`​ Injectable は、以下のインターフェースを提供します。 - 他のポリシーによって消費される認証データを伝播します。 - 別のポリシーで設定済みの認証データをコンシュームします。 データを共有するために、​`Authentication`​ は ​`AuthenticationHandler`​ という trait を実装します。 ```Rust pub trait AuthenticationHandler { fn authentication(&self) -> Option; fn set_authentication(&self, authentication: Option<&AuthenticationData>); } ``` `AuthenticationData`​ 構造体には、以下の認証データが含まれます。 ```Rust pub struct AuthenticationData { pub principal: Option, pub client_id: Option, pub client_name: Option, pub properties: Value, } ``` たとえば、次のコードは ​`Authentication`​ データを読み込み、​`client_id`​ と ​`client_name`​ を上書きして変更します。 ```Rust async fn request_filter(state: RequestState, authentication: Authentication) -> Flow<()> { let state = state.into_headers_state().await; let header_handler = state.handler(); let auth = authentication.authentication().unwrap_or_default(); let properties = auth.properties.as_object().cloned().unwrap_or_default(); let client_id = header_handler .header("custom_client_id_header") .unwrap_or_default(); let client_name = header_handler .header("custom_client_name_header") .unwrap_or_default(); let auth = AuthenticationData::new( auth.principal, Some(client_id), Some(client_name), properties ); authentication.set_authentication(Some(&auth)); Flow::Continue(()) } #[entrypoint] async fn configure(launcher: Launcher) -> Result<()> { let filter = on_request(|rs, auth| request_filter(rs, auth)); launcher.launch(filter).await?; Ok(()) } ``` ## [](#関連情報)関連情報 - [パラメーターの挿入](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-inject-parameters) # 遅延関数、周期関数、同期関数の設定 遅延、周期、および同期関数を有効にするために ​`Clock`​ を挿入してタイマーを作成します。各ポリシーでサポートされるタイマーは 1 つのみです。 各タイマーには、次の 2 つの関数があります。 ```rust pub async fn next_tick(&self) -> bool; pub async fn sleep(&self, interval: Duration) -> bool; ``` - `next_tick`​: タイマーが識別できる最小時間スリープします。 - `sleep`​: 目盛量スリープします。この場合、経過時間は指定した ​`Duration`​ 以上となります。たとえば、クロックの期間を 10 秒に設定した場合、​`timer.sleep(Duration::from_secs(1))`​ をコールすると 10 秒間スリープします。 どちらの関数も、指定した時間が経過すると ​`true`​ を返し、実行中にポリシーが適用解除または編集されると ​`false`​ を返します。 ## [](#タイマーを設定する)タイマーを設定する タイマーをポリシーに挿入するには、ポリシー設定関数に ​`Clock`​ を挿入し、期間を指定してタイマーを定義します。 ```rust #[entrypoint] async fn configure( launcher: Launcher, Configuration(bytes): Configuration, clock: Clock, // Inject the clock to be able to launch async tasks. client: HttpClient, ) -> Result<()> { // set the period between ticks of the timer. let timer = clock.period(Duration::from_secs(10)); ``` タイマーを挿入した後、その参照を ​`on_request`​ 関数と ​`on_response`​ 関数と共有して遅延関数の作成を開始します。 ```rust launcher .launch(on_request(|rs| request_filter(rs, &timer, &config))) .await?; ``` これで、次に示すように、​`on_request`​ 関数と ​`on_response`​ 関数でタイマー関数を待機できます。 ```rust let slept = timer.sleep(duration).await; let tick = timer.next_tick().await; ```
遅延関数を起動するポリシープロジェクトの例については、 スパイクポリシーの例​を参照してください。
## [](#非同期タスクを起動する)非同期タスクを起動する タイマーを使用して、要求フローとは関係なくタスクを実行します。非同期タスクを実行する手順は、次のとおりです。 1. `async`​ 関数内でタスクを定義します。 2. ポリシー設定関数で、関数をコールします。ただし、返される将来は待機しません。 3. ポリシー設定関数で、​`on_request`​ および ​`on_response`​ filter 関数を使用して ​`launch`​ 関数をコールします。ただし、返される将来は待機しません。 4. `join!`​ マクロを使用して、タスク関数と ​`launch`​ 関数の両方の将来を同時に待機します。
join​ マクロを使用するには、​cargo.toml​ ファイルに連動関係として 'futures' クレートを追加します。
各ワーカーは、タスクのコピーを実行します。関数内にループを設定して、周期タスクを実行します。たとえば、次のコード例は両方の関数を待機します。 ```rust let task = my_async_task(&timer, &config); let launched = launcher.launch(filter); let joined = join!(launched, task); ``` 次に示すように、​`my_async_task`​ 関数にループを追加すると周期タスクが作成されます。 ```rust async fn my_async_task(timer: &Timer, config: &Config) { // While the policy is still running. // Wait for the next cycle. while timer.next_tick().await { // Execute periodic task } } ``` 複数の非同期タスクを起動するには、次に示すようにタイマーの参照を ​`async`​ 関数に送信し、それらを ​`launch`​ タスクと結合します。 ```rust let task1 = my_async_task1(&timer, &config); let task2 = my_async_task2(&timer, &config); let launched = launcher.launch(filter); let joined = join!(launched, task1, task2); ```
非同期の周期タスクを起動するポリシープロジェクトの例については、 メトリクスポリシーの例​ を参照してください。
## [](#ワーカー間で非同期タスクを同期する)ワーカー間で非同期タスクを同期する PDK ​`LockBuilder`​ を使用してワーカーを同期します。ロックを使用すると、1 つの期間にタスクを完了するワーカーは 1 つのみになります。各ポリシーは、複数のロックをサポートします。 ロックは、ポリシーが使用制限のある HTTP サービスをコンシュームする場合に便利です。1 つのワーカーがデータをフェッチし、そのデータを他のワーカーと共有して、サービス要求を減らすことができます。 ロックを設定する手順は、次のとおりです。 1. `LockBuilder`​ をポリシー設定関数に挿入します。 ```rust #[entrypoint] async fn configure( launcher: Launcher, Configuration(bytes): Configuration, clock: Clock, // Inject the clock to be able to launch async tasks. lock: LockBuilder, // Inject the lock to be able to synchronize the workers. ) -> Result<()> { ``` 2. ロックを設定し、その参照を非同期関数と共有します。 ```rust let lock = lock .new(ID.to_string()) .expiration(Duration::from_secs(20)) .build(); let task = my_async_task(&timer, &lock); ``` 非同期タスクがタスク内で追加の ​`async`​ 関数コールを実行する場合は、ロックの ​`expiration`​ を、ネストされた ​`async`​ 関数コールを完了するために必要な合計時間よりも長く設定します。 3. 非同期関数内で、目的のタスクを実行する前にロックを取得します。他のワーカーにロックが設定されていない場合、現在のワーカーがロックを取得します。それ以外の場合は、次に示すようにタスクの実行を省略し、次のタスクループを待機する必要があります。 ```rust async fn my_async_task( timer: &Timer, lock: &TryLock, ) { while timer.next_tick().await { if let Some(acquired) = lock.try_lock() { // execute task. } } } ``` ロックを取得した後、結果を待機する必要があるコードを実行する場合は、​`refresh_lock`​ 関数をコールして、ロックの有効期限が切れていないことを確認する必要があります。ロックの有効期限が切れている場合、ワーカーは無応答と見なされます。別のワーカーが同じタスク実行を実行しているため、タスクの実行を中止します。
非同期の周期タスクを同期し、ワーカー間で情報を共有するポリシープロジェクトの例については、 ブロックポリシーの例​を参照してください。
## [](#関連情報)関連情報 - [パラメーターの挿入](https://docs.mulesoft.com/jp/pdk/1.2/policies-pdk-configure-features-inject-parameters) # 遅延関数、周期関数、同期関数の設定 遅延、周期、および同期関数を有効にするために ​`Clock`​ を挿入してタイマーを作成します。各ポリシーでサポートされるタイマーは 1 つのみです。 各タイマーには、次の非同期メソッドがあります。 ```rust pub async fn next_tick(&self) -> bool; pub async fn sleep(&self, interval: Duration) -> bool; ``` - `next_tick`​: タイマーが識別できる最小時間スリープします。 - `sleep`​: 目盛量スリープします。この場合、経過時間は指定した ​`Duration`​ 以上となります。たとえば、クロックの期間を 10 秒に設定した場合、​`timer.sleep(Duration::from_secs(1))`​ をコールすると 10 秒間スリープします。 どちらの関数も、指定した時間が経過すると ​`true`​ を返し、実行中にポリシーが適用解除または編集されると ​`false`​ を返します。 ## [](#タイマーを設定する)タイマーを設定する タイマーをポリシーに挿入するには、ポリシー設定関数に ​`Clock`​ を挿入し、期間を指定してタイマーを定義します。 ```rust #[entrypoint] async fn configure( launcher: Launcher, Configuration(bytes): Configuration, clock: Clock, // Inject the clock to be able to launch async tasks. client: HttpClient, ) -> Result<()> { // set the period between ticks of the timer. let timer = clock.period(Duration::from_secs(10)); ``` タイマーを挿入した後、その参照を ​`on_request`​ 関数と ​`on_response`​ 関数と共有して遅延関数の作成を開始します。 ```rust launcher .launch(on_request(|rs| request_filter(rs, &timer, &config))) .await?; ``` これで、次に示すように、​`on_request`​ 関数と ​`on_response`​ 関数でタイマー関数を待機できます。 ```rust let slept = timer.sleep(duration).await; let tick = timer.next_tick().await; ```
遅延関数を起動するポリシープロジェクトの例については、 スパイクポリシーの例​を参照してください。
## [](#クロックをリリースする)クロックをリリースする 異なるティック周期で新しいタイマーを作成するには、次のメソッドを使用して​`クロック`​をリリースします。 ```rust pub fn release(self) -> Clock; ``` 次のコードスニペットでは、タイマーを作成してからクロックをリリースし、新しいタイマーを作成します。 ```rust // Configure an initial tick period. let initial_timer = clock.period(Duration::from_millis(500)); some_initial_task(&other_timer).await; // Configure another tick period. let other_timer = initial_timer.release().period(Duration::from_millis(3000); some_other_task(&other_timer).await; // Get the clock back. let clock = other_timer.release(); ``` ## [](#非同期タスクを起動する)非同期タスクを起動する タイマーを使用して、要求フローとは関係なくタスクを実行します。非同期タスクを実行する手順は、次のとおりです。 1. `async`​ 関数内でタスクを定義します。 2. ポリシー設定関数で、関数をコールします。ただし、返される将来は待機しません。 3. ポリシー設定関数で、​`on_request`​ および ​`on_response`​ filter 関数を使用して ​`launch`​ 関数をコールします。ただし、返される将来は待機しません。 4. `join!`​ マクロを使用して、タスク関数と ​`launch`​ 関数の両方の将来を同時に待機します。
join​ マクロを使用するには、​cargo.toml​ ファイルに連動関係として 'futures' クレートを追加します。
各ワーカーは、タスクのコピーを実行します。関数内にループを設定して、周期タスクを実行します。たとえば、次のコード例は両方の関数を待機します。 ```rust let task = my_async_task(&timer, &config); let launched = launcher.launch(filter); let joined = join!(launched, task); ``` 次に示すように、​`my_async_task`​ 関数にループを追加すると周期タスクが作成されます。 ```rust async fn my_async_task(timer: &Timer, config: &Config) { // While the policy is still running. // Wait for the next cycle. while timer.next_tick().await { // Execute periodic task } } ``` 複数の非同期タスクを起動するには、次に示すようにタイマーの参照を ​`async`​ 関数に送信し、それらを ​`launch`​ タスクと結合します。 ```rust let task1 = my_async_task1(&timer, &config); let task2 = my_async_task2(&timer, &config); let launched = launcher.launch(filter); let joined = join!(launched, task1, task2); ```
非同期の周期タスクを起動するポリシープロジェクトの例については、 メトリクスポリシーの例​ を参照してください。
## [](#ワーカー間で非同期タスクを同期する)ワーカー間で非同期タスクを同期する PDK ​`LockBuilder`​ を使用してワーカーを同期します。ロックを使用すると、1 つの期間にタスクを完了するワーカーは 1 つのみになります。各ポリシーは、複数のロックをサポートします。 ロックは、ポリシーが使用制限のある HTTP サービスをコンシュームする場合に便利です。1 つのワーカーがデータをフェッチし、そのデータを他のワーカーと共有して、サービス要求を減らすことができます。 ロックを設定する手順は、次のとおりです。 1. `LockBuilder`​ をポリシー設定関数に挿入します。 ```rust #[entrypoint] async fn configure( launcher: Launcher, Configuration(bytes): Configuration, clock: Clock, // Inject the clock to be able to launch async tasks. lock: LockBuilder, // Inject the lock to be able to synchronize the workers. ) -> Result<()> { ``` 2. ロックを設定し、その参照を非同期関数と共有します。 ```rust let lock = lock .new(ID.to_string()) .expiration(Duration::from_secs(20)) .build(); let task = my_async_task(&timer, &lock); ``` 非同期タスクがタスク内で追加の ​`async`​ 関数コールを実行する場合は、ロックの ​`expiration`​ を、ネストされた ​`async`​ 関数コールを完了するために必要な合計時間よりも長く設定します。 3. 非同期関数内で、目的のタスクを実行する前にロックを取得します。他のワーカーにロックが設定されていない場合、現在のワーカーがロックを取得します。それ以外の場合は、次に示すようにタスクの実行を省略し、次のタスクループを待機する必要があります。 ```rust async fn my_async_task( timer: &Timer, lock: &TryLock, ) { while timer.next_tick().await { if let Some(acquired) = lock.try_lock() { // execute task. } } } ``` ロックを取得した後、結果を待機する必要があるコードを実行する場合は、​`refresh_lock`​ 関数をコールして、ロックの有効期限が切れていないことを確認する必要があります。ロックの有効期限が切れている場合、ワーカーは無応答と見なされます。別のワーカーが同じタスク実行を実行しているため、タスクの実行を中止します。
非同期の周期タスクを同期し、ワーカー間で情報を共有するポリシープロジェクトの例については、 ブロックポリシーの例​を参照してください。
## [](#関連情報)関連情報 - [パラメーターの挿入](https://docs.mulesoft.com/jp/pdk/1.3/policies-pdk-configure-features-inject-parameters) # 遅延関数、周期関数、同期関数の設定 遅延、周期、および同期関数を有効にするために ​`Clock`​ を挿入してタイマーを作成します。各ポリシーでサポートされるタイマーは 1 つのみです。 各タイマーには、次の非同期メソッドがあります。 ```rust pub async fn next_tick(&self) -> bool; pub async fn sleep(&self, interval: Duration) -> bool; ``` - `next_tick`​: タイマーが識別できる最小時間スリープします。 - `sleep`​: 目盛量スリープします。この場合、経過時間は指定した ​`Duration`​ 以上となります。たとえば、クロックの期間を 10 秒に設定した場合、​`timer.sleep(Duration::from_secs(1))`​ をコールすると 10 秒間スリープします。 どちらの関数も、指定した時間が経過すると ​`true`​ を返し、実行中にポリシーが適用解除または編集されると ​`false`​ を返します。 ## [](#タイマーを設定する)タイマーを設定する タイマーをポリシーに挿入するには、ポリシー設定関数に ​`Clock`​ を挿入し、期間を指定してタイマーを定義します。 ```rust #[entrypoint] async fn configure( launcher: Launcher, Configuration(bytes): Configuration, clock: Clock, // Inject the clock to be able to launch async tasks. client: HttpClient, ) -> Result<()> { // set the period between ticks of the timer. let timer = clock.period(Duration::from_secs(10)); ``` タイマーを挿入した後、その参照を ​`on_request`​ 関数と ​`on_response`​ 関数と共有して遅延関数の作成を開始します。 ```rust launcher .launch(on_request(|rs| request_filter(rs, &timer, &config))) .await?; ``` これで、次に示すように、​`on_request`​ 関数と ​`on_response`​ 関数でタイマー関数を待機できます。 ```rust let slept = timer.sleep(duration).await; let tick = timer.next_tick().await; ```
遅延関数を起動するポリシープロジェクトの例については、 スパイクポリシーの例​を参照してください。
## [](#クロックをリリースする)クロックをリリースする 異なるティック周期で新しいタイマーを作成するには、次のメソッドを使用して​`クロック`​をリリースします。 ```rust pub fn release(self) -> Clock; ``` 次のコードスニペットでは、タイマーを作成してからクロックをリリースし、新しいタイマーを作成します。 ```rust // Configure an initial tick period. let initial_timer = clock.period(Duration::from_millis(500)); some_initial_task(&other_timer).await; // Configure another tick period. let other_timer = initial_timer.release().period(Duration::from_millis(3000); some_other_task(&other_timer).await; // Get the clock back. let clock = other_timer.release(); ``` ## [](#非同期タスクを起動する)非同期タスクを起動する タイマーを使用して、要求フローとは関係なくタスクを実行します。非同期タスクを実行する手順は、次のとおりです。 1. `async`​ 関数内でタスクを定義します。 2. ポリシー設定関数で、関数をコールします。ただし、返される将来は待機しません。 3. ポリシー設定関数で、​`on_request`​ および ​`on_response`​ filter 関数を使用して ​`launch`​ 関数をコールします。ただし、返される将来は待機しません。 4. `join!`​ マクロを使用して、タスク関数と ​`launch`​ 関数の両方の将来を同時に待機します。
join​ マクロを使用するには、​cargo.toml​ ファイルに連動関係として 'futures' クレートを追加します。
各ワーカーは、タスクのコピーを実行します。関数内にループを設定して、周期タスクを実行します。たとえば、次のコード例は両方の関数を待機します。 ```rust let task = my_async_task(&timer, &config); let launched = launcher.launch(filter); let joined = join!(launched, task); ``` 次に示すように、​`my_async_task`​ 関数にループを追加すると周期タスクが作成されます。 ```rust async fn my_async_task(timer: &Timer, config: &Config) { // While the policy is still running. // Wait for the next cycle. while timer.next_tick().await { // Execute periodic task } } ``` 複数の非同期タスクを起動するには、次に示すようにタイマーの参照を ​`async`​ 関数に送信し、それらを ​`launch`​ タスクと結合します。 ```rust let task1 = my_async_task1(&timer, &config); let task2 = my_async_task2(&timer, &config); let launched = launcher.launch(filter); let joined = join!(launched, task1, task2); ```
非同期の周期タスクを起動するポリシープロジェクトの例については、 メトリクスポリシーの例​ を参照してください。
## [](#ワーカー間で非同期タスクを同期する)ワーカー間で非同期タスクを同期する PDK ​`LockBuilder`​ を使用してワーカーを同期します。ロックを使用すると、1 つの期間にタスクを完了するワーカーは 1 つのみになります。各ポリシーは、複数のロックをサポートします。 ロックは、ポリシーが使用制限のある HTTP サービスをコンシュームする場合に便利です。1 つのワーカーがデータをフェッチし、そのデータを他のワーカーと共有して、サービス要求を減らすことができます。 ロックを設定する手順は、次のとおりです。 1. `LockBuilder`​ をポリシー設定関数に挿入します。 ```rust #[entrypoint] async fn configure( launcher: Launcher, Configuration(bytes): Configuration, clock: Clock, // Inject the clock to be able to launch async tasks. lock: LockBuilder, // Inject the lock to be able to synchronize the workers. ) -> Result<()> { ``` 2. ロックを設定し、その参照を非同期関数と共有します。 ```rust let lock = lock .new(ID.to_string()) .expiration(Duration::from_secs(20)) .build(); let task = my_async_task(&timer, &lock); ``` 非同期タスクがタスク内で追加の ​`async`​ 関数コールを実行する場合は、ロックの ​`expiration`​ を、ネストされた ​`async`​ 関数コールを完了するために必要な合計時間よりも長く設定します。 3. 非同期関数内で、目的のタスクを実行する前にロックを取得します。他のワーカーにロックが設定されていない場合、現在のワーカーがロックを取得します。それ以外の場合は、次に示すようにタスクの実行を省略し、次のタスクループを待機する必要があります。 ```rust async fn my_async_task( timer: &Timer, lock: &TryLock, ) { while timer.next_tick().await { if let Some(acquired) = lock.try_lock() { // execute task. } } } ``` ロックを取得した後、結果を待機する必要があるコードを実行する場合は、​`refresh_lock`​ 関数をコールして、ロックの有効期限が切れていないことを確認する必要があります。ロックの有効期限が切れている場合、ワーカーは無応答と見なされます。別のワーカーが同じタスク実行を実行しているため、タスクの実行を中止します。
非同期の周期タスクを同期し、ワーカー間で情報を共有するポリシープロジェクトの例については、 ブロックポリシーの例​を参照してください。
## [](#関連情報)関連情報 - [パラメーターの挿入](https://docs.mulesoft.com/jp/pdk/1.4/policies-pdk-configure-features-inject-parameters)