# 機能設計書 489-Get-DbaAgentJobStep

## 概要

本ドキュメントは、SQL Agent ジョブステップの詳細情報を取得する Get-DbaAgentJobStep 関数の機能設計書である。

### 本機能の処理概要

Get-DbaAgentJobStep は、1つ以上の SQL Server インスタンスから SQL Agent ジョブステップの包括的な詳細情報を収集する機能を提供する。各ステップのサブシステムタイプ、最終実行日、実行結果、現在の状態などを返し、ジョブパフォーマンスの監視や失敗した自動化タスクのトラブルシューティングに不可欠な情報を提供する。

**業務上の目的・背景**：SQL Agent ジョブは複数のステップで構成されることが多く、ジョブ全体の成功/失敗だけでなく、個々のステップレベルでの分析が必要な場合がある。特定のステップの構成確認、失敗ステップの特定、サブシステム（T-SQL、PowerShell、SSIS など）別の分析などに使用される。

**機能の利用シーン**：
- ジョブステップ構成の確認・監査
- 失敗したステップの特定
- サブシステム別ステップの分析
- メンテナンスルーティンの構成確認
- パイプライン経由での詳細分析

**主要な処理内容**：
1. 指定されたインスタンスへの接続（process ブロック）
2. ジョブの取得と InputObject への追加
3. Job/ExcludeJob/ExcludeDisabledJobs フィルタリング（end ブロック）
4. 各ジョブの JobSteps コレクション走査
5. カスタムプロパティの追加と結果出力

**関連システム・外部連携**：SQL Server Agent の Jobs.JobSteps コレクションを SMO 経由で取得。Get-DbaAgentJob からパイプライン入力を受け付け可能。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 9 | ジョブステップ管理 | 主機能 | SQLエージェントジョブステップの取得 |

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | パイプライン入力可 |
| SqlCredential | PSCredential | No | 認証用資格情報 | Windows/SQL認証対応 |
| Job | string[] | No | 取得するジョブ名（ワイルドカード対応） | - |
| ExcludeJob | string[] | No | 除外するジョブ名（ワイルドカード対応） | - |
| InputObject | Job[] | No | SMOジョブオブジェクト | パイプライン入力可 |
| ExcludeDisabledJobs | Switch | No | 無効化されたジョブを除外 | - |
| EnableException | Switch | No | 例外処理を有効化 | - |

### 入力データソース

SMO を介した SQL Server インスタンスの JobServer.Jobs コレクションから取得、または InputObject パラメータからのパイプライン入力。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverのコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なインスタンス名 |
| AgentJob | String | 親ジョブ名 |
| Name | String | ステップ名 |
| SubSystem | String | サブシステムタイプ（TransactSql/PowerShell/CmdExec等） |
| LastRunDate | DateTime | 最終実行日時 |
| LastRunOutcome | String | 最終実行結果（Succeeded/Failed等） |
| State | String | 現在の状態（Enabled/Disabled等） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. process ブロック: ジョブ収集
   └─ 各インスタンスに対してループ処理
   └─ Connect-DbaInstance で接続
   └─ JobServer.Jobs を InputObject に追加

2. end ブロック: フィルタリングと出力
   └─ Job パラメータでフィルタ
   └─ ExcludeJob パラメータで除外
   └─ ExcludeDisabledJobs で無効ジョブ除外

3. ジョブステップの走査
   └─ 各ジョブの JobSteps コレクション走査
   └─ カスタムプロパティの追加
   └─ Select-DefaultView で出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[processブロック]
    B --> C[インスタンスループ]
    C --> D[インスタンス接続]
    D --> E{接続成功?}
    E -->|No| C
    E -->|Yes| F[Jobs追加]
    F --> G{次のインスタンス?}
    G -->|Yes| C
    G -->|No| H[endブロック]
    H --> I{Job指定?}
    I -->|Yes| J[ジョブ名フィルタ]
    I -->|No| K{ExcludeJob指定?}
    J --> K
    K -->|Yes| L[除外フィルタ]
    K -->|No| M{ExcludeDisabledJobs?}
    L --> M
    M -->|Yes| N[無効ジョブ除外]
    M -->|No| O[ジョブステップループ]
    N --> O
    O --> P[カスタムプロパティ追加]
    P --> Q[Select-DefaultView]
    Q --> R[結果出力]
    R --> S{次のステップ?}
    S -->|Yes| O
    S -->|No| T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 遅延処理 | フィルタリングは end ブロックで実行 | 常時 |
| BR-002 | パイプライン統合 | SqlInstance と InputObject の両方からジョブを収集 | process ブロック |
| BR-003 | プロパティ取得 | ComputerName等は Parent.Parent.Parent から取得 | 常時 |

### 計算ロジック

特になし。

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

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

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

特になし。

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

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

## パフォーマンス要件

- ジョブ数・ステップ数に依存
- process ブロックでジョブを収集し、end ブロックで一括フィルタリング
- 大量のジョブがある環境では、早期フィルタリングの効果は限定的

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

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

## 備考

- SMO の Parent.Parent.Parent 経由でサーバー情報を取得（JobStep -> Job -> JobServer -> Server）
- process ブロックでジョブを収集し、end ブロックでフィルタリングと出力を実行
- InputObject パラメータで Get-DbaAgentJob からのパイプライン入力に対応

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgentJobStep.ps1 | `public/Get-DbaAgentJobStep.ps1` | 117-128行目: パラメータ定義 |
| 1-2 | Get-DbaAgentJobStep.ps1 | `public/Get-DbaAgentJobStep.ps1` | 51-85行目: .OUTPUTS ドキュメント |

**読解のコツ**: SqlInstance と InputObject の両方が ValueFromPipeline であること、両方が必須でないことに注目。

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

ジョブ収集のロジックを特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgentJobStep.ps1 | `public/Get-DbaAgentJobStep.ps1` | 129-139行目: processブロック |

**主要処理フロー**:
1. **130-136行目**: インスタンスへの接続
2. **137行目**: InputObject へのジョブ追加

#### Step 3: end ブロックを理解する

フィルタリングと出力のロジック。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAgentJobStep.ps1 | `public/Get-DbaAgentJobStep.ps1` | 140-159行目: endブロック |

**主要処理フロー**:
- **141-149行目**: Job/ExcludeJob/ExcludeDisabledJobs フィルタ
- **150行目**: Verbose メッセージ
- **151-157行目**: ジョブステップのループと出力

#### Step 4: プロパティ取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaAgentJobStep.ps1 | `public/Get-DbaAgentJobStep.ps1` | 152-157行目: プロパティ追加 |

**主要処理フロー**:
- **152-154行目**: Parent.Parent.Parent からサーバー情報取得
- **155行目**: Parent.Name からジョブ名取得
- **157行目**: Select-DefaultView で表示プロパティ設定

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

```
Get-DbaAgentJobStep
    │
    ├─ [process] foreach ($instance in $SqlInstance)
    │      │
    │      ├─ Connect-DbaInstance
    │      │      └─ インスタンス接続
    │      │
    │      └─ $InputObject += $server.JobServer.Jobs
    │             └─ ジョブ追加
    │
    └─ [end]
           │
           ├─ Where-Object フィルタ
           │      ├─ Job: -In でフィルタ
           │      ├─ ExcludeJob: -NotIn で除外
           │      └─ ExcludeDisabledJobs: IsEnabled
           │
           └─ foreach ($agentJobStep in $InputObject.jobsteps)
                  │
                  ├─ Add-Member
                  │      ├─ ComputerName (Parent.Parent.Parent)
                  │      ├─ InstanceName (Parent.Parent.Parent)
                  │      ├─ SqlInstance (Parent.Parent.Parent)
                  │      └─ AgentJob (Parent.Name)
                  │
                  └─ Select-DefaultView
                         └─ 表示プロパティ設定
```

### データフロー図

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

SqlInstance ─────────────────▶ Connect-DbaInstance ─────────────▶ SMO Server
                                │
                                ▼
                          $server.JobServer.Jobs
                                │
InputObject ─────────────────▶ $InputObject += Jobs
(パイプライン)                  │
                                ▼
                          [end ブロック]
Job/ExcludeJob ──────────────▶ Where-Object フィルタ
ExcludeDisabledJobs             │
                                ▼
                          $InputObject.jobsteps
                                │
                                ▼
                          Add-Member
                          - ComputerName (Parent.Parent.Parent)
                          - InstanceName (Parent.Parent.Parent)
                          - SqlInstance (Parent.Parent.Parent)
                          - AgentJob (Parent.Name)
                                │
                                ▼
                          Select-DefaultView ─────────────────────▶ JobStep Objects
                                                                    - AgentJob
                                                                    - Name
                                                                    - SubSystem
                                                                    - LastRunDate
                                                                    - LastRunOutcome
                                                                    - State
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgentJobStep.ps1 | `public/Get-DbaAgentJobStep.ps1` | ソース | メイン関数 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
| Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | ソース | パイプライン入力元 |
| New-DbaAgentJobStep.ps1 | `public/New-DbaAgentJobStep.ps1` | ソース | 関連機能（ステップ作成） |
| Remove-DbaAgentJobStep.ps1 | `public/Remove-DbaAgentJobStep.ps1` | ソース | 関連機能（ステップ削除） |
| Set-DbaAgentJobStep.ps1 | `public/Set-DbaAgentJobStep.ps1` | ソース | 関連機能（ステップ変更） |
