# 機能設計書 488-Get-DbaAgentJobOutputFile

## 概要

本ドキュメントは、SQL Agent ジョブステップの出力ファイルパスを取得する Get-DbaAgentJobOutputFile 関数の機能設計書である。

### 本機能の処理概要

Get-DbaAgentJobOutputFile は、SQL Agent ジョブステップに設定された出力ファイルパスを取得する機能を提供する。失敗したジョブのトラブルシューティングや実行履歴の確認において、詳細なエラーメッセージや実行詳細を含む出力ファイルを特定する必要がある場合に不可欠な機能である。ローカルファイルパスとリモートアクセス用のUNCパスの両方を返す。

**業務上の目的・背景**：SQL Agent ジョブステップは実行結果を出力ファイルに書き込むように設定できる。ジョブ失敗時の詳細なエラー情報や、ステップの実行結果を確認するために、これらの出力ファイルの場所を特定する必要がある。大規模環境では多数のジョブが存在するため、手動でのファイル場所特定は非効率的である。

**機能の利用シーン**：
- ジョブ失敗時の出力ファイル場所特定
- 出力ファイル設定の監査
- バックアップ対象ファイルの一覧作成
- ジョブ構成のドキュメント化
- リモートからの出力ファイルアクセス

**主要な処理内容**：
1. 指定されたインスタンスへの接続
2. ジョブ一覧の取得と Job/ExcludeJob フィルタリング
3. 各ジョブステップの OutputFileName 確認
4. UNCパスへの変換（Join-AdminUNC）
5. 出力ファイルが設定されているステップのみ出力

**関連システム・外部連携**：SQL Server Agent の Jobs/JobSteps コレクションを SMO 経由で取得。Get-DbaAgentJobHistory の -WithOutputFile オプションから内部的に呼び出される。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 11 | ジョブ履歴・出力 | 補助機能 | ジョブステップ出力ファイルパスの取得 |

## 機能種別

データ取得 / トラブルシューティング支援

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | パイプライン入力可、ValidateNotNull/NotNullOrEmpty |
| SqlCredential | PSCredential | No | 認証用資格情報 | Windows/SQL認証対応 |
| Job | object[] | No | 取得するジョブ名 | - |
| ExcludeJob | object[] | No | 除外するジョブ名 | - |
| EnableException | Switch | No | 例外処理を有効化 | - |

### 入力データソース

SMO を介した SQL Server インスタンスの JobServer.Jobs コレクションから取得。

## 出力仕様

### 出力データ

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

### 出力先

パイプライン出力として PSCustomObject を返す。

## 処理フロー

### 処理シーケンス

```
1. 各インスタンスに対してループ処理
   └─ Connect-DbaInstance で接続
   └─ 接続失敗時は Continue で次へ

2. ジョブ一覧の取得
   └─ $server.JobServer.Jobs から取得
   └─ Job パラメータ: 名前フィルタ
   └─ ExcludeJob パラメータ: 除外フィルタ

3. 各ジョブ/ステップに対するループ処理
   └─ OutputFileName が設定されているか確認
   └─ 設定されている場合: オブジェクト出力
   └─ 未設定の場合: Verbose メッセージ出力

4. 結果の出力
   └─ PSCustomObject 生成
   └─ Select-DefaultView で StepId を非表示
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[インスタンスループ開始]
    B --> C[インスタンス接続]
    C --> D{接続成功?}
    D -->|No| B
    D -->|Yes| E[Jobs取得]
    E --> F{Job指定?}
    F -->|Yes| G[ジョブ名フィルタ]
    F -->|No| H{ExcludeJob指定?}
    G --> H
    H -->|Yes| I[除外フィルタ適用]
    H -->|No| J[ジョブループ開始]
    I --> J
    J --> K[ステップループ開始]
    K --> L{OutputFileName設定?}
    L -->|Yes| M[PSCustomObject生成]
    L -->|No| N[Verboseメッセージ]
    M --> O[Join-AdminUNC変換]
    O --> P[Select-DefaultView]
    P --> Q[結果出力]
    N --> R{次のステップ?}
    Q --> R
    R -->|Yes| K
    R -->|No| S{次のジョブ?}
    S -->|Yes| J
    S -->|No| T{次のインスタンス?}
    T -->|Yes| B
    T -->|No| U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 出力ファイル限定 | OutputFileName が設定されているステップのみ出力 | 常時 |
| BR-002 | UNCパス変換 | ローカルパスをUNCパスに変換 | 常時 |
| BR-003 | Verboseログ | 出力ファイル未設定ステップは Verbose でログ | Verbose指定時 |

### 計算ロジック

特になし。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ジョブ取得 | msdb.dbo.sysjobs | SELECT | ジョブ一覧の取得（SMO経由） |
| ステップ取得 | msdb.dbo.sysjobsteps | SELECT | ステップ情報の取得（SMO経由） |

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | インスタンス接続失敗 | Continue で次のインスタンスへ |

### リトライ仕様

特になし。

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

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

## パフォーマンス要件

- ジョブ数・ステップ数に依存
- 出力ファイル未設定のステップが多い場合、出力は少量
- Join-AdminUNC のオーバーヘッドは軽微

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

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

## 備考

- StepId プロパティは Select-DefaultView で非表示に設定
- 出力ファイル未設定のステップは Verbose メッセージでログ出力
- Join-AdminUNC で管理共有（C$等）を使用したUNCパスに変換
- Get-DbaAgentJobHistory の -WithOutputFile から内部的に呼び出される

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgentJobOutputFile.ps1 | `public/Get-DbaAgentJobOutputFile.ps1` | 91-110行目: パラメータ定義 |
| 1-2 | Get-DbaAgentJobOutputFile.ps1 | `public/Get-DbaAgentJobOutputFile.ps1` | 43-59行目: .OUTPUTS ドキュメント |

**読解のコツ**: SqlInstance パラメータの ValidateNotNull/ValidateNotNullOrEmpty 属性と、パイプライン関連属性に注目。

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

処理の起点となる process ブロックを特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgentJobOutputFile.ps1 | `public/Get-DbaAgentJobOutputFile.ps1` | 112-146行目: processブロック全体 |

**主要処理フロー**:
1. **113-118行目**: インスタンスへの接続
2. **120-126行目**: ジョブの取得とフィルタリング
3. **127-144行目**: ジョブ/ステップのネストループ

#### Step 3: 出力処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAgentJobOutputFile.ps1 | `public/Get-DbaAgentJobOutputFile.ps1` | 129-143行目: 出力ファイル処理 |

**主要処理フロー**:
- **129行目**: OutputFileName の存在チェック
- **130-139行目**: PSCustomObject の生成
- **137行目**: Join-AdminUNC でUNCパス変換
- **139行目**: Select-DefaultView で StepId を非表示
- **141行目**: 未設定時の Verbose メッセージ

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

```
Get-DbaAgentJobOutputFile
    │
    └─ [process] foreach ($instance in $SqlInstance)
           │
           ├─ Connect-DbaInstance
           │      └─ インスタンス接続
           │
           ├─ $server.JobServer.Jobs
           │      └─ ジョブコレクション取得
           │
           ├─ Where-Object フィルタ
           │      ├─ Job: -In でフィルタ
           │      └─ ExcludeJob: -NotIn で除外
           │
           └─ foreach ($j in $Jobs)
                  │
                  └─ foreach ($step in $j.JobSteps)
                         │
                         ├─ [OutputFileName存在]
                         │      ├─ PSCustomObject 生成
                         │      ├─ Join-AdminUNC
                         │      └─ Select-DefaultView
                         │
                         └─ [OutputFileName未設定]
                                └─ Write-Message Verbose
```

### データフロー図

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

SqlInstance ─────────────────▶ Connect-DbaInstance ─────────────▶ SMO Server
                                │
                                ▼
Job/ExcludeJob ──────────────▶ $server.JobServer.Jobs
                                │
                                ▼
                          Where-Object フィルタ
                                │
                                ▼
                          foreach Job.JobSteps
                                │
                                ▼
                          [OutputFileName確認]
                                │
                          ┌─────┴─────┐
                          │           │
                      [存在]      [未設定]
                          │           │
                          ▼           ▼
                    PSCustomObject  Verbose
                    Join-AdminUNC   メッセージ
                          │
                          ▼
                    Select-DefaultView ─────────────────────────▶ OutputFile Objects
                          (-ExcludeProperty StepId)               - Job
                                                                  - JobStep
                                                                  - OutputFileName
                                                                  - RemoteOutputFileName
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgentJobOutputFile.ps1 | `public/Get-DbaAgentJobOutputFile.ps1` | ソース | メイン関数 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
| Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | ソース | 関連機能（ジョブ取得） |
| Get-DbaAgentJobHistory.ps1 | `public/Get-DbaAgentJobHistory.ps1` | ソース | 呼び出し元（-WithOutputFile） |
| Set-DbaAgentJobOutputFile.ps1 | `public/Set-DbaAgentJobOutputFile.ps1` | ソース | 関連機能（出力ファイル設定） |
