# 画面設計書：Agentジョブ管理

## 1. 基本情報

| 項目 | 内容 |
|------|------|
| 画面ID | 8 |
| 画面名 | Agentジョブ管理 |
| 画面種別 | CLI（コマンドラインインターフェース） |
| カテゴリ | Agent |
| 関連ファイル | public/Get-DbaAgentJob.ps1, public/New-DbaAgentJob.ps1, public/Remove-DbaAgentJob.ps1 |

## 2. 概要・目的

Agentジョブ管理は、SQL Server Agentジョブの取得、作成、削除を行うPowerShellコマンド群です。

本コマンド群により以下の操作が可能です：
- ジョブの一覧取得とフィルタリング
- ジョブの作成と通知設定
- ジョブの削除（履歴・スケジュール保持オプション付き）

## 3. 主要機能

### 3.1 Get-DbaAgentJob

SQL Server Agentジョブの詳細情報を取得します。

**入力パラメータ：**

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | はい | - | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | いいえ | - | 代替認証情報 |
| Job | string[] | いいえ | - | 取得するジョブ名 |
| ExcludeJob | string[] | いいえ | - | 除外するジョブ名 |
| ExcludeDisabledJobs | switch | いいえ | false | 無効なジョブを除外 |
| Database | string[] | いいえ | - | 対象データベースでフィルタ |
| Category | string[] | いいえ | - | カテゴリでフィルタ |
| ExcludeCategory | string[] | いいえ | - | 除外するカテゴリ |
| IncludeExecution | switch | いいえ | false | 実行開始日時を含める |
| Type | string[] | いいえ | MultiServer, Local | ジョブタイプ |
| EnableException | switch | いいえ | false | 例外を有効化 |

**出力プロパティ：**

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | SQL Serverインスタンス名 |
| Name | string | ジョブ名 |
| Category | string | カテゴリ |
| OwnerLoginName | string | 所有者ログイン名 |
| CurrentRunStatus | string | 現在の実行状態 |
| CurrentRunRetryAttempt | int | 現在のリトライ回数 |
| Enabled | bool | 有効フラグ |
| LastRunDate | DateTime | 最終実行日時 |
| LastRunOutcome | string | 最終実行結果 |
| HasSchedule | bool | スケジュール有無 |
| OperatorToEmail | string | 通知先メールオペレータ |
| CreateDate | DateTime | 作成日時 |
| StartDate | DateTime | 実行開始日時（IncludeExecution時） |

### 3.2 New-DbaAgentJob

SQL Server Agentジョブを作成します。

**入力パラメータ：**

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | はい | - | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | いいえ | - | 代替認証情報 |
| Job | string | はい | - | ジョブ名（%使用不可） |
| Schedule | object[] | いいえ | - | アタッチするスケジュール |
| ScheduleId | int[] | いいえ | - | アタッチするスケジュールID |
| Disabled | switch | いいえ | false | 無効状態で作成 |
| Description | string | いいえ | - | ジョブの説明 |
| StartStepId | int | いいえ | - | 開始ステップID |
| Category | string | いいえ | - | カテゴリ |
| OwnerLogin | string | いいえ | - | 所有者ログイン |
| EventLogLevel | object | いいえ | 0 (Never) | イベントログ通知レベル |
| EmailLevel | object | いいえ | 0 (Never) | メール通知レベル |
| NetsendLevel | object | いいえ | 0 (Never) | Netsend通知レベル |
| PageLevel | object | いいえ | 0 (Never) | ページャー通知レベル |
| EmailOperator | string | いいえ | - | メール通知オペレータ |
| NetsendOperator | string | いいえ | - | Netsend通知オペレータ |
| PageOperator | string | いいえ | - | ページャー通知オペレータ |
| DeleteLevel | object | いいえ | 0 (Never) | 自動削除レベル |
| Force | switch | いいえ | false | 強制モード |
| EnableException | switch | いいえ | false | 例外を有効化 |

**通知レベル値：**

| 値 | 意味 |
|----|------|
| 0 / Never | 通知しない |
| 1 / OnSuccess | 成功時 |
| 2 / OnFailure | 失敗時 |
| 3 / Always | 常に |

### 3.3 Remove-DbaAgentJob

SQL Server Agentジョブを削除します。

**入力パラメータ：**

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | 条件付き | - | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | いいえ | - | 代替認証情報 |
| Job | object[] | 条件付き | - | 削除するジョブ名 |
| KeepHistory | switch | いいえ | false | 履歴を保持 |
| KeepUnusedSchedule | switch | いいえ | false | 未使用スケジュールを保持 |
| InputObject | Job[] | 条件付き | - | パイプライン入力用ジョブオブジェクト |
| EnableException | switch | いいえ | false | 例外を有効化 |

**出力プロパティ：**

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | SQL Serverインスタンス名 |
| Name | string | ジョブ名 |
| Status | string | 操作ステータス（Dropped/Failed） |

## 4. 処理フロー

### 4.1 Get-DbaAgentJob

```
[開始]
   ↓
[インスタンス接続]
   ├── Connect-DbaInstanceで接続
   ↓
[実行情報取得]（IncludeExecution指定時）
   ├── sysjobs_view + sysjobactivityクエリ実行
   ↓
[ジョブ取得]
   ├── server.JobServer.Jobs取得
   ├── Typeでフィルタ（MultiServer/Local）
   ↓
[フィルタリング]
   ├── Job名でフィルタ
   ├── ExcludeJobで除外
   ├── ExcludeDisabledJobsで無効除外
   ├── CategoryID=1（MSXジョブ）を除外
   ├── Databaseでステップフィルタ
   ├── Categoryでフィルタ
   ├── ExcludeCategoryで除外
   ↓
[出力プロパティ追加]
   ├── ComputerName, InstanceName, SqlInstance追加
   ├── StartDate追加（IncludeExecution時）
   ↓
[ジョブ情報出力]
   ↓
[終了]
```

### 4.2 New-DbaAgentJob

```
[開始]
   ↓
[パラメータ検証]
   ├── 通知レベルの文字列→整数変換
   ├── オペレータ必須チェック（通知レベル>=1の場合）
   ↓
[インスタンス接続]
   ├── Connect-DbaInstanceで接続
   ↓
[既存ジョブチェック]
   ├── [ジョブ存在 + Force未指定] → エラー
   ├── [ジョブ存在 + Force指定] → Remove-DbaAgentJobで削除
   ↓
[ジョブオブジェクト作成]
   ├── New-Object Microsoft.SqlServer.Management.Smo.Agent.Job
   ↓
[ジョブ設定]
   ├── IsEnabled設定
   ├── Description設定
   ├── StartStepID設定
   ├── Category設定（存在確認、Force時は作成）
   ├── OwnerLoginName設定（存在確認）
   ├── EventLogLevel, EmailLevel, NetsendLevel, PageLevel設定
   ├── オペレータ設定（存在確認）
   ├── DeleteLevel設定
   ↓
[ジョブ作成]
   ├── currentjob.Create()
   ├── ApplyToTargetServer("(local)")
   ├── Refresh()
   ↓
[スケジュールアタッチ]（指定時）
   ├── Set-DbaAgentJobでスケジュール設定
   ↓
[作成結果出力]
   ├── Get-DbaAgentJobで取得
   ↓
[終了]
```

### 4.3 Remove-DbaAgentJob

```
[開始]
   ↓
[パラメータ検証]
   ├── Job名の空値チェック
   ↓
[インスタンス接続]
   ├── Connect-DbaInstanceで接続
   ↓
[ジョブ取得]
   ├── Job名で検索、InputObjectに追加
   ↓
[ジョブ削除]
   ├── sp_delete_job実行
   │     ├── @delete_history設定（KeepHistory時は0）
   │     └── @delete_unused_schedule設定（KeepUnusedSchedule時は0）
   ├── JobServer.Jobs.Refresh()
   ↓
[削除結果出力]
   ├── Status="Dropped" or "Failed"
   ↓
[終了]
```

## 5. バリデーションルール

### 5.1 New-DbaAgentJob

| 条件 | エラーメッセージ |
|------|----------------|
| EmailLevel>=1でEmailOperator未指定 | "Please set the e-mail operator when the e-mail level parameter is set." |
| NetsendLevel>=1でNetsendOperator未指定 | "Please set the netsend operator when the netsend level parameter is set." |
| PageLevel>=1でPageOperator未指定 | "Please set the page operator when the page level parameter is set." |
| ジョブ名重複（Force未指定） | "Job $Job already exists on $instance" |
| カテゴリ未存在（Force未指定） | "Job category $Category doesn't exist on $instance. Use -Force to create it." |
| オーナーログイン未存在 | "The owner $OwnerLogin does not exist on instance $instance" |
| オペレータ未存在 | "The e-mail operator name $EmailOperator does not exist on instance $instance." |

### 5.2 Remove-DbaAgentJob

| 条件 | エラーメッセージ |
|------|----------------|
| ジョブ未存在 | "Job $j doesn't exist on $instance." |

## 6. ConfirmImpact

- **Get-DbaAgentJob**: なし（読み取り専用）
- **New-DbaAgentJob**: Low
- **Remove-DbaAgentJob**: High

## 7. 使用例

### 7.1 全ジョブ取得

```powershell
Get-DbaAgentJob -SqlInstance localhost
```

### 7.2 複数サーバーのジョブ取得

```powershell
Get-DbaAgentJob -SqlInstance localhost, sql2016
```

### 7.3 特定ジョブの取得

```powershell
Get-DbaAgentJob -SqlInstance localhost -Job BackupData, BackupDiff
```

### 7.4 有効なジョブのみ取得

```powershell
Get-DbaAgentJob -SqlInstance localhost -ExcludeDisabledJobs
```

### 7.5 特定データベースに関連するジョブ取得

```powershell
Get-DbaAgentJob -SqlInstance sqlserver2014a -Database msdb
```

### 7.6 ジョブ作成

```powershell
New-DbaAgentJob -SqlInstance sql1 -Job 'Job One' -Description 'Just another job'
```

### 7.7 無効状態でジョブ作成

```powershell
New-DbaAgentJob -SqlInstance sql1 -Job 'Job One' -Disabled
```

### 7.8 メール通知付きジョブ作成

```powershell
New-DbaAgentJob -SqlInstance SSTAD-PC -Job 'Job One' -EmailLevel OnFailure -EmailOperator dba
```

### 7.9 ジョブ削除

```powershell
Remove-DbaAgentJob -SqlInstance sql1 -Job Job1
```

### 7.10 履歴を保持してジョブ削除

```powershell
Get-DbaAgentJob -SqlInstance sql1 -Job Job1 | Remove-DbaAgentJob -KeepHistory
```

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

### 8.1 理解の順序

1. **Get-DbaAgentJob.ps1** - ジョブ取得とフィルタリングの基本構造
2. **New-DbaAgentJob.ps1** - ジョブ作成と通知設定のフロー
3. **Remove-DbaAgentJob.ps1** - ジョブ削除とsp_delete_job使用

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

```
Get-DbaAgentJob
├── Connect-DbaInstance (Line 159)
├── server.Query() (Line 172) - IncludeExecution時
├── server.JobServer.Jobs (Line 199)
├── Where-Object (Lines 202-232) - 各種フィルタ
├── Add-Member (Lines 241-247)
└── Select-DefaultView (Line 249)

New-DbaAgentJob
├── Connect-DbaInstance (Line 267)
├── Remove-DbaAgentJob (Line 280) - Force時の既存削除
├── New-Object Job (Line 292)
├── New-DbaAgentJobCategory (Line 329) - Force時のカテゴリ作成
├── currentjob.Create() (Line 420)
├── ApplyToTargetServer() (Line 426)
├── Set-DbaAgentJob (Lines 433, 437) - スケジュールアタッチ
└── Get-DbaAgentJob (Line 446)

Remove-DbaAgentJob
├── Connect-DbaInstance (Line 110)
├── sp_delete_job実行 (Lines 139-140)
└── JobServer.Jobs.Refresh() (Line 141)
```

### 8.3 データフロー図

```
[ユーザー入力]
     │
     ├─[Get-DbaAgentJob]──────────────────────────────────────────────┐
     │       │                                                        │
     │       └── server.JobServer.Jobs                               │
     │                 │                                              │
     │                 ├── Type フィルタ                              │
     │                 ├── Job/ExcludeJob フィルタ                    │
     │                 ├── ExcludeDisabledJobs フィルタ               │
     │                 ├── Database フィルタ                          │
     │                 └── Category/ExcludeCategory フィルタ ─────────┼─→ [ジョブ情報]
     │                                                                │
     ├─[New-DbaAgentJob]──────────────────────────────────────────────┤
     │       │                                                        │
     │       ├── パラメータ検証                                       │
     │       │                                                        │
     │       ├── New-Object Job                                       │
     │       │                                                        │
     │       ├── プロパティ設定                                       │
     │       │                                                        │
     │       ├── Create()                                             │
     │       │                                                        │
     │       └── Get-DbaAgentJob ─────────────────────────────────────┼─→ [作成されたジョブ]
     │                                                                │
     └─[Remove-DbaAgentJob]───────────────────────────────────────────┤
             │                                                        │
             ├── sp_delete_job                                        │
             │     ├── @delete_history                                │
             │     └── @delete_unused_schedule                        │
             │                                                        │
             └── Status=Dropped/Failed ───────────────────────────────┴─→ [削除結果]
```

### 8.4 関連ファイル一覧

| ファイルパス | 役割 | 行数 |
|-------------|------|------|
| public/Get-DbaAgentJob.ps1 | ジョブ取得 | 253 |
| public/New-DbaAgentJob.ps1 | ジョブ作成 | 455 |
| public/Remove-DbaAgentJob.ps1 | ジョブ削除 | 164 |
| public/Set-DbaAgentJob.ps1 | ジョブ設定変更（依存） | - |
| public/Start-DbaAgentJob.ps1 | ジョブ開始（関連） | - |
| public/Stop-DbaAgentJob.ps1 | ジョブ停止（関連） | - |
| public/New-DbaAgentJobCategory.ps1 | カテゴリ作成（依存） | - |

### 8.5 重要コードポイント

#### 実行中ジョブの情報取得（Get-DbaAgentJob.ps1: Lines 165-173）
```powershell
$query = "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;"
```

#### MSXジョブ除外（Get-DbaAgentJob.ps1: Line 211）
```powershell
$jobs = $jobs | Where-Object CategoryID -ne 1
```

#### sp_delete_job使用（Remove-DbaAgentJob.ps1: Lines 139-140）
```powershell
$dropJobQuery = ("EXEC dbo.sp_delete_job @job_name = '{0}', @delete_history = {1}, @delete_unused_schedule = {2}" -f $currentJob.Name.Replace("'", "''"), $dropHistory, $dropSchedule)
$server.Databases['msdb'].ExecuteNonQuery($dropJobQuery)
```

## 9. 権限要件

| 操作 | 必要な権限 |
|------|----------|
| Get-DbaAgentJob | SQLAgentReaderRole以上 |
| New-DbaAgentJob | SQLAgentOperatorRole以上 |
| Remove-DbaAgentJob | SQLAgentOperatorRole以上（所有者）またはsysadmin |

## 10. 関連コマンド

- Get-DbaAgentJobStep - ジョブステップ取得
- New-DbaAgentJobStep - ジョブステップ作成
- Set-DbaAgentJob - ジョブ設定変更
- Start-DbaAgentJob - ジョブ開始
- Stop-DbaAgentJob - ジョブ停止
- Get-DbaAgentJobHistory - ジョブ履歴取得
- New-DbaAgentJobCategory - ジョブカテゴリ作成
- Get-DbaAgentSchedule - スケジュール取得
