版本控制 | Graph API 概念
本主题概述 Azure Active Directory (AD) Graph API 实体和操作之间的版本差异。 你必须通过在请求中包含 api-version 查询字符串参数来指定想要使用的操作版本。 不含 api-version 参数的请求将被拒绝并返回 (400) 错误请求响应。 如果你的服务调用某一较旧版本的操作，则可以选择继续调用该旧版本，也可以对代码进行修改以便调用较新版本。 要对其执行调用的实体的文档中概述了各版本之间的所有功能差异。
重要
强烈建议使用 Microsoft Graph 代替 Azure AD Graph API 来访问 Azure Active Directory 资源。现在我们的开发工作将重点集中在 Microsoft Graph 上，没有计划对 Azure AD Graph API 进行进一步的改进。Azure AD Graph API 仍适用的方案数量非常有限；有关详细信息，请参阅 Office 开发人员中心中的博客文章 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 显示了如何使用 2013-11-08 版本的 Graph API 查询同一租户的顶层资源: 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 兼容，但仍遵循 Model Versioning section in the OData V4 spec（OData V4 规范中的“模型版本控制”部分）中所述的指导。
当我们增加 API 的主要版本号（例如从 1.5 到 2.0）时，我们会告知将放弃对使用早期 1.x 或更早版本的现有客户端的全面支持，并在 12 个月后不再提供支持。 有关更多详细信息，请参阅 Microsoft Online Services Support Lifecycle Policy（Microsoft 在线服务支持生命周期策略）。
支持的版本
为 Graph API 发布了以下版本。
beta 版
目前处于预览状态的 Graph API 功能可以在 Graph API 概念中的预览功能部分，或在 Graph 团队博客上找到。 Beta 功能需要 “api-version = beta” 查询字符串参数。 当 Graph API 团队认为正式版的预览功能准备就绪时，我们将向最新的正式版中添加该功能（或如果它构成重大更改，这将导致新版本号增加）。 我们不保证将预览功能提升到正式版。
对于 beta 版本，我们将尝试尽可能避免任何重大更改，但我们将不做出任何保证。 使用 beta 版本的客户端应用程序预期将会进行不时的重大更改。 请参阅 Supplemental Terms of Use for Microsoft Azure Previews（Microsoft Azure 预览版的补充使用条款）。
版本 1.6
本部分列出 Graph API 版本 1.6 发生的更改。
Graph API 版本 1.6 引入了以下功能更改：
添加了对 Azure Active Directory B2C 本地帐户用户的支持。 这包括 User 实体上的新属性和新的复杂类型 SignInName 以支持本地帐户登录到 Azure Active Directory B2C 租户。 有关 Azure Active Directory B2C 的详细信息，请参阅 Azure Active Directory B2C 文档。
增加了对服务发现的支持，该服务发现在 Application 和 ServicePrincipal 实体上具有 ServiceEndpoint 实体和 serviceEndpoints 导航属性。
增加了对自定义应用行为的支持，该行为可以通过 Application 和 ServicePrincipal 实体上具有 AddIn 和 KeyValue 类型以及 addIns 属性的使用服务调用。
增加了对无密码身份验证的支持，该身份验证在 TenantDetail 实体上具有 TrustedCAsForPasswordlessAuth 实体、CertificateAuthorityInformation 类型和 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 实体表示可分配给用户、组和服务主体的应用程序角色。 还添加了两个相关的复杂类型: 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 属性，用于指定联系人的 IP 语音 (VOIP) 会话发起协议 (SIP) 地址。 |
| DirectoryObject | 添加了 deletionTimestamp 属性，用于指示删除目录对象的时间。 它仅适用于可以还原的那些目录对象。 目前只有 Application 才支持此属性。 |
| DirectoryRole | 已从 Role 重命名。 添加了 roleTemplateId 属性 |
| DirectoryRoleTemplate | 已从 RoleTemplate 重命名。 |
| ExtensionProperty | 允许应用程序在不需要外部数据存储的情况下，定义和使用一组可添加到目录对象（用户、组、租户详细信息、设备、应用程序和服务主体）的附加属性的新实体。 |
| [组] | 添加了 onPremisesSecurityIdentifier 属性，其中包含已从本地同步到云的组的本地安全标识符 (SID)。 添加了 appRoleAssignments 导航属性，用于指向此组分配到的应用程序（服务主体）集。 |
| OAuth2PermissionGrant | 用于指定 OAuth2.0 委托权限作用域的新实体。 调用此资源应用程序的客户端应用程序可以（通过 requiredResourceAccess 集合）请求指定的 OAuth 委托权限作用域。 替换了已从此版本中删除的 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 属性，用于指定用户的 IP 语音 (VOIP) 会话发起协议 (SIP) 地址。 添加了 appRoleAssignments 导航属性，用于指向此用户分配到的应用程序（服务主体）集。 添加了 oauth2PermissionGrants 导航属性，用于指向与此用户关联的 OAuth 2.0 用户模拟授权集。 删除了 permissions 导航属性。 |
复杂类型更改
| 类型 | 更改说明 |
|---|---|
| AppRole | 用于指定调用此应用程序的客户端应用程序可请求的应用程序角色，或者可用于向某个指定的应用程序角色中的用户或组分配应用程序的新类型。 |
| OAuth2Permission | 表示 OAuth 2.0 权限作用域的新类型。 调用此资源应用程序的客户端应用程序可以（通过 requiredResourceAccess 集合）请求指定的 OAuth 2.0 权限作用域。 |
| 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 导航属性，用于指向当前对象拥有的目录对象集。 Important: 从 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 属性，这是一个字符串值，可用于对目录中的用户类型进行分类，如“成员”和“来宾”。 添加了 createdObjects 导航属性，用于指向用户创建的目录对象集。 继承自 DirectoryObject。 添加了 ownedObjects 导航属性，用于指向用户拥有的目录对象集。 继承自 DirectoryObject。 |
复杂类型更改
| 类型 | 更改说明 |
|---|---|
| ServicePrincipalAuthenticationPolicy | 保留给内部使用。 请不要使用。 已从版本 1.5 中删除。 |
操作和函数更改
| 函数 | 更改说明 |
|---|---|
| assignLicense | 使用要添加和/或删除的许可证列表更新用户的新服务操作。 |
版本 2013-04-05
这是 Graph API 的基本版本。