# 機能設計書 513-Set-DbaAgentJob

## 概要

本ドキュメントは、SQL Server Agentジョブのプロパティを変更するdbatools関数「Set-DbaAgentJob」の機能設計書である。

### 本機能の処理概要

Set-DbaAgentJobは、既存のSQL Server Agentジョブの各種プロパティを変更する包括的な機能を提供する。

**業務上の目的・背景**：SQL Server Agentジョブは、バックアップ、メンテナンス、ETLなどの自動化タスクの中核を担う。複数インスタンスで構成されるエンタープライズ環境では、ジョブ設定の標準化、所有者の一括変更、通知設定の統一などが必要となる。本機能は、SSMSを使わずにこれらの設定変更をコマンドラインから実行可能にし、環境間の設定同期やメンテナンス自動化を支援する。

**機能の利用シーン**：
- ジョブの有効/無効切り替え
- ジョブの所有者変更（セキュリティコンプライアンス対応）
- 通知設定（メール、Pager、NetSend）の構成
- スケジュールの割り当て
- ジョブカテゴリの変更
- 環境間でのジョブ設定の標準化

**主要な処理内容**：
1. 対象SQL Serverインスタンスへの接続
2. 指定されたジョブの存在確認と取得
3. 各種プロパティの検証と設定
4. スケジュールの割り当て
5. 通知オペレータの設定
6. SMO Alter()メソッドによる変更のコミット

**関連システム・外部連携**：SQL Server JobServer、Operators、SharedSchedules

**権限による制御**：sysadmin権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SQL Server Management Studio - SQL Agent Jobs | 参照画面 | ジョブプロパティの確認・編集 |
| - | PowerShell Console | 主画面 | コマンド実行インターフェース |

## 機能種別

データ更新操作 (UPDATE)

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | - |
| SqlCredential | PSCredential | No | 代替認証資格情報 | - |
| Job | object[] | No* | 変更するジョブ名 | JobまたはInputObjectの少なくとも一方が必要 |
| Schedule | object[] | No | 割り当てるスケジュール名 | - |
| ScheduleId | int[] | No | 割り当てるスケジュールID | - |
| NewName | string | No | 新しいジョブ名 | - |
| Enabled | switch | No | ジョブを有効化 | - |
| Disabled | switch | No | ジョブを無効化 | - |
| Description | string | No | ジョブの説明 | - |
| StartStepId | int | No | 開始ステップID | 既存ステップID |
| Category | string | No | ジョブカテゴリ | -Force時は自動作成 |
| OwnerLogin | string | No | 所有者ログイン | 有効なログイン名 |
| EventLogLevel | object | No | イベントログレベル | Never/OnSuccess/OnFailure/Always |
| EmailLevel | object | No | メール通知レベル | Never/OnSuccess/OnFailure/Always |
| NetsendLevel | object | No | NetSend通知レベル | Never/OnSuccess/OnFailure/Always |
| PageLevel | object | No | Pager通知レベル | Never/OnSuccess/OnFailure/Always |
| EmailOperator | string | No | メール通知オペレータ | 有効なオペレータ名 |
| NetsendOperator | string | No | NetSend通知オペレータ | 有効なオペレータ名 |
| PageOperator | string | No | Pager通知オペレータ | 有効なオペレータ名 |
| DeleteLevel | object | No | 自動削除レベル | Never/OnSuccess/OnFailure/Always |
| Force | switch | No | 検証エラーをスキップ、カテゴリ自動作成 | - |
| InputObject | Job[] | No* | パイプラインからのジョブオブジェクト | - |
| EnableException | switch | No | 例外処理を有効化 | - |

### 入力データソース

- Get-DbaAgentJobコマンドからのパイプライン入力
- SQL Server JobServer.Jobsコレクション

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | ジョブ名 |
| Enabled | bool | 有効状態 |
| Description | string | 説明 |
| Owner | string | 所有者 |
| Category | string | カテゴリ |
| CurrentRunStatus | string | 現在の実行状態 |
| LastRunDate | DateTime | 最終実行日 |
| LastRunOutcome | string | 最終実行結果 |
| NextRunDate | DateTime | 次回実行日 |
| EventLogLevel | string | イベントログ設定 |

### 出力先

PowerShellパイプライン（Microsoft.SqlServer.Management.Smo.Agent.Job）

## 処理フロー

### 処理シーケンス

```
1. 初期設定（beginブロック）
   ├─ Forceフラグによる確認プロンプト制御
   ├─ 通知レベルの文字列→整数変換
   └─ 通知設定の相互検証

2. 入力検証
   └─ JobまたはInputObjectの存在チェック

3. インスタンス接続とジョブ取得
   ├─ Connect-DbaInstanceで接続
   ├─ ジョブ存在確認
   └─ ジョブオブジェクト取得・リフレッシュ

4. 各ジョブの処理
   ├─ 名前変更（NewName指定時）
   ├─ スケジュール割り当て（Schedule/ScheduleId指定時）
   ├─ 有効/無効設定
   ├─ 説明変更
   ├─ カテゴリ変更（必要に応じて作成）
   ├─ 開始ステップID変更
   ├─ 所有者変更
   ├─ 通知レベル設定
   └─ オペレータ設定

5. 変更のコミット
   └─ Alter()メソッド呼び出し

6. 結果の返却
   └─ Get-DbaAgentJobで更新後のオブジェクト取得
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[beginブロック: 初期設定]
    B --> C[通知レベル変換]
    C --> D[通知設定相互検証]
    D --> E{検証エラー?}
    E -->|Yes| F[エラー終了]
    E -->|No| G[processブロック]
    G --> H{Job/InputObject指定?}
    H -->|No| I[エラー: ジョブ名必須]
    H -->|Yes| J[各インスタンスをループ]
    J --> K[Connect-DbaInstance]
    K --> L[各ジョブをループ]
    L --> M{ジョブ存在?}
    M -->|No| N[エラー: ジョブ不存在]
    M -->|Yes| O[ジョブオブジェクト取得]
    O --> P[InputObjectに追加]
    P --> Q[各InputObjectジョブを処理]
    Q --> R[プロパティ設定]
    R --> S[スケジュール割り当て]
    S --> T[通知設定]
    T --> U[Alter実行]
    U --> V[Get-DbaAgentJobで結果取得]
    V --> W{次のジョブ?}
    W -->|Yes| Q
    W -->|No| X[endブロック: 完了メッセージ]
    X --> Y[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ジョブ識別子必須 | JobまたはInputObjectの少なくとも一方が必要 | 常時 |
| BR-002 | 通知レベルとオペレータの対応 | EmailLevel >= 1 の場合、EmailOperatorが必要 | EmailLevel設定時 |
| BR-003 | オペレータと通知レベルの対応 | EmailOperator設定時、EmailLevelも必要 | EmailOperator設定時 |
| BR-004 | カテゴリ自動作成 | -Force指定時、存在しないカテゴリを自動作成 | Force + Category設定時 |
| BR-005 | 開始ステップID検証 | StartStepIdは既存ステップIDである必要がある | StartStepId設定時 |
| BR-006 | 所有者ログイン検証 | OwnerLoginは有効なログインである必要がある | OwnerLogin設定時 |

### 計算ロジック

**通知レベルの変換**：
- "Never" → 0
- "OnSuccess" → 1
- "OnFailure" → 2
- "Always" → 3

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ジョブ更新 | msdb.dbo.sysjobs | UPDATE | ジョブプロパティの更新 |
| スケジュール関連付け | msdb.dbo.sysjobschedules | INSERT | スケジュール割り当て |
| カテゴリ作成 | msdb.dbo.syscategories | INSERT | -Force時の新規カテゴリ作成 |

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

#### msdb.dbo.sysjobs

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | name | NewName指定値 | Rename()メソッド経由 |
| UPDATE | enabled | 0 or 1 | IsEnabledプロパティ |
| UPDATE | description | Description指定値 | - |
| UPDATE | owner_sid | OwnerLogin指定値 | - |
| UPDATE | notify_level_eventlog | EventLogLevel | - |
| UPDATE | notify_level_email | EmailLevel | - |
| UPDATE | notify_email_operator_id | EmailOperator | - |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | JobもInputObjectも未指定 | どちらかのパラメータを指定 |
| - | Stop-Function | EmailLevel設定時にEmailOperator未指定 | EmailOperatorを指定 |
| - | Stop-Function | EmailOperator設定時にEmailLevel未指定 | EmailLevelを指定 |
| - | Stop-Function | ジョブが存在しない | ジョブ名を確認 |
| - | Stop-Function | カテゴリが存在しない（Forceなし） | -Forceを追加またはカテゴリを事前作成 |
| - | Stop-Function | StartStepIdが存在しない | 有効なステップIDを指定 |
| - | Stop-Function | OwnerLoginが存在しない | 有効なログイン名を指定 |
| - | Stop-Function | オペレータが存在しない | 有効なオペレータ名を指定 |

### リトライ仕様

リトライ機能なし。エラー発生時は-Continueにより次の処理を継続。

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

SMOのAlter()メソッドによる暗黙的トランザクション。

## パフォーマンス要件

特に定義なし。

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

- sysadmin権限が必要
- ジョブ所有者の変更は監査対象となりうる
- WhatIf/Confirmパラメータによる事前確認が可能

## 備考

- SQL Server 2000以上に対応
- 複数サーバー・複数ジョブの一括変更に対応
- NetSend機能は非推奨だが後方互換性のため対応

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Microsoft.SqlServer.Management.Smo.Agent.Job | SMO | ジョブオブジェクトのプロパティ |

**読解のコツ**: SMOのJobクラスにはRename()、AddSharedSchedule()、Alter()など複数のメソッドがある。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaAgentJob.ps1 | `public/Set-DbaAgentJob.ps1` | 関数定義、パラメータ、ブロック構造 |

**主要処理フロー**:
1. **210-241行目**: CmdletBinding属性とパラメータ定義
2. **243-306行目**: beginブロック - 初期設定と検証
3. **308-573行目**: processブロック - メイン処理
4. **575-577行目**: endブロック - 完了メッセージ

#### Step 3: 通知設定検証を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaAgentJob.ps1 | `public/Set-DbaAgentJob.ps1` | beginブロックの検証ロジック |

**主要処理フロー**:
- **247-269行目**: 通知レベルの文字列→整数変換
- **271-305行目**: 通知レベルとオペレータの相互検証

#### Step 4: ジョブプロパティ設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Set-DbaAgentJob.ps1 | `public/Set-DbaAgentJob.ps1` | processブロックのプロパティ設定 |

**主要処理フロー**:
- **346-386行目**: スケジュール割り当て
- **387-425行目**: 有効/無効、説明、カテゴリ設定
- **427-455行目**: 開始ステップID、所有者設定
- **457-553行目**: 通知レベルとオペレータ設定

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

```
Set-DbaAgentJob
    │
    ├─ Connect-DbaInstance
    │
    ├─ JobServer.Jobs[$j] (ジョブ取得)
    │
    ├─ Job.Rename() (名前変更時)
    │
    ├─ Job.AddSharedSchedule() (スケジュール割り当て時)
    │
    ├─ New-DbaAgentJobCategory (カテゴリ作成時)
    │
    ├─ Job.Alter() (変更コミット)
    │
    └─ Get-DbaAgentJob (結果取得)
```

### データフロー図

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

Job名 ──────────────▶ ジョブ存在確認
      │                        │
SqlInstance ─────────▶ Connect-DbaInstance
      │                        │
      ▼                        ▼
各種パラメータ ────────▶ beginブロック検証
      │                        │
      ▼                        ▼
InputObject ─────────▶ processブロック処理
                              │
                              ▼
                       プロパティ設定
                       ├─ Name, Enabled, Description
                       ├─ Category, OwnerLogin
                       ├─ StartStepID
                       ├─ 通知レベル設定
                       └─ オペレータ設定
                              │
                              ▼
                         Alter()
                              │
                              ▼
                    Get-DbaAgentJob ───▶ [Jobオブジェクト出力]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaAgentJob.ps1 | `public/Set-DbaAgentJob.ps1` | ソース | メイン関数 |
| Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | ソース | ジョブ取得 |
| New-DbaAgentJobCategory.ps1 | `public/New-DbaAgentJobCategory.ps1` | ソース | カテゴリ作成 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
