Microsoft Graph のバージョン管理、サポートと重大な変更の方針

[アーティクル]
03/26/2023

この記事は Microsoft Graph のサポート重大な変更の方針と、現在使用可能な Microsoft Graph API のバージョンについて説明します。

サポートポリシーと廃止の情報

Microsoft Graph は Microsoft ライフサイクルポリシーに従います。

Microsoft Graph REST API と Microsoft Graph SDK の新しいバージョンがリリースされると、それ以前のバージョンは廃止されます。 Microsoft は、バージョンを廃止する少なくとも 24 か月前に非推奨として宣言します。同様に、一般に利用可能な (GA) 個々の API の場合、Microsoft は API を GA バージョンから削除する少なくとも 24 か月前に非推奨として宣言します。

API のメジャーバージョン (たとえば、v1.0 から v2.0) をインクリメントすると、現在のバージョン (この例では v1.0) が直ちに非推奨となり、発表から 24 か月後にサポートされなくなります。サービスのセキュリティと信頼性向上のためにこのポリシーを変更することがあります。

API が非推奨と指定された場合、できるだけ早く最新バージョンへ移行することを強くお勧めします。場合によっては、元の API が非推奨になった直後に、新しいアプリケーションで新しい API の使用を開始する必要があることをお知らせします。そのような場合、現在非推奨 APIを使用しているアクティブなアプリケーションのみが使用し続けることができます。

API コントラクトと非バックワード互換性の変更

Microsoft Graph にはバージョン更新の変更履歴があります。バージョン更新に伴う変更は Microsoft Graph Microsoft Graph の変更ログに表示されています。新しい機能とデータが Microsoft Graph に追加されると、API に対するバックワード互換性のない変更に対して API バージョン番号がインクリメントされます。

非バックワード互換性の変更の例を次に示します。

URL またはリソースに関する基本的な要求や応答の変更
宣言済みプロパティの型の削除、変更と、その名前の変更
API と API パラメーターの削除または名前の変更
必須の要求ヘッダーの追加

次に、下位互換性のある変更の例を示します。

Null 許容型プロパティや既定値を持つプロパティの追加
列挙型へのメンバーの追加
オープン拡張情報の削除、変更と、その名前の変更
注釈の削除、変更と、その名前の変更
既存のコレクションへのページングの導入
エラーコードの変更
プロパティの順序の変更
リソース ID のような不透明な文字列の長さまたは形式の変更

注:下位互換性のある変更の一覧は適時変更されます。独自のクライアントプロクシ (WCF クライアントなど) を作成する場合、ガイドラインとしては Microsoft Graph API サービスにあらかじめ定義されていないプロパティや派生型をクライアントアプリケーションが受け入れることができるように準備してください。 Microsoft Graph API は「Microsoft REST API ガイドライン」の「バージョン管理のモデル」セクションの説明に従っています。

バージョン

現在、以下のバージョンの Microsoft Graph API が使用できます。

ベータ版

一般に、API はベータ版でデビューし、https://graph.microsoft.com/beta エンドポイントでアクセスできます。ベータ版 API のドキュメントは、「Microsoft Graph ベータエンドポイントリファレンス」を参照してください。ベータ版には随時 API の重大な変更と廃止が発生することがあります。ベータ API に運用環境の依存関係を設定しないでください。

ベータ版の機能が現行バージョンに採用される保証はありません。 Microsoft Graph API チームがベータ機能を一般提供の準備ができていると判断した場合は、その機能を最新バージョンに追加します。機能の昇格によって現在のバージョンに破壊的変更が発生する場合は、バージョン番号がインクリメントされ、新しいバージョンが現在のバージョンになります。 Microsoft 開発者コミュニティは、 Microsoft 365 Developer Platform のアイデアフォーラムで、新機能の要求や、既存のベータ API を現在のバージョンに昇格させる要求など、機能要求を投稿できます。

現在のバージョン

Microsoft Graph の現在のバージョンは、v1.0 です。 Microsoft Graph API v1.0 バージョンは https://graph.microsoft.com/v1.0 で一般提供されており、一般的に利用可能で本番環境での運用準備が整った機能が含まれています。 v1.0 API のドキュメントを参照します。

プレビューの状態

Microsoft Graph の API または機能には、その動作がベータエンドポイントで一意であることを示す "(プレビュー)" というラベルが付けられます。

v1.0 バージョンのほとんどの API と機能の動作は、ベータ版バージョンと同等です。「プレビュー」は、次の 2 つのケースのいずれかで少数の API と機能を認定します。

ベータ版のみで利用可能
v1.0 とは異なるベータ版で利用可能

ベータ版エンドポイントの他の API と同様に、ドキュメントで「(プレビュー)」としてマークされている API は、予告なく変更が発生することがあります。運用アプリのベータエンドポイントから API にアクセスしないでください。

例として、攻撃シミュレーショントレーニングは、Microsoft 365 Defender ポータルで管理者向けに一般公開された機能です。攻撃シミュレーショントレーニング用の REST API がベータエンドポイントでのみ Microsoft Graph で使用できるようになると、REST API のドキュメントには "(プレビュー)" というラベルが付けられます。サービス自体は一般公開されていますが、Microsoft Graph の REST API とそのドキュメントには "(プレビュー)" ラベルが適用されます。

非推奨およびサポートされないバージョン

現在、Microsoft Graph には非推奨のバージョンはありません。

利用規約

Microsoft Graph API を使用すると、Microsoft API 使用条件に同意したことになります。

お客様からのフィードバックを重視しています。 Microsoft Q&A でご連絡ください。 [microsoft-graph-*] を使用して質問にタグを付けます。