# 機能設計書 487-Get-DbaAgentJobHistory

## 概要

本ドキュメントは、SQL Server Agent ジョブの実行履歴を取得する Get-DbaAgentJobHistory 関数の機能設計書である。

### 本機能の処理概要

Get-DbaAgentJobHistory は、msdb データベースから SQL Server Agent ジョブの詳細な実行記録を取得し、失敗のトラブルシューティング、パフォーマンストレンドの監視、コンプライアンスレポートの作成を支援する機能を提供する。SQL Server Management Studio のジョブアクティビティモニターと同じ履歴データにアクセスでき、強力なフィルタリングと出力オプションを備えている。

**業務上の目的・背景**：ジョブ失敗の原因調査、実行パターンの時系列分析、監査ドキュメントの作成において、ジョブ実行履歴へのアクセスは不可欠である。特定のジョブ、日付範囲、結果タイプでフィルタリングし、オプションでジョブステップの詳細や出力ファイル情報を含めることができる。

**機能の利用シーン**：
- ジョブ失敗の原因調査
- 実行時間のパフォーマンス分析
- 監査・コンプライアンスレポートの作成
- 特定期間のジョブ実行サマリー取得
- 出力ファイルの場所特定

**主要な処理内容**：
1. 指定されたインスタンスへの接続
2. JobHistoryFilter の構築（日付範囲、OutcomeType）
3. EnumJobHistory による履歴取得
4. Job/ExcludeJob パラメータによるフィルタリング
5. Duration/Status などの計算フィールド追加
6. 出力ファイルパスの解決（-WithOutputFile 指定時）
7. 結果の出力

**関連システム・外部連携**：msdb.dbo.sysjobhistory テーブルから SMO の EnumJobHistory メソッド経由でデータ取得。Get-DbaAgentJobOutputFile と連携して出力ファイルパスを解決。SQL Agent トークン（$INST, $SQLLOGDIR など）の展開にも対応。

**権限による制御**：msdb データベースへの読み取りアクセスが必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 11 | ジョブ履歴・出力 | 主機能 | SQLエージェントジョブ実行履歴の取得 |

## 機能種別

データ取得 / 監査・レポーティング / トラブルシューティング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | パイプライン入力可（Server ParameterSet） |
| SqlCredential | PSCredential | No | 認証用資格情報 | Windows/SQL認証対応 |
| Job | object[] | No | 取得するジョブ名（ワイルドカード対応） | - |
| ExcludeJob | object[] | No | 除外するジョブ名 | - |
| StartDate | DateTime | No | 取得開始日時 | デフォルト: 1900-01-01 |
| EndDate | DateTime | No | 取得終了日時 | デフォルト: 現在日時 |
| OutcomeType | CompletionResult | No | 結果フィルタ（Failed/Succeeded/Retry/Cancelled/InProgress/Unknown） | ValidateSet |
| ExcludeJobSteps | Switch | No | ジョブレベル（StepID=0）のみ取得 | - |
| WithOutputFile | Switch | No | 出力ファイルパスを含める | ExcludeJobStepsと併用不可 |
| JobCollection | Job | Yes | SMOジョブオブジェクト | パイプライン入力可（Collection ParameterSet） |
| EnableException | Switch | No | 例外処理を有効化 | - |

### 入力データソース

SMO を介した SQL Server インスタンスの JobServer.EnumJobHistory メソッドから取得。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverのコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なインスタンス名 |
| Job | String | ジョブ名（JobNameエイリアス） |
| StepName | String | ステップ名 |
| RunDate | DateTime | 実行開始日時 |
| StartDate | DbaDateTime | 実行開始日時（フォーマット済み） |
| EndDate | DbaDateTime | 実行終了日時（計算値） |
| Duration | PrettyTimeSpan | 実行時間（フォーマット済み） |
| Status | String | 実行結果（Failed/Succeeded/Retry/Canceled） |
| OperatorEmailed | Boolean | オペレーターへのメール通知有無 |
| Message | String | 実行メッセージまたはエラー内容 |
| OutputFileName | String | 出力ファイルパス（-WithOutputFile時） |
| RemoteOutputFileName | String | UNCパス（-WithOutputFile時） |

### 出力先

パイプライン出力として JobExecutionHistory オブジェクトを返す。

## 処理フロー

### 処理シーケンス

```
1. 初期化処理（begin）
   └─ JobHistoryFilter の構築
   └─ StartDate/EndDate/OutcomeType の設定
   └─ ExcludeJobSteps と WithOutputFile の併用チェック

2. Get-JobHistory 内部関数の定義
   └─ トークン解決ロジック（INST, MACH, SQLDIR など）
   └─ 日付/時刻トークンの解決

3. 各インスタンス/ジョブに対してループ処理
   └─ EnumJobHistory でデータ取得
   └─ ExcludeJobSteps: StepID = 0 のみフィルタ
   └─ WithOutputFile: 出力ファイルパス解決

4. 計算フィールドの追加
   └─ Duration: RunDuration から計算
   └─ EndDate: RunDate + Duration
   └─ Status: RunStatus コード変換

5. 結果の出力
   └─ Select-DefaultView で表示プロパティ設定
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[JobHistoryFilter構築]
    B --> C{ExcludeJobSteps && WithOutputFile?}
    C -->|Yes| D[エラー: 併用不可]
    C -->|No| E{JobCollection?}
    E -->|Yes| F[JobCollectionループ]
    E -->|No| G[SqlInstanceループ]
    F --> H[Get-JobHistory呼び出し]
    G --> I[インスタンス接続]
    I --> J{ExcludeJob?}
    J -->|Yes| K[除外ジョブでフィルタ]
    J -->|No| L[Get-JobHistory呼び出し]
    K --> L
    H --> M[EnumJobHistory実行]
    L --> M
    M --> N{ExcludeJobSteps?}
    N -->|Yes| O[StepID=0のみ]
    N -->|No| P{WithOutputFile?}
    O --> P
    P -->|Yes| Q[出力ファイル情報取得]
    P -->|No| R[計算フィールド追加]
    Q --> R
    R --> S[Select-DefaultView]
    S --> T[結果出力]
    T --> U{次のレコード?}
    U -->|Yes| M
    U -->|No| V{次のインスタンス?}
    V -->|Yes| G
    V -->|No| W[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | パラメータ排他 | ExcludeJobSteps と WithOutputFile は併用不可 | begin時チェック |
| BR-002 | デフォルト日付 | StartDateは1900-01-01、EndDateは現在日時 | 未指定時 |
| BR-003 | ステップフィルタ | ExcludeJobSteps時はStepID=0のみ取得 | スイッチ指定時 |
| BR-004 | トークン解決 | SQL Agentトークンを実際のパスに展開 | WithOutputFile時 |

### 計算ロジック

**Duration の計算**:
```powershell
$DurationInSeconds = ($execution.RunDuration % 100) +
    [math]::floor(($execution.RunDuration % 10000) / 100) * 60 +
    [math]::floor(($execution.RunDuration % 1000000) / 10000) * 60 * 60
```

**Status の変換**:
```powershell
$status = switch ($execution.RunStatus) {
    0 { "Failed" }
    1 { "Succeeded" }
    2 { "Retry" }
    3 { "Canceled" }
}
```

## データベース操作仕様

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 履歴取得 | msdb.dbo.sysjobhistory | SELECT | ジョブ実行履歴の取得（SMO経由） |
| 出力ファイル取得 | msdb.dbo.sysjobsteps | SELECT | ステップの出力ファイル設定取得 |

### テーブル別操作詳細

本機能は読み取り専用であり、データベースへの書き込みは行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ParameterConflict | パラメータエラー | ExcludeJobSteps && WithOutputFile | Stop-Function で処理終了 |
| ConnectionError | 接続エラー | インスタンス接続失敗 | Continue で次のインスタンスへ |
| HistoryError | 履歴取得エラー | EnumJobHistory失敗 | Stop-Function で警告、Continue |

### リトライ仕様

特になし。

## トランザクション仕様

読み取り専用のため、トランザクション制御は不要。

## パフォーマンス要件

- 履歴データ量に大きく依存
- 日付範囲フィルタの使用を推奨
- 履歴保持設定によっては古いデータが存在しない場合あり
- WithOutputFile は追加クエリ（Get-DbaAgentJobOutputFile）を実行

## セキュリティ考慮事項

- msdb データベースへの読み取りアクセスが必要
- SQL 認証を使用する場合、資格情報は PSCredential オブジェクトとして安全に渡される
- 出力ファイルパスはセキュリティ上の機密情報を含む可能性あり

## 備考

- SQL Agentトークン（$(SQLLOGDIR), $(INST) など）を実際のパスに展開
- PrettyTimeSpan 型で Duration を人間が読みやすい形式で表示
- ConvertTo-DbaTimeline との連携用に TypeName プロパティを追加
- 履歴の可用性は SQL Agent の履歴クリーンアップ設定に依存

---

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

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

### 推奨読解順序

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

パラメータ定義と出力プロパティの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgentJobHistory.ps1 | `public/Get-DbaAgentJobHistory.ps1` | 159-176行目: パラメータ定義 |
| 1-2 | Get-DbaAgentJobHistory.ps1 | `public/Get-DbaAgentJobHistory.ps1` | 73-102行目: .OUTPUTS ドキュメント |

**読解のコツ**: 2つのParameterSet（Server/Collection）の使い分けと、OutcomeType の ValidateSet に注目。

#### Step 2: 初期化処理を理解する

begin ブロックでのフィルタ構築を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgentJobHistory.ps1 | `public/Get-DbaAgentJobHistory.ps1` | 178-189行目: 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` | 232-263行目: Resolve-JobToken 関数 |

**主要処理フロー**:
- **198行目**: $tokenrex - トークン正規表現
- **199-207行目**: $propmap - サーバープロパティマッピング
- **214-226行目**: Resolve-TokenEscape - エスケープ処理
- **291-305行目**: Duration/Status の計算とプロパティ追加

#### Step 4: process ブロックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaAgentJobHistory.ps1 | `public/Get-DbaAgentJobHistory.ps1` | 335-361行目: processブロック |

**主要処理フロー**:
- **339-342行目**: JobCollection パラメータ処理
- **345-360行目**: SqlInstance パラメータ処理
- **352-356行目**: ExcludeJob 処理

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

```
Get-DbaAgentJobHistory
    │
    ├─ [begin] 初期化
    │      ├─ JobHistoryFilter 構築
    │      ├─ OutcomeTypes 設定
    │      └─ パラメータ排他チェック
    │
    ├─ Get-JobHistory (内部関数)
    │      │
    │      ├─ $tokenrex / $propmap (トークン定義)
    │      │
    │      ├─ Resolve-TokenEscape (エスケープ処理)
    │      │
    │      ├─ Resolve-JobToken (トークン展開)
    │      │
    │      ├─ $server.JobServer.EnumJobHistory($filter)
    │      │
    │      ├─ [ExcludeJobSteps] Where-Object StepID -eq 0
    │      │
    │      ├─ [WithOutputFile] Get-DbaAgentJobOutputFile
    │      │
    │      └─ Add-Member (Duration, Status, EndDate等)
    │
    └─ [process]
           │
           ├─ [JobCollection] foreach Job -> Get-JobHistory
           │
           └─ [SqlInstance]
                  ├─ Connect-DbaInstance
                  ├─ [ExcludeJob] フィルタ
                  └─ Get-JobHistory
```

### データフロー図

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

SqlInstance/JobCollection ───▶ Connect-DbaInstance ─────────────▶ SMO Server
                                │
StartDate/EndDate ───────────▶ JobHistoryFilter
OutcomeType                     │
                                ▼
Job/ExcludeJob ──────────────▶ EnumJobHistory($filter) ──────────▶ History[]
                                │
                                ▼
                          [ExcludeJobSteps]
                          Where StepID = 0
                                │
                                ▼
                          [WithOutputFile]
                          Get-DbaAgentJobOutputFile
                          Resolve-JobToken
                                │
                                ▼
                          Add-Member
                          - Duration (PrettyTimeSpan)
                          - EndDate (計算)
                          - Status (変換)
                          - OutputFileName (解決)
                                │
                                ▼
                          Select-DefaultView ─────────────────────▶ History Objects
                                                                    - Job
                                                                    - StepName
                                                                    - StartDate
                                                                    - EndDate
                                                                    - Duration
                                                                    - Status
                                                                    - Message
                                                                    ...
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgentJobHistory.ps1 | `public/Get-DbaAgentJobHistory.ps1` | ソース | メイン関数 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
| Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | ソース | パイプライン入力元 |
| Get-DbaAgentJobOutputFile.ps1 | `public/Get-DbaAgentJobOutputFile.ps1` | ソース | 出力ファイル情報取得 |
