共用方式為

作業概觀 | Graph API 概念

  • 發行項

Azure Active Directory (AD) Graph API 是 OData 3.0 相容性服務，您可用以讀取和修改物件，如租用戶中的使用者、群組和連絡人。 Azure AD Graph API 會公開傳送 HTTP 要求，以使用服務執行作業的 REST 端點。 下列章節提供：當您使用 Graph API 讀取和寫入目錄資源、呼叫目錄函數或動作，或對目錄執行查詢時，應如何格式化要求及預期回應中有什麼的一般資訊。 如需執行特定作業目錄資源的詳細資訊，請參閱 Azure AD Graph API 參考中合適的作業主題。

成功的 Graph API 要求必須定址在有效的端點，而且格式要正確，也就是它必須包含所有必要的標頭，且如有需要，要求主體中要有 JSON 裝載。 提出要求的應用程式必須包含接收自 Azure AD 的權杖，證明它有授權可以存取要求鎖定的目標資源。 應用程式必須能夠處理接收自 Graph API 的任何回應。

本主題中的章節會協助您了解 Graph API 使用的要求和回應格式。

重要

我們強烈建議您使用 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 (英文) 部落格文章。

驗證與授權

Graph API 的每個要求都必須附加 Azure Active Directory 所發出的持有人權杖。 權杖攜有下列資訊：應用程式、登入的使用者 (如果是委派的權限)、驗證，和應用程式獲授權在目錄上執行的作業。 要求的授權標頭中會攜帶這個權杖。 例如 (為求簡潔，已縮短權杖)︰

Authorization: Bearer eyJ0eX ... FWSXfwtQ

Graph API 會根據權杖中顯示的 OAuth 2.0 權限範圍執行授權。 如需 Graph API 公開的權限範圍詳細資訊，請參閱 Graph API Permission Scopes (Graph API 權限範圍) 。

為了讓您的應用程式能以 Azure AD 驗證並呼叫 Graph API，您必須將它加入租用戶中並設定為需要 Windows Azure Active Directory 的權限 (OAuth 2.0 權限範圍)。 如需加入及設定應用程式的資訊，請參閱整合應用程式與 Azure Active Directory。

Azure AD 使用 OAuth 2.0 驗證通訊協定。 您可以在在 Azure AD 中的 OAuth 2.0 深入了解 Azure AD 的 OAuth 2.0，包括支援的流程和存取權杖。

端點定址

為了使用 Graph API 執行作業，您要使用支援的方法 (一般是 GET、POST、PATCH、PUT 或 DELETE) 將 HTTP 要求傳送到端點，而端點的目標設為服務、資源集合、個別的資源、資源的導覽屬性，或服務公開的函數或動作。 端點是以 URL 表示。

以下說明 Graph API 端點的基本格式︰

https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}

下列元件組成 URL：

注意︰在某些情況下，在讀取資源集合時，可以在要求中加入 OData 查詢參數來篩選、排序和分頁結果集。 如需詳細資訊，請參閱本主題的 OData 查詢參數一節。

租用戶識別碼 {tenant_id}

您可以使用四種方法的其中之一指定要求的目標租用戶︰

  • 依租用戶物件識別碼。 建立租用戶時指派的 GUID。 這可以在 TenantDetail 物件的 objectId 屬性中找到。 下列 URL 顯示如何使用租用戶物件識別碼處理使用者資源集合：
    https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6。

  • 依驗證 (登錄) 的網域名稱。 租用戶登錄的其中一個網域名稱。 這些可以在 TenantDetail 物件的 verifiedDomains 屬性中找到。 下列 URL 顯示如何處理具有網域 contoso.com 的租用戶使用者資源集合：
    https://graph.windows.net/contoso.com/users?api-version=1.6。

  • 使用 myOrganization 別名。 這個別名只有在使用 OAuth 授權碼授與類型 (3-Legged) 驗證時才可使用，也就是使用委派權限範圍時才使用。 別名不區分大小寫。 可取代 URL 中的物件識別碼或租用戶網域。 使用別名時，Graph API 會從附加至要求之權杖中呈現的宣告來衍生租用戶。 下列 URL 顯示如何處理使用這個別名的租用戶使用者資源集合：
    https://graph.windows.net/myorganization/users?api-version=1.6。

  • 使用 me 別名。 這個別名只有在使用 OAuth 授權碼授與類型 (3-Legged) 驗證時才可使用，也就是使用委派權限範圍時才使用。 別名不區分大小寫。 可取代 URL 中的物件識別碼或租用戶網域。 使用別名時，Graph API 會從附加至要求之權杖中呈現的宣告來衍生使用者。 下列 URL 處理使用這個別名的已登入使用者︰
    https://graph.windows.net/me?api-version=1.6。

注意︰me 別名只以已登入使用者的作業為目標。 如需詳細資訊，請參閱 Signed-in User Operations (已登入使用者作業)。

資源路徑 {resource_path}

您以不同的方式指定 {resource_path}，視您鎖定的目標為資源集合、個別的資源、資源的導覽屬性、租用戶上公開的函數或動作，或資源上公開的函數或動作而定。

目標 路徑 說明
服務中繼資料 /$metadata 傳回服務中繼資料文件。 下列範例使用 contoso.com 租用戶以服務中繼資料為目標︰
https://graph.windows.net/contoso.com/$metadata?api-version=1.6

注意︰不需要驗證即可讀取服務中繼資料。
資源集合 /{resource_collection} 以資源集合為目標，例如租用戶中的使用者或群組。 您可以使用這個路徑來讀取集合中的資源，並根據資源類型在租用戶中建立新的資源。 在許多情況下，讀取所傳回的結果集，可以加入篩選、排序或分頁結果的查詢參數進一步精簡。 下列範例以使用者集合為目標︰
https://graph.windows.net/myorganization/users?api-version=1.6
單一資源 /{resource_collection}/{resource_id} 以租用戶中的特定資源為目標，如使用者、組織的連絡人或群組。 多數資源的 resource_id 是物件識別碼。 某些資源允許額外的規範，例如，使用者也可以依使用者主體名稱 (UPN) 指定。 根據資源，您可以使用這個路徑來取得資源的宣告屬性、修改其宣告的屬性或刪除資源。 下列範例以使用者 john@contoso.com 為目標︰
https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6
導覽屬性 (物件) /{resource_collection}/{resource_id}/{property_name} 以特定資源的導覽屬性為目標，例如使用者的管理員或群組的成員資格，或是群組的成員。 您可以使用這個路徑來傳回目標導覽屬性所參考的一或多個物件。 下列範例以 john@contoso.com 的管理員為目標︰
https://graph.windows.net/contoso.com/users/john@contoso.com/manager?api-version=1.6

注意：這種形式的定址僅供讀取。
導覽屬性 (連結) /{resource_collection}/{resource_id}/$links/{property_name} 以特定資源的導覽屬性為目標，例如使用者的管理員或群組的成員資格，或是群組的成員。 您可以使用這種定址形式來讀取和修改導覽屬性。 讀取時，此屬性所參考的物件會傳回為回應主體中的一或多個連結。 寫入時，物件會指定為要求主體中的一或多個連結。 下列範例以 john@contoso.com 的管理員屬性為目標︰
https://graph.windows.net/contoso.com/users/john@contoso.com/$links/manager?api-version=1.6
租用戶上公開的函數或動作 /{function_name} 以租用戶上公開的函數或動作為目標。 函數和動作通常是使用 POST 要求叫用，可能包含要求主體。 下列範例以 isMemberOf 函數為目標︰
https://graph.windows.net/myorganization/isMemberOf?api-version=1.6。
資源上公開的函數或動作。 /{resource_collection}/{resource_id}/{function_name} 以資源上公開的函數或動作為目標。 函數和動作通常是使用 POST 要求叫用，可能包含要求主體。 下列範例以 getMemberGroups 函數為目標︰
https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6。

Graph API 版本 {api-version}

您使用 api-version 查詢參數來以以作業的特定 Graph API 版本為目標。 這是必要參數。

api-version 參數的值可以是下列其中之一：

  • "beta"
  • "1.6"
  • "1.5"
  • "2013/11/08"
  • "2013/04/05"

例如，下列 URL 會以使用 Graph API 1.6 版的使用者集合為目標︰

https://graph.windows.net/myorganization/users?api-version=1.6

如需版本及版本間功能變更的詳細資訊，請參閱 Versioning (版本設定)。

OData 查詢參數

在許多情況下，當您讀取資源集合時，您可以將 OData 查詢參數附加至要求，來篩選、排序和分頁結果集。

Graph API 支援下列 OData 查詢參數：

  • $filter
  • $batch
  • $expand
  • $orderby
  • $top
  • $skiptoken 和前一頁

如需支援的 OData 查詢參數及其在 Graph API 中限制的詳細資訊，請參閱 Supported Queries, Filters, and Paging Options (支援的查詢、篩選和分頁選項)。

要求和回應標頭

下表顯示 Graph API 要求中常用的 HTTP 標頭。 但它並不十分詳盡。

要求標頭 說明
授權 必要。 由 Azure Active Directory 發出的承載權杖。 如需詳細資訊，請參閱本主題的驗證和授權。
Content-Type 如有要求主體則為必要。 要求主體中內容的媒體類型。 使用 application/json。 可以在參數中併入媒體類型。
注意︰支援 application/atom+xml 和 application/xml (適用於連結)，但基於效能考量兩者都不建議使用，因為未來版本不建議使用 XML 支援。
Content-Length 如有要求主體則為必要。 要求的長度 (以位元組為單位)。

下表顯示 Graph API 傳回的回應中常用的 HTTP 標頭。 但它並不十分詳盡。

回應標頭 說明
Content-Type 回應主體中內容的媒體類型。 預設值為 application/json。 使用者縮圖相片要求預設傳回 image/jpeg。
位置 在 POST 要求的回應中傳回，這些要求會在目錄中建立新的資源 (物件)。 包含新建資源的 URI。
ocp-aad-diagnostics-server-name 執行要求的作業之伺服器的識別碼。
ocp-aad-session-key 識別目錄服務目前工作階段的索引鍵。

我們建議您至少要為每個要求執行下列作業︰

  1. 記錄要求送出的正確時間戳記。
  2. 傳送和記錄 client-request-id。
  3. 記錄 HTTP 回應碼和 request-id。

當您尋求協助或支援時，在這類記錄檔中提供資訊有助於 Microsoft 疑難排解問題。

要求和回應主體

JSON 或 XML 裝載可以傳送 POST、PATCH 和 PUT 要求的要求主體。 JSON 或 XML 裝載可以傳回伺服器回應。 您可以使用 Content-Type 要求標頭在要求主體中指定裝載，使用 Accept 要求標頭在回應中指定裝載。

強烈建議您在 Graph API 要求和回應中使用 JSON 裝載。 兩者都是基於效能考量，因為未來版本不建議使用 XML。

進階功能

前面幾節討論了 Graph API 基本要求和回應的格式。 更多的進階功能可能會加入額外的查詢字串參數，或有和本主題前文中所討論的基本作業大為不同的要求和回應主體。

這些功能包括：

  • 批次處理：Graph API 支援批次處理。 以批次方式傳送要求可以減少往返伺服器的次數，降低網路負荷並有助於作業更快速完成。 如需批次處理 Graph API 的詳細資訊，請參閱批次處理。
  • 差異查詢︰Graph API 支援執行差異查詢。 差異查詢可讓您傳回租用戶中特定實體在不同時間發出之要求間的變更。 這項功能通常用於同步處理本機存放區和租用戶上的變更。 如需 Graph API 差異查詢的詳細資訊，請參閱差異查詢。

其他資源