Gradleによるステップの作成とフローへの追加

始める前に

以下が必要です。

Java SE JDK 8以降
MarkLogicサーバー（「バージョン互換性」を参照してください）
Gradle 4.6以降

このタスクについて

フローには少なくとも1つのステップを含める必要があります。ステップを作成する方法は2つあります。

ステップのサンプルをカスタマイズする。Gradleによるフローの作成を行った場合、結果として得られたフロー定義ファイルには、事前定義された各ステップタイプ（読み込み、マッピング、マッチング、マージング、マスタリング）ごとにステップのサンプルが含まれています。これらのステップをカスタマイズしていきます。
Gradleによるステップの作成とカスタマイズ。GradleタスクhubCreateStepDefinitionを使って、ステップ定義の初期化、フロー定義へのコピー、カスタマイズができます。

フロー定義ファイルで直接設定したステップ、あるいはGradleタスクhubCreateStepDefinitionを実行することで作成されたステップ定義を使用したステップは、QuickStartが生成したカスタムステップと同等になっています。hubCreateStepDefinitionのstepDefTypeパラメータは、QuickStartのCustom Step Typeと同等です。1つ違うのは、Gradleシンタックスの-PstepDefType=customは、QuickStartではCustom Step TypeがOtherとなっています。

このタスクでは、Gradleによるステップ定義の作成およびカスタマイズの方法について説明します。

手順

これらの内容をカスタマイズするには、作成するステップのタイプを選択します。

Gradleでステップ定義を作成します。
1. コマンドラインウィンドウを開き、プロジェクトのルートディレクトリに移動します。
2. プロジェクトルートで、GradleタスクhubCreateStepDefinitionを実行します。その際、stepTypeをingestionに指定します。stepTypeをmappingに指定します。stepTypeをmatchingに指定します。stepTypeをmergingに指定します。stepTypeをmasteringに指定します。stepTypeをcustomに指定します。
  
  ./gradlew hubCreateStepDefinition -PstepDefName=your-ingestion-step-name -PstepDefType=ingestion -igradlew.bat hubCreateStepDefinition -PstepDefName=your-ingestion-step-name -PstepDefType=ingestion -i
  
  ./gradlew hubCreateStepDefinition -PstepDefName=your-mapping-step-name -PstepDefType=mapping -igradlew.bat hubCreateStepDefinition -PstepDefName=your-mapping-step-name -PstepDefType=mapping -i
  
  ./gradlew hubCreateStepDefinition -PstepDefName=your-matching-step-name -PstepDefType=matching -igradlew.bat hubCreateStepDefinition -PstepDefName=your-matching-step-name -PstepDefType=matching -i
  
  ./gradlew hubCreateStepDefinition -PstepDefName=your-merging-step-name -PstepDefType=merging -igradlew.bat hubCreateStepDefinition -PstepDefName=your-merging-step-name -PstepDefType=merging -i
  
  ./gradlew hubCreateStepDefinition -PstepDefName=your-mastering-step-name -PstepDefType=mastering -igradlew.bat hubCreateStepDefinition -PstepDefName=your-mastering-step-name -PstepDefType=mastering -i
  
  ./gradlew hubCreateStepDefinition -PstepDefName=your-custom-step-name -PstepDefType=custom -igradlew.bat hubCreateStepDefinition -PstepDefName=your-custom-step-name -PstepDefType=custom -i
  
  XQueryモジュール（デフォルトのJavaScriptモジュールではなく）をステップ定義に関連付けたい場合、-Pformat=xqyオプションを追加します。これにより、XQueryのサンプルモジュール（カスタマイズ可能）およびJavaScriptラッパーが作成されます。
  
  注: デフォルトのstepTypeは、customです。
  以下のファイルが作成されます。
  - ステップ定義ファイル
```
your-project-root/step-definitions/ingestion/your-ingestion-step-name/your-ingestion-step-name.step.json
```
```
your-project-root/step-definitions/mapping/your-mapping-step-name/your-mapping-step-name.step.json
```
```
your-project-root/step-definitions/matching/your-matching-step-name/your-matching-step-name.step.json
```
```
your-project-root/step-definitions/merging/your-merging-step-name/your-merging-step-name.step.json
```
```
your-project-root/step-definitions/mastering/your-mastering-step-name/your-mastering-step-name.step.json
```
```
your-project-root/step-definitions/custom/your-custom-step-name/your-custom-step-name.step.json
```
  - カスタムモジュールファイル
```
your-project-root/src/main/ml-modules/root/custom-modules/ingestion/your-ingestion-step-def-name/main.sjs
```
```
your-project-root/src/main/ml-modules/root/custom-modules/mapping/your-mapping-step-def-name/main.sjs
```
```
your-project-root/src/main/ml-modules/root/custom-modules/matching/your-matching-step-def-name/main.sjs
```
```
your-project-root/src/main/ml-modules/root/custom-modules/merging/your-merging-step-def-name/main.sjs
```
```
your-project-root/src/main/ml-modules/root/custom-modules/mastering/your-mastering-step-def-name/main.sjs
```
```
your-project-root/src/main/ml-modules/root/custom-modules/custom/your-custom-step-def-name/main.sjs
```
  ステップ定義内のmodulePath設定により、カスタムモジュールファイルが指定されます。
手作業でこのステップをフローに追加します。
1. テキストエディタで、ステップ定義ファイルを開きます。
  カスタムの読み込みステップ定義ファイルには、以下が含まれています。
```
   {
    "language" : "zxx",
    "name" : "your-ingestion-step-def-name",
    "description" : null,
    "type" : "INGESTION",
    "version" : 1,
    "options" : {
      "collections" : [ "your-ingestion-step-def-name" ],
      "outputFormat" : "json",
      "targetDatabase" : "data-hub-STAGING"
    },
    "customHook" : { },
    "modulePath" : "/custom-modules/ingestion/your-ingestion-step-def-name/main.sjs",
    "retryLimit" : 0,
    "batchSize" : 100,
    "threadCount" : 4,
    "fileLocations" : {
      "inputFilePath" : "",
      "outputURIReplacement" : "",
      "inputFileType" : ""
    }
  }
```
2. 同様に、フロー定義ファイルを開きます。
  フロー定義ファイルは、your-project-root/flowsにあります。
  
  デフォルトのフロー定義ファイルにはステップがなく、以下のようになっています。
```
   {
    "name": "your-flow-name",
    "description": "",
    "batchSize": 100,
    "threadCount": 4,
    "options": {
      "sourceQuery": null
    },
    "steps": {}
  }
```
3. stepsノードに、ステップをキー/バリューペアとして追加します。
  - キーとしてシーケンスを入力します。
    注: フローのstepsノード内のキーが一意である限り、ステップは任意の順番で記載できます。キーが重複していた場合、予想外の結果が生じる場合があります。キーの数字は0より大きい値にしてください。
  - バリューとして、ステップ定義ファイルのコンテンツ全体をコピーして貼り付けます。
4. フロー定義ファイル内のステップを編集します。
  - nameをstepDefinitionNameに変更します。
  - typeをstepDefinitionTypeに変更します。
  - nameを新規作成し、ステップの名前を付けます。
  - （オプション）次の設定を削除します。
    - language
    - version
    - modulePath
    これらの設定の値は、ステップ定義から取得されます。
最初のステップ（「1」）としてデフォルトの読み込みステップをデフォルトのフローに追加すると、フロー定義ファイルは次のようになります。
```
   {
    "name": "your-flow-name",
    "description": "",
    "batchSize": 100,
    "threadCount": 4,
    "options": {
      "sourceQuery": null
    },
    "steps": {
      "1": {
        "name" : "your-step-name",
        "stepDefinitionName" : "your-ingestion-step-def-name",
        "description" : null,
        "stepDefinitionType" : "INGESTION",
        "options" : {
          "collections" : [ "your-ingestion-step-name" ],
          "outputFormat" : "json",
          "targetDatabase" : "data-hub-STAGING"
        },
        "customHook" : { },
        "retryLimit" : 0,
        "batchSize" : 100,
        "threadCount" : 4,
        "fileLocations" : {
          "inputFilePath" : "",
          "outputURIReplacement" : "",
          "inputFileType" : ""
        }
      }
    }
  }
```

次のタスク

カスタムモジュールを修正します。
（オプション）データハブ以外の場所で他のタスクを実行したい場合、カスタムフックモジュールを作成し、これをステップ内のカスタムフックに追加できます。

MarkLogic 10 and Data Hub 5.0