カスタム変換関数と論理演算子
IDE 内でカスタムの Python ベースの変換関数と論理演算子を直接作成し、複雑で汎用性の高いユースケースのハンドブックで使用できます。
拡張機能パック
拡張機能パックは、カスタム変換関数と論理演算子のコンテナとして機能するように設計された特殊な統合タイプです。標準のインテグレーションとは異なり、拡張機能パックではインスタンス構成は必要なく、IDE から直接作成できます。
拡張機能パックに関するベスト プラクティス
- 統合: 1 つのメイン拡張機能パックを作成し、複数の変換関数または論理演算子を追加します。
- 分離: メイン パックと競合する可能性のある別の Python ライブラリ（依存関係）のセットが必要な場合は、新しい拡張機能パックを作成します。
拡張機能パックを作成する
新しい拡張機能パックを作成する手順は次のとおりです。
- [レスポンス>IDE] に移動します。
- add [Create New Item] をクリックします。
- プルダウンから [Extension Pack] を選択します。
- 拡張機能パックに一意の名前を指定します。
- [保存] をクリックします。
依存関係をアップロードする
標準の統合と同様に、拡張機能パックは Python ライブラリを管理できる仮想環境で実行されます。
ライブラリを管理する手順は次のとおりです。
- IDE で [Extension Pack settings] を開きます。
- PyPi から必要な Python ライブラリを追加するか、パソコンからアップロードします。
これらの依存関係は、この特定の拡張機能パックに含まれるすべての変換と論理演算子で使用できます。
インポートとエクスポート
IDE インターフェース内で拡張機能パックを手動でインポートおよびエクスポートできます。
カスタム トランスフォーマー
カスタム トランスフォーマーは、式ビルダーの組み込み関数を拡張するユーザー定義の Python 関数です。IDE 内で直接作成してデータを抽出、操作できます。また、既存の組み込み関数と組み合わせて使用することもできます。
カスタム変換器を作成する
新しいカスタム トランスフォーマーを定義する手順は次のとおりです。
- IDE で、対象の拡張機能パックを見つけます。
- 新しいアイテムを追加するターゲット拡張機能パックを選択します。
- [カスタム変換関数] を選択します。
- 名前を付けてください
- （省略可）説明を追加します。これは、式ビルダーでカスタム トランスフォーマーにカーソルを合わせたときに表示されます。
- Python を使用してスクリプト ロジックを定義します。提供されているデフォルトのテンプレートを起点として使用できます。
- スクリプトには、事前定義されたテンプレートに示すように、
main関数を含める必要があります。 - スクリプトは、SDK の
end関数を使用して、式ビルダーに結果を返す必要があります。 - カスタム トランスフォーマーの入力は、さまざまな型（文字列やリストなど）にできます。
main関数で、想定される型に変換してください。 - IDE 内のトランスフォーマーで使用できる SDK メソッドは、次のサブセットのみです。
transformer.extract_param("ParamName"): 入力値を取得します。transformer.LOGGER: デバッグ用のログを書き込みます。transformer.end(result): 変換された値を返します。
- スクリプトには、事前定義されたテンプレートに示すように、
- パラメータを作成します。
- 各カスタム トランスフォーマー関数には、デフォルトの Input パラメータが含まれています。このパラメータは、関数が適用するプレースホルダである入力データを表します。このパラメータは削除できません。
- また、関数内で使用するオプション パラメータを追加することもできます。
- ドキュメント（省略可）: 式ビルダーのプロダクト内ドキュメントを定義します。
- Expected Input: この変換関数が受け取ることを想定しているデータ型（「String」や「List of strings」など）を説明します。
- Expected Output: この変換関数が返すことが想定されるデータ型を説明します（例: 「boolean」）。
- 使用例: 関数の呼び出し方法の例（
if_empty("new_value")など）を示します。
カスタム変換関数のロジックは、プレイブックで使用する前に IDE 内で直接テストできます。これにより、Python スクリプトがさまざまな入力タイプとパラメータを正しく処理し、期待どおりの結果を返すことを確認できます。
タイムアウト
- デフォルトのタイムアウト: 1 分。
- 最大タイムアウト: 3 分。
式ビルダーでカスタム変換器を使用する
保存すると、カスタム トランスフォーマーが式ビルダーの関数リストに組み込み関数とともに表示されます。形式 ExtensionPackName.TransformerName で識別されます。関数にカーソルを合わせると、パラメータの説明から生成されたドキュメントが表示されます。
すべてのプレースホルダ（JSON と非 JSON）のサポート
式ビルダーは、JSON 以外の結果を含め、Playbook デザイナーで公開されているすべてのプレースホルダをサポートしています。
JSON 以外のプレースホルダの場合:
- 式ビルダーにサンプルデータを手動で入力して、文字列、リスト（カンマ区切り値）、JSON など、さまざまな入力タイプに対してロジックをテストできます。
- 入力型でテストしても、プレースホルダが実行時にその特定の型を返すとは限りません。
- ほとんどのプレースホルダは文字列として解決されますが、数量に基づいて文字列またはリストとして解決される特定の型（
entity.identifierなど）は例外です。このような型については、常に入力をリストとして扱うことをおすすめします。
エラー処理
カスタム変換関数が実行中にエラーを検出すると、その変換関数を使用するプレイブック アクションは失敗します。Python スクリプトによって生成された特定のエラー メッセージが、プレイブック実行ビューの画面に表示されるため、ロジックを直接トラブルシューティングできます。
カスタム論理演算子
カスタム論理演算子を使用すると、値を比較するための独自のブール論理を定義できます。
カスタム論理演算子を作成する
新しい論理演算子を定義する手順は次のとおりです。
- IDE で、ターゲットの拡張機能パックを見つけます。
- [カスタム論理演算子] を選択します。
- 名前を付けてください
- 省略可: Playbook デザイナーで、論理演算子メニューの説明を追加します。
- Python を使用してスクリプト ロジックを定義します。提供されている事前定義テンプレートを起点として使用できます。
- スクリプトには
main関数を含める必要があります。 - スクリプトは、SDK の
end関数を使用して、条件にブール値の結果を返す必要があります。 - IDE 内の論理演算子で使用できる SDK メソッドは、サブセットのみです。
logical_operator.extract_param("ParamName"): 入力値を取得します。logical_operator.LOGGER: デバッグ用のログを書き込みます。logical_operator.end(result): 結果はブール値（trueまたはfalse）です。
- スクリプトには
カスタム論理演算子のロジックは、IDE 内で直接テストできます。これにより、引数のテスト値を入力し、定義した条件に基づいて関数が正しいブール値（True または False）の結果を返すことを確認できます。
パラメータ
カスタム論理演算子は、[左側]（必須、編集不可）と [右側]（任意、ユーザーが無効にできる）の 2 つのパラメータを受け取ります。
- 例 1:
if [left side] not in [right side]。 - 例 2:
if [left side] is greater than 80（右側なし）。
タイムアウト
- デフォルトのタイムアウト: 1 分。
- 最大タイムアウト: 3 分。
ハンドブックで使用する
カスタム論理演算子は、[Playbook Conditions]、[Previous Action Conditions]、[Entity Selection] の演算子メニューに表示されます。
カスタム論理演算子は、標準演算子（「等しい」や「含む」など）とともに選択できます。
エラー処理
カスタム論理演算子関数が実行中にエラーを検出すると、その演算子を使用しているプレイブックの条件またはステップは失敗します。Python スクリプトから返されたエラー メッセージは、トラブルシューティングに役立つように、プレイブックの実行ビューに表示されます。
制限事項
- カスタム変換関数と論理演算子は、トリガーまたはウェブフックではサポートされていません。
さらにサポートが必要な場合 コミュニティ メンバーや Google SecOps のプロフェッショナルから回答を得ることができます。