バージョン | Graph API の概念
このトピックは、Azure Active Directory (AD) Graph API のエンティティおよび操作のバージョンによる相違点をまとめたものです。 api-version クエリ文字列パラメーターを要求に含めることによって、使用する操作のバージョンを指定する必要があります。 api-version パラメーターのない要求は拒否され、(400) Bad Request 応答が返されます。 使用しているサービスが旧バージョンの操作を呼び出す場合、旧バージョンの呼び出しをそのまま使用することも、コードを変更して新しいバージョンを呼び出すこともできます。 バージョンによる機能の違いについては、呼び出しを行うエンティティのドキュメントで説明されています。
重要
Azure Active Directory のリソースにアクセスするには、Azure AD Graph API ではなく Microsoft Graph を使用することを強くお勧めします。現在は Microsoft Graph を中心にして開発が進められており、Azure AD Graph API の今後の機能強化は予定されていません。Azure AD Graph API の使用が適切である場合もありますが、非常にまれです。詳細については、Office Dev Center の Microsoft Graph または Azure AD Graph ブログの記事をご覧ください。
Azure AD Graph API バージョン 1.5 以降、一般公開 (GA) バージョンの api-version パラメーターの値は数値として指定します。 次の URL は、Graph API バージョン 1.5 を使用してテナント ドメイン contoso.com のトップレベル リソースに対してクエリを実行する方法を示しています: https://graph.windows.net/contoso.com?api-version=1.5。 以前のバージョンの Graph API の場合、api-version パラメーターの値は日付の文字列として YYYY-MM-DD の形式で指定します。 次の URL は、Graph API の 2013-11-08 バージョンを使用して同じテナントのトップレベル リソースに対してクエリを実行する方法を示しています: https://graph.windows.net/contoso.com?api-version=2013-11-08。 プレビュー機能の場合、api-version パラメーターの値は、次のように文字列 "beta" を使用して指定します: https://graph.windows.net/contoso.com?api-version=beta。
API コントラクト、バージョン管理、重大な変更
クライアント アプリケーションを保護するため、API に対して重大な変更が行われた場合は、API のバージョン番号がインクリメントされます。 重要ではない変更の場合も API のバージョンがインクリメントされることがあります (たとえば、かなり大きい新機能が追加される場合)。
重大な変更とは次のような場合です。
- API または API パラメーターの削除または名前の変更
- 既存の API の動作の変更
- エラー コードおよびエラー コントラクトの変更
- 驚き最小の原則に違反するすべてのもの
注: 応答への新しい JSON フィールドの追加は、重大な変更にはなりません。 独自のクライアント プロキシを生成する開発者の場合 (WCF クライアントなど)、クライアント アプリケーションで以前の Graph API サービスでは定義されていなかったプロパティおよび派生型を受け取ることができるようにしておく必要があります。 この記事の執筆時点では、Graph API はまだ OData V4 に準拠していませんが、OData V4 仕様のモデルのバージョンに関するセクションで説明されているガイダンスには従っています。
API のメジャー バージョンがインクリメントされるときは (たとえば、1.5 から 2.0)、1.x 以前のバージョンを使用する既存クライアントのサポートはすべて非推奨になり、12 か月後にサポートされなくなることが通知されます。 詳しくは、「Microsoft Online Services のサポート ライフサイクル ポリシー」を参照してください。
サポートされているバージョン
次のバージョンの Graph API がリリースされています。
バージョン ベータ
現時点でプレビュー段階にある Graph API の機能については、「Graph API の概念」の「Preview Features (プレビュー機能)」セクション、または Graph チームのブログのいずれかで確認できます。 ベータ版の機能には、"api-version=beta" クエリ文字列パラメーターが必要です。 Graph API チームは、プレビュー機能が GA にできる状態になったと判断したら、その機能を最新の GA バージョンに追加します (または、重大な変更を構成する場合は、新しいバージョン番号にインクリメントされます)。 プレビュー機能が GA に昇格されることは保証されていません。
ベータ バージョンが重大な変更にならないように最大限の努力が払われますが、保証はされません。 ベータ バージョンを使用するクライアント アプリケーションは、重大な変更を想定しておく必要があります。 「Microsoft Azure プレビューの追加使用条件」を参照してください。
バージョン 1.6
このセクションでは、Graph API バージョン 1.6 での変更点を示します。
Graph API バージョン 1.6 では、次の機能変更が行われました。
Azure Active Directory B2C ローカル アカウント ユーザーのサポートが追加されました。 これには、User エンティティの新しいプロパティや、ローカル アカウントの Azure Active Directory B2C テナントへのサインインをサポートする新しい複合型 SignInName が含まれます。 Azure Active Directory B2C の詳細については、「Azure Active Directory B2C のドキュメント」を参照してください。
ServiceEndpoint エンティティと、Application および ServicePrincipal エンティティの serviceEndpoints ナビゲーション プロパティによるサービス検出のサポートが追加されました。
AddIn および KeyValue 型と、Application および ServicePrincipal エンティティの addIns プロパティによって使用サービスで呼び出すことができる、カスタマイズされたアプリ動作のサポートが追加されました。
TrustedCAsForPasswordlessAuth エンティティ、CertificateAuthorityInformation 型、および TenantDetail エンティティの trustedCAsForPasswordlessAuth プロパティによるパスワードのない認証のサポートが追加されました。
サインインしているユーザーがパスワードを変更するために呼び出すことができる changePassword アクションが追加されました。
Graph Client バージョン 2.1.x には Graph API バージョン 1.6、Graph Client バージョン 2.0.x には Graph API 1.5 が必要です。
エンティティの変更
| エンティティ | 変更の説明 |
|---|---|
| [アプリケーション] | addIns プロパティが追加されました。このプロパティは、使用サービスが特定のコンテキストでアプリの呼び出しに使用できるカスタムの動作を定義します。 serviceEndpoints ナビゲーション プロパティが追加されました。このプロパティには、検出で利用可能なサービス エンドポイントのコレクションが含まれます。 |
| LicenseDetail | ユーザーのライセンス詳細が含まれる新しいエンティティ。 |
| ServiceEndpoint | サービス検出情報が含まれる新しいエンティティ。 |
| ServicePrincipal | addIns プロパティが追加されました。このプロパティは、使用サービスが特定のコンテキストでアプリの呼び出しに使用できるカスタムの動作を定義します。 serviceEndpoints ナビゲーション プロパティが追加されました。このプロパティには、検出で利用可能なサービス エンドポイントのコレクションが含まれます。 |
| SubscribedSku | appliesTo プロパティが追加されました。 |
| TenantDetail | trustedCAsForPasswordlessAuth プロパティが追加されました。このプロパティには、パスワードのない認証の実行中に信頼チェーンの検証に使用される証明書機関のセットが含まれます。 |
| TrustedCAsForPasswordlessAuth | パスワードのない認証の実行中に信頼チェーンの検証に使用される証明書機関のセットを表す新しいエンティティ。 |
| User | creationType プロパティが追加されました。このプロパティは、ユーザーがローカル アカウントであることを示すために使用されます。 signInNames プロパティが追加されました。このプロパティには、Azure Active Directory B2C テナントにサインインするためにローカル アカウント ユーザーが使用するサインイン名のコレクションが含まれます。 このプロパティは、ベータ版の alternativeSignInNamesInfo から名前が変更されました。 licenseDetails ナビゲーション プロパティが追加されました。 |
複合型の変更
| 型 | 変更の説明 |
|---|---|
| AddIn | 使用サービスが特定のコンテキストでアプリの呼び出しに使用できるカスタムの動作を定義するための新しい型。 |
| CertificateAuthorityInformation | パスワードのない認証の実行中に信頼チェーンの検証に使用される証明書機関を表す新しい型。 |
| KeyValue | AddIn で指定されたアプリケーションで使用サービスが使用または呼び出すことができるパラメーターを定義するキー/値ペアが含まれる新しい型。 |
| ServicePlanInfo | appliesTo プロパティが追加されました。 provisioningStatus プロパティが追加されました。 |
| SignInName | Azure Active Directory B2C テナントにサインインするためにローカル アカウント ユーザーが使用できるサインイン名に関する情報が保持される新しい型。 この型は、ベータ版の LogonIdentifier から名前が変更されました。 |
アクションと関数の変更
| 関数 | 変更の説明 |
|---|---|
| changePassword | サインインしているユーザーがパスワードを変更するために呼び出すことができる新しいアクション。 |
バージョン 1.5
このセクションでは、Graph API バージョン 1.5 での変更点を示します。
Graph API バージョン 1.5 では、次の機能変更が行われました。
Graph API のスキーマの名前空間は、Microsoft.WindowsAzure.ActiveDirectory から Microsoft.DirectoryServices に変更されました。 これにより、Graph API によって公開されているすべてのエンティティと複合型に影響があります。
ディレクトリ スキーマ拡張機能に対するサポートが追加されました。 これにより、アプリケーションで必要なプロパティをディレクトリ オブジェクトに追加できます。 次のエンティティでスキーマ拡張機能がサポートされます: User、Group、TenantDetail、Device、Application、および ServicePrincipal。 ディレクトリ スキーマ拡張機能をサポートするために、ExtensionProperty エンティティが追加され、extensionProperties ナビゲーション プロパティが Application エンティティに追加され、サポートされるディレクトリ オブジェクトの登録済みの拡張プロパティを返すための新しい関数 getAvailableExtensionProperties が追加されました。 ディレクトリ スキーマの拡張の詳細については、「ディレクトリ スキーマ拡張機能」を参照してください。
権限の表現方法が変更され、OAuth 2.0 の概念および他の Azure コンポーネントでの表現方法とよりいっそう一致するようになりました。 Permission エンティティが削除され、OAuth2PermissionGrant エンティティに置き換えられました。 このエンティティは、OAuth 2.0 アクセス トークン スコープ クレームで到着する委任された OAuth 2.0 アクセス許可スコープを表します。 さらに、新しい AppRoleAssignment エンティティは、ユーザー、グループ、サービス プリンシパルに割り当てることができるアプリケーション ロールを表します。 2 つの関連する複合型の AppRole および OAuth2Permission も追加されました。 この変更により、Application、Group、ServicePrincipal、および User エンティティで一部のプロパティの名前が変更され、いくつかのプロパティが追加されました。
Role エンティティは DirectoryRole という名前に変更されました。
RoleTemplate エンティティは DirectoryRoleTemplate という名前に変更されました。
次の表は、このリリースで追加、変更、削除されたエンティティ、複合型、関数の一覧です。
エンティティの変更
| エンティティ | 変更の説明 |
|---|---|
| [アプリケーション] | appId プロパティが Edm.Guid から Edm.String に更新されました。 appRoles プロパティが追加されました。このプロパティには、アプリケーションが宣言できるアプリケーション ロールのコレクションが含まれます。 これらのロールはユーザー、グループ、サービス プリンシパルに割り当てることができます。 groupMembershipClaims プロパティが追加されました。このプロパティは、アプリケーションが必要とするユーザーまたは OAuth 2.0 アクセス トークンで発行される "groups" 要求を構成するビットマスクです。 ビットマスク値は、0: なし、1: セキュリティ グループと Azure AD ロール、2: 予約済み、4: 予約済みです。 ビットマスクを 7 に設定すると、サインインしているユーザーがメンバーであるすべてのセキュリティ グループ、配布グループ、Azure AD ロールが取得されます。 knownClientApplications プロパティが追加されました。このプロパティには、このリソース アプリケーションに関連付けられているクライアント アプリケーションのリストが含まれます。 既知のクライアント アプリケーションへの同意は、結合された同意ダイアログ (クライアントおよびリソースによって必要な OAuth アクセス許可スコープを示します) によってリソース アプリケーションへの暗黙の同意になります。 oauth2AllowImplicitFlow プロパティが追加されました。このプロパティは、この Web アプリケーションが OAuth2.0 の暗黙のフロー トークンを要求できるかどうかを指定します。 既定値は False です。 oauth2AllowUrlPathMatching プロパティが追加されました。このプロパティは、OAuth 2.0 トークン要求の一部として、Azure AD がアプリケーションの replyUrl に対するリダイレクト URI のパス照合を許可するかどうかを指定します。 既定値は false です。 oauth2Permissions プロパティが追加されました。このプロパティには、Web API (リソース) アプリケーションがクライアント アプリケーションに対して公開する OAuth 2.0 アクセス許可スコープのコレクションが含まれます。 これらのアクセス許可スコープは、同意中にクライアント アプリケーションに与えられます。 oauth2RequiredPostResponse プロパティが追加されました。このプロパティは、OAuth 2.0 トークン要求の一部として、Azure AD が GET 要求ではなく POST 要求を許可するかどうかを指定します。 既定値は false であり、GET 要求のみが許可されることを指定します。 requiredResourceAccess プロパティが追加されました。このプロパティは、このアプリケーションがアクセスする必要のあるリソース、および各リソースの下で必要な OAuth アクセス許可スコープおよびアプリケーション ロールのセットを指定します。 この必要なリソースの事前構成は、エンド ユーザーの同意エクスペリエンスを促進します。 extensionProperties ナビゲーション プロパティが追加されました。このプロパティには、アプリケーションに関連付けられている拡張プロパティが含まれます。 |
| AppRoleAssignment | ユーザーまたはグループがアプリケーションに割り当てられたときを記録するために使用される新しいエンティティ。 この場合、ユーザーのアプリ アクセス パネルに表示されるアプリケーション タイルになります。 このエンティティは、特定のロールのリソース アプリケーションに対する (サービス プリンシパルとしてモデル化された) 別のアプリケーションのアクセスを許可するためにも使用できます。 |
| [連絡先] | sipProxyAddress プロパティが追加されました。このプロパティは、連絡先の Voice over IP (VOIP) Session Initiation Protocol (SIP) アドレスを指定します。 |
| DirectoryObject | deletionTimestamp プロパティが追加されました。このプロパティは、ディレクトリ オブジェクトが削除された日時を示します。 復元可能なディレクトリ オブジェクトにのみ適用されます。 現時点では、Application のみでサポートされています。 |
| DirectoryRole | Role から名前が変更されました。 roleTemplateId プロパティが追加されました。 |
| DirectoryRoleTemplate | RoleTemplate から名前が変更されました。 |
| ExtensionProperty | アプリケーションが外部データ ストアを必要としないでディレクトリ オブジェクト (ユーザー、グループ、テナント詳細、デバイス、アプリケーション、サービス プリンシパル) に追加できる追加プロパティのセットを定義して使用することをアプリケーションに許可する新しいエンティティ。 |
| [グループ] | onPremisesSecurityIdentifier プロパティが追加されました。このプロパティには、オンプレミスからクラウドに同期されたグループのオンプレミス セキュリティ識別子 (SID) が含まれます。 appRoleAssignments ナビゲーション プロパティが追加されました。このプロパティは、このグループが割り当てられているアプリケーション (サービス プリンシパル) のセットを指し示します。 |
| OAuth2PermissionGrant | OAuth2.0 の委任されたアクセス許可スコープを指定する新しいエンティティ。 指定した OAuth の委任されたアクセス許可スコープは、このリソース アプリケーションを呼び出すクライアント アプリケーションによって要求される場合があります (requiredResourceAccess コレクション経由)。 このバージョンから削除された Permission エンティティを置き換えます。 |
| アクセス許可 | OAuth2PermissionGrant に名前が変更されました。 |
| ロール | DirectoryRole に名前が変更されました。 |
| RoleTemplate | DirectoryRoleTemplate に名前が変更されました。 |
| ServicePrincipal | appDisplayName プロパティが追加されました。このプロパティは、関連付けられたアプリケーションによって公開される表示名を指定します。 appRoleAssignmentRequired プロパティが追加されました。このプロパティは、Azure AD がユーザーまたはアクセス トークンをアプリケーションに発行する前にユーザーまたはグループに対する AppRoleAssignment が必要かどうかを指定します。 appRoles プロパティが追加されました。このプロパティには、関連付けられたアプリケーションによって公開されるアプリケーション ロールが含まれます。 詳細については、Application エンティティの appRoles プロパティの定義を参照してください。 oauth2Permissions プロパティが追加されました。このプロパティには、関連付けられたアプリケーションによって公開される OAuth 2.0 アクセス許可が含まれます。 詳細については、Application エンティティの oauth2Permisions プロパティの定義を参照してください。 preferredTokenSigningKeyThumbprint プロパティが追加されました。 内部使用のみに予約されています。 このプロパティに書き込んだり、それ以外で依存したりしないでください。 将来のバージョンで削除される可能性があります。 appRoleAssignedTo ナビゲーション プロパティが追加されました。このプロパティは、サービス プリンシパルが割り当てられているアプリケーションのセットを指し示します。 appRoleAssignments ナビゲーション プロパティが追加されました。このプロパティは、このサービス プリンシパルに割り当てられているプリンシパル (ユーザー、グループ、サービス プリンシパル) のセットを指し示します。 oauth2PermissionGrants ナビゲーション プロパティが追加されました。このプロパティは、このサービス プリンシパルに関連付けられているユーザー偽装許可のセットを指し示します。 permissions ナビゲーション プロパティが削除されました。 |
| TenantDetail | tenantType プロパティが削除されました。 |
| User | onPremisesSecurityIdentifier プロパティが追加されました。このプロパティには、オンプレミスからクラウドに同期されたユーザーのオンプレミス セキュリティ識別子 (SID) が含まれます。 sipProxyAddress プロパティが追加されました。このプロパティは、ユーザーの Voice over IP (VOIP) Session Initiation Protocol (SIP) アドレスを指定します。 appRoleAssignments ナビゲーション プロパティが追加されました。このプロパティは、このユーザーが割り当てられているアプリケーション (サービス プリンシパル) のセットを指し示します。 oauth2PermissionGrants ナビゲーション プロパティが追加されました。このプロパティは、このユーザーと関連付けられている OAuth 2.0 ユーザー偽装許可のセットを指し示します。 permissions ナビゲーション プロパティが削除されました。 |
複合型の変更
| 型 | 変更の説明 |
|---|---|
| AppRole | このアプリケーションを呼び出すクライアント アプリケーションによって要求できる、または指定されたいずれかのアプリケーション ロールのユーザーまたはグループにアプリケーションを割り当てるために使用できる、アプリケーション ロールを指定する新しい型。 |
| OAuth2Permission | OAuth 2.0 アクセス許可スコープを表す新しい型。 指定した OAuth 2.0 アクセス許可スコープは、このリソース アプリケーションを呼び出すクライアント アプリケーションによって要求される場合があります (requiredResourceAccess コレクション経由)。 |
| RequiredResourceAccess | このアプリケーションがアクセスする必要のある指定されたリソースの下の OAuth 2.0 アクセス許可スコープおよびアプリ ロールのセットを指定する新しい型。 |
| ResourceAccess | このアプリケーションで必要な権限を表す新しい型。 |
アクションと関数の変更
| 関数 | 変更の説明 |
|---|---|
| getAvailableExtensionProperties | ディレクトリに登録されている拡張プロパティの完全なリストを返す新しい関数。 拡張プロパティは次のエンティティで登録できます: User、Group、Device、TenantDetail、Application、および ServicePrincipal。 |
| getMemberObjects | ユーザー、連絡先、グループ、またはサービス プリンシパルが推移的にメンバーとなっているすべての Group および DirectoryRole オブジェクトを返す新しい関数。 |
| getObjectsByObjectIds | オブジェクト ID の一覧で指定されているディレクトリ オブジェクトを返す新しい関数。 オプションの types パラメーターを指定して、どのリソース コレクション (ユーザーやグループなど) を検索するかを指定することもできます。 |
| [復元] | 削除されたアプリケーションを復元できる新しいサービス アクション。 |
バージョン 2013-11-08
このセクションでは、Graph API バージョン 2013-11-08 での変更点を示します。
次の表は、このリリースで追加、変更、削除されたエンティティ、複合型、関数の一覧です。
エンティティの変更
| エンティティ | 変更の説明 |
|---|---|
| [アプリケーション] | owners ナビゲーション プロパティが追加されました。このプロパティは、アプリケーションの所有者であるディレクトリ オブジェクトのセットを指し示します。 所有者は、このオブジェクトの変更を許可されている管理者以外のユーザーのセットです。 DirectoryObject から継承されます。 |
| DeviceConfiguration | デバイスの構成を表す新しいエンティティ。 |
| DirectoryObject | createdOnBehalfOf ナビゲーション プロパティが追加されました。このプロパティは、このオブジェクトが代理として作成されたディレクトリ オブジェクトを指し示します。 createdObjects ナビゲーション プロパティが追加されました。このプロパティは、現在のオブジェクトによって作成されたディレクトリ オブジェクトのセットを指し示します。 owners ナビゲーション プロパティが追加されました。このプロパティは、現在のオブジェクトの所有者であるディレクトリ オブジェクトのセットを指し示します。 所有者は、このオブジェクトの変更を許可されている管理者以外のユーザーのセットです。 ownedObjects ナビゲーション プロパティが追加されました。このプロパティは、現在のオブジェクトによって所有されているディレクトリ オブジェクトのセットを指し示します。 重要: DirectoryObject から派生するエンティティは、そのプロパティを継承し、ナビゲーション プロパティを継承できます。 |
| [グループ] | owners ナビゲーション プロパティが追加されました。このプロパティは、グループの所有者であるディレクトリ オブジェクトのセットを指し示します。 所有者は、このオブジェクトの変更を許可されている管理者以外のユーザーのセットです。 DirectoryObject から継承されます。 |
| ロール | ownedObjects ナビゲーション プロパティが追加されました。このプロパティは、ロールによって所有されているディレクトリ オブジェクトのセットを指し示します。 DirectoryObject から継承されます。バージョン 1.5 以降では、Role エンティティが DirectoryRole という名前に変更されています。 Role の詳細については、DirectoryRole を参照してください。 |
| ServicePrincipal | appOwnerTenantID プロパティが追加されました。 autheniticationPolicy プロパティが追加されました。 内部使用のみに予約されています。 使用しないでください。 バージョン 1.5 で削除されました。 createdObjects ナビゲーション プロパティが追加されました。このプロパティは、サービス プリンシパルによって作成されたディレクトリ オブジェクトのセットを指し示します。 DirectoryObject から継承されます。 owners ナビゲーション プロパティが追加されました。このプロパティは、サービス プリンシパルの所有者であるディレクトリ オブジェクトのセットを指し示します。 所有者は、このオブジェクトの変更を許可されている管理者以外のユーザーのセットです。 DirectoryObject から継承されます。 ownedObjects ナビゲーション プロパティが追加されました。このプロパティは、サービス プリンシパルによって所有されているディレクトリ オブジェクトのセットを指し示します。 DirectoryObject から継承されます。 |
| User | immutableId プロパティが追加されました。このプロパティは、オンプレミス Active Directory ユーザー アカウントを Azure AD ユーザー オブジェクトに関連付けます。 ユーザーの userPrincipalName (UPN) プロパティでフェデレーション ドメインを使用している場合、Graph に新しいユーザー アカウントを作成するときにこのプロパティを指定する必要があります。 userType プロパティが追加されました。このプロパティは、ディレクトリ内のユーザー タイプを分類するために使用できる文字列値です (例: "Member"、"Guest")。 createdObjects ナビゲーション プロパティが追加されました。このプロパティは、ユーザーによって作成されたディレクトリ オブジェクトのセットを指し示します。 DirectoryObject から継承されます。 ownedObjects ナビゲーション プロパティが追加されました。このプロパティは、ユーザーによって所有されているディレクトリ オブジェクトのセットを指し示します。 DirectoryObject から継承されます。 |
複合型の変更
| 型 | 変更の説明 |
|---|---|
| ServicePrincipalAuthenticationPolicy | 内部使用のみに予約されています。 使用しないでください。 バージョン 1.5 で削除されました。 |
アクションと関数の変更
| 関数 | 変更の説明 |
|---|---|
| assignLicense | 追加または削除するライセンスのリストでユーザーを更新する新しいサービス アクション。 |
バージョン 2013-04-05
これは Graph API の基本バージョンです。