4 カスタム・フックを使用したワークフローの変更

拡張ポイントという事前に定義されている時点にビジネス固有のカスタム・ロジックを追加して、既存のZDTパッチ適用ワークフローを変更できます。

拡張ポイントについて

拡張ポイントは、カスタム・ロジックを挿入できるZDTパッチ適用ワークフローのプレースホルダです。ZDTパッチ適用は、マルチテナントおよび非マルチテナント・ロールアウトの拡張ポイントおよび事前に定義されている環境変数を提供します。

ZDTカスタム・フック機能は、追加のコマンドを実行して動作をカスタマイズできるパッチ適用ワークフローの特定の時点を識別します。これらの時点は拡張ポイントと呼ばれます。事前に定義されている各拡張ポイントで、拡張機能と呼ばれるリソースの集合を挿入してワークフローの動作をカスタマイズできます。

表4-1に、説明およびユースケースとともに、マルチテナントおよび非マルチテナント環境の使用可能な拡張ポイントを示します。

表4-1 マルチテナントおよび非マルチテナント・ワークフローの使用可能な拡張ポイント

名前	説明	非マルチテナント・ワークフローの拡張機能を実行する場合に使用可能	マルチテナント・ワークフローの拡張機能を実行する場合に使用可能	ユースケース
ep_OnlineBeforeUpdate	パッチ適用操作を各ノードで開始する前に、ワークフローの初期ステージでこの拡張ポイントを使用します。通常これは前提条件チェックを実行できる時点です。	はい	はい	クラスタに提供される外部ドメインを無効化または一時停止するアップグレード前の静止。アプリケーション更新を準備するために必要になる場合があるSQLスクリプトを実行します。
ep_EachNode	ワークフローで各ノードの追加の操作を実行する必要がある場合、この拡張ポイントを使用します。	はい	はい	チェックを追加して、Oracleホームのロールアウトのためにすべてのノードに十分なディスク領域があることを確認します。新しい共有ファイル・システム・アーティファクトが各ノードでアクセス可能であることを確認します。
ep_OfflineBeforeUpdate	OracleホームまたはJavaホームの更新を開始する直前に、すべてのサーバーを停止している場合にワークフローのステージでこの拡張ポイントを使用します。	はい	はい	ファイルまたはディレクトリをバックアップします。
ep_OfflineAfterUpdate	OracleホームまたはJavaホームにパッチが適用されてからサーバーを起動する前に、この拡張ポイントを使用してカスタム操作を実行します。	はい	いいえ	ロールアウトに含まれるソフトウェア・コンポーネントのバージョンを検証します。 JavaホームのJavaプロパティを変更します。
ep_OnlineAfterServerStart	各ノードの更新を完了してサーバーを再起動した後、この拡張ポイントを使用してカスタム操作を実行します。	はい	いいえ	次のようなサーバーおよびアプリケーション・レベルの管理タスクを実行します。 JDBC、JTAまたはJMSサブシステムを確認します。この時点で追加のアプリケーションをデプロイまたは再デプロイします。アプリケーションが予期したとおりに動作するように、管理リクエストをアプリケーションに指示します。
ep_OnlineAfterUpdate	サーバーを再起動した後、この拡張ポイントを使用して追加の操作を実行します。アプリケーションはサービス提供リクエストを続行します。	はい	はい	基本チェックを実行して、影響を受けるアプリケーションが機能してアクセス可能であることを確認します。
ep_RolloutSuccess	パッチ適用に成功した後、この拡張ポイントを使用して通知の送信などのカスタム・ロジックを定義します。	はい	はい	電子メールを管理者に送信して、アップグレードのステータスを通知します。

この機能は、拡張ポイントで渡すことができる特定の事前に定義されている環境変数も提供します。事前に定義されている環境変数はオンライン拡張ポイントとともに使用できますが、その他はオフライン拡張ポイントとともに使用できます。サーバーの実行中にオンライン拡張ポイントを実行できます。また、オフライン拡張ポイントはサーバーの停止中に使用できます。リモート・ノードまたはローカル・ノードでオフラインおよびオンライン拡張ポイントを実行できます。表4-2に、オンラインおよびオフライン拡張ポイントとともに使用できるすべての環境変数のリストを示します。

表4-2 拡張ポイントの事前に定義されている環境変数

変数名	説明	オフラインまたはオンライン拡張ポイントとともに使用可能
javaHome	既存のJavaホームの場所	オフライン
newJavaHome	使用する新しいJavaホームの場所	オフライン
MWHome	ミドルウェア・ホームの場所	オフライン
domainDir	ドメイン・ディレクトリの位置	オフライン
domainTmp	一時ファイルを格納するドメイン・ホームのディレクトリの位置	オフライン
patched	パッチが適用されているOracleホームのロケーション	オフライン
backupDir	既存のOracleホームを移動するロケーション	オフライン
isRevert	スクリプトの実行または回復操作を制御します	オフライン
currentNodeName	現在更新されているノードの完全名。この変数は、`ep_OnlineBeforUpdate`または`ep_RolloutSuccess`拡張ポイントに適用されません。	オンライン
currentServerNames	ターゲット・ノードのサーバーの名前のカンマ区切りリスト。この変数は、`ep_OnlineBeforeUpdate`または`ep_RolloutSuccess`拡張ポイントに適用されません。	オンライン
partitionName	ロールアウトでターゲット指定するパーティション名	オンライン
applicationInfo	アプリケーションごとにカンマで区切られたアプリケーション名、アプリケーションの場所およびアプリケーション・バックアップ。複数のアプリケーションをコロンで区切ります。 `<appName>,<appLoc>,<appBackUp>:<appName2>,<appLoc2>,<appBackUp2>` たとえば、`"scrabble,/pathTo/scrabblev2,/pathTo/scrabbleV1Backup:cart,/pathTo/cartV3,/pathTo/cartV2Backup`などです	オンライン

カスタム・フックのパッチ適用ワークフロー・プロセス

管理サーバー・ノードまたはリモート・ノードで実行されるワークフローの操作をカスタマイズできます。カスタム・フック機能は、非マルチテナント環境およびWebLogic Serverのマルチテナント環境で使用できます。マルチテナント環境では、パーティションへのアプリケーション更新のロールアウト中およびパーティションのローリング再起動中に拡張機能を導入できます。ただし、パーティション管理者は管理サーバーのファイル・システムにアクセスできない可能性があることに注意してください。そのため、パーティション管理者として、パーティション・ファイル・システム・ディレクトリを使用して拡張jarファイルを格納できます。パーティション・ファイル・システム・ディレクトリを使用して、パーティション固有のリソースをアップロードおよび管理できます。図4-1および図4-2に、非マルチテナントおよびマルチテナント・ワークフローの通常のシナリオおよび異なる拡張ポイントを含める方法を示します。

ワークフロー・プロセスがユーザー・フックに達すると、その拡張ポイントのユーザー指定の拡張機能が実行されます。コード0(ゼロ)で終了するスクリプトは正常に完了したとみなされ、ゼロ以外の終了コードを返すスクリプトは失敗したとみなされます。エラーが発生しないアバイ、処理が再開されます。拡張機能の実行中にエラーが発生する場合、ワークフローが以前の状態にロールバックします。スクリプトは組込みの再試行がなく、メソッドを再開しないことに注意してください。スクリプトを一度試行し、失敗した場合にワークフローは再試行しません。そのため、スクリプトで再試行する必要がある操作を実行する場合、スクリプトに再試行ロジックを書き込む必要があります。

ワークフローの実行中に、STDOUTまたはSTDERRへのオフライン・スクリプトで生成された出力が管理サーバー・ログ・ファイルに伝播されます。同様に、ローカルで実行するスクリプトで生成された出力も管理サーバ－・ログ・ファイルに書き込まれます。これには、エラー出力または非エラー出力が含まれます。

図4-1 非マルチテナント・ロールアウトの拡張ポイントを使用したパッチ適用ワークフロー

この図は、OracleホームまたはJavaホームを更新する通常の非マルチテナント・ワークフローで使用できる拡張ポイントを示します。

「図4-1 非マルチテナント・ロールアウトの拡張ポイントを使用したパッチ適用ワークフロー」の説明

図4-2 マルチテナント・ロールアウトの拡張ポイントを使用したパッチ適用ワークフロー

この図は、アプリケーションの更新またはパーティションのローリング再起動のマルチテナント・ワークフローで使用できる拡張ポイントを示します。

「図4-2 マルチテナント・ロールアウトの拡張ポイントを使用したパッチ適用ワークフロー」の説明

拡張機能を指定したワークフローの変更

カスタム・フック機能は、ワークフローの拡張機能を導入するいくつかの方法を提供します。2つのJSONファイル(extensionConfiguration.jsonまたはextensionProperties.json)のいずれかで拡張機能を指定するか、ロールアウト・コマンドのオプションとして直接渡すことができます。拡張パラメータを渡す方法に関係なく、これらのパラメータは環境変数に変換されるスクリプト・パラメータに最終的にマップされます。

この柔軟性により、異なるレベルでパラメータをオーバーライドまたはカスタマイズできます。拡張パラメータを指定する複数の方法を使用する場合、スクリプト・パラメータをオーバーライドする順序は次のとおりです。

extensionConfiguration.jsonファイルで指定される拡張パラメータ。
extensionConfiguration.jsonファイルで設定されているパラメータをオーバーライドする拡張パラメータJSONファイルで指定された拡張パラメータ。
2つのJSONファイルで指定されたパラメータをオーバーライドするWLSTロールアウト・コマンドのオプションとして指定された拡張パラメータ。ワークフローごとのロールアウト・コマンドのオプションのみをカスタマイズして、異なる環境で同じ拡張JARを使用できます。

次の各項では、これらの方法を使用して拡張機能を指定する詳細を説明します。

JSON構成ファイルの作成

extensionConfiguration.jsonファイルは、拡張定義の配列を含むJSON形式ファイルです。各拡張定義では、次を指定する必要があります。

拡張機能をワークフローに挿入する事前に定義されている拡張ポイントの名前。
その拡張ポイントで実行するクラス・ファイルの完全修飾名。

オプションで、拡張機能が使用する追加のパラメータ。追加の拡張パラメータをJSON形式で宣言する必要があります。指定されたクラス・ファイルでは、WebLogic Serverが提供する標準の拡張機能のいずれかを使用できます。次のサンプルのextensionConfiguration.jsonファイルに、拡張機能の定義方法を示します。

{"extensions":[
{
"extensionPoint":"ep_OnlineBeforeUpdate",
"extensionClass":"weblogic.management.patching.extensions.ScriptExecutorExtension",
"extensionParameters":{"scriptName":"checkJar.sh","jarPath":"/tmp/extension.jar"}
},
{
"extensionPoint":"ep_EachNode",
"extensionClass":"weblogic.management.patching.extensions.ScriptExecutorExtension",
"extensionParameters":{"scriptName":"checkDiskSpace.sh"}
},
{
"extensionPoint":"ep_OnlineAfterUpdate",
"extensionClass":"weblogic.management.patching.extensions.ScriptExecutorExtension",
"extensionParameters":{"scriptName":"checkApps.sh","appUrls":"http://localhost:8004/Coke/Simple_stage/handle,http://localhost:8006/Coke/Simple_stage/handle"}
},
{
"extensionPoint":"ep_RolloutSuccess",
"extensionClass":"weblogic.management.patching.extensions.ScriptExecutorExtension",
"extensionParameters":{"scriptName":"emailSuccess.sh"}
}
]}

extensionConfiguration.jsonファイルを作成した後、sampleExtension.jarなどのJARファイルの他の関連するネイティブ・スクリプトとともに配置する必要があります。作成するJARファイルは、Oracle標準に準拠するディレクトリ構造を持つ必要があります。複数の拡張機能を単一の拡張ポイントで指定する場合、拡張機能はextensionConfiguration.jsonファイルに表示される順序で実行されます。各JARファイルは、1つのextensionConfiguration.jsonファイルのみ含む必要があります。図4-3に、拡張JARファイルの構造を示します。

ロールアウト中に、スクリプトがDOMAIN_HOME/binの下にあるpatchingディレクトリで抽出されます。

図4-3 拡張Jarファイル構造

「図4-3 拡張Jarファイル構造」の説明

JSONプロパティ・ファイルの作成

または、extensionProperties.jsonファイルなどの別のJSONファイルの拡張情報を指定できます。ワークフローの複数の拡張機能を渡す必要がある場合およびこれらの拡張機能を複数のJARファイルに配置する場合、このファイルを使用できます。JSONプロパティ・ファイルはextensionConfiguration.jsonファイルと異なることに注意してください。extensionConfiguration.jsonファイルは独自のJARファイル内のスクリプトに固有であり、JSONプロパティ・ファイルは、ワークフローの複数の拡張JARファイルを含める便利な方法を提供します。各JSONプロパティ・ファイルには、拡張構成情報を含む1つ以上のJARファイルへのパスが含まれ、オプションで追加のパラメータが含まれます。

次のスニペットは、サンプルのextensionProperties.jsonファイルの形式を示します。

{"extensionProperties":[
{
"extensionJar":"/pathTo/extension.jar",
"extensionParameters":{"scriptName":"updateProperties.sh", "appURL":"http://localhost:7005/context?param1=val1&param2=val2,http://localhost:7006/context2?param1=val1&param2=val2"}
}
]}

WLSTロールアウト・コマンドのオプションを含む

2つのJSONファイルのいずれかで拡張パラメータを渡すか、extensionまたはextensionPropertiesオプションを使用してWLSTロールアウト・コマンドに直接渡すことができます。これらのオプションを使用して拡張パラメータを指定する方法の詳細は、「WLSTを使用したワークフローの起動と監視」のWLSTロールアウト・コマンドの引数を参照してください。

注意:

JSONファイルを作成して拡張機能を含めて拡張jarに配置する場合、次の条件を満たしていることを確認してください。

ロールアウト前にすべてのリモート・ノードに拡張jarを配置します。
ロールアウトする拡張パラメータを含む拡張jarへのパスを指定します。同じパスはすべてのノードに存在する必要があります。
Windowsシステムで、JSONファイルのパスを指定する場合にバックスラッシュ文字を使用しないでください。
JSONファイルのスクリプト・パラメータの値にカンマを含めないでください。