Azure Active Directory 圖形 APIAzure Active Directory Graph API

重要

強烈建議您使用 Microsoft Graph 取代 Azure AD Graph API 來存取 Azure Active Directory 資源。We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources. 我們的開發工作現在是針對 Microsoft Graph,並沒有針對 Azure AD Graph API 規劃的進一步增強功能 。Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API. 有極少數的案例可能仍適用 Azure AD Graph API;如需詳細資訊,請參閱 Office 開發人員中心的 Microsoft Graph 或 Azure AD Graph 部落格文章。There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

Azure Active Directory 圖形 API 支援以程式設計方式透過 REST API 端點存取 Azure AD。The Azure Active Directory Graph API provides programmatic access to Azure AD through REST API endpoints. 應用程式可以使用 Graph API,來執行有關目錄資料和物件的建立、讀取、更新及刪除 (CRUD) 作業。Applications can use the Graph API to perform create, read, update, and delete (CRUD) operations on directory data and objects. 例如,圖形 API 支援對使用者物件執行下列常見的作業:For example, the Graph API supports the following common operations for a user object:

  • 在目錄中建立新的使用者Create a new user in a directory
  • 取得使用者的詳細屬性,例如其群組Get a user’s detailed properties, such as their groups
  • 更新使用者的屬性 (例如其位置和電話號碼),或變更其密碼Update a user’s properties, such as their location and phone number, or change their password
  • 檢查使用者在角色型存取方面的群組成員資格Check a user’s group membership for role-based access
  • 停用使用者帳戶或完全刪除Disable a user’s account or delete it entirely

除了使用者物件,您也可以在其他物件上執行類似的作業,例如群組和應用程式。In addition to user objects, you can perform similar operations on other objects such as groups and applications. 若要在目錄上呼叫圖形 API,應用程式必須向 Azure AD 註冊並設定為允許存取此目錄。To call the Graph API on a directory, the application must be registered with Azure AD and be configured to allow access to the directory. 這通常是透過使用者或系統管理員同意流程來達成。This is normally achieved through a user or admin consent flow.

若要開始使用 Azure Active Directory Graph API,請參閱Graph API 快速入門指南,或檢視互動式 Graph API 參考文件To begin using the Azure Active Directory Graph API, see the Graph API Quickstart Guide, or view the interactive Graph API reference documentation.

特性Features

圖形 API 提供下列功能:The Graph API provides the following features:

  • REST API 端點:Graph API 是 RESTful 服務,由使用標準 HTTP 要求存取的端點所組成。REST API Endpoints: The Graph API is a RESTful service comprised of endpoints that are accessed using standard HTTP requests. 圖形 API 支援要求和回應的 XML 或 Javascript 物件標記法 (JSON) 內容類型。The Graph API supports XML or Javascript Object Notation (JSON) content types for requests and responses. 如需詳細資訊,請參閱 Azure AD Graph REST API 參考For more information, see Azure AD Graph REST API Reference.
  • 向 Azure AD 驗證:必須在要求的 Authorization 標頭中附加 JSON Web Token (JWT),以驗證 Graph API 的每個要求。Authentication with Azure AD: Every request to the Graph API must be authenticated by appending a JSON Web Token (JWT) in the Authorization header of the request. 您可以向 Azure AD 的權杖端點提出要求並提供有效的認證,以取得此權杖。This token is acquired by making a request to Azure AD’s token endpoint and providing valid credentials. 您可以使用 OAuth 2.0 用戶端認證流程或授權碼授與流程,以取得權杖來呼叫 Graph。You can use the OAuth 2.0 client credentials flow or the authorization code grant flow to acquire a token to call the Graph. 如需詳細資訊,請參閱 Azure AD 中的 OAuth 2.0For more information, OAuth 2.0 in Azure AD.
  • 以角色為基礎的授權 (RBAC):在 Graph API 中使用安全性群組執行 RBAC。Role-Based Authorization (RBAC): Security groups are used to perform RBAC in the Graph API. 例如,如果您想要判斷使用者是否能夠存取特定的資源,應用程式可以呼叫 檢查群組成員資格 (可移轉) 作業,它會傳回 true 或 false。For example, if you want to determine whether a user has access to a specific resource, the application can call the Check Group Membership (transitive) operation, which returns true or false.
  • 差異查詢:如果您想要檢查目錄在兩段時間之間的變更,但不想對 Graph API 進行頻繁的查詢,您可以提出差異查詢要求。Differential Query: If you want to check for changes in a directory between two time periods without having to make frequent queries to the Graph API, you can make a differential query request. 此類型的要求只會傳回前一個差異查詢要求與目前要求之間所做的變更。This type of request will return only the changes made between the previous differential query request and the current request. 如需詳細資訊,請參閱 Azure AD Graph API 差異查詢For more information, see Azure AD Graph API Differential Query.
  • 目錄延伸模組:如果您正在開發的應用程式需要讀取或寫入目錄物件的唯一屬性,您可以使用 Graph API 註冊並使用延伸模組值。Directory Extensions: If you are developing an application that needs to read or write unique properties for directory objects, you can register and use extension values by using the Graph API. 例如,如果應用程式需要每個使用者都有 Skype ID 屬性,您可以在目錄中註冊新的屬性,每個使用者物件上就會有此屬性。For example, if your application requires a Skype ID property for each user, you can register the new property in the directory and it will be available on every user object. 如需詳細資訊,請參閱 Azure AD Graph API 目錄結構描述延伸模組For more information, see Azure AD Graph API Directory Schema Extensions.
  • 受權限範圍保護:AAD 圖形 API 會公開權限範圍,以啟用 AAD 資料的安全/同意存取,並支援各種用戶端應用程式類型,包括︰Secured by permission scopes: AAD Graph API exposes permission scopes that enable secure/consented access to AAD data, and support a variety of client app types, including:

    • 透過登入使用者 (委派) 授權,指定具有資料委派存取權之使用者介面的類型those with a user interface which are given delegated access to data via authorization from the signed-in user (delegated)
    • 使用服務/服務精靈用戶端 (應用程式角色) 等應用程式定義角色型存取控制的類型those that use application-define role-based access control such as service/daemon clients (app roles)

      委派和應用程式角色權限範圍都代表圖形 API 公開的權限,而且用戶端應用程式可以透過應用程式註冊權限要求它們 (Azure 入口網站中的功能)。Both delegated and app role permission scopes represent a privilege exposed by the Graph API and can be requested by client applications through application registration permissions features in the Azure portal. 用戶端可以驗證被授與的權限範圍:檢查委派權限的存取權杖中所收到的範圍 ("scp") 宣告,和應用程式角色權限的角色 (“roles”) 宣告。Clients can verify the permission scopes granted to them by inspecting the scope (“scp”) claim received in the access token for delegated permissions and the roles (“roles”) claim for app role permissions. 深入了解 Azure AD 圖形 API 權限範圍Learn more about Azure AD Graph API Permission Scopes.

案例Scenarios

圖形 API 支援許多應用程式案例。The Graph API enables many application scenarios. 以下是最常見的案例:The following scenarios are the most common:

  • 企業營運 (單一租用戶) 應用程式:在此案例中,企業開發人員任職於具有 Office 365 訂用帳戶的組織中。Line of Business (Single Tenant) Application: In this scenario, an enterprise developer works for an organization that has an Office 365 subscription. 開發人員正在建置的 Web 應用程式會與 Azure AD 互動來執行工作,例如指派授權給使用者。The developer is building a web application that interacts with Azure AD to perform tasks such assigning a license to a user. 這項工作需要存取圖形 API,所以開發人員在 Azure Ad 中註冊單一租用戶應用程式,並設定圖形 API 的讀取和寫入權限。This task requires access to the Graph API, so the developer registers the single tenant application in Azure AD and configures read and write permissions for the Graph API. 然後,將應用程式設定為使用它自己的認證,或目前登入之使用者的認證,以取得權杖來呼叫圖形 API。Then the application is configured to use either its own credentials or those of the currently sign-in user to acquire a token to call the Graph API.
  • 軟體即服務應用程式 (多租用戶):在此案例中,獨立軟體廠商 (ISV) 正在開發託管的多租用戶 Web 應用程式,目的是為使用 Azure AD 的其他組織提供使用者管理功能。Software as a Service Application (Multi-Tenant): In this scenario, an independent software vendor (ISV) is developing hosted multi-tenant web application that provides user management features for other organizations that use Azure AD. 這些功能需要存取目錄物件,所以此應用程式需要呼叫圖形 API。These features require access to directory objects, and so the application needs to call the Graph API. 開發人員在 Azure AD 中註冊此應用程式,將它設定為需要圖形 API 的讀取和寫入權限,然後啟用外部存取,讓其他組織同意在其目錄中使用此應用程式。The developer registers the application in Azure AD, configures it to require read and write permissions for the Graph API, and then enables external access so that other organizations can consent to use the application in their directory. 當另一個組織中的使用者第一次向應用程式驗證時,就會出現同意對話方塊及此應用程式所要求的權限。When a user in another organization authenticates to the application for the first time, they are shown a consent dialog with the permissions the application is requesting. 同意之後,就會給予所要求的權限,讓應用程式在使用者的目錄中存取圖形 API。Granting consent will then give the application those requested permissions to the Graph API in the user’s directory. 如需同意架構的詳細資訊,請參閱 同意架構的概觀For more information on the consent framework, see Overview of the Consent Framework.

另請參閱See Also

Azure AD Graph API 快速入門指南Azure AD Graph API Quickstart Guide

AD Graph REST 文件AD Graph REST documentation

Azure Active Directory 開發人員指南Azure Active Directory developer's guide