データ変換やジョブ管理を効率化するためにPentahoでREST APIを使う

<!--データ変換やジョブ管理を効率化するためにPentahoでREST APIを駆使する方法-->
<!--データ変換やジョブ管理をPentahoとREST APIで達成する方法
データ変換やジョブ管理をPentahoとREST APIで実現するアプローチ
-->
# 概要
多くの企業が抱える課題の一つに、大量のデータを効率的に処理し、ジョブを管理することがあります。複雑なデータ処理やジョブの管理を手動で行うと、時間と労力がかかり、ミスが発生しやすくなります。このような課題を解決するために、PentahoとREST APIを活用する方法をご紹介します。
Pentahoは、日立製作所が提供するソフトウェアで、データの収集・加工を行うETL機能と、データの可視化・分析を行うBI機能を統合した強力なプラットフォームです。Pentahoを利用することで、データの統合から分析までをシームレスに実現し、データ変換やジョブ管理を効率化することができます。
Pentahoについて詳細を知りたい方は、[日立製作所公式の製品紹介ページ](https://www.hitachi.co.jp/products/it/bigdata/platform/pentaho/about/index.html) をご覧ください。
この記事では、よく用いるリクエストをcurlを使用した具体例とともに紹介し、実践的なAPIの利用方法を学びます。

### 対象となる読者

- Pentahoの導入を検討しており、**他のアプリケーションや外部のソフトウェアとの連携**によるデータ変換やジョブ管理の効率化に興味がある方
- Pentahoを既に使用しているが、**REST APIを通じたスムーズなデータ連携を実現する方法**を深く理解したい方
- PentahoでREST API連携を実装していて、**具体的なリクエスト送信方法**を確認したい方

この記事は、特にデータエンジニアやアプリケーション開発者の方々に向けて、Pentahoとアプリケーションを用いた業務課題を解決するための情報を提供します。

# Pentahoとアプリケーションの連携

Pentahoは、RESTベースのAPIを公開しており、データ変換、ジョブの管理、ファイル操作などの機能をアプリケーションから直接実行することが可能です。

# PentahoのREST APIについて

主要なREST APIの使用方法を紹介します。
Pentahoサーバーはデフォルトで`8080`ポートを用いるため、以降のサーバーのURLは`http://localhost:8080`として説明しています。

# 認証
PentahoのREST APIを使うためには、ユーザー認証を通す必要があります。
Pentahoには、クライアント認証システムとして、Basic認証とCookieベース認証の2つの方法があります。今回はBasic認証を用いる場合について説明します。

### Basic認証
#### 概要
Basic認証は、ユーザー名とパスワードを使用して認証を行うシンプルな方法です。

| パラメータ        | 説明                                         | 
|---------------------|--------------------------------------------|
| ユーザー名                 | Pentahoのリポジトリに登録されているユーザー名。<br>ユーザーコンソールにアクセスするときのユーザー名と同じです。                      | 
| パスワード               | Pentahoのリポジトリにアクセスするためのパスワード。<br>ユーザーコンソールにアクセスするときのパスワードと同じです。                | 

![idpass.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3689802/18142fbf-f6f5-49be-8c0c-6e02c4489ef4.png)
デフォルトでは、`admin`ユーザーにパスワードとして`password`が設定されているので、以降のリクエストではこれらを用いて説明します。

#### curlでの実行サンプル
以下は、curlを使用してBasic認証でPentahoにリクエストを送信するGETリクエストのサンプルです。
```bash: 認証方式1：URIに認証情報を記載するパターン
curl -X GET "http://admin:password@localhost:8080/pentaho/kettle/status"
(サーバーからの出力)
```

また、以下のようなURIでリクエストを送ることも可能です。

```bash: 認証方式2：オプションに含めるパターン
curl -X GET -u admin:password "http://localhost:8080/pentaho/kettle/status"
(サーバーからの出力)
```


# APIでのPentahoの操作方法
以下では、REST APIを使用してデータ変換やジョブといったPentahoの機能を操作する方法を紹介します。


## 1. ETLの実行

REST APIを用いて、Pentahoで開発したデータ変換やジョブの実行を行うことができます。
### 1-1. データ変換(ktrファイル)の実行
ktrファイルは、データ変換の定義ファイルです。
#### 概要
`/pentaho/kettle/executeTrans`は、ローカルファイルまたは指定されたリポジトリからデータ変換を実行します。実行中にエラーが発生した場合は、エラーの出力を含むレスポンスが返されます。エラーが発生しなかった場合、レスポンスは空になります。

| エンドポイント        | 説明                                         |
|---------------------|--------------------------------------------|
|  `/pentaho/kettle/executeTrans` |  サーバーからデータ変換を実行します。                      |

| パラメータ名        | 説明                                         | 型       |
|---------------------|--------------------------------------------|----------|
| `trans`               | ロードして実行するジョブの名前を指定します。              | `String` |
| `rep` (任意)                | 接続するリポジトリのIDを指定します。                      | `String` |
| `user` (任意)                | リポジトリに接続するためのユーザー名を指定します。                      | `String` |
| `pass` (任意)                | リポジトリに接続するためのパスワードを指定します。                      | `String` |
| `level`(任意)               | ジョブ実行時に使用するログレベルを指定します。<br>(例: `Debug`)  | `String` |
| その他(任意)  | ジョブのカスタムパラメータを指定できます。 | -      |

#### curlでの実行サンプル

以下は、curlを使用してktrファイルを実行するGETリクエストのサンプルです。



```bash: ktrファイル実行
# ローカルに保存されたファイルを実行する場合
curl -X GET "http://admin:password@localhost:8080/pentaho/kettle/executeTrans/?trans=/home/pentaho/my_trans.ktr&level=INFO"

# リポジトリに保存されたファイルを実行する場合
curl -X GET "http://admin:password@localhost:8080/pentaho/kettle/executeTrans/?trans=/home/admin/my_trans&rep=my_repository&level=INFO"


# データ変換が正常に実行できた場合
(出力なし)

# データ変換でエラーが発生した場合
<webresult>
  <result>ERROR</result>
  <message>
・・・
  </message>
  <id/>
</webresult>

```

- `http://admin:password@localhost:8080`は、Pentahoサーバーのアドレスに置き換えてください
- `my_trans`、`my_repository`、`INFO`は、実際のリポジトリ名、データ変換名、ログレベルに置き換えてください
- リポジトリ名については、`repositories.xml`というファイルの`name`タグに記載された値を指定します。デフォルトでは、ユーザーディレクトリの下の`.kettle`ディレクトリにあります

実行結果は、[2. ETLステータスの確認](#2-etlステータスの確認)で紹介する[`/pentaho/kettle/status`](#2-1-サーバーステータスの確認)や[`/pentaho/kettle/transStatus`](#2-2-データ変換のステータス確認)を用いて確認できます。

### 1-2. ジョブ(kjbファイル)の実行

kjbファイルは、ジョブの定義ファイルです。

#### 概要
ジョブを実行するためには、`/pentaho/kettle/executeJob`を使用します。

| エンドポイント        | 説明                                         |
|---------------------|--------------------------------------------|
|  `/pentaho/kettle/executeJob` |  サーバーからジョブを実行します。                      |

| パラメータ名        | 説明                                         | 型       |
|---------------------|--------------------------------------------|----------|
| `job`               | ロードして実行するジョブの名前を指定します。              | `String` |
| `rep` (任意)                | 接続するリポジトリのIDを指定します。                      | `String` |
| `level`(任意)               | ジョブ実行時に使用するログレベルを指定します。<br>(例: `Debug`)  | `String` |
| その他(任意)  | ジョブのカスタムパラメータを指定できます。 | -      |


#### curlでの実行サンプル

以下は、curlを使用してkjbファイルを実行するGETリクエストのサンプルです。

```bash: kjbファイル実行
# ローカルに保存されたファイルを実行する場合
curl -X GET "http://admin:password@localhost:8080/pentaho/kettle/executeJob/?job=/home/pentaho/my_job.kjb&level=INFO"

# リポジトリに保存されたファイルを実行する場合
curl -X GET "http://admin:password@localhost:8080/pentaho/kettle/executeJob/?job=/home/admin/my_job&rep=my_repository&level=INFO"


# ジョブが正常に起動した場合
<webresult>
  <result>OK</result>
  <message>Job started</message>
  <id>c4c886ed-6ee4-4ed7-9a41-2cd95ef26433</id>
</webresult>

# ジョブが起動できなかった場合
<webresult>
  <result>ERROR</result>
  <message>
・・・
  </message>
  <id/>
</webresult>

```

- `http://admin:password@localhost:8080`は、Pentahoサーバーのアドレスに置き換えてください
- `my_job`、`my_repository`、`INFO`は、実際のリポジトリ名、ジョブ名、ログレベルに置き換えてください
- リポジトリ名については、`repositories.xml`というファイルの`name`タグに記載された値を指定します。デフォルトでは、ユーザーディレクトリの下の`.kettle`ディレクトリにあります

実行結果は、[2. ETLステータスの確認](#2-etlステータスの確認)で紹介する[`/pentaho/kettle/status`](#2-1-サーバーステータスの確認)や[`/pentaho/kettle/jobStatus`](#2-3-ジョブのステータス確認)を用いて確認できます。



## 2. ETLステータスの確認
まずは、現在実行しているサーバーのステータスやデータ変換やジョブの状態を確認するためのコマンドについて説明します。
### 2-1. サーバーステータスの確認

#### 概要
現在のデータ変換の稼働状況やジョブの状態を把握するために、
Pentahoサーバーのステータスを確認するには、`/pentaho/kettle/status`にアクセスします。
| エンドポイント        | 説明                                         |
|---------------------|--------------------------------------------|
|  `/pentaho/kettle/status` |  サーバーのステータスを確認します。                      |


| パラメータ名        | 説明                                         | 型       |
|---------------------|--------------------------------------------|----------|
|  `xml`(任意)                 | Yを指定すると、XML形式で出力されます。<br> デフォルトはHTMLです。(`xml=N`)                      | `boolean` |

#### curlでの実行サンプル
以下は、curlを使用してサーバーステータスを確認するGETリクエストのサンプルです。

```bash: サーバーステータス確認
curl -X GET "http://admin:password@localhost:8080/pentaho/kettle/status/?xml=Y"

<?xml version="1.0" encoding="UTF-8"?>
<serverstatus>
<statusdesc>Online</statusdesc>
    <memory_free>1192312832</memory_free>
    <memory_total>4294967296</memory_total>
    <cpu_cores>4</cpu_cores>
    <cpu_process_time>1618736639378</cpu_process_time>
    <uptime>499852119</uptime>
    <thread_count>108</thread_count>
    <load_avg>0.0</load_avg>
    <os_name>Linux</os_name>
    <os_version>5.14.0-427.13.1.el9_4.x86_64</os_version>
    <os_arch>amd64</os_arch>
    <transstatuslist>
        <transstatus>
             <transname>testTrans</transname>
             <id>7fe3f507-5b07-4369-b7ff-36c7382dbc7c</id>
            ・・・
        </transstatus>
    </transstatuslist>
    <jobstatuslist>
        <jobstatus>
             <jobname>testJob</jobname>
             <id>470d3363-d3fb-47d9-9d63-db802193f556</id>
             ・・・
        </jobstatus>
    </jobstatuslist>
</serverstatus>
```
ブラウザーから下記のURLにアクセスするとスレーブサーバーステータス画面を開けます。
```
http://admin:password@localhost:8080/pentaho/kettle/status
```



![ddd.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3689802/fbc8637a-994c-46ce-b687-d5c0ccf79d94.png)


### 2-2. データ変換のステータス確認

#### 概要
データ変換のステータスを確認することで、データ変換の実行状態、エラーの有無を把握できます。
ステータスを確認するには、`/pentaho/kettle/transStatus`にアクセスします。
| エンドポイント        | 説明                                         |
|---------------------|--------------------------------------------|
|  `/pentaho/kettle/transStatus` |  データ変換のステータスを確認します。                      |


| パラメータ名        | 説明                                         | 型       |
|---------------------|--------------------------------------------|----------|
|  `name`                 | 確認したいデータ変換(ktrファイル)の名前を指定します。                      | `string` |
|  `xml`(任意)                 | Yを指定すると、XML形式で出力されます。<br> デフォルトはHTMLです。(`xml=N`)                      | `boolean` |
|  `Id`(任意)                 | データ変換のIDを指定します。<br>同じデータ変換を複数実行したときに使用します。                      | `string` |
|  `from`(任意)                 | 出力にログの何行目からを含めるかを指定します。 | `integer` |

#### curlでの実行サンプル
以下は、curlを使用してデータ変換ステータスを確認するGETリクエストのサンプルです。

ここで、`Id`は先ほどの`/pentaho/kettle/status`から帰ってきた値を用いています。
```bash: データ変換ステータス確認
curl -X GET "http://admin:password@localhost:8080/pentaho/kettle/transStatus/?name=testTrans&Id=7fe3f507-5b07-4369-b7ff-36c7382dbc7c&xml=Y"

# 出力例
<?xml version="1.0" encoding="UTF-8"?>
<transstatus>
  <transname>testTrans</transname>
  <id>7fe3f507-5b07-4369-b7ff-36c7382dbc7c</id>
  <status_desc>Finished</status_desc>
  <error_desc/>
  <log_date>2025/04/14 10:46:09.421</log_date>
  <paused>N</paused>
  <stepstatuslist>
    <stepstatus><stepname>Data Grid</stepname><copy>0</copy><linesRead>0</linesRead><linesWritten>3</linesWritten><linesInput>0</linesInput><linesOutput>0</linesOutput><linesUpdated>0</linesUpdated><linesRejected>0</linesRejected><errors>0</errors><statusDescription>完了</statusDescription><seconds>0.0</seconds><speed> 1,500</speed><priority>-</priority><stopped>N</stopped><paused>N</paused></stepstatus>
    <stepstatus><stepname>Text file output</stepname><copy>0</copy><linesRead>3</linesRead><linesWritten>3</linesWritten><linesInput>0</linesInput><linesOutput>4</linesOutput><linesUpdated>0</linesUpdated><linesRejected>0</linesRejected><errors>0</errors><statusDescription>完了</statusDescription><seconds>0.0</seconds><speed> 800</speed><priority>-</priority><stopped>N</stopped><paused>N</paused></stepstatus>
  </stepstatuslist>
  <first_log_line_nr>0</first_log_line_nr>
  <last_log_line_nr>196</last_log_line_nr>
<result><lines_input>0</lines_input>
<lines_output>0</lines_output>
<lines_read>0</lines_read>
<lines_written>0</lines_written>
<lines_updated>0</lines_updated>
<lines_rejected>0</lines_rejected>
<lines_deleted>0</lines_deleted>
<nr_errors>0</nr_errors>
<nr_files_retrieved>0</nr_files_retrieved>
<entry_nr>0</entry_nr>
<result>Y</result>
<exit_status>0</exit_status>
<is_stopped>N</is_stopped>
<log_channel_id>874d3f63-0c79-4516-a630-1b299028129f</log_channel_id>
<log_text/>
<elapsedTimeMillis>0</elapsedTimeMillis>
<executionId/>
</result>  <logging_string>&lt;![CDATA[H4sIAAAAAAAA/zMyMDLVNzDRNzRRMDSwMjGzMrBU0FUoSS0uCSlKzCsGsn0yk1PzilMVyhJzMlMS
S1JT9LiMCGpyySwuSCxJzsjMS1coLkksAmpTSMsvUigByQMZuYklmfl5CtFwPbE4DHVJLElUcC/K
TNEzAPKeti97PqHtcdOk51ubnuxqU9DwtDXQUfAHEUEgItzWWEchFMRytTXQxGFkSGpFiUJaZk6q
Qn5pSUFpCV6TTUAmG2OYDAAYsQwDNwEAAA==
]]&gt;</logging_string>
```

ブラウザーから下記のURLにアクセスするとKettleトランスフォーメーションステータス画面を開けます。
```
http://admin:password@localhost:8080/pentaho/kettle/transStatus/?name=testTrans&Id=7fe3f507-5b07-4369-b7ff-36c7382dbc7c
```

![testTransStatus_v3.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3689802/ecf3751c-18f6-4b41-89b1-7f575177e34e.png)



### 2-3. ジョブのステータス確認
ジョブのステータスを確認することで、ジョブの実行状態、エラーの有無を把握できます。
ステータスを確認するには、`/pentaho/kettle/jobStatus`にアクセスします。
#### 概要

| エンドポイント        | 説明                                         |
|---------------------|--------------------------------------------|
|  `/pentaho/kettle/jobStatus` |  ジョブのステータスを確認します。                      |

| パラメータ名        | 説明                                         | 型       |
|---------------------|--------------------------------------------|----------|
|  `name`                 | 確認したいジョブ(kjbファイル)の名前を指定します。                      | `string` |
|  `xml`(任意)                 | Yを指定すると、XML形式で出力されます。<br> デフォルトはHTMLです。(`xml=N`)                      | `boolean` |
|  `id`(任意)                 | ジョブのIDを指定します。<br>同じデータ変換を複数実行したときなどに使用します。                      | `string` |
|  `from`(任意)                 | 出力にログの何行目からを含めるかを指定します。 | `integer` |

#### curlでの実行サンプル
以下は、curlを使用してジョブステータスを確認するGETリクエストのサンプルです。
`Id`は`executeJob`にリクエストを送った際に帰ってきた値を使用します。
```bash: ジョブステータス確認
curl -X GET "http://admin:password@localhost:8080/pentaho/kettle/jobStatus/?name=testJob&id=470d3363-d3fb-47d9-9d63-db802193f556&xml=Y"

# 出力例
<?xml version="1.0" encoding="UTF-8"?>
<jobstatus>
  <jobname>testJob</jobname>
  <id>470d3363-d3fb-47d9-9d63-db802193f556</id>
  <status_desc>Finished</status_desc>
  <error_desc/>
  <log_date>2025/04/14 10:46:42.809</log_date>
  <logging_string>&lt;![CDATA[H4sIAAAAAAAA/zMyMDLVNzDRNzRRMDSwMjGzMjFS0FUoSS0u8cpPArIeN+143Lz8cfO0x02TXk7r
frq8+3Hj9MeN+8Dk/McNTVxGBEzwyUxOzStOVShLzMlMSSxJTdEjqOX5zN0vezY9buyB2Tj1cVMP
3FKFaJfS3NzKWIqNedYx4WnXfMLmwMMAbuDzrU1PdrUhhwTcNAWNotTi0pwS2+iSotLUWE0qmQ7x
MvmGYzUWFH0A+Xsm/gECAAA=
]]&gt;</logging_string>
  <first_log_line_nr>0</first_log_line_nr>
  <last_log_line_nr>196</last_log_line_nr>
<result><lines_input>0</lines_input>
<lines_output>0</lines_output>
<lines_read>0</lines_read>
<lines_written>0</lines_written>
<lines_updated>0</lines_updated>
<lines_rejected>0</lines_rejected>
<lines_deleted>0</lines_deleted>
<nr_errors>0</nr_errors>
<nr_files_retrieved>0</nr_files_retrieved>
<entry_nr>0</entry_nr>
<result>Y</result>
<exit_status>0</exit_status>
<is_stopped>N</is_stopped>
<log_channel_id/>
<log_text/>
<elapsedTimeMillis>0</elapsedTimeMillis>
<executionId/>
</result></jobstatus>
```

ブラウザーから下記のURLにアクセスするとKettleジョブステータス画面を開けます。
```
http://admin:password@localhost:8080/pentaho/kettle/jobStatus/?name=testJob&id=470d3363-d3fb-47d9-9d63-db802193f556
```

![testJobStatus_v2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3689802/9208f8aa-11b0-400c-a330-c7260317f578.png)




## 3. リポジトリの操作

REST APIを使用することで、リポジトリ内のファイルやディレクトリを操作することができます。ここでは、リポジトリ内に新しいディレクトリを作成する方法を紹介します。

### リポジトリフォルダの操作
#### 概要
`/repo/dirs/{pathId}`は、指定された名前で新しいフォルダを作成します。フォルダが既に存在する場合やエラーが発生した場合には、メッセージが返されます。
| エンドポイント        | 説明                                         |
|---------------------|--------------------------------------------|
|  `/repo/dirs/{pathId}` |  リポジトリに新しいディレクトリを作成します。                      |


| パラメータ名        | 説明                                         | 型       |
|---------------------|--------------------------------------------|----------|
| `pathId`      | ルートまでのパスをコロンで区切って指定します。| `String` |

#### curlでの実行サンプル
リポジトリ内にディレクトリを作成するには、`PUT`メソッドを使用します。
以下は、curlを使用して指定されたパスに新しいディレクトリを作成するPUTリクエストのサンプルです。


```bash: ディレクトリ追加
curl -X PUT "http://admin:password@localhost:8080/pentaho/api/repo/dirs/:home:admin:dir"

# 正常終了した場合
(出力なし)

# 異常終了した場合
(エラーメッセージ)
```

- `http://admin:password@localhost:8080`は、Pentahoサーバーのアドレスです
- `:home:admin:dir`は、作成するディレクトリのパスです。コロンで区切られた形式で指定します

このリクエストを送信することで、指定されたパスに新しいディレクトリが作成されます。

```plantuml
@startuml
<style>
root {
  Padding 0
  Margin 0
}
footer {
  FontColor black
  FontSize 17
}
</style>
footer ディレクトリ作成前
title <img:https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3689802/3fc3de61-5bfd-45a2-8f0b-b09eafc6582f.png>
@enduml
```

先ほどのコマンドを実行すると、以下のようにディレクトリが作成されます。


```plantuml
@startuml
<style>
root {
  Padding 0
  Margin 0
}
footer {
  FontColor black
  FontSize 17
}
</style>
footer ディレクトリ作成後
title <img:https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3689802/fed0348b-e882-43ec-b3ac-747d91543799.png>
@enduml
```

# もっと知りたい方のために


## 詳細や公式情報へのリンク
他のリクエストや、さらに詳細なAPI仕様については、Hitachi Vantaraより提供されている[公式リファレンス](https://docs.hitachivantara.com/v/u/en-us/pentaho-data-integration-and-analytics/10.2.x/mk-95pdia010)を参照してください。

[日立製作所Pentahoチーム](https://qiita.com/organizations/hitachi-pentaho)では、Pentahoを使いたい方や既に使用している方に向けて、さまざまな記事を公開しています。  
気になる機能や質問がありましたら、ぜひコメントをお寄せください。
公開されている記事に関するご意見やご質問もお待ちしております。

# まとめ
本記事では、PentahoのREST APIを活用してデータ統合と分析を効率化する方法について解説しました。REST APIを通じてPentahoの機能をアプリケーションから直接操作することが可能です。

# 他社商品名、商標等の引用に関する表示
HITACHIは，株式会社 日立製作所の商標または登録商標です。
Pentahoは、Hitachi Vantara LLCの商標または登録商標です。
その他記載の会社名，製品名などは，それぞれの会社の商標もしくは登録商標です。