# 機能設計書 482-Find-DbaAgentJob

## 概要

本ドキュメントは、SQL Server Agent ジョブを複数の検索条件で検索・フィルタリングする Find-DbaAgentJob 関数の機能設計書である。

### 本機能の処理概要

Find-DbaAgentJob は、複数の SQL Server インスタンスにわたって SQL Agent ジョブを検索し、様々なフィルタ条件を使用して問題のあるジョブや特定の条件に一致するジョブを特定する機能を提供する。ジョブ名、ステップ名、実行状態、スケジュール状態、通知設定などの条件を組み合わせて検索できる。

**業務上の目的・背景**：大規模な SQL Server 環境では数百のジョブが稼働しており、失敗したジョブ、長期間実行されていないジョブ、無効化されたジョブ、スケジュールが設定されていないジョブ、メール通知が設定されていないジョブなどを効率的に特定する必要がある。手動での確認は時間がかかり、見落としが発生しやすいため、自動化された検索機能が不可欠である。

**機能の利用シーン**：
- 日次のヘルスチェックで失敗したジョブの特定
- メンテナンス監査で未使用ジョブの特定
- コンプライアンスレポートで通知設定の確認
- トラブルシューティング時の特定ジョブの検索
- 複数サーバーにまたがるジョブ構成の監査

**主要な処理内容**：
1. 1つ以上のインスタンスに接続してジョブ情報を取得
2. ジョブ名またはステップ名でのフィルタリング
3. カテゴリ、所有者、実行状態でのフィルタリング
4. 失敗ジョブ、無効ジョブ、未スケジュールジョブの検索
5. 最終実行日からの経過日数でのフィルタリング
6. メール通知設定の有無でのフィルタリング
7. 結果のパイプライン出力

**関連システム・外部連携**：SQL Server Agent のジョブ情報は SMO (SQL Server Management Objects) を介して取得。Get-DbaAgentJob と内部的に連携し、パイプライン経由で Start-DbaAgentJob などの他のコマンドに渡すことが可能。

**権限による制御**：sysadmin 権限が必要。SQL Server 2000 以降のバージョンをサポート。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | Agentジョブ管理 | 補助機能 | SQLエージェントジョブの検索とフィルタリング |

## 機能種別

検索・フィルタリング / 監査・レポーティング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 検索対象のSQL Serverインスタンス | パイプライン入力可 |
| SqlCredential | PSCredential | No | 認証用資格情報 | Windows/SQL認証対応 |
| JobName | string[] | No | 検索するジョブ名（ワイルドカード対応） | 少なくとも1つの検索条件が必要 |
| ExcludeJobName | string[] | No | 除外するジョブ名 | 完全一致 |
| StepName | string[] | No | 検索するステップ名（ワイルドカード対応） | - |
| LastUsed | int | No | 指定日数以上実行されていないジョブを検索 | 正の整数 |
| IsDisabled | Switch | No | 無効化されたジョブを検索 | - |
| IsFailed | Switch | No | 最後の実行が失敗したジョブを検索 | - |
| IsNotScheduled | Switch | No | スケジュール未設定のジョブを検索 | - |
| IsNoEmailNotification | Switch | No | メール通知未設定のジョブを検索 | - |
| Category | string[] | No | カテゴリ名でフィルタ | - |
| Owner | string | No | 所有者でフィルタ（-付きで除外） | - |
| Since | datetime | No | 指定日時以降に実行されたジョブのみ | - |
| EnableException | Switch | No | 例外処理を有効化 | - |

### 入力データソース

SMO を介した SQL Server インスタンスの JobServer.Jobs コレクションから取得。内部的に Get-JobList 関数を使用。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverのコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なインスタンス名 |
| Name | String | ジョブ名 |
| Category | String | ジョブカテゴリ |
| OwnerLoginName | String | ジョブ所有者のログイン名 |
| CurrentRunStatus | String | 現在の実行状態（Idle/Running等） |
| CurrentRunRetryAttempt | Int | 現在の実行のリトライ回数 |
| Enabled | Boolean | ジョブの有効/無効状態 |
| LastRunDate | DateTime | 最終実行日時 |
| LastRunOutcome | String | 最終実行結果（Succeeded/Failed等） |
| DateCreated | DateTime | ジョブ作成日時 |
| HasSchedule | Boolean | スケジュールの有無 |
| OperatorToEmail | String | メール通知先オペレーター |
| CreateDate | DateTime | ジョブ作成日時（エイリアス） |

### 出力先

パイプライン出力として Microsoft.SqlServer.Management.Smo.Job オブジェクトを返す。

## 処理フロー

### 処理シーケンス

```
1. 検索条件の検証
   └─ 少なくとも1つの検索条件が指定されているか確認
   └─ 未指定の場合は Stop-Function でエラー

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

3. ジョブリストの取得
   └─ Get-JobList 関数でジョブ取得
   └─ JobName/StepName指定時はフィルタリング

4. 各種条件でのフィルタリング
   └─ Category: カテゴリ名でフィルタ
   └─ IsFailed: LastRunOutcome -eq "Failed"
   └─ LastUsed: LastRunDate が指定日数以前
   └─ IsDisabled: IsEnabled -eq $false
   └─ IsNotScheduled: HasSchedule -eq $false
   └─ IsNoEmailNotification: OperatorToEmail が空
   └─ Owner: 所有者でフィルタ（-で除外）
   └─ ExcludeJobName: 除外ジョブをフィルタ
   └─ Since: LastRunDate が指定日時以降

5. 結果の重複除去と出力
   └─ Select-Object -Unique で重複除去
   └─ Add-Member でカスタムプロパティ追加
   └─ Select-DefaultView で表示プロパティ設定
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{検索条件あり?}
    B -->|No| C[エラー: 検索条件必須]
    B -->|Yes| D[インスタンスループ開始]
    D --> E[インスタンス接続]
    E --> F{接続成功?}
    F -->|No| D
    F -->|Yes| G[Get-JobList実行]
    G --> H{JobName指定?}
    H -->|Yes| I[ジョブ名フィルタ]
    H -->|No| J{StepName指定?}
    I --> J
    J -->|Yes| K[ステップ名フィルタ]
    J -->|No| L[条件フィルタ適用]
    K --> L
    L --> M[Category/IsFailed/LastUsed等]
    M --> N[ExcludeJobName適用]
    N --> O[Since適用]
    O --> P[重複除去]
    P --> Q[プロパティ追加]
    Q --> R[結果出力]
    R --> S{次のインスタンス?}
    S -->|Yes| D
    S -->|No| T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 検索条件必須 | 少なくとも1つの検索条件が必要 | 常時 |
| BR-002 | ワイルドカード対応 | JobName/StepNameはワイルドカードをサポート | パラメータ指定時 |
| BR-003 | 所有者除外記法 | Owner先頭に-を付けると除外フィルタ | Owner指定時 |
| BR-004 | LastUsed計算 | 指定日数を負数に変換して日付計算 | LastUsed指定時 |

### 計算ロジック

**LastUsed の日付計算**:
```powershell
$DaysBack = $LastUsed * -1
$SinceDate = (Get-Date).AddDays($DaysBack)
# LastRunDate -le $SinceDate でフィルタ
```

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

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

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NoSearchTerm | バリデーションエラー | 検索条件未指定 | Stop-Functionで処理終了 |
| ConnectionError | 接続エラー | インスタンス接続失敗 | Continue で次のインスタンスへ |

### リトライ仕様

特になし。接続失敗時は次のインスタンスへ続行。

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

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

## パフォーマンス要件

- 大量のジョブを持つ環境では、SMO経由でのジョブ取得に時間がかかる可能性あり
- 複数のフィルタ条件を組み合わせる場合、メモリ内でのフィルタリングが実行される
- 結果セットに対して重複除去 (Select-Object -Unique) が適用される

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

- sysadmin 権限が必要
- SQL 認証を使用する場合、資格情報は PSCredential オブジェクトとして安全に渡される
- ジョブの詳細情報（コマンドテキストなど）にアクセス可能

## 備考

- SQL Server 2000 以降をサポート
- パイプライン出力は Start-DbaAgentJob 等の他のコマンドに直接渡すことが可能
- エイリアス: Disabled (IsDisabled), Failed (IsFailed), NoSchedule (IsNotScheduled), NoEmailNotification (IsNoEmailNotification), Name (JobName)

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Find-DbaAgentJob.ps1 | `public/Find-DbaAgentJob.ps1` | 186-208行目: パラメータ定義 |
| 1-2 | Find-DbaAgentJob.ps1 | `public/Find-DbaAgentJob.ps1` | 77-121行目: .OUTPUTS ドキュメント |

**読解のコツ**: Alias属性（Disabled, Failed等）に注目。旧パラメータ名との互換性維持のため。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Find-DbaAgentJob.ps1 | `public/Find-DbaAgentJob.ps1` | 209-213行目: beginブロック、検索条件バリデーション |
| 2-2 | Find-DbaAgentJob.ps1 | `public/Find-DbaAgentJob.ps1` | 214-312行目: processブロック、メインロジック |

**主要処理フロー**:
1. **209-213行目**: 検索条件の存在チェック（-notcontains $true で未指定を検出）
2. **217-224行目**: インスタンスへの接続
3. **226-244行目**: ジョブリストの取得（JobName/StepName/全件）

#### Step 3: フィルタリングロジックを理解する

各検索条件によるフィルタリング処理の流れ。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Find-DbaAgentJob.ps1 | `public/Find-DbaAgentJob.ps1` | 246-249行目: Categoryフィルタ |
| 3-2 | Find-DbaAgentJob.ps1 | `public/Find-DbaAgentJob.ps1` | 251-254行目: IsFailedフィルタ |
| 3-3 | Find-DbaAgentJob.ps1 | `public/Find-DbaAgentJob.ps1` | 256-261行目: LastUsedフィルタ |
| 3-4 | Find-DbaAgentJob.ps1 | `public/Find-DbaAgentJob.ps1` | 263-275行目: IsDisabled/IsNotScheduled/IsNoEmailNotificationフィルタ |
| 3-5 | Find-DbaAgentJob.ps1 | `public/Find-DbaAgentJob.ps1` | 277-287行目: Ownerフィルタ（除外記法対応） |
| 3-6 | Find-DbaAgentJob.ps1 | `public/Find-DbaAgentJob.ps1` | 289-298行目: ExcludeJobName/Sinceフィルタ |

**主要処理フロー**:
- **257-260行目**: LastUsedの日数計算とフィルタ適用
- **279-286行目**: Owner先頭の `-` で除外/包含を判定
- **274行目**: IsNoEmailNotification は `[string]::IsNullOrEmpty()` で判定

#### Step 4: 結果出力処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Find-DbaAgentJob.ps1 | `public/Find-DbaAgentJob.ps1` | 300-310行目: 結果の整形と出力 |

**主要処理フロー**:
- **300行目**: `Select-Object -Unique` で重複除去
- **302-306行目**: `Add-Member` でカスタムプロパティ追加
- **309行目**: `Select-DefaultView` で表示プロパティとエイリアス設定

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

```
Find-DbaAgentJob
    │
    ├─ [begin] 検索条件バリデーション
    │      └─ Stop-Function (条件未指定時)
    │
    └─ [process] foreach ($instance in $SqlInstance)
           │
           ├─ Connect-DbaInstance
           │      └─ インスタンス接続
           │
           ├─ Get-JobList (内部関数)
           │      ├─ JobFilter指定時: ジョブ名でフィルタ
           │      ├─ StepFilter指定時: ステップ名でフィルタ
           │      └─ 未指定時: 全ジョブ取得
           │
           ├─ Where-Object フィルタチェーン
           │      ├─ Category
           │      ├─ IsFailed (LastRunOutcome -eq "Failed")
           │      ├─ LastUsed (日付計算)
           │      ├─ IsDisabled (IsEnabled -eq $false)
           │      ├─ IsNotScheduled (HasSchedule -eq $false)
           │      ├─ IsNoEmailNotification (OperatorToEmail空)
           │      ├─ Owner (除外/包含判定)
           │      ├─ ExcludeJobName
           │      └─ Since
           │
           └─ Select-DefaultView
                  └─ 表示プロパティ設定
```

### データフロー図

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

SqlInstance ─────────────────▶ Connect-DbaInstance ─────────────▶ SMO Server
                                │
                                ▼
検索パラメータ ──────────────▶ Get-JobList ──────────────────────▶ Job[]
  - JobName                     │
  - StepName                    ▼
  - Category              フィルタチェーン
  - IsFailed                    │
  - LastUsed                    ▼
  - IsDisabled            Select-Object -Unique
  - IsNotScheduled              │
  - IsNoEmailNotification       ▼
  - Owner                 Add-Member
  - ExcludeJobName              │
  - Since                       ▼
                          Select-DefaultView ─────────────────────▶ Job Objects
                                                                    - ComputerName
                                                                    - InstanceName
                                                                    - SqlInstance
                                                                    - Name
                                                                    - Category
                                                                    - LastRunOutcome
                                                                    ...
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Find-DbaAgentJob.ps1 | `public/Find-DbaAgentJob.ps1` | ソース | メイン関数 |
| Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | ソース | 関連機能（ジョブ取得） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
| Start-DbaAgentJob.ps1 | `public/Start-DbaAgentJob.ps1` | ソース | パイプライン連携先 |
