カスタム変換器を開発する

以下でサポートされています。

カスタムの Python ベースの変換関数と論理演算子を IDE 内で直接作成し、複雑で汎用性の高いユースケースのハンドブックで使用できます。

拡張機能パック

拡張機能パックは、カスタム変換関数と論理演算子のコンテナとして機能するように設計された、特殊な統合タイプです。標準の統合とは異なり、拡張機能パックではインスタンス構成は必要ありません。IDE から直接作成できます。

拡張機能パックのベスト プラクティス

  • 統合: 1 つのメイン拡張機能パックを作成し、複数の変換関数または論理演算子を追加します。
  • 分離: メインパックと競合する可能性のある別の Python ライブラリ(依存関係)のセットが必要な場合は、新しい拡張パックを作成します。

拡張機能パックを作成する

新しい拡張パックを作成する手順は次のとおりです。

  1. [Automation] > [IDE] に移動します。
  2. [add Create New Item] をクリックします。
  3. プルダウンから [Extension Pack] を選択します。
  4. 拡張機能パックに一意の名前を指定します。
  5. [保存] をクリックします。

依存関係をアップロードする

標準の統合と同様に、拡張パックは Python ライブラリを管理できる仮想環境で実行されます。

ライブラリを管理する手順は次のとおりです。

  1. IDE で拡張機能パックの設定を開きます。
  2. 必要な Python ライブラリを PyPi から追加するか、パソコンからアップロードします。

これらの依存関係は、この特定の拡張機能パックに含まれるすべての変換関数と論理演算子で使用できます。

インポートとエクスポート

拡張機能パックは、IDE インターフェース内で直接手動でインポートおよびエクスポートできます。

カスタム Transformer

カスタム変換は、式ビルダーの事前構築済み関数を拡張するユーザー定義の Python 関数です。IDE 内で直接作成してデータを抽出して操作できます。また、既存の組み込み関数とともに使用することもできます。

カスタム変換器を作成する

新しいカスタム変換を定義する手順は次のとおりです。

  1. IDE で、ターゲット拡張機能パックを見つけます。
  2. ターゲット拡張機能パックを選択して、パックに新しいアイテムを追加します。
  3. [カスタム変換関数] を選択します。
  4. 名前を付けてください
  5. (省略可)説明を追加します。これは、Expression Builder でカスタム変換ツールにカーソルを合わせると表示されます。
  6. Python を使用してスクリプト ロジックを定義します。提供されているデフォルトのテンプレートを出発点として使用できます。
    • スクリプトには、事前定義されたテンプレートに示されているように、main 関数を含める必要があります。
    • スクリプトは、SDK の end 関数を使用して、式ビルダーに結果を返す必要があります。
    • カスタム変換ツールの入力は、さまざまな型(文字列やリストなど)にできます。main 関数で、想定される型に変換してください。
    • トランスフォーマーの IDE 内で使用できるのは、SDK メソッドのサブセットのみです。
      • transformer.extract_param("ParamName"): 入力値を取得します。
      • transformer.LOGGER: デバッグ用のログを書き込みます。
      • transformer.end(result): 変換された値を返します。
  7. パラメータを作成します。
    • 各カスタム変換関数には、デフォルトの Input パラメータが含まれています。このパラメータは、関数が適用されるプレースホルダである入力データを表します。このパラメータは削除できません。
    • さらに、関数内で使用するオプション パラメータを追加することもできます。
  8. ドキュメント(省略可): Expression Builder のプロダクト内ドキュメントを定義します。
    • 想定される入力: この変換関数が受け取ることを想定しているデータ型(「文字列」や「文字列のリスト」など)を記述します。
    • Expected Output: この変換ツールに対して関数が返すことが想定されるデータ型を記述します(例: 「boolean」)。
    • 使用例: 関数を呼び出す方法の例(if_empty("new_value") など)を指定します。

カスタム変換関数のロジックは、ハンドブックで使用する前に IDE 内で直接テストできます。これにより、Python スクリプトがさまざまな入力タイプとパラメータを正しく処理し、想定される結果を返すことを確認できます。

タイムアウト

  • デフォルトのタイムアウト: 1 分。
  • 最大タイムアウト: 3 分。

Expression Builder でカスタム変換器を使用する

保存すると、カスタム変換ツールが組み込み関数とともに Expression Builder の関数リストに表示されます。これらは ExtensionPackName.TransformerName の形式で識別されます。関数にカーソルを合わせると、パラメータの説明から生成されたドキュメントが表示されます。

すべてのプレースホルダ(JSON と JSON 以外)のサポート

式ビルダーは、JSON 以外の結果を含む、Playbook デザイナーで公開されているすべてのプレースホルダをサポートしています。

JSON 以外のプレースホルダの場合:

  • Expression Builder にサンプルデータを手動で入力して、文字列、リスト(カンマ区切り値)、JSON などのさまざまな入力タイプに対してロジックをテストできます。
  • 入力タイプでテストしても、プレースホルダが実行時にその特定のタイプを返すとは限りません。
  • ほとんどのプレースホルダは文字列として解決されますが、数量に基づいて文字列またはリストとして解決される特定のタイプ(entity.identifier など)は例外です。これらのタイプについては、常に入力をリストとして扱うことをおすすめします。

エラー処理

カスタム変換関数が実行中にエラーを検出すると、その変換関数を使用するハンドブック アクションが失敗します。Python スクリプトによって生成された特定のエラー メッセージが、ハンドブックの実行ビュー内の画面に表示されるため、ロジックを直接トラブルシューティングできます。

カスタム論理演算子

カスタム論理演算子を使用すると、値を比較するための独自のブール論理を定義できます。

カスタムの論理演算子を作成する

新しい論理演算子を定義する手順は次のとおりです。

  1. IDE で、ターゲットの拡張機能パックを見つけます。
  2. [カスタム論理演算子] を選択します。
  3. 名前を付けてください
  4. 省略可: プレイブック デザイナーの論理演算子メニューの説明を追加します。
  5. 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 分。

ハンドブックで使用する

カスタム論理演算子は、[ハンドブックの条件]、[前のアクションの条件]、[エンティティの選択] の演算子メニューに表示されます。

カスタム論理演算子は、標準演算子(「等しい」や「含む」など)とともに選択できます。

エラー処理

カスタム論理演算子関数が実行中にエラーが発生すると、その演算子を使用するハンドブックの条件またはステップが失敗します。Python スクリプトから返されたエラー メッセージは、トラブルシューティングに役立つように、ハンドブックの実行ビューに表示されます。

制限事項

  • カスタム変換関数と論理演算子は、トリガーまたは Webhook ではサポートされていません。

さらにサポートが必要な場合 コミュニティ メンバーや Google SecOps のプロフェッショナルから回答を得ることができます。