# 画面設計書 183-KB更新

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるMicrosoft KB更新情報の取得・ダウンロード機能の設計を定義する。

### 本画面の処理概要

Microsoft更新カタログWebサイトを検索して、サービスパック、ホットフィックス、累積更新プログラムなどのKB更新に関する包括的な情報を取得する。サポート対象製品、アーキテクチャ、言語、ファイルサイズ、置き換え情報、直接ダウンロードリンクなどの詳細メタデータを返す。

**業務上の目的・背景**：データベース管理者はSQL Serverパッチの詳細情報を把握し、オフラインインストールのためにパッチファイルをローカルに保存する必要がある。この機能により、MicrosoftのWebサイトを手動で検索することなく、パッチ情報の取得とダウンロードを自動化できる。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行する：
- `Get-DbaKbUpdate` - KB更新情報の取得
- `Save-DbaKbUpdate` - KB更新ファイルのダウンロード

**主要な操作・処理内容**：
1. Microsoft更新カタログサイトへHTTPリクエストを送信
2. KB番号に基づいて検索結果をパース
3. 各更新のダウンロードダイアログから詳細情報を抽出
4. Get-DbaBuildと連携してSQL Serverバージョン情報を補完
5. 更新ファイルをローカルファイルシステムにダウンロード

**画面遷移**：単独のCLIコマンド群として動作。Get-DbaKbUpdateの出力をSave-DbaKbUpdateにパイプライン入力可能。

**権限による表示制御**：インターネットアクセスが必要。プロキシ環境ではシステムプロキシ設定を自動使用。ファイル保存には書き込み権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 127 | Get-DbaKbUpdate | 主機能 | KB更新情報の取得 |
| 215 | Save-DbaKbUpdate | 補助機能 | KB更新の保存 |

## 画面種別

コマンドラインインターフェース（CLI）

## URL/ルーティング

PowerShellコマンド:
- `Get-DbaKbUpdate`
- `Save-DbaKbUpdate`

## 入出力項目

### Get-DbaKbUpdate パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Name | string[] | Yes | KB記事番号（KBプレフィックス有無どちらも可） |
| Simple | switch | No | 基本情報のみ取得（高速化） |
| Language | string | No | 言語フィルタ（例: "en", "ja"） |
| EnableException | switch | No | 例外を有効にするフラグ |

### Save-DbaKbUpdate パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Name | string[] | No | ダウンロードするKB番号 |
| Path | string | No | 保存先ディレクトリ（デフォルト: カレントディレクトリ） |
| FilePath | string | No | 保存ファイルパス（カスタムファイル名指定） |
| Architecture | string | No | アーキテクチャフィルタ（x64/x86/ia64/All、デフォルト: x64） |
| Language | string | No | 言語フィルタ（3文字コード） |
| InputObject | object[] | No | Get-DbaKbUpdateからのパイプライン入力 |
| EnableException | switch | No | 例外を有効にするフラグ |

## 表示項目

### Get-DbaKbUpdate 出力（フル）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Title | string | KB更新のタイトル |
| NameLevel | string | SQL Server製品名 |
| SPLevel | string | サービスパックレベル |
| KBLevel | string | KB記事番号 |
| CULevel | string | 累積更新レベル |
| BuildLevel | version | ビルドバージョン |
| SupportedUntil | DateTime | サポート終了日 |
| Architecture | string | CPUアーキテクチャ（x64/x86/ARM64） |
| Language | string | 言語識別子 |
| Hotfix | string | ホットフィックスフラグ |
| Description | string | 更新の説明 |
| LastModified | string | 最終更新日 |
| Size | string | ファイルサイズ |
| Classification | string | 分類（Critical/Important等） |
| SupportedProducts | string[] | サポート製品一覧 |
| MSRCNumber | string | MSRCセキュリティ情報番号 |
| MSRCSeverity | string | MSRC重大度 |
| RebootBehavior | string | 再起動要件 |
| RequestsUserInput | string | ユーザー入力要求フラグ |
| ExclusiveInstall | string | 排他インストールフラグ |
| NetworkRequired | string | ネットワーク要件フラグ |
| UninstallNotes | string | アンインストール注意事項 |
| UninstallSteps | string | アンインストール手順 |
| UpdateId | string | Microsoft更新カタログGUID |
| Supersedes | string[] | この更新が置き換える更新一覧 |
| SupersededBy | string[] | この更新を置き換える更新一覧 |
| Link | string | 直接ダウンロードURL |

### Get-DbaKbUpdate 出力（-Simple指定時）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Title | string | KB更新のタイトル |
| Architecture | string | CPUアーキテクチャ |
| Language | string | 言語識別子 |
| Hotfix | string | ホットフィックスフラグ |
| UpdateId | string | 更新カタログGUID |
| Link | string | 直接ダウンロードURL |

### Save-DbaKbUpdate 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (FileInfo) | System.IO.FileInfo | ダウンロードしたファイルのFileInfoオブジェクト |

## イベント仕様

### 1-KB情報取得（Get-DbaKbUpdate）

1. KB番号からKBプレフィックスを正規化
2. Microsoft更新カタログサイトに検索リクエスト送信
3. 検索結果からダウンロードボタンIDを抽出
4. 各更新についてダウンロードダイアログを取得
5. HTMLパースで各種メタデータを抽出
6. -Simpleでない場合は詳細ダイアログも取得
7. Get-DbaBuildでSQL Serverバージョン情報を補完
8. 結果オブジェクトを出力

### 2-KBファイルダウンロード（Save-DbaKbUpdate）

1. KB名が指定された場合はGet-DbaKbUpdateを呼び出し
2. アーキテクチャと言語でリンクをフィルタリング
3. BITSまたはInvoke-TlsWebRequestでファイルダウンロード
4. 保存ファイルのFileInfoオブジェクトを返却

## データベース更新仕様

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

この機能はデータベースへの更新操作を行わない。Microsoft更新カタログサイトの読み取りとファイルダウンロードのみ。

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| KB情報取得 | Microsoft更新カタログ | HTTP GET | Web検索とメタデータ取得 |
| ファイルダウンロード | ローカルファイルシステム | ファイル書き込み | 更新パッケージの保存 |

## メッセージ仕様

| 種別 | メッセージ | 発生条件 |
|------|----------|---------|
| Warning | No results found for {Name} | KB番号の検索結果がない場合 |
| Warning | The response from the webserver did not include the expected information | Webサーバーからの応答が不完全な場合 |
| Error | You can only specify one KB when using FilePath | FilePath使用時に複数KB指定 |
| Error | You can only specify one Architecture when using FilePath | FilePath使用時にArchitecture=All指定 |
| Error | You must specify a KB name or pipe in results | KB名もパイプライン入力もない場合 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| Web接続エラー | Stop-Functionでエラーメッセージを表示 |
| KB番号不正 | 警告メッセージを表示して継続 |
| ダウンロード失敗 | Stop-Functionでエラーメッセージを表示 |

## 備考

- Microsoft更新カタログにはAPIが提供されていないため、Webページのスクレイピングを使用
- 複数のWebページをパースするため処理が遅くなる場合がある
- -Simpleスイッチで詳細スクレイピングをスキップして高速化可能
- BITSTransferが利用可能な場合は優先使用される

---

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

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

### 推奨読解順序

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

出力オブジェクトのプロパティ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaKbUpdate.ps1 | `public/Get-DbaKbUpdate.ps1` | $basepropertiesで定義される出力プロパティ一覧（行199-225） |

**読解のコツ**: $basepropertiesの配列がフル出力のプロパティセットを定義している。

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

Get-DbaKbUpdate関数のWeb スクレイピング処理を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaKbUpdate.ps1 | `public/Get-DbaKbUpdate.ps1` | Invoke-KbTlsWebRequest、HTMLパース、Get-Info関数 |

**主要処理フロー**:
1. **行121-156**: Invoke-KbTlsWebRequest内部関数（TLS/プロキシ対応Webリクエスト）
2. **行159-161**: Webセッション初期化
3. **行163-197**: Get-Info/Get-SuperInfo内部関数（HTMLパース）
4. **行233**: 更新カタログ検索リクエスト
5. **行235-249**: ダウンロードボタンIDとGUID抽出
6. **行253-311**: 各更新の詳細情報取得（ダウンロードダイアログとScopedViewInline）
7. **行315-356**: 結果オブジェクト構築

#### Step 3: ファイルダウンロード機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Save-DbaKbUpdate.ps1 | `public/Save-DbaKbUpdate.ps1` | パラメータ検証、アーキテクチャ/言語フィルタ、ダウンロード処理 |

**主要処理フロー**:
- **行110-123**: パラメータ相互排他検証
- **行125-127**: KB名からGet-DbaKbUpdate呼び出し
- **行129-135**: アーキテクチャと言語でフィルタリング
- **行144-150**: BITS優先、フォールバックでInvoke-TlsWebRequest

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

```
Get-DbaKbUpdate (public/Get-DbaKbUpdate.ps1)
    │
    ├─ Invoke-KbTlsWebRequest (内部関数)
    │      └─ Invoke-WebRequest (TLS/プロキシ対応)
    │
    ├─ Get-Info / Get-SuperInfo (内部関数)
    │      └─ HTMLテキストパース
    │
    └─ Get-DbaBuild (SQL Serverバージョン情報補完)

Save-DbaKbUpdate (public/Save-DbaKbUpdate.ps1)
    │
    ├─ Get-DbaKbUpdate (KB情報取得)
    │
    ├─ Start-BitsTransfer (利用可能な場合)
    │
    └─ Invoke-TlsWebRequest (フォールバック)
```

### データフロー図

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

KB番号 ──────────────────▶ Invoke-KbTlsWebRequest
                                    │
                                    ▼
                           catalog.update.microsoft.com
                           /Search.aspx?q=KB{番号}
                                    │
                                    ▼
                           ダウンロードボタンID抽出
                           (InputFields解析)
                                    │
                                    ▼
                           /DownloadDialog.aspx
                           (POST: updateIDs)
                                    │
                                    ▼
                           HTMLパース
                           (enTitle, architectures, longLanguages...)
                                    │
                           ┌───────┴───────┐
                           │               │
                    -Simple指定        詳細取得
                           │               │
                           │               ▼
                           │     /ScopedViewInline.aspx
                           │     (Description, Size, Classification...)
                           │               │
                           └───────┬───────┘
                                    │
                                    ▼
                           Get-DbaBuild (KB番号)
                                    │
                                    ▼
                           [PSCustomObject]
                           ├─ Title
                           ├─ NameLevel, SPLevel, CULevel
                           ├─ Architecture, Language
                           ├─ Description, Size, Classification
                           ├─ Supersedes, SupersededBy
                           └─ Link (ダウンロードURL)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaKbUpdate.ps1 | `public/Get-DbaKbUpdate.ps1` | ソース | KB情報取得メイン関数 |
| Save-DbaKbUpdate.ps1 | `public/Save-DbaKbUpdate.ps1` | ソース | KBファイルダウンロード |
| Get-DbaBuild.ps1 | `public/Get-DbaBuild.ps1` | ソース | SQL Serverバージョン情報補完 |
