カスタムジョブステップの作成
学習の目的
- カスタムジョブを作成するために実行する必要のある手順を挙げる。
- タスク指向型とチャンク指向型のスクリプトモジュールの違いを説明する。
- steptypes.json ファイルとは何かを説明する。
はじめに
Cloud Kick の管理者である Linda Rosenberg がジョブを作成していますが、想定しているとおりの作業を実行するシステムステップが見つかりません。具体的には、外部の商品情報 (PIM) システムからデータを直接 Production (本番) インスタンスにインポートしたいと考えています。カタログデータをインポートして処理し、Salesforce B2C Commerce データベースに保存するつもりのため、この操作を実行するカスタムコードが必要です。これは単純なインポートではありません。このカスタムジョブを作成するために、Linda は Cloud Kicks のデベロッパーである Vijay Lahiri に次の手順を実行するよう依頼しました。
- カートリッジを作成します。カートリッジとは、B2C Commerce のストアフロントプログラムのコードやデータをパッケージ化して導入するメカニズムです。
- タスク指向型またはチャンク指向型のスクリプトを記述して、プロセスのステップ (例: 商品レコードを読み取って処理し、データベースに書き込む) を実行します。
- カスタムステップについて説明する steptypes.json ファイルを作成し、そのファイルをカートリッジのルートに配置します。
- カートリッジをアップロードして、カートリッジパスに含めます。
Vijay は快諾してくれました。
Vijay の作業が終了したら、Linda が次の手順を実行します。
- コードを Production (本番) にレプリケートし、新しいカートリッジを含むコードのバージョンを有効にします。
- Business Manager でカスタムステップを使用してジョブを作成します。
タスク指向型スクリプトモジュール
ここはやや技術的な説明になりますが、Linda には、以下のデベロッパー向けの概念やプロセスを理解し、Vijay と協力してジョブの成功を監視し、今後必要な事項を計画できるようになることが求められます。
タスク指向型 CommonJS スクリプトモジュールは、ジョブステップの main 関数として呼び出される関数を公開します。Linda は Business Manager を使用してジョブを作成するときに、このモジュールの関数と dw.job.JobStepExecution オブジェクトのスクリプト実行可能なオブジェクトとして使用できるパラメーターを設定します。dw.job.JobStepExecution オブジェクトにより、現在のステップの実行とジョブの実行に関する情報に対する参照のみのアクセスが可能になります。
終了ステータスを管理するために、この関数で dw.system.Status API オブジェクトを返すことができます。スクリプトの終了時に未対応の例外が発生している場合は、デフォルトで終了ステータスコードが ERROR、エラーステータスのフラグが true になります。ステータスオブジェクトが返され、例外が発生していない場合は、デフォルトでステータスコードが OK になります。
FTP 経由で接続してからデータをダウンロードするタスク指向型スクリプトモジュールの例については、Infocenter を参照してください。Vijay はこの例を参考にしてスクリプトモジュールを作成します。
チャンク指向型スクリプトモジュール
チャンク指向型 CommonJS スクリプトモジュールは、指定したサイズのチャンクで項目を読み取って処理します。リストに記載されている項目数が B2C Commerce の 1 回のチャンクで処理できる数を上回っている場合は、新しいチャンクが開始されます。チャンク指向型スクリプトには、データベーストランザクションだけでなく、任意の一連の処理ステップを含めることができます。
チャンク指向型スクリプトを使用するジョブステップでは、チャンクが終了するたびに書き込まれた要素数を B2C Commerce が更新するため、進行状況を細かく監視できます。
Vijay と Linda がチャンク処理の例を確認します。
たとえば、エクスポートするファイルに 8 件の注文がリストされ、1 回のチャンクのサイズが注文 4 件分であるとします。このスクリプトはチャンクを次の順序で処理します。
- Order1 の読み取り、Order1 の処理、Order2 の読み取り、Order2 の処理、Order3 の読み取り、Order3 の処理、Order4 の読み取り、Order4 の処理
- Order1 の書き込み、Order2 の書き込み、Order3 の書き込み、Order4 の書き込み
- Order5 の読み取り、Order5 の処理、Order6 の読み取り、Order6 の処理、Order7 の読み取り、Order7 の処理、Order8 の読み取り、Order8 の処理
- Order5 の書き込み、Order6 の書き込み、Order7 の書き込み、Order8 の書き込み
チャンクスクリプトの関数
Linda はこの例の 3 つの関数に気が付きました。チャンク指向型スクリプトモジュールは、読み取り、処理、書き込みの関数を公開します。
- read-function: 1 つの項目を返すか、何も返しません。
- process-function: 項目を変換し、ビジネスロジックをその項目に適用できます。
- write-function: 項目のリストを受け取ります。
チャンク指向型スクリプトモジュールでは、次の省略可能な関数も使用できます。
- total-count-function: チャンク処理が開始されるまでに使用可能な項目の総数を返します。
- before-step-function: チャンクステップが開始される前に実行します。
- before-chunk-function: チャンクが開始される前に実行します。
- after-chunk-function: チャンクが終了した後に実行します。
- after-step-function: チャンクステップが正常に終了した後に実行します。
チャンク指向型スクリプトモジュールの例については、Infocenter を参照してください。
steptypes ファイル
Vijay はカスタムステップの作成時に、ステップのメタデータを説明する steptypes.json ファイルを作成する必要があります。このファイルは、ステップを実装するスクリプトモジュール、ステップの必須パラメーター、ステップが返す終了ステータスを指定します。steptypes.json ファイルは極めて特異な構文を要します。たとえば、steptypes.json ファイルの一部で次の名前と値のペアが使用されます。
"@name":"MyParameter1", "@type":"boolean", "@required":"true", "description":"A required boolean parameter."
構文の詳細と steptypes.json ファイルの例については、Infocenter を参照してください。
無効な steptypes.json ファイルのトラブルシューティング
B2C Commerce は、次の場合に steptypes.json ファイルを解析して読み込みます。
- サーバーの起動時。
- コードのアクティブなバージョンが変更されたとき。
- Sandbox (サンドボックス) でステップが実行されるたび。
属性が指定されていないなどの問題により、steptypes.json ファイルにエラーがある場合は、B2C Commerce がそのエラーをエラーファイルに記録し、カスタムステップを登録しません。そして、B2C Commerce が他のカートリッジの steptypes.json ファイルからステップを読み込みます。
steptypes.json ファイルが無効な場合は、Business Manager に次のようなメッセージが表示されます。
Invalid step [Step1]! Type with id [custom.MyCustomStep1] is unknown!
Linda が無効なジョブをインポートすると、インポート/エクスポートログに警告が記載され、Business Manager にエラーメッセージが表示されます。Vijay が steptypes.json を変更した結果、無効のジョブが作成された場合には、ジョブが実行されなくなり、ジョブログのエントリを除いて何も行われません。
steptypes.xml の使用
Vijay は、カスタムステップを定義するために、JSON ではなく XML 定義を使用できます。この場合は、steptypes.xml ファイルを呼び出して、ルートフォルダーのカスタムカートリッジに配置する必要があります。コードのアクティブのバージョンが変更されるたびに、B2C Commerce がそのファイルを解析して再読み込みします。steptypes.json ファイルまたは steptypes.xml ファイルのいずれか 1 つのみを保持できます。
