カスタム変換器を開発する
IDE 内でカスタムの Python ベースの変換関数と論理演算子を直接作成し、複雑で汎用性の高いユースケースのハンドブックで使用できます。
拡張機能パック
拡張機能パック は、カスタム変換関数と論理演算子のコンテナとして機能するように設計された特殊な統合タイプです。標準の統合とは異なり、拡張機能パックではインスタンス構成は不要で、IDE から直接作成できます。
拡張機能パックに関するおすすめの方法
- 統合: 1 つのメインの拡張機能パックを作成し、複数の 変換関数または論理演算子を追加します。
- 分離: メインパックと競合する可能性のある別の Python ライブラリ（依存関係）のセットが必要な場合は、新しい拡張機能パックを作成します。
拡張機能パックを作成する
新しい拡張機能パックを作成する手順は次のとおりです。
- レスポンス > IDE に移動します。
- [add] [**新規作成**] をクリックします。
- プルダウンから [拡張機能パック] を選択します。
- 拡張機能パックの一意の名前 を指定します。
- [保存] をクリックします。
依存関係をアップロードする
標準の統合と同様に、拡張機能パックは Python ライブラリを管理できる仮想環境で実行されます。
ライブラリを管理する手順は次のとおりです。
- IDE で拡張機能パックの設定 を開きます。
- PyPi から必要な Python ライブラリを追加するか、 パソコンからアップロードします。
これらの依存関係は、この特定の拡張機能パックに含まれるすべての変換器と論理演算子で使用できます。
インポートとエクスポート
拡張機能パックは、IDE インターフェース内で直接手動でインポートおよびエクスポートできます。
カスタム変換器
カスタム変換器 は、Expression Builder の組み込み関数を拡張するユーザー定義の Python 関数です。IDE 内で直接作成してデータを抽出、操作できます。また、既存の組み込み関数と組み合わせて使用することもできます。
カスタム変換器を作成する
新しいカスタム変換器を定義する手順は次のとおりです。
- IDE で、ターゲットの拡張機能パックを見つけます。
- ターゲットの拡張機能パックを選択して、パックの下に新しいアイテムを追加します。
- [カスタム変換関数] を選択します。
- 名前を付けてください
- 省略可: 説明を追加します。これは、Expression Builder で カスタム変換器にカーソルを合わせると表示されます。
- Python を使用してスクリプト ロジックを定義します。提供されているデフォルト
テンプレートを出発点として使用できます。
- スクリプトには、
main関数を 事前定義されたテンプレート に示すように含める必要があります。 - スクリプトは、SDK の
end関数を使用して、結果を Expression Builder に返す必要があります。 - カスタム変換器の入力は、さまざまなタイプ
（文字列やリストなど）にできます。`
main` 関数で想定される タイプに変換してください。 - IDE 内の変換器では、SDK メソッドのサブセットのみを使用できます。
変換器:
transformer.extract_param("ParamName"): 入力値を取得します。transformer.LOGGER: デバッグ用のログを書き込みます。transformer.end(result): 変換された値を返します。
- スクリプトには、
- パラメータを作成します。
- 各カスタム変換器関数には、デフォルトの [入力] パラメータが含まれています。このパラメータは入力データを表します。これは、 関数が適用されるプレースホルダです。この パラメータは削除できません。
- また、関数内で使用する省略可能なパラメータを 追加することもできます。
- ドキュメント（省略可）:
Expression Builder のプロダクト内ドキュメントを定義します:
- 想定される入力: この変換器で関数が受け取るデータ型（「文字列」や「文字列のリスト」など）を記述します。
- 想定される出力: この変換器で関数が返すデータ型（「ブール値」など）を記述します。
- 使用例: 関数を呼び出す方法の例（
if_empty("new_value")など）を示します。
カスタム変換関数のロジックは、ハンドブックで使用する前に IDE 内で直接テストできます。これにより、Python スクリプトがさまざまな入力タイプとパラメータを正しく処理し、想定される 結果を返すことを確認できます。
タイムアウト
- デフォルトのタイムアウト: 1 分。
- 最大タイムアウト: 3 分。
Expression Builder でカスタム変換器を使用する
保存すると、カスタム変換器は Expression Builder の関数リストに組み込み関数とともに表示されます。形式 ExtensionPackName.TransformerName で識別されます。関数にカーソルを合わせると、パラメータの説明から生成されたドキュメントが表示されます。
すべてのプレースホルダ（JSON と非 JSON）のサポート
Expression Builder は、非 JSON の結果など、ハンドブック デザイナーで公開されているすべてのプレースホルダをサポートしています。
非 JSON プレースホルダの場合:
- Expression Builder にサンプルデータを手動で入力して、 さまざまな入力タイプ（文字列、リスト（カンマ区切り値）、 JSON）に対するロジックをテストできます。
- 入力タイプでテストしても、プレースホルダが 実行時にその特定のタイプを返すとは限りません。
- ほとんどのプレースホルダは文字列として解決されますが、数量に基づいて文字列またはリストとして解決される特定のタイプ（たとえば、
entity.identifier）は除きます。これらの場合は、入力を常にリストとして扱うことをおすすめします。
エラー処理
カスタム変換関数が実行中にエラーを検出すると、 その変換器を使用するハンドブック アクションは失敗します。Python スクリプトによって生成された特定のエラー メッセージが ハンドブック実行ビューの画面に表示されるため、ロジックを直接トラブルシューティングできます。
カスタム論理演算子
カスタム論理演算子 を使用すると、値を比較するための独自のブール ロジックを定義できます。
カスタム論理演算子を作成する
新しい論理演算子を定義する手順は次のとおりです。
- IDE で、ターゲットの拡張機能パック を見つけます。
- [カスタム論理演算子] を選択します。
- 名前を付けてください
- 省略可: ハンドブック デザイナーの論理演算子メニューの説明を追加します。
- 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 のプロフェッショナルから回答を得ることができます。