Azure REST API documentation update: Param name fixは、Azure REST API全体に広く影響する大規模変更ではありません。確認すべき対象は、Microsoft Purview Data Qualityの「Get Asset Scores For Asset DQ」をREST API、Postman、独自スクリプト、生成クライアントで呼び出している環境です。今回の要点は、必須クエリパラメーター名が assetIdString から assetId に修正される点にあります。該当APIを使っていない場合、基本的に対応は不要です。一方で、該当エンドポイントを直接呼び出している場合は、URL、テスト、API Managementのポリシー、生成SDKの再生成設定まで確認しておくべきです。(GitHub)
Azure REST APIのParam name fixで何が変わったのか
今回の「Param name fix」は、Azure REST API仕様リポジトリにあるPR #42861で確認できる変更です。Azure REST API仕様リポジトリは、Microsoft AzureのREST API仕様の正規ソースとして位置付けられています。(GitHub)
変更対象は、Microsoft Purview Data QualityのデータプレーンAPIです。特に、指定した資産のデータ品質スコアを取得する Get Asset Scores For Asset DQ のクエリパラメーター名が修正されています。
| 項目 | 内容 |
|---|---|
| 対象サービス | Azure REST API / Microsoft Purview Data Quality |
| 対象API | Get Asset Scores For Asset DQ |
| APIバージョン | 2026-01-12-preview |
| 変更前 | assetIdString |
| 変更後 | assetId |
| パラメーター種別 | query |
| 必須かどうか | 必須 |
| 値の内容 | スコアを取得したい資産IDのカンマ区切りリスト |
| 主な影響 | REST呼び出しURL、サンプル、OpenAPI定義、TypeSpec定義、生成クライアント |
差分では、TypeSpec側の @query("assetIdString") と変数名 assetIdString が、@query("assetId") と assetId に変更されています。OpenAPI JSONでも、クエリパラメーターの name が assetIdString から assetId に変わっています。さらに、サンプルリクエストのJSONでも同じ修正が行われています。(GitHub)
変更前後のリクエスト例
Microsoft Learn上の該当APIは、指定した資産のスコアを取得するGET APIとして説明されています。エンドポイントは、ビジネスドメイン配下の asset-scores を呼び出す形式です。(Microsoft Learn)
変更前のイメージは次のとおりです。
GET {endpoint}/datagovernance/quality/business-domains/{businessDomainId}/asset-scores?api-version=2026-01-12-preview&assetIdString={assetIdString}今回の修正を反映した後は、次のように assetId を使います。
GET {endpoint}/datagovernance/quality/business-domains/{businessDomainId}/asset-scores?api-version=2026-01-12-preview&assetId={assetId}dataProductId を指定する場合は、次のような形になります。
GET {endpoint}/datagovernance/quality/business-domains/{businessDomainId}/asset-scores?api-version=2026-01-12-preview&assetId={assetId1},{assetId2}&dataProductId={dataProductId}ここで重要なのは、値の意味が変わったわけではない点です。変更されるのは、クエリ文字列のキー名です。つまり、82f21bcc-ae71-40b9-88ab-dae3f64fd711 のような資産IDを渡すこと自体は同じで、assetIdString= と書いていた部分を assetId= に直す必要があります。
なぜ単なるドキュメント修正でも確認が必要なのか
「パラメーター名の修正」と聞くと、軽微なドキュメント更新に見えるかもしれません。しかしREST APIでは、クエリパラメーター名はリクエスト契約の一部です。サービス側が assetId を必須パラメーターとして解釈する場合、古い assetIdString を送っても必須パラメーターが渡されていない扱いになる可能性があります。
特に注意したいのは、次のような環境です。
| 利用形態 | 起きやすい影響 | 確認ポイント |
|---|---|---|
| curlやPowerShellで直接呼び出し | URLに旧パラメーター名が残る | assetIdString を検索して置換する |
| Postmanコレクション | 保存済みクエリが古いままになる | Query Params欄のキー名を確認する |
| Azure API Management経由 | ポリシーで旧名を追加・変換している可能性 | inbound policy、rewrite-uri、set-query-parameterを確認する |
| OpenAPIから生成したクライアント | メソッド引数名や型定義が変わる可能性 | 最新仕様で再生成し、差分をレビューする |
| 自動テスト・監視 | 期待URLやモックが旧名のままになる | テストデータ、モック、スナップショットを更新する |
| 社内ドキュメント | 開発者が旧サンプルをコピーする | 手順書・README・Wikiを更新する |
このPRではAPIViewがAPIレベルの変更を検出し、SwaggerとTypeSpecのAPIレビューが作成されています。つまり、見た目は名前修正でも、生成物やクライアントコードに影響する可能性がある変更として扱うのが安全です。(GitHub)
対応が必要な人、不要な人
今回のAzure REST API documentation update: Param name fixで、すべてのAzure利用者が対応する必要はありません。対象はかなり限定的です。
対応が必要な可能性が高いケース
次のいずれかに当てはまる場合は、確認した方がよいでしょう。
- Microsoft Purview Data QualityのREST APIを直接呼び出している
Get Asset Scores For Asset DQを使って資産別のデータ品質スコアを取得している2026-01-12-previewのPurview Data Quality APIを検証・導入している- OpenAPIまたはTypeSpecから社内向けクライアントを生成している
- Postman、Logic Apps、Azure Functions、PowerShellなどで
asset-scoresエンドポイントを呼んでいる - API Managementやプロキシでクエリパラメーターを加工している
対応不要の可能性が高いケース
次のケースでは、基本的に今回の修正による直接影響はありません。
| ケース | 理由 |
|---|---|
| Purview Data Qualityを使っていない | 対象APIが限定されているため |
| Microsoft PurviewをUIだけで利用している | REST APIのクエリ名を直接扱わないため |
| 別のAzure REST APIだけを利用している | 変更対象がPurview Data Qualityの特定APIだから |
asset-scores エンドポイントを呼んでいない | 該当パラメーターを使わないため |
| 安定版APIのみを利用している | 今回の対象は 2026-01-12-preview の仕様だから |
ただし、社内の共通APIクライアントやOpenAPI定義をまとめて更新している場合は、直接利用していなくてもビルド差分に出ることがあります。依存先の自動生成コードを使っているチームでは、影響なしと決めつけず、差分確認だけは行うのが現実的です。
移行・設定確認の手順
実務では、次の順序で確認すると抜け漏れを減らせます。
| 手順 | 作業内容 | 見落としやすいポイント |
|---|---|---|
| 1 | コード全体で assetIdString を検索する | README、テスト、Postman JSON、環境変数も対象にする |
| 2 | 該当APIの呼び出し箇所を特定する | 別APIの変数名として使っている場合は安易に置換しない |
| 3 | クエリ名を assetId に変更する | 値ではなくキー名を変更する |
| 4 | ステージング環境でリクエストを実行する | 200 OKだけでなく、返却された資産IDとスコアを確認する |
| 5 | 自動テストとモックを更新する | 古いURLを期待値にしているテストが失敗しやすい |
| 6 | 生成クライアントを使う場合は再生成する | メソッド引数名が変わる可能性がある |
| 7 | 社内ドキュメントを更新する | 開発者が旧サンプルを再利用しないようにする |
コード検索では、次のようなコマンドを使えます。
rg "assetIdString"Windows環境でPowerShellを使う場合は、次のように検索できます。
Get-ChildItem -Recurse -File | Select-String "assetIdString"検索対象はソースコードだけでは不十分です。Postmanコレクション、OpenAPI定義、TerraformやBicepから呼び出す外部スクリプト、CI/CDのテストリクエスト、API Managementのポリシーにも旧名が残ることがあります。
修正時の具体的な判断基準
単純に全ファイルの assetIdString を assetId に一括置換するのは避けてください。変数名、コメント、古い仕様の説明、別APIの項目まで巻き込む可能性があります。
判断基準は次のとおりです。
| 確認対象 | assetId に変更すべきか | 理由 |
|---|---|---|
asset-scores APIのクエリキー | 変更する | 今回の修正対象 |
サンプルURL内の assetIdString= | 変更する | 実行時のリクエストに影響する |
| PostmanのQuery Paramsキー | 変更する | 旧キーでは必須パラメーター扱いされない可能性がある |
レスポンスJSONの assetId | 変更しない | もともと資産IDを表すレスポンス項目として使われる |
| 説明文中の「assetIdStringからassetIdへ変更」 | 変更しない | 変更履歴として必要 |
| 社内の一時変数名 | 状況次第 | APIに送るキー名と混同しないように整理する |
Microsoft Learnの該当ページでは、レスポンス例として assetId と score を含む資産スコアのリストが示されています。今回のPR差分で中心になっているのは、レスポンス項目ではなくリクエスト側のクエリパラメーター名です。(Microsoft Learn)
Microsoft LearnとGitHub仕様に差がある場合の見方
公開直後の仕様変更では、GitHub上の仕様リポジトリ、Microsoft LearnのREST APIリファレンス、実際のサービス挙動の反映タイミングがそろわないことがあります。今回も、確認時点のMicrosoft Learnページでは assetIdString を使ったURL例が表示されています。一方、PR #42861の差分では assetId へ修正されています。(Microsoft Learn)
そのため、本番環境でいきなり切り替えるのではなく、次の4点を確認するのが安全です。
| 確認項目 | 確認方法 |
|---|---|
| PRの状態 | マージ済みか、まだOpenかを確認する |
| Microsoft Learnの表示 | 該当ページのクエリ名が更新されているか確認する |
| 実APIの挙動 | ステージングまたは検証環境で assetId を使って実行する |
| 生成クライアント | OpenAPI/TypeSpec更新後にメソッド名・引数名の差分を見る |
PR画面では、2026年5月5日に PublishToCustomers や Versioning-Approved-BugFix などのラベルが付与されており、顧客向け反映を意識したバグ修正として扱われていることが分かります。ただし、PRは確認時点でOpen表示だったため、導入時には最新状態を確認してください。(GitHub)
dataProductId と複数の資産IDもあわせて確認する
このAPIでは、assetId だけでなく businessDomainId、api-version、必要に応じて dataProductId も使います。Microsoft Learnでは、データプロダクトに関連付かない資産では dataProductId に Guid.Empty を使う説明があります。(Microsoft Learn)
複数の資産IDを指定する場合は、カンマ区切りで渡します。
assetId=82f21bcc-ae71-40b9-88ab-dae3f64fd711,8de0ec1c-93da-4da0-8719-a8d89c54eeef実装時は、次の点に注意してください。
| 注意点 | 理由 |
|---|---|
| 資産IDの区切りを配列ではなくカンマ区切りにする | 仕様上、カンマ区切りリストとして説明されているため |
| URLビルダーを使う場合はエンコード結果を確認する | ライブラリによってカンマの扱いが異なる場合があるため |
dataProductId の有無で結果が変わる可能性を確認する | データプロダクト文脈のスコア取得に関係するため |
businessDomainId と資産IDの対応を確認する | 別ドメインの資産IDを指定すると期待結果にならない可能性があるため |
単にパラメーター名を変えるだけでなく、「同じ資産IDで同じスコアが返るか」「ページングがある場合に nextLink を処理できているか」まで確認しておくと、移行後の不具合を見つけやすくなります。
よくある失敗パターン
古いサンプルをそのままコピーしてしまう
REST APIリファレンスの反映には時間差が出ることがあります。古いサンプルに assetIdString が残っている場合でも、仕様リポジトリの修正内容と実APIの挙動を見て判断しましょう。
生成クライアントだけ更新して呼び出し側を直していない
OpenAPIやTypeSpecからクライアントを生成している場合、メソッドの引数名が変わることがあります。生成物だけ更新しても、呼び出し側のコードが旧引数名を使っているとビルドエラーや実行時エラーにつながります。
API Managementで旧名を付け直している
Azure API Managementで、バックエンドに渡す前にクエリパラメーターを加工しているケースがあります。アプリ側を assetId に直しても、APIMポリシーで assetIdString に戻してしまうと、修正が反映されません。
確認すべきポリシーの例は次のとおりです。
<set-query-parameter name="assetIdString" exists-action="override">このような設定が残っている場合は、意図に応じて assetId に変更します。
<set-query-parameter name="assetId" exists-action="override">旧名と新名を両方送ってしまう
移行期に不安だからといって、assetIdString と assetId の両方を送るのは避けた方がよいです。サービス側の解釈が明確でない場合、どちらが優先されるか分からず、将来の保守性も下がります。
一時的に互換対応が必要な場合は、アプリケーション設定で切り替えられるようにし、検証後は新しい assetId に統一するのが現実的です。
今回の変更を安全に取り込むチェックリスト
本番適用前に、次の項目を確認してください。
| チェック | 内容 |
|---|---|
| 利用有無 | Get Asset Scores For Asset DQ を使っているか |
| 旧名検索 | assetIdString がコードや設定に残っていないか |
| URL確認 | クエリキーが assetId になっているか |
| APIバージョン | 2026-01-12-preview を使っているか |
| 認証 | Purview向けの認証設定が変わっていないか |
| レスポンス | 期待する assetId と score が返るか |
| テスト | モック、スナップショット、監視URLを更新したか |
| ドキュメント | 社内手順書やREADMEを更新したか |
| 生成コード | OpenAPI/TypeSpec由来のクライアント差分を確認したか |
| ロールバック | 旧名に戻す必要がある場合の切り戻し手順があるか |
まとめ：小さな名称修正でもAPI利用者はURLと生成物を確認する
Azure REST API documentation update: Param name fixの本質は、Microsoft Purview Data Qualityの特定APIで、必須クエリパラメーター名を assetIdString から assetId に直す変更です。Azure REST API全体を見直す必要はありませんが、asset-scores エンドポイントを直接呼び出しているチームは、URL、Postman、API Management、生成クライアント、自動テストを確認する価値があります。
次に取るべき行動はシンプルです。まずリポジトリや設定ファイル全体で assetIdString を検索し、該当するAPI呼び出しだけを assetId に更新します。そのうえで、検証環境で実APIを呼び出し、期待する資産IDとスコアが返ることを確認してください。ドキュメント反映のタイミングに差が出る可能性があるため、PRの状態、Microsoft Learnの表示、実際のサービス挙動をセットで見ることが、安全な移行の近道です。
コメント