LoginSignup
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@shiori_nin株式会社セゾンテクノロジー

【HULFT10 API Gatewayの歩き方】⑦APIでHULFTを操作する方法

Last updated at Posted at 2025-07-16

この【HULFT10 API Gatewayの歩き方】シリーズは、
「HULFTは知っているけど、HULFT10 API Gatewayって何？どう操作するの？」
といった方に向けた実践ガイドブックです。

ぜひご自身でも実際にHULFT10 API Gatewayを操作してみてください！
他のシリーズはこちら👉【HULFT10 API Gatewayの歩き方】シリーズまとめ

紹介で使用している製品

HULFT10 API Gateway v10.2.1

今回のテーマ：APIの使い方

この章を読み進めることで、APIでHULFTを操作する方法についてマスターできます。

  1. API利用の流れについて
  2. APIで管理情報登録
  3. APIで配信要求発行
  4. APIで配信履歴取得

APIの利用経験がない方にも理解いただけるよう、丁寧に解説しています！

この記事ではWindowsコマンドプロンプトを使った検証になります。
PowerShellとは異なる箇所がありますのでご注意ください。

1. API利用の流れ

今回はcurlコマンドを使用して検証します。
（※他のAPIプラットフォームでも利用可能です。）

APIを利用する際に必要な情報は大きく3つあります。

  • ホストID
  • アクセストークン
  • URL

加えてPOSTやPUTの場合、リクエストボディが必要になります！

以下で必要な情報の取得方法をご紹介します。

ホストIDの取得方法

操作したいHULFTごとに割り振られる一意のIDです。
管理対象のHULFTに接続した後のURLから取得することができます。

①管理対象のHULFTに接続
画像1.png


②接続後のURLバーにある「HOSTID(数字)」がホストIDです。
画像24.png

このIDはURL指定時に使用します。

アクセストークンの取得方法

作成したユーザーに対して生成されるトークンです。
このトークンは、対象ユーザーの詳細画面から確認・取得できます。

①アクセストークンを取得するユーザーを選択します。
画像3.png


②画面をスクロールし、最下部にある「アクセストークンを発行」をクリックします。
画像4.png

↓

画像16.png


③コピーマークをクリックし、アクセストークンを取得できます。
画像8.png

アクセストークンはこの画面を閉じると再表示されません。
再発行は可能ですが、取り扱いに注意が必要です。

アクセストークンはリクエストヘッダにてBearer認証として使用します。

URLの取得方法

APIの送り先であるURLはマニュアルに記載されています。
👉【公式】HULFT10 API Gateway WebAPIリファレンス

①topページの左サイドメニューにある「WebAPI仕様」をクリックします。
画像9.png


②接続先HULFTのOSを選択します。
画像10.png

OSごとに分かれているのは、HTTPリクエストのボディの内容が各機種ごとに異なるためです。


③HULFTの操作を選択すると、該当のURLが表示されます。
image.png
ControlURL：サーバーのURL（例：localhost:8080）
{hulft-host-id}：①で取得したHOSTID

このURLは画面からも取得できます。
その場合、[ControlURL]より後ろのパスにAPI用のパスを追加する必要があります。

例）配信管理情報一覧取得
画面URL：http://[ControlURL]/hulft/[HOSTIDxxxxxxxx]/logs/sendings/list
↓
APIURL：http://[ControlURL]/api/v1/hulft/[HOSTIDxxxxxxxx]/logs/sendings/list

その他に適宜必要なもの

リクエストボディ

POSTやPUTの場合はリクエストボディが必要になります。

curlコマンドで行う場合でも、リクエストボディをファイルに記載しておくと、コピー＆ペーストで簡単に作成できるため便利です。
画像14.png

クエリ

URLの最後に?をつけ、任意のクエリパラメータを付与することで条件を指定できます。
画像15.png

curlコマンドでの指定方法

指定するのは大きく5項目です。

curl -X POST
-H "Content-Type:application/json"
-H "Authorization: Bearer [Access Token]"
-d @C:\api_gateway_snd_data.json
http://[ControlURL]/api/v1/hulft/[HOSTID]/managements/sendings/detail​

①-X：HTTPメソッドを指定します。
②③-H：HTTPヘッダーを指定します。HULFT10 API Gatewayでは「Content-Type」と「Authorization」の2つのヘッダーを指定する必要があります。

Authorizationを指定する際、アクセストークンの前にBearer を入れます。
Bearerの後ろの半角スペースを忘れないでください！

検証ではWindowsコマンドプロンプトを使用しているため、
引用符はシングルクォーテーションではなく、
例のようにダブルクォーテーションを使用しています。

④-d：データを指定します。上の例ではファイルの内容をリクエストボディとして指定しています。

ファイルパスを指定する時は@を使用します。

⑤URL：HTTPリクエスト先のURLを指定します。

このコマンドを実行し、成功するとレスポンスが返ってきます。

✅ APIの利用方法についてわかりました！

2.APIで管理情報登録

それでは、前の章「④~HULFTの操作~ 管理情報作成」で作成した管理情報をもとに、
配信管理情報をAPIで新規作成しましょう！
image.png


まずは必要な情報から取得していきます。

  • ホストID（先ほどのものを使用）

  • アクセストークン（先ほどのものを使用）

  • URL　⇒HULFT10 API Gateway WebAPIリファレンスから取得

    http://ControlURL/api/v1/hulft/{hulft-host-id}/managements/sendings/detail

  • リクエストボディ　⇒HULFT10 API Gateway WebAPIリファレンスからコピー

    {
  "id": "FILEID",
  "comment": "コメント",
  "file": {
    "name": "C:\\testfile\\testfile.bin",
    "type": "binary",
    "treat": "keep"
  },
  "communication": {
    "transfer_group": "LOOPBACK",
    "block_length": 128,
    "block_count": 99,
    "priority": 1,
    "interval": 100
  },
  "code_conversion": {
    "side": "sending",
    "ebcdic_set": "auto",
    "shiftcode": "none"
  },
  "compression": {
    "type": "deflate",
    "mode": "standard"
  },
  "job": {
    "pre": "PREJOB",
    "successful": "SUCCJOB",
    "unsuccessful": "FAILJOB"
  },
  "security": {
    "password": "PASSWORD"
  },
  "windows": {
    "mail_id": "MAIL"
  }
}

これをjsonファイルに貼り付けます。（※ファイルパスをメモしておきます。）

インデントがズレないよう、注意してください。

JSON内のWindowsファイルパスでは、バックスラッシュ（\）を二重（\\）に記述する必要があります。


以下のように、内容を変更します。

{
  "id": "LOOPBACK_TEST_2",
  "comment": "テスト",
  "file": {
    "name": "C:\\test\\send.txt",
    "type": "text",
    "treat": "keep"
  },
  "communication": {
    "transfer_group": "LOOPBACK"
  },
  "code_conversion": {
    "side": "sending"
  },
  "compression": {
    "type": "none"
  }
}

スキーマ情報に「必須」とある項目は必ず値を設定しましょう。

画像18.png

次に上記の情報をcurlコマンドに当てはめていきます。

curl -X POST
-H "Content-Type:application/json"
-H "Authorization: Bearer [Access Token]"
-d @C:\post_snd_managements.json
http://[ControlURL]/api/v1/hulft/[HOSTID]/managements/sendings/detail​
コピー用 
curl -X POST -H "Content-Type:application/json" -H "Authorization: Bearer [Access Token]" -d @C:\post_snd_managements.json http://[ControlURL]/api/v1/hulft/[HOSTID]/managements/sendings/detail​

すると以下のレスポンスが出力されました。

{"meta":{"request_user_role":"admin","os_type":"windows","strong_key_mode":"disable","product_version":"V10L02R00P00"},"id":"LOOPBACK_TEST_2","comment":"テスト","file":{"name":"C:\\test\\send.txt","type":"text","treat":"keep"},"communication":{"transfer_group":"LOOPBACK","block_length":0,"block_count":0,"priority":50,"interval":0},"code_conversion":{"side":"sending","ebcdic_set":"auto","shiftcode":"add"},"compression":{"type":"none","mode":"","unit":0},"job":{"pre":"","successful":"","unsuccessful":""},"multiformat_id":"","security":{"password":""},"database_id":"","windows":{"mail_id":""}}

画面からも確認できました！
画像17.png

✅ APIで管理情報を登録できました！

※次のトピックで、上記の配信管理情報の対となる集信管理情報も必要になります。

【WebAPIリファレンス】

【公式】集信管理情報の登録（Windows）

【リクエストボディ】

{
  "id": "LOOPBACK_TEST_2",
  "comment": "テスト",
  "file": {
    "name": "C:\\test\\receive2.txt",
    "write_mode": "replace",
    "abnormal_treat": "delete",
    "receive_mode": "single",
    "generational_management": "disable"
  }
}

【curlコマンド】

curl -X POST
-H "Content-Type:application/json"
-H "Authorization: Bearer [Access Token]"
-d @C:\post_rcv_managements.json
http://[ControlURL]/api/v1/hulft/[HOSTID]/managements/receivin/detail​

コピー用

curl -X POST -H "Content-Type:application/json" -H "Authorization: Bearer [Access Token]" -d @C:\post_rcv_managements.json http://[ControlURL]/api/v1/hulft/[HOSTID]/managements/receivin/detail​

3. APIで配信要求発行

続いて、今登録した配信管理情報で配信要求をしてみましょう！

必要な情報は配信管理情報登録時とほぼ同じなため、詳細な説明は割愛します。
以下のWebAPIリファレンスを適宜ご覧ください。

今回もPOSTですが、指定するデータの数が少ないためcurlコマンドに直接指定します。

curl -X POST
-H "Content-Type:application/json"
-H "Authorization: Bearer [Access Token]" 
-d "{\"id\":\"LOOPBACK_TEST_2\"}"
http://[ControlURL]/api/v1/hulft/[HOSTID]/requests/sendings
コピー用 
curl -X POST -H "Content-Type:application/json" -H "Authorization: Bearer [Access Token]" -d "{\"id\":\"LOOPBACK_TEST_2\"}" http://[ControlURL]/api/v1/hulft/[HOSTID]/requests/sendings

以下のレスポンスが出力されました。

{"meta":{"request_user_role":"admin","os_type":"windows","strong_key_mode":"disable","product_version":"V10L02R00P00"},"latest_transfer_id":"71CC60B36111D032C805AC95BAD54CE061000100000000000000000000000000","latest_process_id":"71CC60B36111D032C805AC95BAD54CE061"}

新規作成したファイルに、配信管理情報で設定したファイルの内容が反映されていました。
image.png

✅ APIで配信要求できました！

4. APIで配信履歴取得

最後に、先ほどの配信の履歴を取得します！

これまでの手順とほぼ同じなため、詳細な説明は割愛します。
以下のWebAPIリファレンスを適宜ご覧ください。

今回はGETなため、curlコマンドの-dは使用せず実行します。
また、わかりやすさを重視し、ファイルIDを指定して取得する方法で行います。

curl -X GET
-H "Content-Type:application/json"
-H "Authorization: Bearer [Access Token]"
http://[ControlURL]/api/v1/hulft/[HOSTID]/logs/sendings/list?file-id=LOOPBACK_TEST_2
コピー用 
curl -X GET -H "Content-Type:application/json" -H "Authorization: Bearer [Access Token]" http://[ControlURL]/api/v1/hulft/[HOSTID]/logs/sendings/list?file-id=LOOPBACK_TEST_2

以下のレスポンスが出力されました。

{"meta":{"total":1,"request_user_role":"admin","os_type":"windows","strong_key_mode":"disable","product_version":"V10L02R00P00"},"records":[{"file_id":"LOOPBACK_TEST_2","id":{"latest_transfer":"71CC60B36111D032C805AC95BAD54CE061000100000000000000000000000000","latest_process":"71CC60B36111D032C805AC95BAD54CE061"},"comment":"テスト","status":{"code":0,"detail":0,"description":"","measure":""},"file":{"name":"C:\\test\\send.txt","transferred":{"rows":1,"size":19}},"code_conversion":{"side":"sending"},"communication":{"host":[HOSTNAME],"ip_version":"ipv4","rate":19,"block_length":65520,"block_count":1},"datetime":{"accept":"2025-07-15T00:45:28Z","start":"2025-07-15T00:45:28Z","end":"2025-07-15T00:45:28Z"},"compression":{"type":"none","ratio":0},"database_id":"","security":{"encryption_scheme":"none"},"message":{"short":["","","","","",""],"long":["",""]},"windows":{"connection_type":"lan","job_id":""}}]}

画面の通り、指定したファイルIDの配信履歴（1件）を取得できました。
画像21.png

✅ APIで配信履歴を取得できました！

まとめ

今回はAPIでHULFTを操作する一連の流れを操作しました！
✅ API利用方法
✅ APIで管理情報を登録する方法
✅ APIで配信要求を発行する方法
✅ APIで配信履歴を取得する方法

次回は「HULFT SquareからAPIでHULFTを操作」についてご紹介いたします！

📢「こんなこと知りたい！」などリクエストがあればぜひコメントをお寄せください。

付録

WebAPIリファレンスの使い方（補足）

本編でご紹介した内容に加え、WebAPIリファレンスをより効果的に活用するためのポイントが2つあります。

  • パラメーターの値を省略できる！
  • パラメーターの説明が記載されている！

パラメーターの値を省略

例えば、パラメーターが多い配信管理情報では、サンプルのように多くの値を指定する必要があります。
画像22.png


サンプルや本編では、分かりやすくするために正式な名称で値を設定していましたが、
実は、これらの値を1文字に省略して設定することが可能です！


スキーマ情報には、設定可能な値の横に括弧（ ）で囲まれた文字が記載されており、
この値の省略文字であることを示しています。
画像23.png
そのため、転送タイプを「binary」にしたい場合、「B」と指定しても同様の意味として認識されます！

サンプルをすべて省略文字にした例 
{
  "id": "FILEID",
  "comment": "コメント",
  "file": {
    "name": "C:\\testfile\\testfile.bin",
    "type": "B",
    "treat": "K"
  },
  "communication": {
    "transfer_group": "LOOPBACK",
    "block_length": 128,
    "block_count": 99,
    "priority": 1,
    "interval": 100
  },
  "code_conversion": {
    "side": "S",
    "ebcdic_set": "0",
    "shiftcode": "N"
  },
  "compression": {
    "type": "3",
    "mode": "D"
  },
  "job": {
    "pre": "PREJOB",
    "successful": "SUCCJOB",
    "unsuccessful": "FAILJOB"
  },
  "security": {
    "password": "PASSWORD"
  },
  "windows": {
    "mail_id": "MAIL"
  }
}

多くの省略文字は頭文字になっていますが、一部の値は頭文字とは異なるものもあります。

パラメーターの説明

スキーマ情報には、各パラメーターの説明、およびそのパラメーターに設定できる値の詳細も記載されています。
image.png

画面操作を行う上でも有用な情報です。ぜひご活用ください！

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?