# 機能設計書 521-Start-DbaAgentJob

## 概要

本ドキュメントは、SQL Server Agent ジョブを開始し、オプションで完了を待機する `Start-DbaAgentJob` コマンドの機能設計書です。

### 本機能の処理概要

SQL Server Agent ジョブの開始を制御し、ジョブの実行状況を監視する PowerShell コマンドです。アイドル状態のジョブを検証して開始し、順次実行または並列実行の両方をサポートします。

**業務上の目的・背景**：SQL Server Agent ジョブは、データベース管理における定期的なメンテナンス、バックアップ、ETL処理などの自動化に不可欠な機能です。本コマンドは、PowerShell スクリプトからプログラム的にジョブを制御することで、より高度な自動化シナリオや、障害復旧時の迅速なジョブ再実行を可能にします。手動でSSMSからジョブを開始する必要がなくなり、大規模環境での一括ジョブ実行や依存関係のあるジョブの順次実行を効率的に管理できます。

**機能の利用シーン**：
- メンテナンスウィンドウ後のバッチジョブ一括開始
- 障害復旧時の失敗したジョブの再実行
- 複数のジョブを特定の順序で実行する必要がある場合
- CI/CD パイプラインからのデータベースジョブ制御
- 特定のステップからジョブを再開する必要がある場合

**主要な処理内容**：
1. SQL Server インスタンスへの接続確立
2. 指定されたジョブまたは全ジョブの取得
3. ジョブの現在のステータス検証（アイドル状態確認）
4. ジョブの開始（オプションで特定ステップから）
5. ジョブステータスの監視とポーリング
6. 完了待機（-Wait パラメータ使用時）
7. 結果の出力

**関連システム・外部連携**：SQL Server Agent サービス、SMO (SQL Server Management Objects)

**権限による制御**：SQLAgentOperatorRole 以上の権限が必要です。ジョブの所有者またはsysadmin権限を持つユーザーのみがジョブを開始できます。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SQL Server Management Studio - SQL Server Agent Jobs | 参照画面 | GUI でのジョブ開始操作と同等の機能を提供 |

## 機能種別

システム操作 / ジョブ制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes (Instance ParameterSet) | 対象の SQL Server インスタンス | 有効なインスタンス名である必要がある |
| SqlCredential | PSCredential | No | 代替認証情報 | 有効な資格情報オブジェクト |
| Job | string[] | No | 開始するジョブ名の配列 | ジョブ名が存在する必要がある |
| StepName | string | No | 開始するステップ名 | 指定ジョブ内に存在するステップ名 |
| ExcludeJob | string[] | No | 除外するジョブ名 | - |
| InputObject | Microsoft.SqlServer.Management.Smo.Agent.Job[] | Yes (Object ParameterSet) | パイプラインからのジョブオブジェクト | 有効なJobオブジェクト |
| AllJobs | switch | No | 全ジョブを開始 | -Job, -InputObject と排他 |
| Wait | switch | No | ジョブ完了を待機 | - |
| WaitPeriod | int | No | ポーリング間隔（秒）、デフォルト3秒 | 正の整数 |
| Parallel | switch | No | 並列実行モード | -Wait が必要 |
| SleepPeriod | int | No | 初期待機時間（ミリ秒）、デフォルト300ms | 正の整数 |
| EnableException | switch | No | 例外をスローする | - |

### 入力データソース

- SQL Server Agent JobServer オブジェクト経由でジョブ情報を取得
- パイプラインからのジョブオブジェクト入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Server をホストするコンピュータ名 |
| InstanceName | string | SQL Server インスタンス名 |
| SqlInstance | string | 完全な SQL Server インスタンス名 |
| Name | string | ジョブ名 |
| CurrentRunStatus | string | 現在の実行ステータス |
| LastRunDate | DateTime | 最後の実行日時 |
| LastRunOutcome | string | 最後の実行結果 |
| IsEnabled | bool | ジョブが有効かどうか |
| HasSchedule | bool | スケジュールが設定されているか |
| OwnerLoginName | string | ジョブ所有者 |

### 出力先

- PowerShell パイプライン出力（Microsoft.SqlServer.Management.Smo.Agent.Job オブジェクト）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ -AllJobs, -Job, -InputObject のいずれかが必要
   └─ -Parallel を使用する場合は -Wait が必要
2. SQL Server インスタンスへの接続
   └─ Connect-DbaInstance を使用
3. ジョブオブジェクトの収集
   └─ -AllJobs: 全ジョブを取得
   └─ -Job: 指定ジョブのみ取得
   └─ -ExcludeJob: 除外処理
4. 各ジョブの処理ループ
   └─ ステータス確認（Idle以外はスキップ）
   └─ ジョブ開始（StepName指定時は特定ステップから）
   └─ 初期待機（SleepPeriod）
   └─ ステータス変化の監視
5. 待機処理（-Wait指定時）
   └─ 順次モード: 各ジョブ完了まで待機
   └─ 並列モード: 全ジョブ開始後に一括待機
6. 結果出力
   └─ Get-DbaAgentJob で最新状態を取得して出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{パラメータ検証}
    B -->|失敗| C[エラー終了]
    B -->|成功| D[SQL Server 接続]
    D --> E{ジョブ収集}
    E --> F[各ジョブをループ]
    F --> G{ステータス=Idle?}
    G -->|No| H[スキップ]
    G -->|Yes| I{ShouldProcess?}
    I -->|No| H
    I -->|Yes| J[ジョブ開始]
    J --> K[初期待機]
    K --> L{-Wait指定?}
    L -->|Yes| M{-Parallel?}
    M -->|No| N[完了まで待機]
    M -->|Yes| O[次のジョブへ]
    L -->|No| P[結果出力]
    N --> P
    H --> Q{次のジョブ?}
    O --> Q
    P --> Q
    Q -->|Yes| F
    Q -->|No| R{-Parallel?}
    R -->|Yes| S[全ジョブ完了待機]
    R -->|No| T[終了]
    S --> T
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | アイドル状態チェック | Idle 状態でないジョブは開始できない | 常時 |
| BR-002 | パラメータ排他制御 | -AllJobs, -Job, -InputObject のいずれか1つが必須 | 常時 |
| BR-003 | 並列実行の待機要件 | -Parallel を使用する場合は -Wait が必須 | -Parallel 指定時 |
| BR-004 | ステップ存在確認 | -StepName 指定時、該当ステップが存在しない場合はスキップ | -StepName 指定時 |

### 計算ロジック

- ポーリング間隔: WaitPeriod パラメータ（デフォルト3秒）
- 初期待機: SleepPeriod パラメータ（デフォルト300ミリ秒）
- 最大待機ループ: ジョブ開始後、ステータス変化まで最大60回のループ

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ジョブ開始 | msdb.dbo.sysjobs | UPDATE (間接) | SMO 経由でジョブ開始 |
| ステータス確認 | msdb.dbo.sysjobactivity | SELECT (間接) | SMO 経由でステータス取得 |

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

#### msdb.dbo.sysjobs

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | job_id, name, enabled | 全ジョブまたは指定ジョブ | SMO の Jobs コレクション経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | SQL Server に接続できない | 接続情報を確認 |
| - | ステータスエラー | ジョブが Idle 状態でない | ジョブの完了を待つか Stop-DbaAgentJob で停止 |
| - | パラメータエラー | 必須パラメータが不足 | -Job, -AllJobs, または -InputObject を指定 |
| - | ステップエラー | 指定ステップが存在しない | 正しいステップ名を指定 |

### リトライ仕様

ステータス変化の確認で最大60回のリトライを実行（各リトライ間隔は SleepPeriod）

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

SMO の Start() メソッドを使用するため、SQL Server Agent サービスが内部的にトランザクション管理を行う

## パフォーマンス要件

- ジョブ開始自体は即座に完了
- -Wait 使用時はジョブ完了まで待機
- ポーリング間隔は WaitPeriod で調整可能

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

- SQLAgentOperatorRole 以上の権限が必要
- Windows 認証または SQL Server 認証をサポート
- MFA サポートは Connect-DbaInstance を経由

## 備考

- -Parallel オプションは複数ジョブを同時に開始し、全完了を待機
- パイプライン入力で Get-DbaAgentJob や Find-DbaAgentJob と連携可能

---

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

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

### 推奨読解順序

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

SMO の Agent.Job オブジェクトが中心的なデータ構造です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SMO Agent.Job | Microsoft.SqlServer.Management.Smo.Agent | Job オブジェクトのプロパティと Start() メソッド |

**読解のコツ**: SMO の Job オブジェクトは CurrentRunStatus, LastRunDate, JobSteps などのプロパティを持ち、Start() メソッドでジョブを開始します。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Start-DbaAgentJob.ps1 | `public/Start-DbaAgentJob.ps1` | 関数定義とパラメータセット |

**主要処理フロー**:
1. **150-166行目**: パラメータ定義とパラメータセット
2. **167-186行目**: begin ブロックで waitBlock スクリプトブロック定義
3. **187-220行目**: process ブロックでジョブ収集
4. **222-278行目**: 各ジョブの開始処理
5. **280-289行目**: 並列実行の完了待機

#### Step 3: 待機ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Start-DbaAgentJob.ps1 | `public/Start-DbaAgentJob.ps1` | waitBlock スクリプトブロック |

**主要処理フロー**:
- **168-185行目**: waitBlock の定義
- **174-181行目**: 現在のステップ情報とリトライ状況の取得
- **183-184行目**: ポーリング間隔での待機と Refresh()

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

```
Start-DbaAgentJob
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server SMO 接続確立
    │
    ├─ $server.JobServer.Jobs
    │      └─ ジョブコレクション取得
    │
    ├─ $currentjob.Start() / $currentjob.Start($StepName)
    │      └─ ジョブ開始
    │
    ├─ $currentjob.Refresh()
    │      └─ ステータス更新
    │
    └─ Get-DbaAgentJob
           └─ 結果オブジェクト取得
```

### データフロー図

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

SqlInstance ───▶ Connect-DbaInstance ───▶ SMO Server Object
                         │
Job/AllJobs ───▶ JobServer.Jobs Filter ───▶ Job Collection
                         │
StepName ───────▶ job.Start(StepName) ───▶ Job Execution
                         │
Wait ───────────▶ Polling Loop ─────────▶ Job Status
                         │
                  Get-DbaAgentJob ───────▶ Job Objects (Pipeline)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Start-DbaAgentJob.ps1 | `public/Start-DbaAgentJob.ps1` | ソース | メイン関数定義 |
| Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | ソース | ジョブ情報取得（結果出力に使用） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続 |
