使用 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 方法
GET
和DELETE
,不需要任何要求本文。 -
POST
、PATCH
和PUT
方法需要以 JSON 格式指定的要求本文,其中包含其他資訊, 例如資源屬性的值。
版本
Microsoft Graph 目前支援兩個版本:v1.0
和 beta
。
-
v1.0
包含正式提供的 API。 針對所有生產應用程式使用 v1.0 版本。 -
beta
包含目前處於預覽狀態的 API。 由於我們可能會對搶鮮版 (Beta) API 推出中斷性變更,因此建議您只使用搶鮮版 (Beta) 來測試開發中的應用程式;請勿在生產應用程式中使用搶鮮版 (Beta) API。
資源
資源可以是實體或複雜類型,通常以屬性定義。 實體與複雜類型不同,其一律包含 id 屬性。
您的 URL 會包含您在要求中互動的資源,例如 me
、使用者、群組、磁碟機和網站。 通常,最上層資源也包含關聯性,您可以用來存取其他資源,例如 me/messages
或 me/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 來建置和測試要求的一些工具連結。