Azure REST APIのFabricMirroringSettings更新とは？Default指定・非同期PUTの注意点

Azure REST APIの「fix: address ARM review comments for FabricMirroringSettings」は、FabricMirroringSettingsを新しく大きく作り替える更新ではなく、Azure Resource Manager（ARM）向けのAPI仕様を実サービスの挙動に合わせて修正する更新です。管理者や開発者がまず確認すべきポイントは、fabricMirroringSettingsName を Default と大文字始まりで扱うこと、state を Enabled にする場合は identityResourceId を指定すること、PUTを非同期操作として処理すること、Listをページング前提で実装しないことです。

このPRは、Azure REST API仕様リポジトリの Microsoft.DBforMySQL/flexibleServers 配下にある FabricMirroringSettings に関する修正で、2026年5月20日に mysql/2025-12-01 ブランチへマージされています。対象APIバージョンは 2025-12-01-preview で、GET、PUT、Listの例やTypeSpec／OpenAPI定義が更新されています。(GitHub)

Azure REST APIのFabricMirroringSettings更新は何が変わるのか

今回の更新は、MySQL Flexible Serverに関連するFabric Mirroring設定のARM API仕様を、レビューコメントと実サービスの動作に合わせて整えるものです。Azure REST APIでは、ARMプロバイダーAPIが https://management.azure.com/ を使い、api-version をクエリ文字列で指定する形式が基本です。(Microsoft Learn)

FabricMirroringSettings は名前に「Fabric」が含まれますが、Microsoft Fabric REST API全般の項目管理APIではなく、Microsoft.DBforMySQL/flexibleServers 配下のAzure管理プレーンAPIとして扱われます。Microsoft Fabric REST APIはFabricプロセスの自動化向けのAPI群として別に整理されています。(Microsoft Learn)

変更点	実務上の意味	確認すべき人
`default` ではなく `Default` を使う	小文字の `default` を送るとサービス側で拒否される可能性がある	REST API実装者、テスト作成者、SDK利用者
`Enabled` 時の `identityResourceId` が明示された	有効化時にユーザー割り当てマネージドIDのリソースIDが必要	Azure管理者、IaC担当者
PUTに `202 Accepted` の非同期レスポンスが追加	200／201だけを成功扱いする実装は失敗しやすい	アプリ開発者、SDK生成担当者
Listが単一ページ前提に変更	`nextLink` やページングを前提にした実装を見直す	SDK利用者、運用自動化担当者
OpenAPI／TypeSpec／サンプルが修正	生成SDKやモック、テストデータに影響する可能性がある	SDK利用者、CI担当者

この差分では、TypeSpecで identityResourceId の説明が「state が Enabled の場合は必須」に更新され、FabricMirroringSettingsName の値が Default に変更されました。また、PUTは実サービスが非同期操作として 202 Accepted を返す挙動に合わせ、ArmAcceptedLroResponse とポーリング用ヘッダーの扱いが追加されています。(GitHub)

変更点の詳細

`fabricMirroringSettingsName` は `Default` を使う

最も分かりやすい変更は、設定名の大文字小文字です。以前の例では default が使われていましたが、今回の修正では fabricMirroringSettingsName、レスポンス内の id、name が Default に統一されています。(GitHub)

誤りやすい例は次の形です。

{
  "fabricMirroringSettingsName": "default"
}

修正後に合わせるなら、次のようにします。

{
  "fabricMirroringSettingsName": "Default"
}

PR上の説明では、サービス側が大文字小文字を区別して名前を検証し、小文字の default は400エラーになる可能性があるとされています。つまり、API仕様書だけでなく、既存の自動化スクリプト、モックサーバー、単体テスト、固定レスポンスのJSONも Default へ更新する必要があります。(GitHub)

`state: Enabled` では `identityResourceId` を指定する

FabricMirroringSettings のPUT例では、properties.state に Enabled を指定し、同時に identityResourceId としてユーザー割り当てマネージドIDのARMリソースIDを渡しています。今回の更新では、identityResourceId の説明に「state が Enabled の場合は必須」という条件が明記されました。(GitHub)

実装時は、リクエストを送る直前に次の条件を検証しておくと安全です。

{
  "properties": {
    "state": "Enabled",
    "identityResourceId": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName>"
  }
}

注意したいのは、identityResourceId がスキーマ上は省略可能に見えても、Enabled のときはサービス側で400エラーになる可能性がある点です。PR上でも、ミラーリングを有効化するPUTリクエストでIDを指定しない場合、サービスが400を返すと説明されています。(GitHub)

PUTは非同期操作として扱う

FabricMirroringSettings_CreateOrUpdate の例では、PUTのレスポンスとして 200、201、202 が示されています。201 では Azure-AsyncOperation と Retry-After、202 では Azure-AsyncOperation と Location が例示されており、リクエスト直後に完了レスポンスだけが返るとは限りません。(GitHub)

Azureの非同期操作では、元のレスポンスヘッダーを見て状態確認用URLを判断します。Microsoftの説明では、Azure-AsyncOperation が返る場合はそれを使って進行状況を追跡し、Retry-After がある場合はその秒数を待ってから状態を確認します。Azure-AsyncOperation がない場合は Location を確認し、Retry-After が返らない場合は独自の再試行ロジックを実装します。(Microsoft Learn)

そのため、手書きのRESTクライアントでは次のような判定が必要です。

レスポンス	実装上の扱い
`200 OK`	更新完了として処理
`201 Created`	作成または更新開始。ヘッダーがあればポーリング
`202 Accepted`	操作受付済み。失敗扱いにせず、ポーリングへ進む
`400 Bad Request`	`Default` の大文字小文字、`identityResourceId`、リクエスト本文を確認

特にCIや監視で「PUTは200または201だけ成功」と固定している場合、202 Accepted を失敗として誤検知する可能性があります。今回の修正ではOpenAPIにも 202 レスポンスが追加されているため、APIクライアント、SDK、テストコードの成功条件を見直してください。(GitHub)

Listはページング前提ではなく単一ページ前提になる

今回の更新では、List操作が ArmResourceListByParent から Azure.ResourceManager.Legacy.ArmListSinglePageByParent に戻されています。PR上の説明では、サーバーごとに存在するのは常に1つの Default 項目で、ページングはないため、この定義が適切だとされています。(GitHub)

レスポンス形状は value 配列ですが、nextLink を前提にしたページング処理は不要です。Listの例でも、value 配列内に Default の1件が返る形になっています。(GitHub)

{
  "value": [
    {
      "name": "Default",
      "type": "Microsoft.DBforMySQL/flexibleServers/fabricMirroringSettings",
      "properties": {
        "state": "Enabled",
        "provisioningState": "Succeeded"
      }
    }
  ]
}

ページングがないことを前提にしてよい一方で、配列で返ること自体は変わりません。アプリ側では「1件だけ返るが、配列として処理する」という実装にしておくと、SDKやRESTレスポンスの扱いが安定します。

影響範囲

今回の更新はドキュメント・仕様の修正に見えますが、実装側では破壊的変更として扱うべき箇所があります。PRでは BreakingChange-Go-Sdk ラベルが付与され、Swagger BreakingChangeチェックも失敗として検出されていました。また、APIViewではTypeSpec、Go、Python、C#、Java向けのAPIレビューが作成されています。(GitHub)

対象	想定される影響
REST APIを直接呼ぶスクリプト	`default` 指定、`202` 未対応、`identityResourceId` 不足で失敗する可能性
Azure SDK利用コード	enum値、戻り型、LRO処理、List処理の差分が出る可能性
Go SDK利用者	PR上でBreakingChangeラベルが付いているため重点確認が必要
IaC／自動展開パイプライン	PUT後の完了待ち、マネージドID指定、検証環境での再テストが必要
テスト・モック	固定レスポンスの `name: default`、`id` の末尾、成功ステータス条件の更新が必要
運用監視	`202 Accepted` をエラーとして扱わないようにする必要

管理者と開発者が確認すべきチェックリスト

確認項目	見る場所	対処
`default` を使っていないか	REST URL、JSON本文、テストデータ、モック	`Default` に統一する
`Enabled` 時に `identityResourceId` があるか	PUTリクエスト本文	ユーザー割り当てマネージドIDのARM IDを指定する
PUTの `202` を成功扱いしているか	HTTPクライアント、CI、監視ルール	`202` を受けたらポーリングへ進む
ポーリングヘッダーを読んでいるか	RESTクライアント、SDK設定	`Azure-AsyncOperation`、`Location`、`Retry-After` を確認する
非同期状態確認に必要な権限があるか	実行ユーザー、サービスプリンシパル、マネージドID	リソースグループレベルで十分な権限を確認する
Listで `nextLink` を必須扱いしていないか	SDKラッパー、ページング処理	1ページ・1件前提で処理する
SDK生成物を自動更新していないか	dependency lock、CIのcodegen	本番反映前に差分レビューを行う

Azureの非同期操作では、状態追跡URLがリソース自体のスコープに含まれない場合があるため、状態確認にはリソースグループレベルで十分なアクセス許可が必要だと説明されています。運用自動化でサービスプリンシパルやマネージドIDを使っている場合は、PUTを開始できてもポーリングで権限不足になるケースを想定して確認してください。(Microsoft Learn)

移行・展開時の進め方

既存コードを検索して `default` を洗い出す

まず、リポジトリ全体で次のような文字列を検索します。

fabricMirroringSettingsName
fabricMirroringSettings/default
"name": "default"

該当箇所がAPI呼び出し、テスト、サンプル、監視条件に含まれている場合は、Default へ変更します。大文字小文字の違いだけなので見落としやすく、レビューでも差分が軽く見られがちです。しかし今回の更新では、実サービスの検証が大文字小文字を区別することが明示されています。(GitHub)

PUTの事前検証を追加する

state を Enabled にする前に、アプリ側で次の条件を検証します。

state == "Enabled" の場合:
  - identityResourceId が空でない
  - identityResourceId が /subscriptions/... から始まるARM ID形式である
  - 対象のユーザー割り当てマネージドIDが存在する

identityResourceId の権限や必要ロールは、実際のFabric Mirroring構成や接続先によって変わる可能性があります。ここでは「PUT本文にIDが必要」という点と、「実行主体が非同期状態を追跡できる権限を持つ」という点を分けて確認するのが安全です。

手動検証では `az rest` でHTTPステータスとヘッダーを見る

Azure CLIでログイン済みの検証環境がある場合、次のような形でPUTのレスポンスを確認できます。実行前に、対象APIバージョンが利用可能か、プレビューAPIの利用条件を確認してください。

az rest \
  --method put \
  --url "https://management.azure.com/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.DBforMySQL/flexibleServers/<serverName>/fabricMirroringSettings/Default?api-version=2025-12-01-preview" \
  --body '{
    "properties": {
      "state": "Enabled",
      "identityResourceId": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName>"
    }
  }'

確認すべき結果は、本文だけではありません。200、201、202 のどれが返るか、Azure-AsyncOperation、Location、Retry-After が返るか、ポーリング先へアクセスできるかをセットで確認します。

SDK利用者は生成差分をレビューする

今回のPRでは、Go SDKに破壊的変更ラベルが付いています。さらに、TypeSpec、Go、Python、C#、JavaのAPIViewが作成されているため、SDKを使うチームは「RESTのJSON差分だけ」を見て判断しないほうが安全です。(GitHub)

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

観点	確認内容
enum値	`Default` が生成SDK上でどう表現されるか
PUTメソッド	LRO開始メソッドや戻り型が変わっていないか
ポーリング	`202` をSDKが正しく追跡するか
List	ページング用の型やイテレーターが変わっていないか
エラー処理	`400` 発生時に原因をログで追えるか

本番環境では、SDKの自動更新をそのまま流すのではなく、dependency lockや生成コードの差分を確認してから反映するのが現実的です。

公開状況で注意したいこと

PR #43335は2026年5月20日に mysql/2025-12-01 ブランチへマージされていますが、親となる「2025-12-01-preview version」を追加するPR #39083は、確認時点では main へのマージ待ちとして表示されています。#39083の説明では、MySQL FlexibleServers配下にFabricMirroringSettingsのシングルトンプロキシリソースを追加し、GET、PUT（LRO）、List操作を含むとされています。(GitHub)

そのため、実務では次のように判断してください。

状況	判断
仕様リポジトリの差分を追っている	#43335の修正内容を取り込んで設計・テストを更新する
本番でAPIを呼ぶ	対象APIバージョンが実際に利用可能か確認する
SDKを使う	利用中のSDKバージョンがこの仕様を反映しているか確認する
LearnのREST APIリファレンスだけを見ている	反映に時間差がある可能性を考慮する
プレビュー機能を扱う	仕様や挙動が変わる可能性を前提に、固定実装を避ける

よくある失敗パターン

`Default` の大文字小文字を軽視する

default と Default は見た目の差が小さいため、レビューで見逃されやすいポイントです。今回の更新では、サンプルだけでなくOpenAPIのenum値も Default に変更されています。固定URLやテストデータに小文字が残っていると、検証環境では通っても本番相当のサービス検証で失敗する可能性があります。(GitHub)

`identityResourceId` を「任意項目」と誤解する

スキーマ上の ? やnullableだけを見て「省略できる」と判断すると失敗します。state が Enabled のときは、ユーザー割り当てマネージドIDのリソースIDを必ず送る前提で実装してください。(GitHub)

`202 Accepted` を失敗扱いする

PUT後に 202 が返るのは、操作が受け付けられて処理中であることを示すケースです。APIクライアントが200番台のうち200／201だけを成功扱いしている場合、正しいレスポンスをエラーとして処理してしまいます。

Listでページング処理を強制する

Listレスポンスは value 配列ですが、今回の仕様では単一ページ前提です。nextLink がないことをエラー扱いする、またはページング前提の型に強く依存する実装は見直してください。

削除でロールバックしようとする

TypeSpec上では、FabricMirroringSettingsは親サーバーに紐づくシングルトン設定として扱われ、独立した削除操作ではなくPUTで Enabled／Disabled を切り替える考え方が示されています。ロールバック手順を作る場合は、削除ではなく状態変更を基本に設計するのが安全です。(GitHub)

次にやるべきこと

今回のAzure REST API更新で優先して対応すべきことは明確です。まず、コードとテスト内の default を検索し、Default に統一します。次に、state: Enabled のPUTで identityResourceId を必ず送るように検証を追加します。最後に、PUT後の 202 Accepted とポーリングヘッダーを処理できるよう、RESTクライアント、SDKラッパー、CI、監視ルールを確認してください。

特にSDK利用者は、Goを中心に生成物の差分を確認し、Listのページング前提やLRO処理の戻り型が変わっていないかをレビューする必要があります。プレビューAPIの仕様は公開反映やSDK反映に時間差が出ることがあるため、本番展開前には対象APIバージョン、公式リファレンス、利用SDKのバージョンをそろえて確認するのが最も安全です。

この記事を書いた人

佐藤健司

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

Azure REST APIのFabricMirroringSettings更新とは？Default指定・非同期PUTの注意点

Azure REST APIのFabricMirroringSettings更新は何が変わるのか

変更点の詳細

fabricMirroringSettingsName は Default を使う

state: Enabled では identityResourceId を指定する

PUTは非同期操作として扱う

Listはページング前提ではなく単一ページ前提になる

影響範囲

管理者と開発者が確認すべきチェックリスト

移行・展開時の進め方

既存コードを検索して default を洗い出す

PUTの事前検証を追加する

手動検証では az rest でHTTPステータスとヘッダーを見る

SDK利用者は生成差分をレビューする

公開状況で注意したいこと

よくある失敗パターン

Default の大文字小文字を軽視する

identityResourceId を「任意項目」と誤解する

202 Accepted を失敗扱いする