Azure DevOpsのREST APIを使っているなら、まず確認すべき点はシンプルです。すべてのAPIリクエストでapi-versionを明示しているか、-preview付きのバージョンに依存していないか、Azure DevOps Serverのバージョンと利用APIの対応が合っているかを点検してください。
Microsoft Learnの「REST API Versioning for Azure DevOps」は、Azure DevOps REST APIを安全に使い続けるためのバージョン指定ルールを整理した公式情報です。Azure DevOpsのAPIは継続的に進化するため、バージョン指定を曖昧にしたまま運用すると、将来の仕様変更やプレビューAPIの無効化によって、連携アプリ、社内ツール、CI/CDパイプラインが突然失敗する可能性があります。公式ドキュメントでは、すべてのリクエストでAPIバージョンを指定する必要があること、バージョン表記の形式、プレビュー版から正式版へ移行すべきタイミングが示されています。(Microsoft Learn)
Azure DevOps REST APIのバージョン管理で押さえるべき結論
Azure DevOps REST APIのバージョン管理は、新機能を使うためだけの仕組みではありません。実務では、API連携を壊さずに運用するための契約として扱うべきものです。
特に重要なのは、次の4点です。
| 確認項目 | 実務上の意味 | 放置した場合のリスク |
|---|---|---|
api-versionを毎回指定しているか | APIの仕様を明示して呼び出せる | 将来の変更でレスポンスや挙動が変わる可能性がある |
-previewを使い続けていないか | プレビューAPIへの依存を把握できる | 正式版公開後、プレビュー版が無効化されるとリクエストが拒否される |
| Azure DevOps ServerのバージョンとAPIバージョンが合っているか | オンプレミス環境で対応範囲を判断できる | 存在しないAPIバージョンを呼び出して失敗する |
| 本番展開前にレスポンス差分を検証しているか | 仕様変更の影響を事前に確認できる | JSON項目の差分やエラー処理漏れで障害につながる |
公式ドキュメントでは、APIバージョンは{major}.{minor}[-{stage}[.{resource-version}]]という形式で、例として1.0、1.1、1.2-preview、2.0などが示されています。プレビュー段階では1.0-preview.1のように特定リビジョンを指定でき、正式版公開後はプレビュー版が非推奨となり、一定期間後に無効化される可能性があります。(Microsoft Learn)
何が変わるのか：新機能よりも「運用ルールの再点検」が重要
今回のテーマである「REST API Versioning for Azure DevOps」は、特定のAPIエンドポイントが一斉に変更されるというより、Azure DevOps REST APIを使う管理者・開発者が守るべきバージョン管理の基本を明確にする内容です。
実務での変更点は、次のように捉えると分かりやすいです。
API呼び出しでバージョン指定が前提になる
Azure DevOps REST APIでは、リクエストURIにapi-version={version}を含める形が基本です。Azure DevOps Servicesの場合、公式リファレンスでは次のような形式が示されています。(Microsoft Learn)
GET https://dev.azure.com/{organization}/_apis/{area}/{resource}?api-version={version}たとえば、プロジェクト一覧を取得するAPIであれば、次のように指定します。
curl -u {username}:{personalaccesstoken} \
"https://dev.azure.com/{organization}/_apis/projects?api-version=7.1"ここで重要なのは、api-versionを「なんとなく付ける」のではなく、利用しているAzure DevOps ServicesまたはAzure DevOps Serverでサポートされるバージョンを選ぶことです。
ヘッダー指定とクエリパラメーター指定の両方を理解する
公式ドキュメントでは、APIバージョンはHTTPヘッダーまたはURLクエリパラメーターで指定できると説明されています。ヘッダーではAccept: application/json;api-version=1.0のように指定し、URLでは?api-version=1.0のように指定します。(Microsoft Learn)
実務では、チーム内で指定方法を統一することをおすすめします。
| 指定方法 | 例 | 向いているケース |
|---|---|---|
| URLクエリパラメーター | ?api-version=7.1 | curl、PowerShell、CI/CDスクリプト、検証用リクエスト |
| HTTPヘッダー | Accept: application/json;api-version=7.1 | 共通HTTPクライアントやSDKラッパーで制御したい場合 |
多くの現場では、ログやトラブルシューティングで確認しやすいURLクエリパラメーター方式が扱いやすいです。一方、APIクライアントを自社ライブラリ化している場合は、ヘッダーで一元管理する方法も有効です。
対象者：誰が確認すべきか
Azure DevOps REST APIのバージョン管理は、開発者だけの問題ではありません。Azure DevOpsを業務システムや自動化基盤に組み込んでいる組織では、管理者、開発者、運用担当者がそれぞれ確認すべきポイントがあります。
| 対象者 | 確認すべき内容 |
|---|---|
| Azure DevOps管理者 | 組織内で利用しているAPI連携、PAT、サービス接続、拡張機能、オンプレミス版のバージョン |
| アプリ開発者 | ソースコード内のapi-version、-preview利用、レスポンス項目への依存 |
| DevOpsエンジニア | Pipeline、PowerShell、Bash、Azure CLI、GitHub Actionsなどの自動化スクリプト |
| 情シス・運用担当 | 社内ツール、監視、レポート出力、棚卸しバッチ、チケット連携 |
| セキュリティ担当 | 古いPAT利用、不要な権限、失敗時ログにトークンが出ていないか |
特に注意したいのは、昔作った社内ツールや一度だけ作ったつもりの自動化スクリプトです。担当者が変わったあとも動き続けているAPI連携は、バージョン指定が古いまま放置されやすく、障害時に原因追跡が難しくなります。
影響範囲：どのAPI連携を棚卸しすべきか
Azure DevOps REST APIは、Boards、Repos、Pipelines、Artifacts、Test Plansなど、さまざまな領域で使われます。影響範囲を確認するときは、「どのサービスを使っているか」ではなく、どこからHTTPリクエストを投げているかで棚卸しするのが効率的です。
棚卸し対象になりやすい場所
| 場所 | 具体例 | 探すべき文字列 |
|---|---|---|
| ソースコード | C#、Python、Node.js、GoなどのAPIクライアント | _apis/、api-version、dev.azure.com |
| CI/CD | Azure Pipelines、GitHub Actions、Jenkins | curl、Invoke-RestMethod、az devops |
| 運用スクリプト | PowerShell、Bash、バッチファイル | PAT、Authorization、Basic |
| 社内ツール | チケット集計、ビルド状況表示、承認ワークフロー | workitems、builds、release |
| 拡張機能 | Azure DevOps Extension、社内ポータル連携 | REST API呼び出し箇所 |
たとえば、PowerShellでは次のような記述を検索すると、API連携を見つけやすくなります。
Select-String -Path .\* -Pattern "_apis","api-version","dev.azure.com" -RecurseGitリポジトリ全体で探す場合は、次のような検索も有効です。
git grep -n "_apis\|api-version\|dev.azure.com"検索結果が多い場合は、まず-previewを含むものから確認してください。正式版に移行できるAPIであれば、優先度を上げて対応すべきです。
プレビューAPIを使っている場合の注意点
Azure DevOps REST APIでは、1.0-previewや7.1-preview.1のように、プレビュー段階のAPIを指定することがあります。プレビューAPIは新機能を早く使える一方で、仕様が変わる可能性が高く、長期運用には向きません。
公式ドキュメントでは、APIが正式リリースされた後、そのプレビュー版は非推奨となり、12週間後に非アクティブ化できると説明されています。非アクティブ化後は、-previewを指定したリクエストが拒否されます。(Microsoft Learn)
プレビューAPI利用時の判断基準
| 状況 | 判断 |
|---|---|
| 正式版がすでに公開されている | 正式版へ移行する |
| 正式版がないが業務上必須 | リスクを明記し、監視と代替手段を用意する |
| 検証目的で一時的に使っている | 本番コードへ混入させない |
| レスポンス項目が頻繁に変わる | 固定的なJSONパースを避け、例外処理を厚くする |
| 外部公開サービスで使っている | 仕様変更時の影響が大きいため、採用可否を慎重に判断する |
プレビューAPIを使う場合は、コードコメントに「なぜpreviewが必要なのか」「正式版が出たら何を確認するのか」を残しておくと、後任者が判断しやすくなります。
このAPIは現時点で正式版がないため preview を利用。
正式版公開後は api-version を更新し、レスポンス項目の差分を確認する。Azure DevOps ServicesとAzure DevOps Serverで確認ポイントは違う
Azure DevOps REST APIのバージョン管理では、クラウド版のAzure DevOps Servicesと、オンプレミス版のAzure DevOps Serverを分けて考える必要があります。
Azure DevOps Servicesは継続的に更新されるため、公式リファレンスでは最新のリリース版REST APIの利用が推奨されています。一方、Azure DevOps Serverや旧TFSでは、サーバーバージョンによって利用できるREST APIバージョンが異なります。(Microsoft Learn)
環境別の確認ポイント
| 利用環境 | 確認ポイント |
|---|---|
| Azure DevOps Services | 最新の安定版APIを使っているか、古いapi-versionに固定されていないか |
| Azure DevOps Server 2022以降 | サーバーの更新レベルと対応APIバージョンが一致しているか |
| Azure DevOps Server 2019/2020 | 使いたいAPIが対応バージョン内にあるか |
| TFS 2015〜2018 | 古いAPIドキュメントや互換性の確認が必要 |
| 混在環境 | クラウド前提のスクリプトをオンプレミスへ流用していないか |
注意したいのは、Azure DevOps Services向けに作ったAPI連携を、そのままAzure DevOps Server環境へ持ち込むケースです。エンドポイントのホスト名だけ変えても、APIバージョンや利用可能なリソースが一致するとは限りません。
Azure DevOps Serverでは、次のような観点で確認してください。
・現在のAzure DevOps Serverのバージョン
・適用済みUpdateやビルド番号
・利用しているREST APIバージョン
・参照しているMicrosoft Learnのドキュメント表示バージョン
・preview APIの有無管理者が確認すべき設定と運用ポイント
管理者は、APIのコードそのものよりも、組織全体でどの連携が存在するかを把握する役割が重要です。特に、個人のPATに依存した古いスクリプトは、退職・異動・権限変更で突然止まる原因になります。
管理者向けチェックリスト
| チェック項目 | 確認方法 |
|---|---|
| API連携の所有者が明確か | リポジトリ、Pipeline、社内ツール台帳を確認 |
| 個人PATに依存していないか | 認証情報の管理場所を確認 |
| 不要なプレビューAPIが残っていないか | -previewでコード検索 |
| APIバージョンが古すぎないか | api-version=でコード検索 |
| 障害時の通知先があるか | Pipeline通知、監視、ログ出力を確認 |
| 本番反映前の検証環境があるか | ステージング組織やテストプロジェクトで確認 |
APIバージョンの見直しは、セキュリティ点検や棚卸しと相性が良い作業です。単にapi-versionを書き換えるだけでなく、認証方式、権限、ログ出力、失敗時のリトライも合わせて見直すと、運用リスクを減らせます。
開発者が確認すべき実装ポイント
開発者は、APIバージョンを「リクエストごとに直書き」するのではなく、設定値として一元管理することをおすすめします。複数箇所にapi-version=7.0やapi-version=7.1-previewが散らばっていると、移行時に漏れが発生しやすくなります。
悪い例：APIバージョンを各所に直書きする
var url = $"https://dev.azure.com/{org}/_apis/projects?api-version=7.0";この書き方でも動作はしますが、複数APIに広がると変更が難しくなります。
良い例：共通設定として管理する
public static class AzureDevOpsApiSettings
{
public const string ApiVersion = "7.1";
}
var url = $"https://dev.azure.com/{org}/_apis/projects?api-version={AzureDevOpsApiSettings.ApiVersion}";さらに実務では、API領域ごとにバージョンを分けた方が安全な場合もあります。すべてのAPIが同じバージョンで同じように動くとは限らないためです。
public static class AzureDevOpsApiVersions
{
public const string Core = "7.1";
public const string WorkItemTracking = "7.1";
public const string Git = "7.1";
public const string Pipelines = "7.1-preview.1";
}previewを使う場合は、定数名やコメントで目立たせておくと、棚卸し時に見落としにくくなります。
移行時に見るべきポイント
APIバージョンの移行では、単にリクエストが成功するかだけを見るのは不十分です。実際には、レスポンスの項目、型、ページング、エラーコード、権限チェックの違いが影響することがあります。
移行テストで確認する項目
| 確認項目 | 具体的に見ること |
|---|---|
| HTTPステータス | 200、201、204だけでなく、400、401、403、404、429も確認 |
| レスポンスJSON | 必須として扱っている項目が存在するか |
| ページング | continuationTokenなどの扱いが変わっていないか |
| フィルター条件 | クエリパラメーターの解釈が変わっていないか |
| 権限 | 同じPATやOAuthスコープで取得できるか |
| エラー処理 | 失敗時にログが十分か、再試行すべきか |
| パフォーマンス | 大量データ取得時にタイムアウトしないか |
特に、JSONを厳密にクラスへマッピングしているアプリでは、レスポンス項目の追加や欠落で例外が出ることがあります。移行前後のレスポンスを保存し、差分を比較すると安全です。
curl -s "https://dev.azure.com/{organization}/_apis/projects?api-version=7.0" > before.json
curl -s "https://dev.azure.com/{organization}/_apis/projects?api-version=7.1" > after.json差分確認には、jqで整形してから比較すると見やすくなります。
jq . before.json > before.pretty.json
jq . after.json > after.pretty.json
diff before.pretty.json after.pretty.json展開時の注意点：一括変更より段階的な切り替えが安全
APIバージョンの変更は、見た目には小さな修正です。しかし、Azure DevOps REST APIはビルド、リリース、作業項目、リポジトリ、権限管理などに関わることが多く、影響範囲が広がりやすいです。
本番反映では、次の順序で進めると失敗を減らせます。
| 手順 | 実施内容 |
|---|---|
| 現状把握 | 既存コードからapi-versionと-previewを棚卸しする |
| 優先順位付け | 本番影響が大きいAPI、preview利用API、古いAPIから対応する |
| 検証 | テスト環境でレスポンス差分とエラー処理を確認する |
| 段階展開 | 一部プロジェクト、低リスクジョブから切り替える |
| 監視 | 失敗率、APIレスポンス時間、Pipeline失敗を確認する |
| 文書化 | 利用API、バージョン、認証方式、所有者を記録する |
避けたいのは、全リポジトリのapi-versionを一括置換して、そのまま本番反映することです。APIによってサポート状況やレスポンスが異なる場合があるため、最低限、主要なAPIごとに疎通確認を行いましょう。
失敗しやすいポイント
Azure DevOps REST APIのバージョン管理でよくある失敗は、技術的に難しい部分ではなく、運用上の見落としです。
api-versionが指定されていない
古いサンプルコードや社内メモをもとに作ったスクリプトでは、api-versionが抜けていることがあります。公式リファレンスでは、APIの進化によってアプリやサービスが壊れるのを避けるため、すべてのAPIリクエストでapi-versionを含めるべきと説明されています。(Microsoft Learn)
previewを正式運用で使い続ける
検証時に便利だった-previewを、そのまま本番に入れてしまうケースです。正式版が公開されたAPIでは、preview版が非推奨となり、将来的に拒否される可能性があります。(Microsoft Learn)
Azure DevOps ServicesとServerを同じ扱いにする
Azure DevOps Servicesでは使えるAPIでも、Azure DevOps Serverではバージョンや更新レベルによって使えない場合があります。オンプレミス版では、サーバーバージョンとREST APIバージョンの対応を確認する必要があります。(Microsoft Learn)
APIバージョンだけ変えてレスポンス検証をしない
HTTP 200が返っても、業務ロジックが期待する項目が変わっていれば障害になります。特に、作業項目、ビルド結果、リリース情報、承認状態などを集計しているツールでは、レスポンス差分の確認が重要です。
実務でおすすめの管理方法
APIバージョン管理を属人化させないために、次のような運用にしておくと保守しやすくなります。
API利用台帳を作る
大げさな管理表である必要はありません。最低限、次の項目を記録しておくと、更新時の影響調査が楽になります。
| 項目 | 記入例 |
|---|---|
| 利用システム | ビルド結果集計バッチ |
| 所有者 | DevOpsチーム |
| API領域 | Build、Work Item Tracking |
| エンドポイント | _apis/build/builds |
| APIバージョン | 7.1 |
| preview利用 | なし |
| 認証方式 | PATまたはOAuth |
| 実行場所 | Azure Pipelines |
| 影響範囲 | 日次レポート、Teams通知 |
preview利用を定期レビューする
月次または四半期ごとに、-previewを含むコードを検索するだけでも効果があります。
git grep -n -- "-preview"検索結果が出たら、次の順に判断します。
| 判断 | 対応 |
|---|---|
| 正式版がある | 正式版へ移行 |
| 正式版がない | 利用理由と代替策を記録 |
| 使われていない | 削除または無効化 |
| 不明 | 所有者を確認し、分からなければ検証環境で停止テスト |
APIクライアントを共通化する
複数のツールがAzure DevOps REST APIを呼び出している場合、認証、URL生成、APIバージョン、リトライ、ログ出力を共通化すると、変更に強くなります。
たとえば、共通クライアントに次の処理を持たせます。
・ベースURLの生成
・api-versionの付与
・Authorizationヘッダーの設定
・429や一時的な5xxのリトライ
・エラー時のログ出力
・preview API利用時の警告ログ小規模なスクリプトでも、URLを文字列連結で散らばらせないだけで、将来の移行コストを下げられます。
すぐに実施すべき確認アクション
Azure DevOps REST APIを使っている組織は、まず次の順番で確認してください。
- リポジトリ、Pipeline、運用スクリプトから
_apisとapi-versionを検索する api-versionが未指定のリクエストを修正する-previewを使っているAPIを一覧化する- 正式版へ移行できるAPIは、検証環境で差分確認する
- Azure DevOps Serverを使っている場合は、サーバーバージョンと対応APIバージョンを確認する
- 本番反映後に失敗率、ログ、Pipeline実行結果を確認する
- 利用API、バージョン、所有者を台帳化する
最初から完璧なAPI管理体制を作る必要はありません。まずは、api-version未指定と-preview依存をなくすことが、最も効果の高い第一歩です。
まとめ：Azure DevOps REST APIは「明示的なバージョン指定」が安全運用の基本
Azure DevOps REST APIのバージョン管理で最も重要なのは、APIバージョンを明示し、プレビュー版への依存を放置しないことです。
管理者は組織内のAPI連携を棚卸しし、開発者はコード内のapi-versionとレスポンス依存を確認しましょう。Azure DevOps Serverを利用している場合は、サーバーバージョンとREST APIバージョンの対応確認も欠かせません。
次に取るべき行動は明確です。まず、リポジトリとPipelineで_apis、api-version、-previewを検索し、どの連携がどのAPIバージョンに依存しているかを見える化してください。そこから正式版への移行、検証、段階展開を進めれば、Azure DevOps REST APIの変更に強い運用へ近づけます。
コメント