MENU

Azure REST API更新：Microsoft.DBforPostgreSQL 2026-04-01-previewの変更点と確認手順

Azure

2026年5月2日に公開または更新された「Microsoft.DBforPostgreSQL の 2026-04-01-preview 追加レビュー」は、Azure REST APIを使ってAzure Database for PostgreSQLを管理しているチームにとって、今すぐ本番APIを切り替える話ではなく、プレビューAPIで追加される管理機能を先に確認するべき更新です。

特に確認すべきポイントは、Azure Database for PostgreSQL Flexible Server向けに、メンテナンスイベントの取得・延期・即時適用、メジャーバージョンアップグレードの事前チェック、マルチテナントMicrosoft Entraアプリケーション関連の暗号化プロパティ、immutable backup関連プロパティが追加される点です。PR自体は既存リソースプロバイダーに対する新しいAPIバージョン追加として提出されており、ARM、resource-manager、new-api-version、PostgreSQL、TypeSpecなどのラベルが付いています。執筆時点でPRはOpenで、ARMChangesRequestedやSuppressionReviewRequiredのラベルも残っているため、GA済みの安定版APIとして扱うのは避けるべきです。(GitHub)

目次

Azure REST APIで何が変わるのか

今回の更新は、Azure REST APIのうち、Azure Database for PostgreSQLを管理するMicrosoft.DBforPostgreSQLのARMコントロールプレーンAPI仕様に、2026-04-01-previewという新しいプレビューAPIバージョンを追加するレビューリクエストです。PRの説明では、対象がデータプレーンではなくARM関連仕様であること、新しいリソースプロバイダーではなく既存リソースプロバイダーの新APIバージョンであることが示されています。(GitHub)

大きな変更点は次のとおりです。

変更点主な対象実務上の意味
2026-04-01-previewの追加API versionプレビュー機能をREST APIやAzAPIで検証できる可能性がある
MaintenanceEvent APIの追加Flexible Serverのメンテナンス管理予定メンテナンスの一覧取得、詳細取得、延期、即時適用をAPIから扱える
MajorVersionUpgradePrecheck APIの追加メジャーバージョンアップグレードPostgreSQLのメジャーバージョンアップ前に、失敗要因をAPIで確認しやすくなる
Servers APIへの新アクション追加majorVersionUpgradePrecheckサーバー単位でアップグレード事前チェックを開始できる
Microsoft Entra関連プロパティの追加dataEncryptionマルチテナントMicrosoft Entraアプリケーションを使う暗号化構成を確認する必要がある
immutable backupプロパティの追加backupバックアップの不変性に関わる設定項目がAPIモデルに追加される

PR説明の「Additional information」では、新APIバージョンの導入、MaintenanceEvent APIの追加、MajorVersionUpgradePrecheck APIの追加、Servers APIへのMajorVersionUpgradePrecheck操作追加、マルチテナントMicrosoft Entraアプリケーション用プロパティ追加、immutable backup用プロパティ追加が明記されています。(GitHub)

まず押さえるべき前提：これはプレビューAPIであり、既存の本番APIを置き換えるものではない

Azure REST APIでは、呼び出し時のapi-versionが非常に重要です。同じリソースを操作していても、指定するAPIバージョンによって使えるプロパティや操作、レスポンス形式が変わることがあります。

Microsoft LearnのAzure Database for PostgreSQL REST APIページでは、一般提供済み機能を使う場合は2025-08-01などの最新安定版APIを、まだ一般提供されていない機能を使う場合は2026-01-01-previewなどのプレビューAPIを使う考え方が示されています。(Microsoft Learn)

今回の2026-04-01-previewは、安定版APIに全面移行するための更新ではありません。判断基準は次のように分けると安全です。

利用状況推奨される判断
既存の本番運用でPostgreSQL Flexible Serverを作成・更新しているいきなりapi-versionを置き換えない
MaintenanceEvent APIを運用自動化に組み込みたい検証環境でプレビューAPIとして試す
メジャーバージョンアップ前のチェックを自動化したいAPIのレスポンス設計と失敗時の運用フローを先に確認する
TerraformのAzureRM provider中心で管理しているprovider対応を待つか、検証用途でAzAPI利用を検討する
独自コードでREST APIレスポンスを厳密にパースしている新プロパティ追加でパーサーや型定義が壊れないか確認する

Azure Database for PostgreSQLのAPIリリースノートでは、安定版とプレビュー版のAPIバージョンは累積的で、以前の機能に加えて新しい機能を含む考え方が説明されています。また、AzureRM Terraform providerで未対応のプレビューAPI機能を扱う場合は、Azure Resource Manager REST APIを任意のAPIバージョンで呼び出せるAzAPI providerが補完手段になることも説明されています。(Microsoft Learn)

対応すべき読者は誰か

今回のAzure REST API更新で特に確認すべきなのは、Azure Database for PostgreSQLを手作業ではなくコードで管理しているチームです。

立場確認すべきこと
Azure運用担当者メンテナンスイベントの確認・延期・即時適用を運用手順に組み込めるか
DBA / SREメジャーバージョンアップ前のPrecheck結果を、移行判断や障害予防に使えるか
IaC担当者ARMテンプレート、Bicep、Terraform AzAPIでapi-versionを固定している箇所
アプリ開発者自動化スクリプトや社内ツールが新しいレスポンス項目に耐えられるか
セキュリティ・監査担当immutable backupやMicrosoft Entra関連プロパティの意味を確認する必要があるか
SDK・APIクライアント保守担当OpenAPI仕様更新後に生成コードや型定義へ影響が出るか

逆に、Azure PortalだけでPostgreSQL Flexible Serverを管理しており、REST APIやIaCを直接使っていない場合、急ぎの作業は多くありません。ただし、メジャーバージョンアップやメンテナンス調整の運用ルールに関わるため、DBAや運用責任者は概要だけでも把握しておく価値があります。

MaintenanceEvent APIで確認できるようになること

今回の注目点の一つが、MaintenanceEvent APIです。PRで追加された例では、サーバー単位でメンテナンスイベントを一覧取得し、イベントID、メンテナンス種別、ステータス、開始時刻、終了時刻、推定ダウンタイム、延期可否、延期期限などを確認できる構成になっています。(GitHub)

MaintenanceEvent APIの主な操作は次のとおりです。

操作目的運用での使いどころ
List by Serverサーバーのメンテナンスイベント一覧を取得影響を受けるサーバーを自動収集する
Get特定メンテナンスイベントの詳細を取得イベントID単位で開始・終了時刻を確認する
Rescheduleメンテナンスイベントを延期業務ピークやリリース作業と重なる場合に調整する
ApplyNowメンテナンスを即時適用検証環境や早期適用したい環境で使う

例では、maintenanceStatusにUpcomingを指定して予定または進行中のメンテナンスイベントを絞り込むケースも示されています。レスポンスにはPlannedやInProgressといったステータス、deferrable、deferralDeadlineなどが含まれています。(GitHub)

メンテナンス管理で失敗しやすいポイント

MaintenanceEvent APIが使えるようになると、メンテナンス対応を自動化しやすくなります。ただし、APIで取得できる情報をそのまま「延期できる」と判断するのは危険です。

Azure Database for PostgreSQL Flexible Serverのメンテナンスに関するMicrosoft Learnでは、メンテナンス中にサーバー変更、構成変更、開始・停止などの操作を避けるべきとされています。また、通常は5日前に通知されるものの、重大な緊急更新では通知期間が短くなったり省略されたりする可能性があります。(Microsoft Learn)

実務では、次のルールを運用に入れておくと安全です。

確認項目判断基準
deferrabletrueの場合のみ延期候補にする
deferralDeadline延期可能な最終期限を超えない
startTime / endTime日本時間へ変換して業務影響を確認する
estimatedDowntimeアプリケーション側の冗長化・リトライ設計と照合する
statusInProgressになった後の変更操作を避ける
緊急メンテナンス通常の延期・通知ルールが当てはまらない可能性を考慮する

たとえば、APIでdeferrable: trueが返ってきたとしても、延期先の時刻がアプリのバッチ処理、月次締め、データ移行作業と重なっていれば、別の障害要因になります。自動延期を実装する場合は、単に「次の空き時間へ移す」のではなく、業務カレンダー、DB負荷、監視体制、メンテナンス後の確認時間まで含めて判定するべきです。

MajorVersionUpgradePrecheck APIで確認できるようになること

もう一つの重要な追加が、MajorVersionUpgradePrecheck APIです。PostgreSQLのメジャーバージョンアップは、マイナーバージョンアップよりも互換性リスクが高く、拡張機能、レプリケーション、ビュー依存、認証方式、ストレージ空き容量などが失敗要因になります。

Microsoft Learnでは、Azure Database for PostgreSQL Flexible Serverのメジャーバージョンアップ時にPrecheckが実行され、互換性問題が見つかるとアップグレードがブロックされること、アップグレード前に10〜20%程度の空きストレージを確保すること、論理レプリケーションスロットや一部の拡張機能がブロック要因になり得ることが説明されています。(Microsoft Learn)

PRの例では、サーバーに対してtargetVersionを指定してPrecheckを作成し、202の非同期レスポンスまたは200の結果を受け取る形が示されています。たとえば、targetVersionに18を指定する例があります。(GitHub)

Precheck結果の取得例では、次のような情報が返る構成です。

レスポンス項目意味
statusPrecheckの実行状態や結果
targetVersionアップグレード先のPostgreSQLメジャーバージョン
precheckResult.upgradeSequenceアップグレード元・先のバージョン
precheckResult.errorInfoエラーコードと関連パラメーター
policyDetails各チェックポリシーの合否、エラーコード、説明

例では、NoViewDependentObjectsPrecheckPolicyがpassed: falseとなり、ビュー依存オブジェクトがあるためアップグレード前に対応が必要なケースが示されています。(GitHub)

Precheck APIを運用に組み込む手順

Precheck APIは「アップグレード直前に一度だけ実行する」よりも、計画段階から繰り返し実行するほうが役立ちます。

タイミング実施内容
1〜2か月前対象サーバー一覧を作り、アップグレード候補バージョンを決める
1か月前Precheckを実行し、失敗ポリシーを一覧化する
2〜3週間前拡張機能、ビュー依存、レプリケーションスロット、認証方式を修正する
1週間前再度Precheckを実行し、残課題がないか確認する
実施直前メンテナンス時間、バックアップ、監視、ロールバック方針を確認する
実施後ANALYZEや性能確認、アプリ接続確認を実施する

失敗しやすいのは、Precheckのstatusだけを見て、policyDetailsを読まないケースです。statusが成功に見えても、ポリシーごとの詳細に警告や修正対象が含まれる可能性があります。運用自動化では、policyDetails[].passed、errorCode、errorMessageを監視・チケット化する設計にしておくと、DBAとアプリ担当の分担が明確になります。

非同期操作への対応が必要になる

MaintenanceEventsのRescheduleやApplyNow、MajorVersionUpgradePrecheckの作成例では、202レスポンスとLocation、Azure-AsyncOperation、Retry-Afterヘッダーを使う非同期操作の例が示されています。(GitHub)

つまり、自動化スクリプトでは「POSTしたらすぐ完了」と考えないほうが安全です。

実装時は次のように処理します。

1. POSTで操作を開始する
2. 202が返った場合はAzure-AsyncOperationまたはLocationを保存する
3. Retry-Afterがある場合は指定秒数を待つ
4. 操作結果をポーリングする
5. 成功、失敗、タイムアウトを分けてログに残す
6. 失敗時はイベントID、サーバーID、レスポンス本文、x-ms-request-idを保存する

特にメンテナンス操作は、途中で失敗した場合の影響が大きくなります。自動化する場合は、成功時だけでなく、Acceptedのまま進まない、タイムアウトする、メンテナンス状態が変わる、対象イベントが消える、といった異常系を必ずテストしてください。

immutable backupプロパティ追加で確認すべきこと

今回のTypeSpecモデルでは、BackupにimmutableBackupプロパティが追加されています。値はEnabledまたはDisabledで、既定値としてDisabledが示されています。(GitHub)

ここで注意したいのは、API仕様にプロパティが追加されたことと、実際のサービス上でどのリージョン・どの条件で有効化できるかは別問題だという点です。バックアップの不変性は、監査、ランサムウェア対策、削除防止、復旧手順に関わる重要な設定です。名称だけを見て本番に適用するのは避けるべきです。

確認すべき観点は次のとおりです。

観点確認内容
有効化条件対象リージョン、サーバー構成、バックアップ設定との組み合わせ
変更可否有効化後に無効化できるか、保持期間変更に制限があるか
コンプライアンス社内の保存期間、削除ポリシー、監査要件と矛盾しないか
復旧手順PITR、GeoRestore、LTRなど既存の復旧設計と整合するか
IaC管理ARM/Bicep/Terraformで差分検出されるか

特にIaCでサーバーを管理している場合、既存テンプレートにbackupブロックを追加するだけで、意図しない差分や再作成リスクが発生しないか確認してください。プレビューAPIでは、プロパティの意味や制約が今後変わる可能性があるため、検証環境でレスポンスと実際の挙動を照合することが重要です。

Microsoft Entraとデータ暗号化関連の追加プロパティ

DataEncryptionモデルには、マルチテナントMicrosoft EntraアプリケーションのクライアントIDに関するprimaryFederatedIdentityClientIdとgeoBackupFederatedIdentityClientIdが追加されています。前者はプライマリ側、後者はgeo backup構成時のMicrosoft Entraアプリケーションに関する項目です。(GitHub)

この変更は、カスタマー管理キー、ユーザー割り当てマネージドID、Microsoft Entraアプリケーション、geo redundant backupを組み合わせている環境で特に重要です。

確認すべきポイントは次のとおりです。

確認項目理由
primaryUserAssignedIdentityIdKey VaultへアクセスするIDと整合しているか
geoBackupUserAssignedIdentityIdgeo backup側の暗号化に必要なIDが設定されているか
primaryFederatedIdentityClientIdマルチテナントEntraアプリを使う場合の主系クライアントID
geoBackupFederatedIdentityClientIdgeo backup構成時のクライアントID
Key Vault権限キー読み取り、ラップ、アンラップなど必要権限があるか
テナント境界運用テナント、委任先テナント、監査責任が整理されているか

暗号化まわりの設定は、API呼び出しが成功しても実際の復旧やgeo backup時に問題が出ることがあります。設定値だけでなく、フェイルオーバー、復旧、キー無効化時の動作まで検証するのが安全です。

既存コードへの影響範囲

今回の更新で、既存の安定版APIを使い続ける限り、すぐに既存コードが壊れるとは限りません。ただし、次のような実装では注意が必要です。

api-versionを一括置換している

最も危険なのは、全API呼び出しのapi-versionをまとめて2026-04-01-previewへ置き換えることです。

Azure REST APIはAPIバージョン単位で契約が変わるため、プレビューAPIへ一括移行すると、レスポンス項目、非同期操作、エラー形式、サンプルと実環境の差異で問題が出る可能性があります。まずは新機能を使うAPI呼び出しだけを個別に切り替えてください。

JSONレスポンスを厳密に型チェックしている

独自クライアントや社内ツールで、レスポンスに未知のプロパティがあるとエラーになる実装は要注意です。

たとえば、ServerのbackupやdataEncryptionに新しいプロパティが追加されると、厳密なスキーマ検証や生成モデルのデシリアライズで失敗する可能性があります。APIクライアントは、基本的に未知フィールドを無視できる設計にしておくと、Azure REST APIの将来更新に強くなります。

メンテナンス操作を即時完了前提にしている

ApplyNowやRescheduleは、例の上では200だけでなく202も返り得ます。202 Acceptedを「成功完了」と誤解すると、実際にはまだ処理中なのに後続作業を始めてしまう可能性があります。(GitHub)

Precheck結果を単純な成功・失敗だけで見ている

メジャーバージョンアップ前のPrecheckは、単なるバイナリ判定ではなく、ポリシーごとの詳細確認が重要です。例では、拡張機能、レプリケーションスロット、ビュー依存、prepared transaction、pending restart settings、event trigger、search_pathなど、複数のポリシー観点が含まれています。(GitHub)

移行・設定確認の実務チェックリスト

今回のAzure REST API更新を受けて、現場では次の順で確認すると無駄がありません。

手順作業完了条件
1現在使っているAPIバージョンを棚卸しする2025-08-01、2026-01-01-previewなどの利用箇所が分かる
2Microsoft.DBforPostgreSQLを呼ぶスクリプトを洗い出すREST、AzAPI、Bicep、ARM、社内ツールを含めて一覧化する
3新機能を使う必要があるか判断するMaintenanceEvent、Precheck、immutable backup、Entra暗号化の要否が明確
4検証環境で2026-04-01-previewを試すレスポンス、非同期操作、エラー処理を確認済み
5JSONパーサーと型定義を確認する未知プロパティで落ちない
6運用手順に組み込むメンテナンス延期、即時適用、Precheck失敗時の判断基準がある
7本番適用判断を分けるプレビューAPI利用範囲が限定されている

特に重要なのは、APIの移行を「バージョン番号の更新作業」として扱わないことです。今回の更新は、メンテナンス、バックアップ、暗号化、メジャーバージョンアップという、運用リスクの高い領域に関わります。変更の影響はアプリコードだけでなく、監視、障害対応、監査、変更管理にも及びます。

検証用のREST API呼び出し例

実際に利用可能になった環境で確認する場合は、まずaz restなどでサーバー単位の情報取得から始めると安全です。以下は構成を確認するための例です。実行前に、対象サブスクリプション、リソースグループ、サーバー名、権限を必ず確認してください。

メンテナンスイベント一覧を確認する

az rest \
  --method get \
  --url "https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DBforPostgreSQL/flexibleServers/{serverName}/maintenanceEvents?api-version=2026-04-01-preview"

確認する項目は、status、startTime、endTime、estimatedDowntime、deferrable、deferralDeadlineです。延期可能かどうかだけでなく、業務影響と監視体制をセットで判断してください。

メジャーバージョンアップのPrecheckを開始する

az rest \
  --method post \
  --url "https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DBforPostgreSQL/flexibleServers/{serverName}/majorVersionUpgradePrecheck?api-version=2026-04-01-preview" \
  --body '{"targetVersion":"18"}'

例では、Precheck作成時にtargetVersionを指定し、レスポンスとしてname、createTime、statusが返る構成になっています。非同期レスポンスが返る場合は、Azure-AsyncOperationやLocationを使って結果を追跡します。(GitHub)

Precheck結果を取得する

az rest \
  --method get \
  --url "https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DBforPostgreSQL/flexibleServers/{serverName}/majorVersionUpgradePrecheck/{precheckValidationId}?api-version=2026-04-01-preview"

取得後は、statusだけでなくpolicyDetailsを必ず確認します。passed: falseのポリシーがあれば、エラーコード、エラーメッセージ、対象オブジェクトをチケット化し、DBAまたはアプリ担当へ割り当てるのが現実的です。

本番適用前に決めておくべき運用ルール

プレビューAPIを本番運用に近い環境で使う場合は、次のルールを先に決めておくとトラブルを避けやすくなります。

ルール理由
APIバージョンは機能単位で固定する全APIを一括でプレビューへ移行しない
重要操作は手動承認を挟むメンテナンス即時適用や延期は業務影響が大きい
202レスポンスを必ずポーリングする非同期操作の途中状態を誤判定しない
Precheck結果はポリシー単位で保存する再実行時の差分や原因追跡に使える
UTCと日本時間を併記するメンテナンス時刻の誤読を防ぐ
監査ログにリクエストIDを残すAzureサポート問い合わせや原因調査に必要
プレビューAPIの利用範囲を文書化する将来のGA版移行時に差分確認しやすい

今回の更新で「すぐやるべきこと」

今回のAzure REST API更新は、PostgreSQL Flexible Serverの運用をより細かく自動化できる可能性がある一方、プレビューAPIであること、PRがレビュー中であること、メンテナンスやアップグレードといった重要操作に関わることから、慎重な確認が必要です。

まず実施すべきことは、既存のMicrosoft.DBforPostgreSQL API利用箇所を棚卸しし、api-versionを固定している場所を把握することです。そのうえで、メンテナンスイベント管理、メジャーバージョンアップPrecheck、immutable backup、Microsoft Entra連携のどれが自社運用に関係するかを切り分けます。

本番環境では、安定版APIを維持しながら、新機能が必要な箇所だけ検証環境で2026-04-01-previewを試すのが安全です。特に、Precheck APIはメジャーバージョンアップ計画の早い段階で使う価値があります。失敗ポリシーを早めに見つけ、DB設計、拡張機能、ビュー依存、レプリケーション、認証方式の修正に時間を確保できるからです。

最終的には、「新しいAPIが出たから切り替える」ではなく、「運用上のリスクを下げるために、どのAPIをどの範囲で使うか」を決めることが重要です。

Azure
PostgreSQL Azure Database for PostgreSQL Azure REST API Microsoft.DBforPostgreSQL API version

この記事を書いた人

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

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

関連記事

コメント

コメントする

目次