VSCodeでz/OSを操作するためのAPI連携の仕組み：z/OSMFとZoweまとめ

## はじめに：VSCodeでz/OSを操作する
z/OS（メインフレーム）の操作といえば、昔ながらの3270エミュレータを思い浮かべる方が多いのではないでしょうか。黒い画面と緑の文字、独特のキー操作など…慣れれば効率的に操作できますが、使いづらさを感じることもあるかもしれません。特に、若い世代にとっては、使いづらさの壁がメインフレーム開発への参入障壁になっている可能性も否めません。

そこで登場するのが、VSCodeを使ったz/OSの操作です。Zowe ExplorerプラグインとZowe CLIコマンドラインツールを組み合わせることで、VSCodeからz/OSのリソースにアクセスできるようになります。ファイル編集、ジョブ実行、データセット操作などがVSCode上で行えるため、開発効率の向上、学習コストの削減に繋がります。

VSCodeとz/OSを連携させるには、z/OS側にz/OS Management Facility (z/OSMF) が必要です。z/OSMFは、z/OSの様々な機能をREST APIとして公開するミドルウェアで、ZoweはこのAPIを利用してz/OSと通信します。

実際にVSCodeとz/OSの連携環境を構築してみたところ、「Zoweとz/OSMFはどのように連携しているのか？ z/OSMFはAPIリクエストをどのように処理するのか？ z/OSMFにはどのような定義が必要なのか？」という疑問が浮かびました。

まずは、z/OSMF固有ではなく、一般的なサーバー内部に必要な定義や処理フローについて調査してまとめました。
詳細は以下の記事をご覧ください。
[APIサーバーの内部動作：リクエストからレスポンスまでの処理の流れ](https://qiita.com/uga_zosmf/items/f60f71775308b2ae2a4f?utm_campaign=post_article&utm_medium=twitter&utm_source=twitter_share "APIサーバーの内部動作：リクエストからレスポンスまでの処理の流れ")

本記事では、z/OSMFを経由したVSCodeとz/OSを連携について、APIリクエストが発行されてからレスポンスが返されるまでの流れ、そしてz/OSMFに存在する定義について詳しく見ていきます。
## z/OSMFの役割
z/OSMFの役割について解説していきます。
z/OSの操作はISPFなどの専用インターフェースを介して行われ、他システムとの連携には高いハードルがありました。z/OSMFはz/OSの機能をREST APIとして公開することでこれらを解決し、様々なツールがz/OSにアクセスできるようになりました。

その代表例が Zowe です。Zowe Explorer と Zowe CLI は、z/OSMF の API を利用して z/OS のリソースへのアクセスと操作を実現します。Zowe Explorer を使用すると、VSCode 上で、クリック操作による z/OS の操作が可能になります。一方、Zowe CLI を使用すると、Node.js のコマンドプロンプトからコマンドを実行することで z/OS を操作できます。

z/OSMFのAPIは多種多様で、データセット操作、ジョブ実行、システム情報取得などz/OSの主要機能をAPI経由で利用できます。
概念的に図示すると以下のようなイメージになるかと思います。

![20250313_ZOSMF_VSCODE連携_API連携_1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4030603/6993c11a-026c-4ed0-b1ba-f4dd7ffaf5a4.png)

## APIリクエスト処理の流れ：サーバー内部の動き
前回の記事でも記載しましたが、APIサーバーはクライアントからのリクエストを受け取ると、内部で様々な処理を行います。順を追って解説します。
1.	リクエストの受信: クライアントからのHTTPリクエストをAPIサーバーが受信。サーバーは特定ポートでリクエストを待ち受け、接続を確立する
2.	ルーティング: 受信したリクエストはURLに基づき適切な処理へルーティングされる。例えば、/datasets ならデータセット一覧取得処理、/jobs ならジョブ操作処理へと振り分けられる
3.	認証認可: APIによってはアクセス制限があり、リクエストに含まれる認証情報（APIキーやアクセストークンなど）を検証し、アクセス権限を持つクライアントのみ処理を行う
4.	ビジネスロジックの実行: 認証認可後、リクエストに対応するビジネスロジック（APIの具体的な機能を実装した処理）が実行される。データセット一覧取得APIならz/OSのデータセット一覧を取得する処理、ジョブ実行APIならz/OSにジョブを実行する処理が実行される
5.	レスポンスの生成: ビジネスロジックの実行結果に基づき、HTTPレスポンス（ステータスコード、ヘッダー、ボディ）が生成される。ボディにはリクエストされたデータやエラーメッセージなどが含まれる
6.	レスポンスの送信: 生成されたHTTPレスポンスはクライアントに送信される。クライアントはレスポンスを受信し、データを取得したり、ステータスコードを確認してエラー処理などを行う

## z/OSMFのAPI連携
この章では、z/OSMFを経由したVSCodeとz/OSを連携におけるAPI リクエスト処理を解説します。 Zowe Explorer と Zowe CLI の両ツールを使用した場合の、具体的な処理の流れと例を示します。
### 0. 共通のポイント
- Zowe Explorer (VS Code 拡張) や Zowe CLI は、z/OS と直接対話するのではなく、z/OSMF が提供する REST API を利用して z/OS の機能にアクセスする
- z/OSMF は、API リクエストを受け取ると、z/OS の対応するサービスを呼び出し、結果を返す
- セキュリティ確保のため、z/OSMF への API リクエストには認証情報が必要
### 1. Zowe Explorer (VS Code 拡張) の場合
例えば、VS Code 上で Zowe Explorer を使ってデータセットを閲覧する場合、以下の流れで処理が行われます。
1.	操作: ユーザーが Zowe Explorer でデータセットの閲覧操作を行う
2.	API リクエスト生成: Zowe Explorer は、この操作に対応する API リクエストを生成する
3.	リクエスト送信: Zowe Explorer は生成した API リクエストを z/OSMF に送信
4.	z/OSMF による処理: z/OSMF はリクエストを受け取り、対応する z/OS サービスを呼び出す
5.	z/OS からの応答: z/OS は処理結果を z/OSMF に返す
6.	レスポンス返却: z/OSMF は結果を Zowe Explorer に返す
7.	表示: Zowe Explorer は結果を VS Code 上に表示する
### 2. Zowe CLI の場合
例えば、`zowe zos-files list data-set "SAMPLE.DATASET.NO*" `コマンドを実行する場合、以下の流れで処理が行われます。
1.	コマンド入力: ユーザーが上記のコマンドを入力する
2.	API リクエスト生成: Zowe CLI はコマンドを解析し、対応する API リクエストを生成する
3.	リクエスト送信: Zowe CLI は生成した API リクエストを z/OSMF に送信
4.	z/OSMF による処理: z/OSMF はリクエストを受け取り、対応する z/OS サービスを呼び出す
5.	z/OS からの応答: z/OS は処理結果を z/OSMF に返す
6.	レスポンス返却: z/OSMF は結果を Zowe CLI に返す
7.	出力: Zowe CLI は結果をコマンドプロンプトに出力
### 3. 具体的な例
#### API リクエスト
上記の `zowe zos-files list data-set "SAMPLE.DATASET.NO*"` コマンドは、内部で以下のような HTTP リクエストに変換されて z/OSMF に送信されると推測されます。
```shell
curl -X GET \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
'https://<IPaddress>:<Port>/zosmf/restfiles/ds?dslevel=SAMPLE.DATASET.NO*'
```
- `-X GET`: GET メソッドを指定
- `--header 'Content-Type: application/json'`: リクエストボディのデータ形式を JSON と指定
- `--header 'Authorization: Bearer <access_token>'`: 認証ヘッダー。`<access_token>` には、z/OSMF へのアクセスに必要な認証トークンが入る
- `'https://<IPaddress>:<Port>/zosmf/restfiles/ds?dslevel=SAMPLE.DATASET.NO*'`: API エンドポイントとリクエストパラメータを指定
#### z/OSMF 内部の処理
z/OSMF は、受信したリクエストを解析し、内部のルーティング定義に基づいて対応する z/OS モジュールにリクエストを転送します。 このルーティング定義は、API のエンドポイントと z/OS モジュールのマッピングを規定するものです。 例えば、データセット一覧取得のリクエストの場合、`IZUGLSDS` モジュールがそのビジネスロジックを担っていると推測されます。 このモジュールは、リクエストに含まれる dslevel パラメータの値 (データセット名のパターン) を受け取り、z/OS 上で該当するデータセットの検索コマンドを実行すると考えられます。 （`IZUGLSDS` モジュールの詳細な動作は IBM の非公開情報であるため、推測に基づく記述となります。）

ルーティング定義の例:
```jsonc
{
  "servlet-name": "ListDatasets", // z/OSMF 内で使用する識別名
  "url-pattern": "(/ds)$",       // API のエンドポイントのパス
  "method": "GET",                // サポートする HTTP メソッド
  "module": "IZUGLSDS"            // 呼び出す z/OS モジュール名 (ビジネスロジックの実装)
}
```
この例では、`/ds` というエンドポイントへの GET リクエストが `IZUGLSDS` という z/OS モジュールにルーティングされます。 z/OSMF は、この定義に基づいてリクエストを適切なモジュールに転送し、そこでビジネスロジックが実行されます。 `IZUGLSDS`モジュールは、dslevel パラメータの値に基づいてデータセットを検索し、その結果を z/OSMF に返します。

z/OSMF からのレスポンスの例:
```jsonc
  "items": [
    { "dsname": "SAMPLE.DATASET.NO1" },
    { "dsname": "SAMPLE.DATASET.NO2" },
    { "dsname": "SAMPLE.DATASET.NO3" }
  ],
  "returnedRows": 3
}
```
### 概念図
概念的に図示すると以下のようなイメージになるかと思います。

![20250313_ZOSMF_VSCODE連携_API連携_2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4030603/c18d4270-489c-40f3-b7cb-1e0598860530.png)


VSCode と z/OS の連携において、z/OSMF は API リクエストを処理する役割を担います。 z/OSMF は、リクエストされた API のエンドポイントに基づいて、定義されたルーティングに従い、対応する z/OS モジュール(ビジネスロジック) を呼び出します。 これにより、z/OS の様々な機能を API 経由で利用できるようになります。

## まとめ：VSCode で z/OS を操作する際の z/OSMF の役割と連携の仕組み
この記事では、VSCode と z/OS を連携させる際の z/OSMF の役割と、API リクエスト処理の流れについて解説しました。 この連携において、z/OSMF は z/OS の機能を REST API として公開するミドルウェアとして重要な役割を果たします。
VSCode 上での操作は、Zowe によって API リクエストに変換され、z/OSMF に送信されます。 z/OSMF は以下の手順でこのリクエストを処理します。
1.	リクエスト受信: z/OSMF は Zowe から API リクエストを受信
2.	ルーティング: リクエストに含まれるエンドポイントに基づいて、内部のルーティング定義を参照し、対応する z/OS モジュールを特定
3.	モジュール実行 (ビジネスロジック): 特定された z/OS モジュールにリクエストのパラメータを渡し、実行を依頼。 例えば、データセット一覧取得のリクエストでは、IZUGLSDS モジュールが dslevel パラメータの値に基づいてz/OS上でデータセットを検索する
4.	結果返却: z/OS モジュールからの処理結果を z/OSMF が受け取り、JSON 形式等に変換して Zowe に返送
5.	表示: Zowe は受信した結果を VSCode 上に表示

実際に VSCode と z/OS の連携環境を構築する中で、「Zowe と z/OSMF はどのように連携しているのか？ z/OSMF は API リクエストをどのように処理するのか？ z/OSMF にはどのような定義が必要なのか？」という疑問が浮かびました。 今回の調査を通して、これらの疑問に対する答えが得られました。
- Q1: Zowe と z/OSMF はどのように連携しているのか？ 
A1: Zowe CLI や Zowe Explorer はユーザー操作を API リクエストに変換し、z/OSMF に送信。z/OSMF は REST API を用いて z/OS のサービスを呼び出し、結果を Zowe に返す
- Q2: z/OSMF は API リクエストをどのように処理するのか？ 
A2: z/OSMF はルーティング定義に基づき API リクエストを処理する。リクエストのエンドポイントと HTTP メソッドを元に、対応する z/OS モジュールを特定し、パラメータを渡して実行を依頼。モジュールからの処理結果を JSON 形式などでクライアントに返送。
- Q3: z/OSMF にはどのような定義が必要なのか？ 
A3: z/OSMF には API エンドポイントと z/OS モジュールの対応関係を定義する「ルーティング定義」が必要。※API アクセス制御を行う「セキュリティー定義」も必要ですが、これについては別の記事で詳しく解説します

z/OSMF を利用することで、VSCode から z/OS のリソースを操作するためのモダンなインターフェースが実現されます。 これにより、開発効率の向上、学習コストの削減が期待できます。 下記の記事では、APIリクエストを受け付ける一般的なサーバー内部の定義や処理フローについて解説していますので、合わせてご参照ください。
[APIサーバーの内部動作：リクエストからレスポンスまでの処理の流れ](https://qiita.com/uga_zosmf/items/f60f71775308b2ae2a4f?utm_campaign=post_article&utm_medium=twitter&utm_source=twitter_share "APIサーバーの内部動作：リクエストからレスポンスまでの処理の流れ")


※Zowe = 操作をAPIに変換する、という形で解説してきましたが、実はこの理解は少し限定的です。Zoweの役割は「操作やコマンドをREST APIに変換する」ことだけではなく、Zowe自体もREST APIを提供しています。またZoweは包括的なプラットフォームで、様々なツールやインターフェースを提供してz/OSへのアクセスのモダナイズを実現できます。詳細は公式ドキュメントをご覧いただければと思います。

### 参考文献
[Zowe 公式ドキュメント](https://docs.zowe.org/ "Zowe 公式ドキュメント")
[Zowe GitHub リポジトリ](https://github.com/zowe "Zowe GitHub リポジトリ")
[IBM® z/OS 管理機能構成要約のガイド - IBM Documentation](https://www.ibm.com/docs/ja/zos/2.5.0?topic=facility-zos-management-configuration-guide "IBM® z/OS 管理機能構成要約のガイド - IBM Documentation")
[IBM z/OS Management Facility Programming Guide - IBM Documentation](https://www.ibm.com/docs/ja/zos/2.5.0?topic=facility-zos-management-programming-guide "IBM z/OS Management Facility Programming Guide - IBM Documentation")