# 機能設計書 498-New-DbaAgentJob

## 概要

本ドキュメントは、SQL Server Agent ジョブの作成機能 `New-DbaAgentJob` の設計仕様を記載する。

### 本機能の処理概要

SQL Server Agent ジョブを新規作成する機能である。ジョブの基本設定に加え、通知設定（メール、イベントログ、ページャー、ネットセンド）やスケジュールの割り当てまで一括で行える。

**業務上の目的・背景**：SQL Server Agent ジョブは、データベースメンテナンス、ETL処理、バックアップなど自動化タスクの基盤である。SSMS を使用した手動でのジョブ作成は、特に複数インスタンスへの展開時に非効率であり、設定の標準化も困難である。本機能により、PowerShell からジョブの一括作成と標準化された設定展開が可能となり、運用効率が大幅に向上する。

**機能の利用シーン**：
- 新規 SQL Server インスタンスへのジョブ展開
- 複数インスタンスへのジョブ一括作成
- 自動化スクリプトでのジョブ管理
- ジョブ設定の標準化と文書化
- 開発環境から本番環境へのジョブ移行

**主要な処理内容**：
1. 対象 SQL Server インスタンスへの接続
2. ジョブの重複チェック（Force指定時は削除して再作成）
3. SMO Job オブジェクトの作成と設定
4. 通知設定（Email/NetSend/Page/EventLog）
5. スケジュールの割り当て
6. ジョブの保存と結果出力

**関連システム・外部連携**：SQL Server Agent ジョブシステム、Database Mail（メール通知用）、Windows イベントログ（イベントログ通知用）。

**権限による制御**：SQL Server への sysadmin 権限が必要。SQL Server 2000 以上が対象。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | Agentジョブ管理 | 主画面 | SQLエージェントジョブの新規作成 |

## 機能種別

データ作成（INSERT）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQLServerインスタンス | 必須、配列対応 |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| Job | string | Yes | ジョブ名 | 必須、%文字禁止 |
| Schedule | object[] | No | 割り当てるスケジュール名 | - |
| ScheduleId | int[] | No | 割り当てるスケジュールID | - |
| Disabled | switch | No | 無効状態で作成 | - |
| Description | string | No | ジョブの説明 | - |
| StartStepId | int | No | 開始ステップID | - |
| Category | string | No | ジョブカテゴリ | - |
| OwnerLogin | string | No | 所有者ログイン | - |
| EventLogLevel | object | No | イベントログ通知レベル | 0/Never/1/OnSuccess/2/OnFailure/3/Always |
| EmailLevel | object | No | メール通知レベル | 0/Never/1/OnSuccess/2/OnFailure/3/Always |
| NetsendLevel | object | No | ネットセンド通知レベル | 0/Never/1/OnSuccess/2/OnFailure/3/Always |
| PageLevel | object | No | ページャー通知レベル | 0/Never/1/OnSuccess/2/OnFailure/3/Always |
| EmailOperator | string | No | メール通知先オペレーター | EmailLevel と併用 |
| NetsendOperator | string | No | ネットセンド通知先オペレーター | NetsendLevel と併用 |
| PageOperator | string | No | ページャー通知先オペレーター | PageLevel と併用 |
| DeleteLevel | object | No | 自動削除レベル | 0/Never/1/OnSuccess/2/OnFailure/3/Always |
| Force | switch | No | 既存ジョブを削除して再作成 | - |
| EnableException | switch | No | 例外処理の制御フラグ | - |

### 入力データソース

- ユーザー指定のパラメータ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピューター名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | ジョブ名 |
| Enabled | bool | 有効フラグ |
| Description | string | ジョブ説明 |
| Owner | string | 所有者 |
| CreateDate | datetime | 作成日時 |
| LastModifiedDate | datetime | 最終更新日時 |
| Category | string | カテゴリ名 |
| EventLogLevel | enum | イベントログ通知レベル |
| EmailLevel | enum | メール通知レベル |
| NetSendLevel | enum | ネットセンド通知レベル |
| PageLevel | enum | ページャー通知レベル |
| DeleteLevel | enum | 自動削除レベル |
| IsScheduled | bool | スケジュール有無 |

### 出力先

PowerShell パイプラインへの出力（`Microsoft.SqlServer.Management.Smo.Agent.Job` オブジェクト、Get-DbaAgentJob 経由）

## 処理フロー

### 処理シーケンス

```
1. パラメータ前処理
   └─ 通知レベルの文字列から数値への変換
2. パラメータ検証
   └─ 通知レベルとオペレーターの整合性チェック
3. インスタンスループ開始
   └─ 各 SqlInstance に対して処理
4. SQL Server 接続
   └─ Connect-DbaInstance で接続確立
5. ジョブ重複チェック
   └─ 既存ジョブの確認（Force時は削除）
6. SMO Job オブジェクト作成
   └─ New-Object Microsoft.SqlServer.Management.Smo.Agent.Job
7. ジョブオプション設定
   └─ 各プロパティの設定
8. ジョブ作成・ターゲット設定
   └─ Create() および ApplyToTargetServer()
9. スケジュール割り当て
   └─ Set-DbaAgentJob 経由
10. 結果出力
    └─ Get-DbaAgentJob で出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[通知レベル変換]
    B --> C[パラメータ検証]
    C --> D{検証エラー?}
    D -->|Yes| E[Stop-Function で終了]
    D -->|No| F{SqlInstance ループ}
    F --> G[Connect-DbaInstance]
    G --> H{接続成功?}
    H -->|No| I[Stop-Function]
    I --> F
    H -->|Yes| J{ジョブ存在?}
    J -->|Yes| K{Force指定?}
    K -->|Yes| L[Remove-DbaAgentJob]
    K -->|No| M[Stop-Function でスキップ]
    L --> N[SMO Job 作成]
    J -->|No| N
    M --> F
    N --> O[プロパティ設定]
    O --> P[Job.Create]
    P --> Q[ApplyToTargetServer]
    Q --> R{Schedule指定?}
    R -->|Yes| S[Set-DbaAgentJob]
    R -->|No| T[Get-DbaAgentJob]
    S --> T
    T --> F
    F -->|終了| U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-498-01 | ジョブ名一意性 | 同名ジョブが存在する場合は作成をスキップ（Force時は削除後再作成） | 常時 |
| BR-498-02 | 通知オペレーター必須 | 通知レベル1以上の場合、対応するオペレーターの指定が必須 | 通知レベル指定時 |
| BR-498-03 | カテゴリ自動作成 | Force指定時、存在しないカテゴリは自動作成 | Force + Category 指定時 |
| BR-498-04 | 所有者存在確認 | 指定したOwnerLoginがインスタンスに存在する必要がある | OwnerLogin 指定時 |
| BR-498-05 | オペレーター存在確認 | 通知オペレーターはインスタンスに存在する必要がある | 通知オペレーター指定時 |
| BR-498-06 | AG リスナー制限 | 可用性グループリスナー経由ではジョブ作成不可 | AG リスナー接続時 |

### 計算ロジック

**通知レベル変換**:
```powershell
$EventLogLevel = switch ($EventLogLevel) {
    "Never" { 0 } "OnSuccess" { 1 } "OnFailure" { 2 } "Always" { 3 }
    default { 0 }
}
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ジョブ作成 | msdb.dbo.sysjobs | INSERT | ジョブの作成 |
| スケジュール割当 | msdb.dbo.sysjobschedules | INSERT | スケジュール関連付け |
| ジョブステップ | msdb.dbo.sysjobsteps | INSERT | ステップ情報 |

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

#### msdb.dbo.sysjobs

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | job_id, name, enabled, description, owner_sid, category_id など | SMO Job.Create() 経由 | |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Server への接続失敗 | Stop-Function で Continue |
| JobExists | 重複エラー | 同名ジョブが存在（Force なし） | Stop-Function で Continue |
| InvalidOperator | オペレーターエラー | 通知オペレーターが存在しない | Stop-Function で Continue |
| InvalidOwner | 所有者エラー | OwnerLogin が存在しない | Stop-Function で Continue |
| InvalidCategory | カテゴリエラー | カテゴリが存在しない（Force なし） | Stop-Function で終了 |
| AGListener | AG制限 | AGリスナー経由での接続 | Stop-Function で Continue |

### リトライ仕様

リトライ処理は実装されていない。

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

各ジョブは個別に作成される。SMO の Create() メソッドで内部的にトランザクション管理。

## パフォーマンス要件

- 各インスタンスへの接続は順次処理
- ジョブ作成後のスケジュール割り当ては Set-DbaAgentJob を使用

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

- SQL Server への接続には SqlCredential による認証情報指定が可能
- sysadmin 権限が必要
- ShouldProcess（WhatIf/Confirm）をサポート

## 備考

- ジョブステップは本機能では作成しない（New-DbaAgentJobStep を使用）
- Pager と NetSend は将来の SQL Server で廃止予定

---

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

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

### 推奨読解順序

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

SMO の Job オブジェクト構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaAgentJob.ps1 | `public/New-DbaAgentJob.ps1` | 105-129行目の .OUTPUTS セクション |

**読解のコツ**: Job オブジェクトは多数のプロパティを持ち、通知設定は OperatorToEmail/OperatorToNetSend/OperatorToPage プロパティで管理される。

#### Step 2: パラメータと前処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaAgentJob.ps1 | `public/New-DbaAgentJob.ps1` | 167-197行目のパラメータ定義、199-259行目の begin ブロック |

**主要処理フロー**:
1. **200行目**: Force による ConfirmPreference 設定
2. **202-240行目**: 通知レベルの文字列から数値への変換
3. **242-258行目**: 通知オペレーター必須チェック

#### Step 3: ジョブ作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaAgentJob.ps1 | `public/New-DbaAgentJob.ps1` | 261-448行目の process ブロック |

**主要処理フロー**:
- **272-287行目**: ジョブ存在チェックと Force 時の削除
- **289-299行目**: SMO Job オブジェクト作成（AG リスナーエラー処理含む）
- **301-414行目**: ジョブオプション設定（#region job options）
- **416-438行目**: Job.Create() とスケジュール割り当て

#### Step 4: ジョブオプション設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | New-DbaAgentJob.ps1 | `public/New-DbaAgentJob.ps1` | 301-414行目のジョブオプション設定 |

**主要処理フロー**:
- **303-309行目**: IsEnabled 設定
- **311-314行目**: Description 設定
- **321-342行目**: Category 設定（存在チェック、Force 時は自動作成）
- **359-374行目**: EmailLevel と EmailOperator 設定
- **376-391行目**: NetsendLevel と NetsendOperator 設定

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

```
New-DbaAgentJob
    │
    ├─ begin ブロック
    │      ├─ Force による ConfirmPreference 設定
    │      ├─ 通知レベル変換
    │      └─ 通知オペレーター必須チェック
    │
    ├─ Connect-DbaInstance
    │      └─ SMO 接続確立
    │
    ├─ Remove-DbaAgentJob（Force 時）
    │      └─ 既存ジョブ削除
    │
    ├─ New-Object Microsoft.SqlServer.Management.Smo.Agent.Job
    │      └─ SMO Job オブジェクト作成
    │
    ├─ New-DbaAgentJobCategory（Force + Category 時）
    │      └─ カテゴリ自動作成
    │
    ├─ Job.Create()
    │      └─ ジョブ作成
    │
    ├─ Job.ApplyToTargetServer("(local)")
    │      └─ ターゲットサーバー設定
    │
    ├─ Set-DbaAgentJob（Schedule 指定時）
    │      └─ スケジュール割り当て
    │
    ├─ Add-TeppCacheItem
    │      └─ タブ補完キャッシュ更新
    │
    └─ Get-DbaAgentJob
           └─ 作成したジョブの取得・出力
```

### データフロー図

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

SqlInstance ─────────────┬─► Connect-DbaInstance ──────────────► SMO Server
SqlCredential ───────────┘                                              │
                                                                        ▼
Job ─────────────────────────► ジョブ重複チェック ◄─────────────────────┤
                                        │                               │
Force ───────────────────────────► 削除判定                             │
                                   │      │                             │
                                 Yes      No                            │
                                   │      │                             │
                           Remove-DbaAgentJob                           │
                                   │      │                             │
                                   └──────┴─► New-Object Job            │
                                                    │                   │
Disabled ────────────────────────────────────────────┤                  │
Description ─────────────────────────────────────────┤                  │
Category ────────────────────────────────────────────┤                  │
OwnerLogin ──────────────────────────────────────────┤                  │
EventLogLevel ───────────────────────────────────────┤                  │
EmailLevel ──────────────────────────────────────────┤                  │
EmailOperator ───────────────────────────────────────┤                  │
NetsendLevel ────────────────────────────────────────┤                  │
NetsendOperator ─────────────────────────────────────┤                  │
PageLevel ───────────────────────────────────────────┤                  │
PageOperator ────────────────────────────────────────┤                  │
DeleteLevel ─────────────────────────────────────────┘                  │
                                                    │                   │
                                                    ▼                   │
                                             Job.Create()               │
                                                    │                   │
                                                    ▼                   │
                                      ApplyToTargetServer("(local)")    │
                                                    │                   │
Schedule ────────────────────────────────────► Set-DbaAgentJob          │
ScheduleId ──────────────────────────────────►      │                   │
                                                    ▼                   │
                                           Get-DbaAgentJob ────────► Job オブジェクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaAgentJob.ps1 | `public/New-DbaAgentJob.ps1` | ソース | メイン機能実装 |
| Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | ソース | ジョブ取得 |
| Remove-DbaAgentJob.ps1 | `public/Remove-DbaAgentJob.ps1` | ソース | ジョブ削除 |
| Set-DbaAgentJob.ps1 | `public/Set-DbaAgentJob.ps1` | ソース | ジョブ設定変更 |
| New-DbaAgentJobCategory.ps1 | `public/New-DbaAgentJobCategory.ps1` | ソース | カテゴリ作成 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続 |
| Stop-Function.ps1 | `internal/functions/Stop-Function.ps1` | ソース | エラー処理 |
