MENU

Azure REST API documentation updateで確認すべきSQL VA例の表記変更

Azure

Azure REST API documentation updateで今回確認すべきポイントは、SQL Vulnerability Assessmentsの2026-04-01-previewに含まれるサンプル名が、従来の(server-level)から(using databaseName parameter)へ改名されたことです。結論から言うと、通常のREST API呼び出しそのものを大きく移行する変更ではなく、「サーバーレベル」という曖昧な表現を避け、親リソースに対して呼び出す場合はdatabaseNameクエリパラメーターで対象DBを指定する、という意図を明確にするドキュメント・仕様例の更新です。PRは2026年4月16日にマージされ、2026年5月5日にGo、Java、.NET向けSDK生成の再実行が依頼されています。(GitHub)

この変更で注意すべきなのは、APIのエンドポイントを見直す人よりも、サンプル名、x-ms-examples、生成ドキュメント、SDK生成、テストのスナップショットを参照している人です。特に「server-levelだからデータベース名は不要」と誤解していた運用手順がある場合は、databaseNameの扱いを確認してください。

目次

Azure REST API documentation updateで何が変わったか

今回のAzure REST API documentation updateは、Azure REST API仕様リポジトリのMicrosoft.Security配下にあるSQL Vulnerability Assessments関連のサンプル名を変更するものです。PR説明では、SQL Vulnerability Assessments 2026-04-01-preview API specsにおいて、x-ms-examples名を(server-level)から(using databaseName parameter)へ改名し、分かりやすさを改善すると説明されています。(GitHub)

確認項目変更前変更後実務上の意味
サンプル名の表現(server-level)(using databaseName parameter)「サーバー単位の操作」ではなく、親リソースに対してdatabaseNameを付けて対象DBを指定する例だと分かる
対象APIバージョン2026-04-01-preview2026-04-01-preview既存の安定版API全体に一律適用された変更ではない
変更対象x-ms-examplesの表示名表示名の明確化RESTパスやレスポンスモデルの破壊的変更とは読み取らない
注意点ServerLevel_...jsonという例ファイル名が残る箇所がある表示名だけが変更されているファイル名や$refまで機械的に置換しない

PRの差分では、sqlVulnerabilityAssessmentsBaselineRuleOperations.json、sqlVulnerabilityAssessmentsScanOperations.json、sqlVulnerabilityAssessmentsScanResultsOperations.jsonの3ファイルが対象になっています。GitHub上の差分では、Baseline Ruleで15件、Scanで12件、Scan Resultsで6件の名称変更が確認できます。(GitHub)

影響を受けるSQL Vulnerability Assessmentsの操作

今回の変更は、SQL Vulnerability Assessments、つまりSQL VAのスキャン、スキャン結果、ベースラインルールの例に関係します。対象サービスはDefender for CloudのREST APIで、管理プレーンのmanagement.azure.comに対する操作です。PRのチェックリストでも、これはARM、つまりAzure Resource Manager関連仕様の変更であり、データプレーンAPIではないことが示されています。(GitHub)

操作グループ影響を受ける主な操作確認すべきポイント
Baseline RulesCreate、Get、Delete、List、Setベースライン設定・取得・削除・一覧・一括設定のサンプル名が変更対象
ScansGet、List、Initiate Scan、Get Scan Operation Resultスキャン開始やスキャン履歴確認時に、親リソース呼び出しとDBリソース呼び出しを混同しない
Scan ResultsGet、Listスキャン結果取得時にscanIdとdatabaseNameの両方が必要になるケースを確認する

対象リソースの例としては、Azure SQL Server、Azure SQL Managed Instance、Azure Synapseが含まれます。Virtual MachineやArc Machineの例もドキュメント内にはありますが、今回のリネームの中心は、親リソースに対してdatabaseNameを付けるSQL Server、SQL Managed Instance、Synapseのサンプルです。(Microsoft Learn)

「server-level」ではなくdatabaseNameを意識すべき理由

従来の(server-level)という表現は、実務では誤解を招きやすい表現でした。SQL VAは最終的にはデータベースを評価するため、親リソースに対してAPIを呼び出す場合でも、どのデータベースを評価するかを指定する必要があります。

Microsoft Learnの2026-04-01-previewドキュメントでは、databaseNameは「親リソース、たとえばサーバーレベルでAPIを呼び出す場合に必要」と説明されています。理由は、親リソースのURIにはデータベース名が含まれないためです。また、masterなどURI上で直接参照できないシステムデータベースを評価する方法としても説明されています。(Microsoft Learn)

親リソースに対して呼び出す例

このパターンでは、URIに/databases/{databaseName}がありません。そのため、クエリ文字列でdatabaseName=masterのように指定します。

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Sql/servers/{serverName}/providers/Microsoft.Security/sqlVulnerabilityAssessments/default/scans/initiateScan?api-version=2026-04-01-preview&databaseName=master

Microsoft LearnのInitiate Scanページでも、SQL Server、SQL Managed Instance、Synapseの親リソースに対してdatabaseName=masterを付けるサンプルが示されています。(Microsoft Learn)

データベースリソースに対して呼び出す例

一方、URIに/databases/{databaseName}が含まれる場合は、データベース名はリソースID側に含まれています。この場合、同じ目的の操作でもdatabaseNameクエリパラメーターを付けない例になります。

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Sql/servers/{serverName}/databases/{databaseName}/providers/Microsoft.Security/sqlVulnerabilityAssessments/default/scans/initiateScan?api-version=2026-04-01-preview

つまり、今回の名称変更は「サーバーレベルでまとめて何かをする」ことを強調するものではありません。正しくは、「親リソースを起点に呼び出すが、評価対象DBはdatabaseNameで指定する」ことを明確にする変更です。

誰が対応すべきか

この更新は、全利用者が急いでコードを書き換えるタイプの変更ではありません。ただし、次のような立場の人は確認した方が安全です。

対象者対応優先度確認内容
REST APIを直接呼び出す開発者中親リソースURIを使う呼び出しでdatabaseNameを正しく指定しているか
SDK生成やコード生成を管理する担当者高x-ms-examples名の変更で生成ドキュメント、サンプル一覧、スナップショットテストが壊れないか
セキュリティ運用・監査担当者中手順書の「server-level」という表現が、DB名不要という誤解を生まないか
IaCやCI/CDでAPI仕様を検証している担当者中OpenAPI/Swaggerの例名を文字列一致で参照していないか
単にAzureポータルからSQL VAを使う利用者低直接的な作業は少ないが、REST API連携がある場合は担当者に確認する

PR上では、マージ時点でGo、JavaScript、Java、Python向けのAPIレビューが作成され、2026年5月5日にはGo、Java、.NETのSDK生成PRが開かれていなかったため、SDK生成の再実行が依頼されています。SDKや生成物に依存するチームは、該当言語のパッケージ更新や生成PRの状態を別途確認しておくとよいでしょう。(GitHub)

移行・設定確認で見るべきポイント

まず、既存コードを一括置換する前に、何を参照しているかを切り分けます。今回変わったのは主にサンプル名です。REST APIの実行URL、api-version、リクエストボディ、レスポンスモデルが変更されたと決めつけて修正すると、逆に動作確認コストが増えます。

既存リポジトリで検索する文字列

仕様ファイル、社内手順書、テストコード、SDK生成ログを対象に、次のような文字列を検索します。

rg "\(server-level\)"
rg "using databaseName parameter"
rg "databaseName"
rg "sqlVulnerabilityAssessments"

検索結果を見たら、次のように分類してください。

見つかった場所判断
ドキュメント本文や手順書using databaseName parameterの意図が伝わる表現に更新する
テストの期待値サンプル名の変更だけで失敗していないか確認する
API呼び出しURL親リソースURIならdatabaseNameが必要か確認する
例ファイル名や$refPRで変わっていない箇所まで無理に改名しない
監査・証跡のログ名表示名変更による検索条件のズレに注意する

親リソース呼び出しかDBリソース呼び出しかを見分ける

判断基準はシンプルです。resourceIdに/databases/やSynapseの/sqlPools/など、評価対象のDBまたはSQLプールが含まれているかを見ます。

URIの形databaseNameの考え方
/providers/Microsoft.Sql/servers/{serverName}/providers/Microsoft.Security/...DB名がURIにないため、databaseNameを指定する
/providers/Microsoft.Sql/servers/{serverName}/databases/{databaseName}/providers/Microsoft.Security/...DB名がURIにあるため、通常はクエリで重ねて指定しない
/providers/Microsoft.Sql/managedInstances/{managedInstanceName}/providers/Microsoft.Security/...親リソース呼び出しなのでdatabaseNameを確認する
/providers/Microsoft.Synapse/workspaces/{workspaceName}/providers/Microsoft.Security/...親リソース呼び出しなのでdatabaseNameを確認する
VMやArc Machineで/databases/master/がURIに含まれる例DB名がURIに含まれるパターンとして扱う

この確認を怠ると、masterを評価したかったのにユーザーDBを見ていた、あるいはその逆のような運用ミスにつながります。SQL VAのスキャン結果やベースラインはセキュリティ監査に使われるため、単なる表記ゆれとして流さず、対象DBの指定方法まで確認することが重要です。

Baseline Rulesでは上書き動作にも注意する

今回の変更に直接含まれるBaseline Rules関連操作では、名前の変更だけでなく、操作の性質も理解しておく必要があります。特にAdd、つまりSet baseline rulesの操作は、すでに存在する全ルールの結果を上書きする操作として説明されています。リクエストボディにはlatestScanとresultsがあり、latestScan == trueの場合はresultsを空にできることも示されています。(Microsoft Learn)

このため、サンプル名の変更をきっかけに手順書を更新する場合は、次の点も一緒に確認してください。

確認項目失敗しやすい例対策
対象DBdatabaseName=masterのままコピーして本番の別DBに適用する変数化し、実行前に対象DB名をログ出力する
ベースライン上書き既存ベースラインを意図せず消す実行前に現在のベースラインを取得して保存する
最新スキャン利用latestScan=trueで想定外のスキャン結果を基準にする直近スキャンのscanIdや実行日時を確認する
例名の依存(server-level)でテストや検索条件を組んでいる表示名ではなく操作ID、パス、APIバージョンで識別する

SDKや生成ドキュメントで起きやすい影響

x-ms-examplesの名称変更は、APIを直接叩くコードよりも、生成物に影響しやすい変更です。たとえば、次のようなケースでは小さな差分でも検知されます。

影響箇所起きること対応
SDKサンプル一覧見出し名が変わる新旧名の差分をレビューし、コード生成結果を更新する
ドキュメントのスナップショットテスト期待文字列が一致しない期待値を新名称に更新する
APIViewや生成レビュー例名の変更がAPIレベル差分として表示される実行時APIの変更か、表示名の変更かを切り分ける
社内ナレッジ検索旧名で検索しても新しいページが見つからないserver-levelとdatabaseNameの両方で検索できるようにする

今回のPRでは、APIViewがSwagger、Go、JavaScript、Java、Python向けのAPIレビューを作成したことが記録されています。レビュー上でAPIレベル変更として見える場合でも、差分の中身がサンプル名なのか、パラメーターやモデルの変更なのかを分けて確認することが重要です。(GitHub)

この記事を読んだ後にやること

今回のAzure REST API documentation updateで最初に行うべきことは、REST APIの大規模な書き換えではありません。まず、SQL Vulnerability Assessments 2026-04-01-previewを使っているコード、手順書、生成ドキュメント、テストで(server-level)というサンプル名を参照していないかを確認してください。

次に、親リソースに対する呼び出しでdatabaseNameを正しく指定しているかを見直します。URIにデータベース名が含まれていない場合は、databaseNameが実際の評価対象を決める重要な情報になります。最後に、SDKや生成ドキュメントを使っているチームは、2026年5月5日のSDK生成再実行依頼を踏まえ、該当言語の生成物が最新仕様を反映しているか確認しましょう。(GitHub)

今回の変更は小さく見えますが、SQL VAの運用では「どのDBを評価したか」が監査品質に直結します。server-levelという古い表現に引きずられず、databaseNameで対象を明示する、という観点で手順と自動化を見直すのが実務上の最善策です。

Azure
Defender for Cloud Azure REST API SQL Vulnerability Assessments ARM API

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次