使用 REST 查询 Microsoft Graph

已完成

Microsoft Graph 是一種 RESTful Web API,可讓您存取 Microsoft 雲端服務資源。 在註冊您的應用程式並取得使用者或服務的驗證權杖之後,您可以對 Microsoft Graph API 提出要求。

Microsoft Graph API 會在 microsoft.graph的 OData 命名空間 中定義其大部分的資源、方法和列舉。 其子命名空間中定義了一些 API 集合,例如通話記錄 API,其會定義 中的 microsoft.graph.callRecords 之類的資源。

除非在對應的主題中明確指定,否則假設類型、方法和列舉都是 microsoft.graph 命名空間的一部分。

呼叫 REST API 方法

若要從資源 (例如使用者或電子郵件訊息) 讀取或寫入至資源,請建構如下列範例所示的要求:

{HTTP method} https://graph.microsoft.com/{version}/{resource}?{query-parameters}

要求的組成部分包括:

  • {HTTP method} - 在針對 Microsoft Graph 的要求上所使用的 HTTP 方法。
  • {version} - 您的應用程式正在使用的 Microsoft Graph API 版本。
  • {resource} - 您參考的 Microsoft Graph 中的資源。
  • {query-parameters} - 自訂回應的選用 OData 查詢選項或 REST 方法參數。

提出要求之後,會傳回回應,其包括:

  • 狀態碼 - 指出成功或失敗的 HTTP 狀態碼。
  • 回應訊息 - 您要求的資料或作業的結果。 某些作業的回應訊息可以是空白。
  • nextLink - 如果您的要求傳回許多資料,您必須使用 @odata.nextLink 中傳回的 URL 逐頁瀏覽。

HTTP 方法

Microsoft Graph 會使用您的要求上的 HTTP 方法來判斷您的要求正在執行的動作。 API 支援下列方法。

方法 描述
GET 從資源讀取資料。
POST 建立新資源,或執行動作。
修補檔 使用新的值更新資源。
PUT 使用新的資源取代資源。
DELETE 移除資源。
  • 對於 CRUD 方法 GETDELETE,不需要任何要求本文。
  • POSTPATCHPUT 方法需要以 JSON 格式指定的要求本文,其中包含其他資訊, 例如資源屬性的值。

版本

Microsoft Graph 目前支援兩個版本:v1.0beta

  • v1.0 包含正式提供的 API。 針對所有生產應用程式使用 v1.0 版本。
  • beta 包含目前處於預覽狀態的 API。 由於我們可能會對搶鮮版 (Beta) API 推出中斷性變更,因此建議您只使用搶鮮版 (Beta) 來測試開發中的應用程式;請勿在生產應用程式中使用搶鮮版 (Beta) API。

資源

資源可以是實體或複雜類型,通常以屬性定義。 實體與複雜類型不同,其一律包含 id 屬性。

您的 URL 會包含您在要求中互動的資源,例如 me使用者群組磁碟機網站。 通常,最上層資源也包含關聯性,您可以用來存取其他資源,例如 me/messagesme/drive。 您也可以使用方法來與資源互動;例如,若要傳送電子郵件,請使用 me/sendMail

每個資源可能需要不同的權限才能存取它。 相較於讀取資源,您通常需要較高層級的權限,才能建立或更新資源。 如需必要權限的詳細資訊,請參閱方法參考主題。

查詢參數

查詢參數可以是 OData 系統查詢選項,或是方法接受以自訂其回應的其他字串。

您可使用選用的 OData 系統查詢選項來包含比預設回應更多的或更少的屬性。 您可以針對符合自訂查詢的項目篩選回應,或為方法提供另一些參數。

例如,新增下列 filter 參數會將傳回的訊息限制為 emailAddress 屬性為 jon@contoso.com 的訊息。

GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq 'jon@contoso.com'

其他資源

以下是您可以使用 Microsoft Graph API 來建置和測試要求的一些工具連結。