Azure Active Directory 圖形 APIAzure Active Directory Graph API

重要

從 2019 年 2 月起,我們展開了將某些舊版 Azure Active Directory Graph API 汰換為 Microsoft Graph API 的程序。As of February 2019, we started the process to deprecate some earlier versions of Azure Active Directory Graph API in favor of the Microsoft Graph API.

如需詳細資料、更新及時間範圍,請參閱 Office 開發人員中心的 Microsoft Graph 或 Azure AD GraphFor details, updates, and time frames, see Microsoft Graph or the Azure AD Graph in the Office Dev Center.

應用程式於未來皆應該使用 Microsoft Graph API。Moving forward, applications should use the Microsoft Graph API.

本文適用於 Azure AD Graph API。This article applies to Azure AD Graph API. 如需與 Microsoft Graph API 相關的類似資訊,請參閱使用 Microsoft Graph APIFor similar info related to Microsoft Graph API, see Use the Microsoft Graph API.

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

此外,您也可以在其他物件上執行類似的作業,例如群組和應用程式。Additionally, you can perform similar operations on other objects such as groups and applications. 若要在目錄上呼叫 Azure AD 圖形 API,應用程式必須向 Azure AD 註冊。To call Azure AD Graph API on a directory, your application must be registered with Azure AD. 您還必須對應用程式授與 Azure AD 圖形 API 的存取權。Your application must also be granted access to Azure AD Graph API. 此存取權通常是透過使用者或系統管理員同意流程來實現。This access is normally achieved through a user or admin consent flow.

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

功能Features

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

  • REST API 端點:Azure AD Graph API 是 RESTful 服務,由使用標準 HTTP 要求存取的端點所組成。REST API Endpoints: Azure AD Graph API is a RESTful service comprised of endpoints that are accessed using standard HTTP requests. Azure AD 圖形 API 支援要求和回應的 XML 或 Javascript 物件標記法 (JSON) 內容類型。Azure AD 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),以驗證 Azure AD Graph API 的每個要求。Authentication with Azure AD: Every request to Azure AD 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) :在 Azure AD Graph API 中使用安全性群組執行 RBAC。Role-Based Authorization (RBAC): Security groups are used to perform RBAC in Azure AD 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.

  • 差異查詢:差異查詢可讓您追蹤兩段時間之間的目錄變更,而不必對 Azure AD Graph API 進行頻繁的查詢。Differential Query: Differential query allows you to track changes in a directory between two time periods without having to make frequent queries to Azure AD Graph API. 此類型的要求只會傳回前一個差異查詢要求與目前要求之間所做的變更。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.

  • 目錄擴充:您可以將自訂屬性新增至目錄物件,而不需要用到外部資料存放區。Directory Extensions: You can add custom properties to directory objects without requiring an external data store. 例如,如果應用程式需要每個使用者都有 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 for use on every user object. 如需詳細資訊,請參閱 Azure AD Graph API 目錄結構描述延伸模組For more information, see Azure AD Graph API directory schema extensions.

  • 受權限範圍保護:Azure AD Graph API 會公開權限範圍,以供使用 OAuth 2.0 安全存取 Azure AD 資料。Secured by permission scopes: Azure AD Graph API exposes permission scopes that enable secure access to Azure AD data using OAuth 2.0. 其支援各種用戶端應用程式類型,包括︰It supports a variety of client app types, including:

    • 透過登入使用者 (委派) 授權而獲得資料委派存取權的使用者介面user interfaces that are given delegated access to data via authorization from the signed-in user (delegated)

    • 未顯示登入使用者而在背景中作業,並使用應用程式所定義的角色型存取控制服務/精靈應用程式service/daemon applications that operate in the background without a signed-in user being present and use application-defined role-based access control

      委派和應用程式權限都代表 Azure AD 圖形 API 公開的權限,而且用戶端應用程式可以透過應用程式註冊權限要求它們 (Azure 入口網站中的功能)。Both delegated and application permissions represent a privilege exposed by the Azure AD Graph API and can be requested by client applications through application registration permissions features in the Azure portal. Azure AD Graph API 權限範圍會提供可供用戶端應用程式使用的權限資訊。Azure AD Graph API permission scopes provides information on what's available for use by your client application.

案例Scenarios

Azure AD 圖形 API 支援許多應用程式案例。Azure AD 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 as assigning a license to a user. 這項工作需要存取 Azure AD 圖形 API,所以開發人員在 Azure Ad 中註冊單一租用戶應用程式,並設定 Azure AD 圖形 API 的讀取和寫入權限。This task requires access to the Azure AD Graph API, so the developer registers the single tenant application in Azure AD and configures read and write permissions for Azure AD Graph API. 然後,將應用程式設定為使用它自己的認證,或目前登入的使用者認證,以取得權杖來呼叫 Azure AD 圖形 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 Azure AD Graph API.
  • 軟體即服務應用程式 (多租用戶) :在此案例中,獨立軟體廠商 (ISV) 正在開發託管的多租用戶 Web 應用程式,目的是為使用 Azure AD 的其他組織提供使用者管理功能。Software as a Service Application (Multi-Tenant): In this scenario, an independent software vendor (ISV) is developing a hosted multi-tenant web application that provides user management features for other organizations that use Azure AD. 這些功能需要存取目錄物件,所以此應用程式需要呼叫 Azure AD 圖形 API。These features require access to directory objects, so the application needs to call the Azure AD Graph API. 開發人員在 Azure AD 中註冊此應用程式,將它設定為需要 Azure AD 圖形 API 的讀取和寫入權限,然後啟用外部存取,讓其他組織同意在其目錄中使用此應用程式。The developer registers the application in Azure AD, configures it to require read and write permissions for Azure AD 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. 同意之後,就會給予所要求的權限,讓應用程式在使用者的目錄中存取 Azure AD 圖形 API。Granting consent will then give the application those requested permissions to Azure AD Graph API in the user’s directory. 如需同意架構的詳細資訊,請參閱 同意架構的概觀For more information on the consent framework, see Overview of the consent framework.

後續步驟Next steps

若要開始使用 Azure Active Directory Graph API,請參閱下列主題:To begin using the Azure Active Directory Graph API, see the following topics: