Azure の Data API builder custom paths は、REST API の URL をデータベースのテーブル名やエンティティ名にそのまま合わせるのではなく、業務領域や利用者目線で整理できるようにする DAB 2.0 の更新です。結論から言うと、既存 API をすぐ変更しなければならないタイプの強制移行ではありません。ただし、REST エンドポイントの URL はクライアント、API Management、監視、認可設計に影響するため、新規 API や API v2 化のタイミングでは積極的に見直す価値があります。
2026年6月30日に Azure SQL Dev Corner で公開された公式情報では、Data API builder 2.0 により REST エンドポイントの entity path に複数階層のパスを設定できるようになったことが説明されています。これにより、/api/Customer のような単純な構成だけでなく、/api/sales/Customer や /api/support/CustomerCase のように、業務ドメインごとに API surface を構成できます。(Microsoft for Developers)
Azure Data API builder custom paths の更新ポイント
Data API builder は、データベースに対して REST API や GraphQL API を生成する構成ベースのエンジンです。公式ドキュメントでは、SQL Server、Azure SQL、Azure Cosmos DB、PostgreSQL、MySQL などのデータベースを対象に、アプリケーションコードを書かずに API を公開できる仕組みとして説明されています。(Microsoft Learn)
今回の「Compose your API surface with Data API builder custom paths」で重要なのは、DAB 2.0 の REST エンドポイントで compound paths、つまり複合パスが使えるようになった点です。従来のようにエンティティ名をそのまま URL に出すだけでなく、業務領域、利用者、API の用途に合わせて階層的な URL を設計できます。(Microsoft for Developers)
| 観点 | これまでの考え方 | DAB 2.0 の custom paths でできること |
|---|---|---|
| URL 設計 | /api/Customer のようにエンティティ名中心 | /api/sales/Customer のように業務領域で整理 |
| API の見通し | エンティティ数が増えると一覧性が下がる | sales、accounting、support などで分類できる |
| DB 設計との関係 | DB のテーブル名やスキーマが表に出やすい | DB 構造ではなく API 利用者目線で公開名を決められる |
| 影響範囲 | 主に DAB の entity 設定 | クライアント、OpenAPI、API Gateway、監視ルールにも影響 |
| 移行の必要性 | 既存パスを継続利用可能 | 新規 API やバージョン更新時に採用しやすい |
DAB 2.0 は 2026年6月時点で一般提供されており、Microsoft Learn では最新の 2.0 リリースを利用することが推奨されています。custom paths だけでなく、認証既定値、OpenAPI、監視性、MCP 関連機能も DAB 2.0 の更新範囲に含まれるため、単なる URL 設定の変更としてではなく、DAB 実行環境全体の更新として確認するのが安全です。(Microsoft Learn)
REST エンドポイントは「ホスト名」「グローバル REST パス」「エンティティパス」で決まる
DAB の REST エンドポイントは、大きく分けると次の3つの要素で構成されます。
| 要素 | 例 | 管理する場所 |
|---|---|---|
| ホスト名 | https://api.example.com | Azure Container Apps、App Service、リバースプロキシなど |
| グローバル REST パス | /api | runtime.rest.path |
| エンティティごとの REST パス | /sales/Customer | entities.<EntityName>.rest.path |
公式ブログでは、runtime.rest.path の既定例として /api が示され、その後ろに各エンティティの REST パスが連結される形で説明されています。たとえば Customer エンティティの rest.path を /sales/Customer にすると、最終的な REST パスは https://localhost/api/sales/Customer のようになります。(Microsoft for Developers)
{
"runtime": {
"rest": {
"enabled": true,
"path": "/api"
}
},
"entities": {
"Customer": {
"source": {
"object": "dbo.Customer",
"type": "table"
},
"rest": {
"enabled": true,
"path": "/sales/Customer"
}
}
}
}この設定で重要なのは、source.object はデータベース上の実体を指し、rest.path は外部に公開する API の見え方を決める点です。つまり、DB の物理構造と API の公開設計を分離しやすくなります。
なぜ custom paths が重要なのか
custom paths の価値は、単に URL を長くできることではありません。API 利用者にとって自然な単位でエンドポイントを整理できることにあります。
たとえば、顧客、注文、請求、支払い、問い合わせをすべて同じ階層に並べると、エンティティが増えるほど API の意味が見えにくくなります。
/api/Customer
/api/Order
/api/Invoice
/api/Payment
/api/CustomerCase業務領域ごとに整理すると、API の利用者は「どの業務で使う API か」を URL から判断しやすくなります。
/api/sales/Customer
/api/sales/Order
/api/sales/Invoice
/api/accounting/Payment
/api/support/CustomerCaseMicrosoft の公式ブログでも、compound paths によって API surface をデータベーストポロジではなくビジネス構造に合わせて構成できると説明されています。これは、API を単なる DB アクセス手段ではなく、業務アプリケーションの公開インターフェースとして設計するうえで大きな変更です。(Microsoft for Developers)
採用すると効果が出やすいケース
custom paths は、特に次のような環境で効果があります。
| ケース | 採用メリット | パス設計例 |
|---|---|---|
| 業務ドメインが複数ある | sales、billing、support などで API を整理できる | /api/sales/orders |
| 同じような名前のエンティティが複数ある | コンテキスト別に意味を分けられる | /api/shopping-cart/item、/api/invoice/item |
| DB スキーマを外部に見せたくない | 内部構造を隠し、公開 API 名を安定させられる | /api/customers |
| API 利用チームが多い | 利用部門別にドキュメントや権限設計を分けやすい | /api/partner/orders |
| API Management と組み合わせる | ルーティング、ポリシー、バージョン管理を整理しやすい | /api/v2/sales/orders |
一方で、エンティティが数個しかない小規模な社内 API では、無理に階層を深くする必要はありません。/api/Customer のような単純なパスで十分に分かりやすいなら、そのまま維持する方が運用負荷は低くなります。
影響範囲は DAB の設定ファイルだけではない
custom paths は DAB の rest.path 設定で有効化できますが、実務上の影響は DAB 内に閉じません。REST API の URL は、多くの周辺システムで前提として使われているためです。
| 影響を受ける領域 | 確認すべきこと |
|---|---|
| クライアントアプリ | 呼び出し先 URL をハードコードしていないか。SDK や環境変数で切り替えられるか |
| API Management | パスベースのルーティング、リライト、認証ポリシー、レート制限が新パスに対応しているか |
| Azure Front Door / Application Gateway | WAF ルール、パスルール、ヘルスプローブ、リダイレクト設定が壊れないか |
| CORS | 新しい呼び出し元やパスでプリフライトリクエストが通るか |
| 監視・ログ | ダッシュボード、アラート、ログクエリが旧パス前提になっていないか |
| OpenAPI / Swagger | API 仕様書とクライアント生成コードを更新する必要があるか |
| 認可設計 | URL の分類と DAB の permissions 設定が矛盾していないか |
| テスト | E2E テスト、負荷テスト、疎通確認スクリプトを新パスに対応させるか |
DAB の REST ドキュメントでは、REST のパスコンポーネントとクエリパラメーターは大文字小文字を区別すると説明されています。/api/Sales/Customer と /api/sales/customer を別物として扱う前提で、命名規則を最初に決めておくことが重要です。(Microsoft Learn)
設定変更時の実務手順
custom paths を導入する場合は、いきなり本番設定を書き換えるのではなく、API 契約の変更として扱います。特に外部システムや複数チームが利用する API では、旧 URL を使う利用者が残っていないか確認してから進めるべきです。
| 手順 | 作業内容 | 失敗しやすいポイント |
|---|---|---|
| 現状把握 | 既存の REST エンドポイント、利用クライアント、API Management の設定を棚卸しする | 監視スクリプトやバッチ処理の URL を見落とす |
| パス設計 | 業務ドメイン、バージョン、命名規則を決める | DB スキーマ名をそのまま公開して将来変更しにくくなる |
| 設定変更 | entities.<EntityName>.rest.path に複合パスを指定する | 大文字小文字、スラッシュ、既存パスとの重複を確認しない |
| ローカル検証 | DAB 2.0 以降で起動し、想定パスにアクセスできるか確認する | 旧パスで動く前提のテストだけを実行してしまう |
| 周辺設定更新 | APIM、Front Door、CORS、WAF、監視、OpenAPI を更新する | DAB は動くが入口側で 404 や 403 になる |
| 段階移行 | 必要に応じて旧パスを残す、またはリライトで吸収する | クライアント更新前に旧パスを削除して障害になる |
| 本番反映 | リリース後に 404、401、403、5xx、レイテンシを監視する | URL 別メトリクスの粒度が粗く、問題箇所を特定できない |
Microsoft Learn の REST ドキュメントでは、DAB 2.0 以降で entity REST path にスラッシュを含められること、またサブディレクトリ形式の URL 構造を作れることが説明されています。さらに、ルーティングでは longest-prefix matching が使われ、パストラバーサルにつながる ..、バックスラッシュ、エンコードされた区切り文字などは検証でブロックされるとされています。(Microsoft Learn)
パス設計のおすすめルール
custom paths を使うと自由度が上がりますが、自由にしすぎると API が読みにくくなります。グローバル向け、複数チーム向け、長期運用向けの API では、次のようなルールを先に決めておくと管理しやすくなります。
| ルール | 推奨例 | 理由 |
|---|---|---|
| 英数字とハイフンを中心にする | /api/sales-orders | 多言語チーム、ログ分析、ドキュメントで扱いやすい |
| 業務ドメインを第1階層に置く | /api/sales/orders | API 利用者が用途を判断しやすい |
| DB スキーマ名を安易に出さない | /api/billing/payments | DB リファクタリング時に API 契約を守りやすい |
| 階層を深くしすぎない | 2〜3階層程度 | URL が長くなると運用・監視・説明が難しくなる |
| 大文字小文字を統一する | /api/sales/customers | パスの取り違えを防げる |
| バージョン管理を検討する | /api/v2/sales/customers | 既存クライアントとの互換性を保ちやすい |
特におすすめなのは、DB の都合ではなく、API 利用者の業務フローから逆算してパスを決めることです。たとえば、テーブル名が dbo.CustomerMaster でも、API 利用者にとって自然なのが顧客一覧であれば /api/sales/customers の方が分かりやすくなります。
移行期限はあるのか
2026年6月30日の公式ブログと DAB 2.0 の Microsoft Learn で確認できる範囲では、custom paths の利用に伴って既存の REST パスを変更しなければならない移行期限は示されていません。既存の単純なパスを使い続けることも、新しい compound paths を採用することもできます。(Microsoft for Developers)
ただし、DAB 2.0 へ上げる場合は custom paths 以外の変更も確認が必要です。DAB 2.0 では Unauthenticated プロバイダーが新しい認証プロバイダーとして導入され、新規構成の既定値になること、またロール継承や permission-aware OpenAPI などの変更も追加されています。既存環境を更新する管理者は、REST パスだけでなく、認証・認可・OpenAPI 出力・監視設定も合わせて確認するべきです。(Microsoft Learn)
既存 API に導入する場合の判断基準
既存 API で custom paths を採用するかどうかは、「URL を変えるメリットが、移行コストを上回るか」で判断します。
| 状況 | 判断 |
|---|---|
| 既存クライアントが少なく、社内利用に限られる | 早めに整理してもよい |
| 外部パートナーやモバイルアプリが利用している | 旧パス維持またはバージョン分離を優先 |
| エンティティ数が急増している | 業務ドメイン別パスへの整理を検討 |
| DB スキーマ変更の予定がある | API パスを DB 名から切り離す価値が高い |
| API Management で既にバージョン管理している | APIM 側のルーティングと合わせて導入しやすい |
| 一時的な検証環境のみ | 無理に複雑な設計にしない |
既存 API で一番避けたいのは、DAB の設定だけを変更して、クライアント側の URL、API Management のポリシー、監視設定を更新し忘れることです。URL 変更は小さく見えても、利用者から見ると API 契約の変更です。必要であれば /api/v1/... と /api/v2/... を一定期間併存させる、または API Management で旧パスを新パスへリライトする設計を検討します。
管理者が確認すべきチェックリスト
DAB 2.0 の custom paths を本番利用する前に、管理者は次の項目を確認しておくと安全です。
| 確認項目 | チェック内容 |
|---|---|
| DAB バージョン | 実行環境が DAB 2.0 以降か |
| 構成ファイル | runtime.rest.path と各 entities の rest.path が意図どおりか |
| JSON schema | 利用中の DAB バージョンに合った schema で検証しているか |
| パス競合 | 似たパス、大小文字違い、重複しやすい階層がないか |
| 認証・認可 | DAB の permissions と入口側の認証ポリシーが一致しているか |
| API Management | ルーティング、リライト、レート制限、サブスクリプションキー設定が新パス対応済みか |
| OpenAPI | 仕様書、クライアント生成、開発者ポータルが新パスを反映しているか |
| 監視 | URL 別のログ、アラート、ダッシュボードが更新されているか |
| テスト | GET、POST、PUT、PATCH、DELETE の主要シナリオを新パスで確認したか |
| ロールバック | 問題発生時に旧設定へ戻す手順があるか |
DAB の REST API では、$select、$filter、$orderby、$first、$after といったクエリ機能も提供されます。パスを変更しても、これらのクエリ利用やページング、フィルタリングのテストは継続して必要です。(Microsoft Learn)
よくある失敗と回避策
URL を業務名ではなく組織名で切ってしまう
/api/tokyo-sales/customers のように組織名や拠点名を入れると、組織変更のたびに API 名が古くなります。グローバル展開や長期運用を考えるなら、組織ではなく業務ドメインで切る方が安定します。
避けたい例: /api/japan-sales/customers
推奨例: /api/sales/customersDB スキーマをそのまま公開してしまう
/api/dbo/Customer のようなパスは開発者には分かりやすい場合がありますが、API 利用者に内部実装を意識させます。DB スキーマの再編やテーブル名変更が予定されている場合は、公開 API 名を別に設計した方が安全です。
大文字小文字のルールを決めない
DAB の REST パスでは大文字小文字が区別されます。チームによって /Customer、/customer、/Customers が混在すると、テストや運用で混乱します。公開 API は小文字とハイフンまたは複数形で統一するなど、ルールを明文化しておきましょう。(Microsoft Learn)
旧パスの利用者を調べずに切り替える
custom paths は便利ですが、既存 API の URL を変えればクライアントは影響を受けます。アクセスログ、APIM の分析、Application Insights、リポジトリ検索などで旧パスの利用状況を確認してから移行します。
OpenAPI の更新を忘れる
DAB 2.0 では permission-aware OpenAPI も追加されています。OpenAPI ドキュメントをクライアント生成や開発者ポータルに使っている場合、パス変更後の仕様書を必ず確認します。Microsoft Learn では、ロール別の OpenAPI パス /openapi/{role} は Development mode のみで利用できると説明されています。(Microsoft Learn)
新規 API なら custom paths を前提に設計する価値がある
これから DAB で新しい API を作るなら、最初から custom paths を前提に API surface を設計する価値があります。理由は、公開後に URL を変える方がはるかに難しいからです。
おすすめの進め方は、まずエンティティ一覧を作るのではなく、利用者の業務単位を洗い出すことです。
| 先に考えること | 例 |
|---|---|
| 誰が使う API か | 社内営業、経理、サポート、外部パートナー |
| 何の業務で使うか | 顧客管理、受注、請求、問い合わせ |
| 将来増えそうな領域は何か | 返品、契約、サブスクリプション、監査 |
| 外部に見せたくない内部名は何か | DB スキーマ名、略称、古い業務名 |
| バージョン管理が必要か | /api/v1/...、/api/v2/... |
そのうえで、DAB の entity 名は内部管理しやすい名前にし、rest.path は API 利用者が理解しやすい名前にします。これにより、DB 側の命名やスキーマ構造を変えても、外部公開 API の安定性を保ちやすくなります。
まとめ：custom paths は「URL変更機能」ではなく API 設計機能
Azure の Data API builder custom paths は、DAB 2.0 における REST API 設計の柔軟性を高める更新です。ポイントは、REST エンドポイントをデータベース構造に引きずられず、業務ドメインや利用者目線で構成できることです。
既存 API に対する強制移行期限は確認されていないため、すぐに全 API を変更する必要はありません。一方で、新規 API、API v2、複数チームで利用する業務 API、将来的に DB スキーマ変更が見込まれる環境では、custom paths を使って API surface を整理するメリットがあります。
まずは現在の REST エンドポイント、利用クライアント、API Management、監視設定を棚卸ししましょう。そのうえで、DAB 2.0 以降の検証環境で rest.path を使った複合パスを試し、OpenAPI、認可、ログ、テストまで含めて移行計画を作るのが現実的な進め方です。
コメント