カスタム変換器を開発する
カスタムの Python ベースの変換関数と論理演算子を IDE 内で直接作成し、複雑で汎用性の高いユースケースのハンドブックで使用できます。
拡張機能パック
拡張機能パックは、カスタム変換関数と論理演算子のコンテナとして機能するように設計された特殊な統合タイプです。標準のインテグレーションとは異なり、拡張機能パックではインスタンス構成は必要なく、IDE から直接作成できます。
拡張機能パックのベスト プラクティス
- 統合: 1 つのメイン拡張機能パックを作成し、複数の変換関数または論理演算子を追加します。
- 分離: メインパックと競合する可能性のある別の Python ライブラリ（依存関係）のセットが必要な場合は、新しい拡張パックを作成します。
拡張機能パックを作成する
新しい拡張機能パックを作成する手順は次のとおりです。
- [レスポンス] > [IDE] に移動します。
- [add] [Create New Item] をクリックします。
- プルダウンから [拡張機能パック] を選択します。
- Extension Pack に一意の名前を指定します。
- [保存] をクリックします。
依存関係をアップロードする
標準の統合と同様に、拡張機能パックは Python ライブラリを管理できる仮想環境で実行されます。
ライブラリを管理する手順は次のとおりです。
- IDE で Extension Pack の設定を開きます。
- 必要な Python ライブラリを PyPi から追加するか、パソコンからアップロードします。
これらの依存関係は、この特定の拡張機能パックに含まれるすべての変換関数と論理演算子で使用できます。
インポートとエクスポート
拡張機能パックは、IDE インターフェース内で直接手動でインポートおよびエクスポートできます。
カスタム Transformer
カスタム変換は、式ビルダーの事前構築済み関数を拡張するユーザー定義の Python 関数です。これらは IDE 内で直接作成してデータを抽出および操作でき、既存の組み込み関数とともに使用できます。
カスタム変換器を作成する
新しいカスタム変換を定義する手順は次のとおりです。
- IDE で、対象の拡張機能パックを見つけます。
- 新しいアイテムを追加するターゲット拡張機能パックを選択します。
- [カスタム変換関数] を選択します。
- 名前を付けてください
- （省略可）説明を追加します。これは、式ビルダーでカスタム変換ツールにカーソルを合わせると表示されます。
- Python を使用してスクリプト ロジックを定義します。提供されているデフォルト テンプレートを起点として使用できます。
- スクリプトには、事前定義されたテンプレートに示されているように、
main関数を含める必要があります。 - スクリプトは、SDK の
end関数を使用して、式ビルダーに結果を返す必要があります。 - カスタム トランスフォーマーの入力は、さまざまな型（文字列やリストなど）にできます。
main関数で、想定される型に変換してください。 - IDE 内のトランスフォーマーでは、SDK メソッドのサブセットのみを使用できます。
transformer.extract_param("ParamName"): 入力値を取得します。transformer.LOGGER: デバッグ用のログを書き込みます。transformer.end(result): 変換された値を返します。
- スクリプトには、事前定義されたテンプレートに示されているように、
- パラメータを作成します。
- 各カスタム変換関数には、デフォルトの Input パラメータが含まれています。このパラメータは入力データを表します。これは、関数が適用するプレースホルダです。このパラメータは削除できません。
- また、関数内で使用するオプション パラメータを追加することもできます。
- ドキュメント（省略可）: 式ビルダーのプロダクト内ドキュメントを定義します。
- 想定される入力: この変換関数が受け取ることを想定しているデータ型を説明します（「文字列」や「文字列のリスト」など）。
- Expected Output: この変換関数が返すことが想定されるデータ型を説明します（例: 「boolean」）。
- 使用例: 関数を呼び出す方法の例（
if_empty("new_value")など）を指定します。
カスタム変換関数のロジックは、プレイブックで使用する前に IDE 内で直接テストできます。これにより、Python スクリプトがさまざまな入力タイプとパラメータを正しく処理し、想定される結果を返すことを確認できます。
タイムアウト
- デフォルトのタイムアウト: 1 分。
- 最大タイムアウト: 3 分。
式ビルダーでカスタム変換器を使用する
保存されたカスタム変換は、組み込み関数とともに Expression Builder の関数リストに表示されます。形式 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 スクリプトから返されたエラー メッセージは、トラブルシューティングに役立つように、プレイブックの実行ビューに表示されます。
制限事項
- カスタム変換関数と論理演算子は、トリガーまたは Webhook ではサポートされていません。
さらにサポートが必要な場合 コミュニティ メンバーや Google SecOps のプロフェッショナルから回答を得ることができます。