カスタムステップモジュールの編集

カスタムステップのモジュール

カスタムステップを使うと、フローシーケンスの任意の場所にカスタム機能を追加できます。

特化したタスクをデータハブ内で実行するには、カスタムステップモジュールを呼び出すカスタムステップを作成します。QuickStartによるカスタムステップの設定あるいはGradleタスクhubCreateStepDefinitionによって作成されたカスタムステップモジュールには、モジュールを構築していくための指示が含まれています。

必要なインプット

コンテンツオブジェクト。処理対象となるものすべてを含んだオブジェクト。任意のContentオブジェクトの配列（各ドキュメントあるいはレコードごと）。それぞれのContentオブジェクトは以下のものから構成されています。
- content.uri。処理対象となるドキュメントあるいはレコードのURI。
- content.context。ドキュメントあるいはレコードに関連付けられたあらゆるメタデータ（データベース内に存在するがエンベロープ内には含まれていないもの）。例：パーミッション、コレクションタグ、テンポラル（時間）設定。
- content.value。カスタムモジュール内で処理される情報。
Optionsオブジェクト。ステップに渡されるパラメータ（JSONのキー/バリューパラメータ）であるカスタムオブジェクト。

必要な出力


ステップのタイプ	必要な出力
カスタム - 読み込み	`Content`オブジェクト。
カスタム - マッピングカスタム - マスタリングカスタム - その他	`Content`オブジェクトあるいは`Content`オブジェクトの配列。

それぞれのContentオブジェクトにはデータベースに書き込まれる処理済みのデータが含まれ、以下のものから構成されています。

content.uri。データベース内で上書きあるいは作成されるドキュメントやレコードのURI。ドキュメントがまだ存在していない場合、このURIは一意的なものとなります。それ以外の場合は、同じURIの昔のデータは上書きされ、その変更は出自データに記録されます。
content.context。ドキュメントあるいはレコードに関連付けられたすべてのメタデータ。
content.value。データベース内に格納される情報。
content.provenance。（オプション）格納される追加のプロパティレベルの出自情報（出自のレベルがfineになっている場合）。

カスタムステップにおける出自

デフォルトのドキュメントレベルの出自情報に加えて、プロパティレベルの出自情報をトラッキングできます。詳細は、「手作業による出自の粒度の設定」を参照してください。

カスタムステップで、どのプロパティレベルの出自情報をトラッキングするのかも指定できます。以下のように行います。

カスタムモジュールが返したContentオブジェクトには、content.provenanceコンポーネントが必要です。
content.provenanceには、トラッキングしたいプロパティとその値が必要です。
content.provenanceの値は、以下の形式になっている必要があります。データハブは、これをthe PROV-XMLスキーマに変換してからJOBSデータベースに格納します。
```
   {
    "<originalURI>": {
      "<originalXPathOrPropertyName>": {
       "destination": "<XPathOrPropertyInNewDocument>",
       "value": "<newValue>"
      }
    }
  }
```

例1：lastNameプロパティをsurNameプロパティにマッピングした場合、content.provenanceを以下のように設定できます。

   {
    "/26451baa-fe14-471f-bd77-364ac3f64c82.json": {
      "lastName": {
       "destination": "surName",
       "value": "Smith"
      }
    }
  }

例2：カスタムモジュールにおいて複数のドキュメントからの情報を1つにまとめている場合、これらのソースドキュメントの出自情報をcontent.provenanceに1つにまとめることができます。

   {
    "/26451baa-fe14-471f-bd77-364ac3f64c82.json": {
      "lastName": {
        "destination": "surName",
        "value": "Smith"
      }
    },
    "/5455fd37-6d96-4883-9349-8e79fa700145.json": {
      "firstName": {
        "destination": "givenName",
        "value": "John"
      }
    }
  }

注: content.provenanceが、カスタムモジュールが返したContentオブジェクト内に存在せず、ステップの粒度がfineに設定されている場合、デフォルトであるドキュメントレベルの出自情報のみがトラッキングされます（coarseの場合も同様です）。エラーはスローされません。

ベストプラクティス

カスタムモジュールはXQueryでもコーディング可能ですが、MarkLogicはJavaScriptの使用を推奨します。
DataHubオブジェクトを使用してください。これによりデータハブライブラリにアクセス可能になります。例えば、DataHubオブジェクトにより、XML/JSONドキュメントの周りにエンベロープを生成できます。
エラー処理の方法は2つあります。
- オーケストレーションアプリケーション（Nifiなど）を使用している場合：
  1. モジュール内でエラーをスローできます。スローされたエラーはすべて、オーケストレーションツールに返されます。この際、失敗したドキュメントのURIと一緒に記録されます。
  2. 他のステップ（これは別のフロー内にある場合もあります）において、特定のエラーが発生したドキュメントに関するオーケストレーションログを検索し、適宜修正します。
- エラーをスローしない場合：
  1. 失敗したドキュメントに特別なコレクションタグを付けます。
  2. 他のステップで、このコレクションタグが付いたドキュメントを検索し、適宜修正します。

MarkLogic 10 and Data Hub 5.0