共用方式為

版本設定 | Graph API 概念

  • 發行項

本主題摘要說明 Azure Active Directory (AD) Graph API 實體和作業的版本差異。 您必須在要求中包含 api-version 查詢字串參數，以指定您要使用的操作版本。 不含 api-version 參數的要求會遭到拒絕，且會傳回「(400) 不正確的要求」****回應。 如果您的服務呼叫舊版作業，您可以選擇繼續呼叫該較舊版本，或是修改程式碼呼叫較新的版本。 您執行呼叫的實體的相關文件中，描述版本之間的任何功能差異。

重要

我們強烈建議您使用 Microsoft Graph 來存取 Azure Active Directory 資源，而不是使用 Azure AD Graph API。我們目前致力於開發 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 示範如何使用 Graph API 2013-11-08 版查詢同一個租用戶的最上層資源：https://graph.windows.net/contoso.com?api-version=2013-11-08。 如需預覽功能，如下所示使用字串 "beta" 來指定 api-version 參數值：https://graph.windows.net/contoso.com?api-version=beta

API 合約、版本控制和重大變更

我們會增加應用程式開發介面，任何重大變更的應用程式開發介面版本號碼以保護用戶端應用程式。 我們可以選擇增加太 (例如，如果我們加入一些相當龐大的新功能) 的非中斷變更的 API 版本。

因此，構成一項重大變更？

  • 移除或重新命名應用程式開發介面或應用程式開發介面參數
  • 現有的應用程式開發介面的行為變更
  • 錯誤碼中的變更&錯誤合約
  • 任何違反最小驚訝原則的項目

注意：將新 JSON 欄位新增至回應不會構成一項重大變更。 我們的指引開發人員產生自己的用戶端 proxy (例如 WCF 用戶端) 是用戶端應用程式應該準備好接收屬性和 Graph API 服務之前未定義的衍生型別。 雖然在撰寫本文時，Graph API 與 OData V4 尚不相容，但其仍遵循本指南中所述 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 Team Blog (圖形團隊部落格) 中找到。 搶鮮版 (Beta) 版功能需要 “api-version=beta” 查詢字串參數。 當圖形 API 團隊認為預覽功能可供 GA，我們會將該功能新增至最新的 GA 版本 (或如果構成中斷變更，這會導致遞增的新版本號碼)。 我們讓預覽功能將會升級至 GA 不保證

Beta 版中，我們將會嘗試避免盡可能，任何重大變更，但是我們將不提供任何保證。 使用 beta 版的用戶端應用程式應不時預期的重大變更。 請參閱 Microsoft Azure 預覽版增補使用條款。

1.6 版

本節列出 Graph API 1.6 版的變更。

Graph API 1.6 版引進下列功能變更：

實體變更

實體 變更描述
[應用程式] 加入 addIns 屬性，定義取用服務可用來在特定內容中呼叫應用程式的自訂行為。

加入 serviceEndpoints 導覽屬性，其中包含可供探索的服務端點集合。
LicenseDetail 新的實體包含使用者的授權詳細資料。
ServiceEndpoint 新實體包含服務探索資訊。
ServicePrincipal 加入 addIns 屬性，定義取用服務可用來在特定內容中呼叫應用程式的自訂行為。

加入 serviceEndpoints 導覽屬性，其中包含可供探索的服務端點集合。
SubscribedSku 加入 appliesTo 屬性。
TenantDetail 加入 trustedCAsForPasswordlessAuth 屬性，可執行無密碼驗證時用來驗證信任鏈結的一組憑證授權單位。
TrustedCAsForPasswordlessAuth 新實體代表執行無密碼驗證時要驗證信任鏈結的一組憑證授權單位。
User 加入 creationType 屬性，用來指出使用者為本機帳戶。

加入 signInNames 屬性，其中包含由本機帳戶使用者所使用以登入 Azure Active Directory B2C 租用戶的登入名稱集合。 此屬性在搶鮮版 (Beta) 中從 alternativeSignInNamesInfo 重新命名。

加入 licenseDetails 導覽屬性。

複雜類型變更

類型 變更描述
AddIn 新類型用來定義取用服務可用來在特定內容中呼叫應用程式的自訂行為。
CertificateAuthorityInformation 新類型代表執行無密碼驗證時用來驗證信任鏈結的憑證授權單位。
KeyValue 新類型包含索引鍵/值組，定義取用服務可對 AddIn 中指定的應用程式使用或呼叫的參數。
ServicePlanInfo 加入 appliesTo 屬性。

加入 provisioningStatus 屬性。
SignInName 新的類型保留關於可以由本機帳戶使用者用來登入 Azure Active Directory B2C 租用戶的登入名稱資訊。 此類型已從搶鮮版 (Beta) 中的 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 是否允許根據應用程式的回覆 URL 來比對重新導向 URI 的路徑。 預設值為 false。

加入 oauth2Permissions 屬性，其中包含 Web API (資源) 應用程式公開給用戶端應用程式的 OAuth 2.0 權限範圍集合。 這些權限範圍可以在同意期間授與用戶端應用程式。

加入 oauth2RequiredPostResponse 屬性，在 OAuth 2.0 權杖要求中指定 Azure AD 是否允許 POST 要求，而不是 GET 要求。 預設值是 false，指定只允許 GET 要求。

加入 requiredResourceAccess 屬性，指定此應用程式需要存取的資源，以及它在每個資源下所需的一組 OAuth 權限範圍和應用程式角色。 這樣預先設定必要的資源存取權可決定使用者的同意體驗。

加入 extensionProperties 導覽屬性，其中包含與應用程式建立關聯的擴充功能屬性。
AppRoleAssignment 當使用者或群組指派給應用程式時用來記錄的新實體。 在此情況下，將會導致使用者的應用程式存取面板上顯示應用程式磚。 此實體也可用來授權另一個應用程式 (模擬成服務主體) 以特定的角色存取資源應用程式。
Contact 加入 sipProxyAddress 屬性，指定連絡人的 voice over IP (VOIP) 工作階段初始通訊協定 (SIP) 位址。
DirectoryObject 加入 deletionTimestamp 屬性，指出刪除目錄物件的時間。 僅適用於可還原的目錄物件。 目前只有 Application 支援此屬性。
DirectoryRole 從角色重新命名。

加入 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) 工作階段初始通訊協定 (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 可傳回物件識別碼清單中指定之目錄物件的新函數。 您也可以指定選擇性 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。 如需角色的資訊，請參閱 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 的基本版本。

其他資源