# 画面設計書 11-ジョブ履歴・出力

## 概要

本ドキュメントは、SQL Server Agent のジョブ実行履歴の取得および出力ファイル設定を行うコマンド群の設計仕様を記述したものです。

### 本画面の処理概要

本機能は、SQL Server Agent ジョブの実行履歴を取得し、トラブルシューティングやコンプライアンスレポート作成を支援します。また、ジョブステップの出力ファイルパスの取得・設定機能も提供します。

**業務上の目的・背景**：SQL Server Agent ジョブの実行状況を監視し、失敗したジョブの原因調査、パフォーマンス傾向分析、監査ドキュメント作成を行う必要があります。手動で SQL Server Management Studio からジョブアクティビティモニターを確認する代わりに、PowerShell コマンドで効率的にデータを取得・分析できます。

**画面へのアクセス方法**：PowerShell コンソールまたはスクリプトから以下のコマンドを実行してアクセスします。
- `Get-DbaAgentJobHistory` - ジョブ実行履歴の取得
- `Get-DbaAgentJobOutputFile` - ジョブステップ出力ファイルパスの取得
- `Set-DbaAgentJobOutputFile` - ジョブステップ出力ファイルの設定

**主要な操作・処理内容**：
1. SQL Server インスタンスに接続し、msdb データベースから SQL Agent ジョブの実行履歴を取得
2. 期間、結果タイプ（成功/失敗/リトライ/キャンセル）、ジョブ名でフィルタリング
3. ジョブステップレベルまたはジョブサマリーレベルでの履歴表示
4. 出力ファイルパスの取得と SQL Agent トークンプレースホルダーの解決
5. ジョブステップの出力ファイルパス設定の変更

**画面遷移**：本機能はCLIコマンドであり、他のコマンドとパイプライン連携が可能です。
- `Get-DbaAgentJob` からパイプラインで `Get-DbaAgentJobHistory` へ連携可能
- `Get-DbaAgentJobHistory -WithOutputFile` で出力ファイル情報を含めて取得可能

**権限による表示制御**：msdb データベースへの読み取り権限が必要です。出力ファイル設定の変更には SQLAgentOperatorRole または sysadmin 権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 487 | Get-DbaAgentJobHistory | 主機能 | SQLエージェントジョブ実行履歴の取得 |
| 488 | Get-DbaAgentJobOutputFile | 補助機能 | ジョブステップ出力ファイルパスの取得 |
| 515 | Set-DbaAgentJobOutputFile | 補助機能 | ジョブステップ出力ファイルの設定 |

## 画面種別

一覧 / 設定

## URL/ルーティング

PowerShell コマンドとして提供（CLIベース）
- `Get-DbaAgentJobHistory`
- `Get-DbaAgentJobOutputFile`
- `Set-DbaAgentJobOutputFile`

## 入出力項目

### Get-DbaAgentJobHistory パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Job | object[] | No | 対象ジョブ名（ワイルドカード対応） |
| ExcludeJob | object[] | No | 除外するジョブ名 |
| StartDate | DateTime | No | 開始日時（デフォルト: 1900-01-01） |
| EndDate | DateTime | No | 終了日時（デフォルト: 現在日時） |
| OutcomeType | CompletionResult | No | 結果タイプ（Failed/Succeeded/Retry/Cancelled/InProgress/Unknown） |
| ExcludeJobSteps | switch | No | ジョブステップを除外（サマリーのみ） |
| WithOutputFile | switch | No | 出力ファイルパスを含める |
| JobCollection | Job[] | No | SMOジョブオブジェクト（パイプライン入力） |
| EnableException | switch | No | 例外を有効化 |

### Get-DbaAgentJobOutputFile パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Job | object[] | No | 対象ジョブ名 |
| ExcludeJob | object[] | No | 除外するジョブ名 |
| EnableException | switch | No | 例外を有効化 |

### Set-DbaAgentJobOutputFile パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Job | object[] | No | 対象ジョブ名 |
| Step | object[] | No | 対象ステップ名 |
| OutputFile | string | Yes | 出力ファイルパス |
| WhatIf | switch | No | 実行確認のみ |
| Confirm | switch | No | 確認プロンプト |
| EnableException | switch | No | 例外を有効化 |

## 表示項目

### Get-DbaAgentJobHistory 出力

| 項目名 | 説明 |
|--------|------|
| ComputerName | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | SQL Serverインスタンス名 |
| SqlInstance | 完全なSQL Serverインスタンス名 |
| Job | SQL Agentジョブ名（JobNameのエイリアス） |
| StepName | 実行されたジョブステップ名 |
| RunDate | 実行開始日時 |
| StartDate | 実行開始日時（DbaDatTime形式） |
| EndDate | 実行終了日時（計算値） |
| Duration | 実行時間（PrettyTimeSpan形式） |
| Status | 実行ステータス（Failed/Succeeded/Retry/Canceled） |
| OperatorEmailed | オペレーターへのメール送信有無 |
| Message | 実行メッセージまたは失敗理由 |
| OutputFileName | 出力ファイルパス（-WithOutputFile時） |
| RemoteOutputFileName | リモートUNCパス（-WithOutputFile時） |

### Get-DbaAgentJobOutputFile 出力

| 項目名 | 説明 |
|--------|------|
| ComputerName | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | SQL Serverインスタンス名 |
| SqlInstance | 完全なSQL Serverインスタンス名 |
| Job | SQL Agentジョブ名 |
| JobStep | ジョブステップ名 |
| OutputFileName | ローカル出力ファイルパス |
| RemoteOutputFileName | リモートUNCパス |
| StepId | ステップID（非表示） |

## イベント仕様

### 1-ジョブ履歴取得

**処理フロー**:
1. `Connect-DbaInstance` でSQL Serverインスタンスに接続
2. `JobHistoryFilter` オブジェクトを作成し、日付範囲・結果タイプを設定
3. `$server.JobServer.EnumJobHistory($filter)` でmsdbから履歴を取得
4. 各実行記録にComputerName、Duration、Status等の計算フィールドを追加
5. `-WithOutputFile` 指定時は出力ファイルパスのトークンを解決
6. `Select-DefaultView` で整形して出力

### 2-出力ファイルパス取得

**処理フロー**:
1. `Connect-DbaInstance` でSQL Serverインスタンスに接続
2. `$server.JobServer.Jobs` から対象ジョブを取得
3. 各ジョブの `JobSteps` を反復処理
4. `OutputFileName` が設定されているステップのみ出力
5. `Join-AdminUNC` でリモートUNCパスを生成

### 3-出力ファイルパス設定

**処理フロー**:
1. `Connect-DbaInstance` でSQL Serverインスタンスに接続
2. 対象ジョブとステップを特定
3. ステップ未指定かつ複数ステップの場合は `Out-GridView` で選択UI表示
4. `$jobStep.OutputFileName = $OutputFile` でパスを設定
5. `$jobStep.Alter()` でSQL Server側に変更を反映
6. 変更前後の設定値を含むオブジェクトを出力

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaAgentJobHistory | msdb.dbo.sysjobhistory | SELECT | ジョブ実行履歴の取得 |
| Get-DbaAgentJobOutputFile | msdb.dbo.sysjobsteps | SELECT | ジョブステップ設定の取得 |
| Set-DbaAgentJobOutputFile | msdb.dbo.sysjobsteps | UPDATE | ジョブステップの出力ファイル設定更新 |

### テーブル別更新項目詳細

#### msdb.dbo.sysjobsteps

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | output_file_name | ユーザー指定のファイルパス | Set-DbaAgentJobOutputFile実行時 |

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|---------------|------|---------------|
| Warning | -ExcludeJobSteps と -WithOutputFile を同時指定 | "You can't use -ExcludeJobSteps and -WithOutputFile together" |
| Warning | -Job 未指定（Set-DbaAgentJobOutputFile） | "You must specify a job using the -Job parameter." |
| Warning | 指定ステップが見つからない | "$Step didn't return any steps" |
| Verbose | 出力ファイル未設定のステップ | "$step for $j has no output file" |
| Error | 接続失敗 | "Failure" (ConnectionError) |
| Error | 履歴取得失敗 | "Could not get Agent Job History from $instance" |
| Error | 出力ファイル設定失敗 | "Failed to add $OutputFile to $jobStep for $currentJob" |

## 例外処理

| 例外条件 | 対応 |
|---------|------|
| SQL Serverインスタンスへの接続失敗 | Stop-Function でエラー出力し、次のインスタンスへ継続 |
| ジョブ履歴取得失敗 | Stop-Function でエラー出力し、処理継続 |
| 出力ファイル設定更新失敗 | Stop-Function で内部エラーと共に出力 |
| 無効なパラメータ組み合わせ | Stop-Function で即時停止 |

## 備考

- ジョブ履歴の保存期間はSQL Agent履歴クリーンアップ設定に依存
- トークンプレースホルダー（`$(SQLLOGDIR)`, `$(INST)`, `$(MACH)` 等）は自動解決される
- `ConvertTo-DbaTimeline` との連携のため、TypeName プロパティが追加される

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

SMO (SQL Server Management Objects) の JobHistory 関連クラスを理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgentJobHistory.ps1 | `public/Get-DbaAgentJobHistory.ps1` | 74-102行: .OUTPUTS セクションで出力されるオブジェクト構造を確認 |

**読解のコツ**: PowerShell の `Add-Member` で動的にプロパティが追加されるため、関数内で追加されるプロパティを追跡する必要があります。

#### Step 2: エントリーポイントを理解する

処理の起点となるパラメータ処理とフィルター設定を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgentJobHistory.ps1 | `public/Get-DbaAgentJobHistory.ps1` | 159-176行: パラメータ定義とParameterSet |
| 2-2 | Get-DbaAgentJobHistory.ps1 | `public/Get-DbaAgentJobHistory.ps1` | 178-190行: begin ブロックでのフィルター初期化 |

**主要処理フロー**:
1. **179-181行**: JobHistoryFilter オブジェクトを作成し、日付範囲を設定
2. **183-185行**: OutcomeType パラメータが指定された場合、フィルターに設定
3. **187-189行**: -ExcludeJobSteps と -WithOutputFile の排他チェック

#### Step 3: 履歴取得ロジックを理解する

内部関数 `Get-JobHistory` の処理を追跡します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAgentJobHistory.ps1 | `public/Get-DbaAgentJobHistory.ps1` | 191-332行: Get-JobHistory 内部関数 |
| 3-2 | Get-DbaAgentJobHistory.ps1 | `public/Get-DbaAgentJobHistory.ps1` | 198-207行: トークンマッピング定義 |
| 3-3 | Get-DbaAgentJobHistory.ps1 | `public/Get-DbaAgentJobHistory.ps1` | 264-276行: EnumJobHistory による履歴取得 |

**主要処理フロー**:
- **198行**: 正規表現でSQL Agentトークンをパース
- **199-207行**: トークン値のマッピング（INST, MACH, SQLDIR等）
- **269行**: `$server.JobServer.EnumJobHistory($filter)` でSMO経由で履歴取得
- **301-304行**: Duration計算と日時フォーマット

#### Step 4: 出力ファイル機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaAgentJobOutputFile.ps1 | `public/Get-DbaAgentJobOutputFile.ps1` | 112-146行: process ブロックのメイン処理 |
| 4-2 | Set-DbaAgentJobOutputFile.ps1 | `public/Set-DbaAgentJobOutputFile.ps1` | 108-171行: 出力ファイル設定処理 |

**主要処理フロー**:
- **Get-DbaAgentJobOutputFile 127-143行**: 各ジョブステップをループし、OutputFileName が設定されているものを出力
- **Set-DbaAgentJobOutputFile 152-154行**: `$jobStep.OutputFileName` を更新し、`Alter()` でコミット

### プログラム呼び出し階層図

```
Get-DbaAgentJobHistory
    |
    +-- Connect-DbaInstance (接続確立)
    |
    +-- Get-JobHistory (内部関数)
           |
           +-- New-Object JobHistoryFilter (フィルター作成)
           |
           +-- $server.JobServer.EnumJobHistory($filter) (履歴取得)
           |
           +-- [WithOutputFile指定時]
           |       |
           |       +-- Get-DbaAgentJobOutputFile (出力ファイル情報取得)
           |       |
           |       +-- Resolve-JobToken (トークン解決)
           |
           +-- Select-DefaultView (出力整形)

Get-DbaAgentJobOutputFile
    |
    +-- Connect-DbaInstance (接続確立)
    |
    +-- $server.JobServer.Jobs (ジョブ一覧取得)
    |
    +-- $job.JobSteps (ステップ反復)
    |
    +-- Join-AdminUNC (UNCパス生成)

Set-DbaAgentJobOutputFile
    |
    +-- Connect-DbaInstance (接続確立)
    |
    +-- $server.JobServer.Jobs[$name] (ジョブ取得)
    |
    +-- Out-GridView (ステップ選択UI、複数ステップ時)
    |
    +-- $jobStep.Alter() (設定反映)
```

### データフロー図

```
[入力]                     [処理]                          [出力]

SqlInstance ────────> Connect-DbaInstance ─────────> SMO Server Object
                            |
Job/ExcludeJob ─────> JobHistoryFilter 設定 ─────────> Filter Object
                            |
StartDate/EndDate ──> EnumJobHistory() ──────────────> 履歴レコード
                            |
                      Add-Member (計算フィールド追加)
                            |
WithOutputFile ─────> Resolve-JobToken ──────────────> 解決済みパス
                            |
                      Select-DefaultView ────────────> [出力オブジェクト]
                                                        - ComputerName
                                                        - Job
                                                        - StepName
                                                        - Duration
                                                        - Status
                                                        - Message
                                                        - OutputFileName
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgentJobHistory.ps1 | `public/Get-DbaAgentJobHistory.ps1` | ソース | ジョブ履歴取得のメインコマンド |
| Get-DbaAgentJobOutputFile.ps1 | `public/Get-DbaAgentJobOutputFile.ps1` | ソース | 出力ファイルパス取得コマンド |
| Set-DbaAgentJobOutputFile.ps1 | `public/Set-DbaAgentJobOutputFile.ps1` | ソース | 出力ファイル設定コマンド |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続管理 |
| Join-AdminUNC.ps1 | `internal/functions/Join-AdminUNC.ps1` | ソース | UNCパス生成ユーティリティ |
| Select-DefaultView.ps1 | `internal/functions/Select-DefaultView.ps1` | ソース | 出力整形ユーティリティ |
