# 機能設計書 485-Get-DbaAgentJob

## 概要

本ドキュメントは、SQL Server Agent ジョブの詳細情報と実行状態を取得する Get-DbaAgentJob 関数の機能設計書である。

### 本機能の処理概要

Get-DbaAgentJob は、1つ以上の SQL Server インスタンスから SQL Server Agent ジョブの詳細情報を取得する基本的かつ重要な機能を提供する。ジョブの構成、ステータス、スケジュール、実行履歴などの包括的な情報を返し、様々なフィルタリングオプションで特定のジョブに絞り込むことができる。

**業務上の目的・背景**：SQL Server Agent ジョブは、データベースメンテナンス、バックアップ、ETL処理などの自動化タスクを管理する中核的なコンポーネントである。環境全体のジョブヘルスを監視し、デプロイメント前のジョブ構成を監査し、特定のデータベースに関連するジョブを特定してメンテナンス計画を立てる必要がある。

**機能の利用シーン**：
- 全ジョブの一覧取得と状態確認
- 特定カテゴリのジョブのみの取得
- 特定データベースに関連するジョブの特定
- 無効化されたジョブの除外
- 現在実行中のジョブの確認（-IncludeExecution）
- パイプライン経由での他コマンドへの連携

**主要な処理内容**：
1. 指定されたインスタンスへの接続
2. JobServer.Jobs コレクションからジョブ取得
3. Job/ExcludeJob パラメータによるフィルタリング
4. Type/Category/ExcludeCategory によるフィルタリング
5. Database パラメータによるステップレベルフィルタリング
6. 実行情報の取得（-IncludeExecution 指定時）
7. カスタムプロパティの追加と結果出力

**関連システム・外部連携**：SQL Server Agent の Jobs コレクションを SMO 経由で取得。msdb データベースの sysjobactivity テーブルから実行情報を取得。パイプライン経由で Start-DbaAgentJob, Stop-DbaAgentJob, Export-DbaScript 等に連携可能。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | Agentジョブ管理 | 主機能 | SQLエージェントジョブの取得と実行状態確認 |

## 機能種別

データ取得 / 監査・モニタリング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | パイプライン入力可 |
| SqlCredential | PSCredential | No | 認証用資格情報 | Windows/SQL認証対応 |
| Job | string[] | No | 取得するジョブ名 | 空文字/null値は自動除外 |
| ExcludeJob | string[] | No | 除外するジョブ名 | 空文字/null値は自動除外 |
| Database | string[] | No | T-SQLステップがターゲットとするデータベース名 | - |
| Category | string[] | No | 取得するカテゴリ名 | - |
| ExcludeCategory | string[] | No | 除外するカテゴリ名 | - |
| ExcludeDisabledJobs | Switch | No | 無効化されたジョブを除外 | - |
| IncludeExecution | Switch | No | 実行中ジョブの開始日時を含める | - |
| Type | string[] | No | ジョブタイプ（Local/MultiServer） | デフォルト: 両方 |
| EnableException | Switch | No | 例外処理を有効化 | - |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 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等） |
| HasSchedule | Boolean | スケジュールの有無 |
| OperatorToEmail | String | メール通知先オペレーター |
| CreateDate | DateTime | ジョブ作成日時 |
| StartDate | DateTime | 実行開始日時（-IncludeExecution時のみ） |

### 出力先

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

## 処理フロー

### 処理シーケンス

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

2. 実行情報クエリ（-IncludeExecution 指定時）
   └─ msdb.dbo.sysjobactivity から実行中ジョブ情報取得

3. パラメータのバリデーション
   └─ Job/ExcludeJob の空文字/null値を除外

4. ジョブ一覧の取得とフィルタリング
   └─ JobType でフィルタ（Local/MultiServer）
   └─ Job パラメータでフィルタ
   └─ ExcludeJob パラメータで除外
   └─ ExcludeDisabledJobs で無効ジョブ除外
   └─ MSXジョブ（CategoryID = 1）を常に除外
   └─ Database パラメータでステップレベルフィルタ
   └─ Category/ExcludeCategory でカテゴリフィルタ

5. 結果の出力
   └─ StartDate 追加（実行中の場合）
   └─ カスタムプロパティの追加
   └─ Select-DefaultView で表示プロパティ設定
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[インスタンスループ開始]
    B --> C[インスタンス接続]
    C --> D{接続成功?}
    D -->|No| B
    D -->|Yes| E{IncludeExecution?}
    E -->|Yes| F[実行情報クエリ]
    E -->|No| G[パラメータバリデーション]
    F --> G
    G --> H[JobType フィルタ]
    H --> I[Job/ExcludeJob フィルタ]
    I --> J{ExcludeDisabledJobs?}
    J -->|Yes| K[無効ジョブ除外]
    J -->|No| L[MSXジョブ除外]
    K --> L
    L --> M{Database指定?}
    M -->|Yes| N[ステップレベルフィルタ]
    M -->|No| O[Category/ExcludeCategoryフィルタ]
    N --> O
    O --> P[ジョブループ]
    P --> Q{実行中?}
    Q -->|Yes| R[StartDate追加]
    Q -->|No| S[カスタムプロパティ追加]
    R --> S
    S --> T[Select-DefaultView]
    T --> U[結果出力]
    U --> V{次のジョブ?}
    V -->|Yes| P
    V -->|No| W{次のインスタンス?}
    W -->|Yes| B
    W -->|No| X[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | MSXジョブ除外 | CategoryID = 1 のジョブは常に除外 | 常時 |
| BR-002 | 空値パラメータ除外 | Job/ExcludeJob の空文字/null値は無視 | パラメータ指定時 |
| BR-003 | Databaseフィルタ | T-SQLステップのDatabaseNameでフィルタ | Database指定時 |
| BR-004 | Typeデフォルト | 未指定時はLocal/MultiServerの両方を取得 | Type未指定時 |

### 計算ロジック

特になし。

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

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

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

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

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

**実行情報クエリ（IncludeExecution）**:
```sql
SELECT [job].[job_id] AS [JobId], [activity].[start_execution_date] AS [StartDate]
FROM [msdb].[dbo].[sysjobs_view] AS [job]
    INNER JOIN [msdb].[dbo].[sysjobactivity] AS [activity] ON [job].[job_id] = [activity].[job_id]
WHERE [activity].[run_requested_date] IS NOT NULL
    AND [activity].[start_execution_date] IS NOT NULL
    AND [activity].[stop_execution_date] IS NULL;
```

## エラー処理

### エラーケース一覧

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

### リトライ仕様

特になし。

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

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

## パフォーマンス要件

- 大量のジョブを持つ環境では、SMO経由でのジョブ取得に時間がかかる可能性あり
- Database フィルタは各ジョブのステップを走査するため、ジョブ数・ステップ数に比例
- IncludeExecution は追加のSQLクエリを実行

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

- msdb データベースへの読み取りアクセスが必要
- SQL 認証を使用する場合、資格情報は PSCredential オブジェクトとして安全に渡される

## 備考

- MSXジョブ（CategoryID = 1）はセカンダリレプリカに同期できないため、常に除外
- Job/ExcludeJob パラメータの空文字/null値は自動的にフィルタリング
- パイプライン出力は Start-DbaAgentJob, Export-DbaScript 等に直接渡すことが可能

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | 139-154行目: パラメータ定義 |
| 1-2 | Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | 67-97行目: .OUTPUTS ドキュメント |

**読解のコツ**: Type パラメータの ValidateSet と、Job/ExcludeJob のnull/空値ハンドリングに注目。

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

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

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

**主要処理フロー**:
1. **157-162行目**: インスタンスへの接続
2. **164-173行目**: IncludeExecution 時の実行情報クエリ
3. **175-197行目**: Job/ExcludeJob パラメータのnull/空値除外

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | 199行目: JobType フィルタ |
| 3-2 | Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | 201-211行目: Job/ExcludeJob/Disabled フィルタ |
| 3-3 | Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | 211行目: MSXジョブ除外 |
| 3-4 | Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | 212-226行目: Database フィルタ（ステップレベル） |
| 3-5 | Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | 227-232行目: Category/ExcludeCategory フィルタ |

**主要処理フロー**:
- **199行目**: `Where-Object JobType -in $Type`
- **211行目**: `Where-Object CategoryID -ne 1` (MSXジョブ除外)
- **213-225行目**: Database フィルタはルックアップハッシュテーブルを使用

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | 234-250行目: ジョブループと出力 |

**主要処理フロー**:
- **235行目**: デフォルト表示プロパティの定義
- **237-243行目**: 実行中ジョブの場合は StartDate を追加
- **245-247行目**: カスタムプロパティ追加（Parent.Parent から取得）
- **249行目**: Select-DefaultView

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

```
Get-DbaAgentJob
    │
    └─ [process] foreach ($instance in $SqlInstance)
           │
           ├─ Connect-DbaInstance
           │      └─ インスタンス接続
           │
           ├─ [IncludeExecution時] $server.Query()
           │      └─ sysjobactivity から実行中ジョブ取得
           │
           ├─ [Job/ExcludeJob] パラメータバリデーション
           │      └─ 空文字/null値の除外
           │
           ├─ $server.JobServer.Jobs
           │      └─ ジョブコレクション取得
           │
           ├─ Where-Object フィルタチェーン
           │      ├─ JobType
           │      ├─ Job (-In)
           │      ├─ ExcludeJob (-NotIn)
           │      ├─ ExcludeDisabledJobs (IsEnabled)
           │      ├─ CategoryID -ne 1 (MSXジョブ除外)
           │      ├─ Database (ステップレベル)
           │      ├─ Category (-in)
           │      └─ ExcludeCategory (-notin)
           │
           └─ foreach ($agentJob in $jobs)
                  │
                  ├─ [実行中] Add-Member StartDate
                  │
                  ├─ Add-Member
                  │      ├─ ComputerName (Parent.Parent)
                  │      ├─ InstanceName (Parent.Parent)
                  │      └─ SqlInstance (Parent.Parent)
                  │
                  └─ Select-DefaultView
                         └─ 表示プロパティ設定
```

### データフロー図

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

SqlInstance ─────────────────▶ Connect-DbaInstance ─────────────▶ SMO Server
                                │
                                ▼
IncludeExecution ────────────▶ $server.Query(sysjobactivity) ───▶ JobExecutionResults
                                │
                                ▼
Job/ExcludeJob ──────────────▶ パラメータバリデーション
Database/Category             （空文字/null除外）
Type                            │
                                ▼
                          $server.JobServer.Jobs
                                │
                                ▼
                          Where-Object フィルタチェーン
                                │
                                ├──▶ JobExecutionResults と照合 ──▶ StartDate
                                │
                                ▼
                          Add-Member (ComputerName等)
                                │
                                ▼
                          Select-DefaultView ─────────────────────▶ Job Objects
                                                                    - Name
                                                                    - Category
                                                                    - LastRunOutcome
                                                                    - HasSchedule
                                                                    - StartDate (optional)
                                                                    ...
```

### 関連ファイル一覧

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