この記事では、データベース移動アプリケーション プログラミング インターフェイス (API) のバージョン管理と重大な変更ポリシーの概要について説明します。
サポートおよび廃止に関する情報
Microsoft が新しいバージョンの REST API をリリースすると、以前のバージョンは廃止されます。 Microsoft では、API エンドポイントを廃止する少なくとも 6 か月前に非推奨のバージョンを宣言しています。
API のバージョン番号 (例: v1 から v2) を増やすと、Microsoft は、最下位バージョン (この例では v1) が直ちに非推奨となり、お知らせの 6 か月後にサポートが終了することを発表します。 ただし、Microsoft はサービスの正常性およびセキュリティ問題に対するこのポリシーの例外を作成する可能性があります。
Microsoft が API を非推奨としてマークすると、 VersionEOL (バージョン の有効期間) フィールドに日付値が入力されます。 このフィールドを事前に監視し、今後の変更を計画できます。
互換性のある重大な変更
Microsoft では、プライベート プレビュー グループでの API の変更の詳細を提供します。 変更が重大でない場合、API のバージョン番号は変わりません。 変更が中断している場合、Microsoft は API バージョン番号をインクリメントします。
重大な変更の例を次に示します。
- URL または基本的な要求または応答が変更されます。
- 宣言されたプロパティが削除または名前変更されたか、またはタイプが変更されています。
- API または API パラメーターは削除されるか、名前変更されます。
- 必要な要求パラメーターが追加されます。
中断されない変更の例を次に示します。
- nullable または既定値を持つプロパティが追加されます。
- 列挙にメンバーが追加されます。
- ページングが既存のコレクションに導入されます。
- エラーコードが変更されます。
- 要求または応答のプロパティの順序が変更されます。
応答契約での VersionEOL の例
次の例は、JavaScript Object Notation (JSON) 形式の応答契約を示します。 すべての応答コントラクトには VersionEOL プロパティが含まれています。このプロパティの既定値は、Microsoft .NET Framework の DateMax() です。 アプリケーションは、Microsoft からの応答でこのフィールドの値を監視して、Microsoft が特定のエンドポイントまたは API バージョン全体を非推奨にしたときにすぐにアラートを受け取ることができます。
{
"IsSuccess": true,
"OperationActivityId": "55eb4327-9346-4c7b-82bd-fe8ef15112c6",
"ErrorMessage": null,
"VersionEOL": "9999-12-31T23:59:59.9999999"
}