Microsoft 圖形 API 提供跨 Microsoft 365 服務資源的變更通知,包括 Microsoft Entra ID、Teams、Outlook 和 OneDrive。 透過 Azure 事件方格 訂閱這些事件,你可以建立即時回應資源變動的事件驅動應用程式。
本文說明如何:
- 建立Microsoft 圖形 API 訂用帳戶,以將事件傳遞至 Azure 事件方格合作夥伴主題。
- 使用自動更新來管理訂用帳戶生命週期。
- 利用事件網格的過濾與路由功能,將事件導向多個目的地。
Azure 事件方格 提供數個優點,相較於傳統 Webhook 型 Microsoft 圖形 API 訂閱:
- 簡化路由:使用單一圖形 API 訂用帳戶將事件傳送至多個目的地。
- 進階篩選:根據事件屬性將特定事件類型路由傳送至不同的應用程式。
- 標準合規性:以 CloudEvents 格式接收事件,以獲得更佳的互作性。
- 可靠性:內建的重試邏輯和死信佇列可以確保可靠的事件傳遞。
所支援的事件來源
下表列出了你可以透過 圖形 API 取得事件的事件來源。 對於大多數資源,圖形 API 支援宣告其建立、更新與刪除的事件。 如需可作為事件來源來引發事件之資源的詳細資訊,請參閱 Microsoft 圖形 API 變更通知所支援的資源。
| Microsoft 事件來源 | 資源 | 可用的事件類型 |
|---|---|---|
| Microsoft Entra ID | 使用者、群組 | Microsoft Entra ID 事件類型 |
| Microsoft Outlook | 事件 (行事曆會議)、訊息 (電子郵件)、聯絡人 | Microsoft Outlook 事件類型 |
| Microsoft 團隊 | ChatMessage、CallRecord (會議) | Microsoft Teams 事件類型 |
| OneDrive | DriveItem | Microsoft OneDrive 事件 |
| Microsoft SharePoint | 清單 | Microsoft SharePoint 事件 |
| 待辦事項 | 待辦工作 | Microsoft ToDo 事件 |
| 安全性警示 | 警報 | Microsoft 安全性警示事件 |
| 雲端列印 | 印表機、列印工作定義 | Microsoft Cloud 列印事件 |
| Microsoft對話 | 交談 | Microsoft 365 群組交談事件 |
建立 Microsoft 圖形 API 訂用帳戶,讓圖形 API 事件流向合作夥伴主題。 圖形 API 在你建立訂閱時會自動建立合作夥伴主題。 使用該合作夥伴主題 來建立事件訂閱 ,將您的事件傳送至任何最符合您處理事件需求的支援 事件處理程式 。
重要事項
如果您不熟悉 合作夥伴事件 功能,請參閱 合作夥伴事件概觀。
為什麼要透過 Event Grid 訂閱來自 Microsoft 圖形 API 來源的事件?
除了透過事件網格訂閱 Microsoft 圖形 API 事件外,你還有其他方式可以接收類似通知(非事件)。 如果您至少符合下列其中一項需求,請使用 Microsoft 圖形 API 將事件傳遞至事件方格:
- 您正在開發事件驅動解決方案,其會使用來自 Microsoft Entra ID、Outlook 或 Teams 的事件來響應資源變更。 您需要事件方格提供的健全事件驅動模型和發佈-訂閱功能。 如需事件格線的概觀,請參閱事件格線概念。
- 你想用 Event Grid 透過單一 圖形 API 訂閱,將事件導向多個目的地,並且避免管理多個 圖形 API 訂閱。
- 您必須根據事件中的某些屬性,將事件路由傳送至不同的下游應用程式、Webhook 或 Azure 服務。 例如,您可能需要將如
Microsoft.Graph.UserUpdated和Microsoft.Graph.UserDeleted等事件種類路由至處理使用者上線和下線的特殊應用程式。 例如,您也可以將Microsoft.Graph.UserUpdated事件傳送至另一個同步聯絡人資訊的應用程式。 當你使用 Event Grid 作為通知目的地時,只需訂閱單一 圖形 API 即可達成此目標。 如需詳細資訊,請參閱事件篩選和事件處理常式。 - 互通性對您來說至關重要。 你希望透過使用 Cloud Native Computing Foundation(CNCF) CloudEvents 規範標準,以標準方式轉發並處理事件。
- 您重視 CloudEvents 所提供的擴充性支援。 例如,若要跨相容系統追蹤事件,請使用 CloudEvents 延伸模組 分散式追蹤。 深入瞭解 CloudEvents 擴充功能。
- 你使用業界採用的經過驗證的事件導向方法。
啟用 圖形 API 事件以流向您的合作夥伴主題
使用 Microsoft 圖形 API 軟體開發工具套件 (SDK) 建立圖形 API 訂用帳戶,並 遵循本節中提供的範例連結中的步驟 ,要求Microsoft 圖形 API 將事件轉送至事件方格合作夥伴主題。 如需可用的 SDK 支援,請參閱 Microsoft 圖形 API SDK 支援的語言。
一般先決條件
在實作應用程式建立及續訂 Microsoft 圖形 API 訂閱前,請確保你符合以下一般前提條件:
熟悉訂閱 合作夥伴活動的高層次步驟。 如同該文章所述,在建立 圖形 API 訂閱前,請依照以下步驟操作:
使用您的 Azure 訂用帳戶註冊事件方格資源提供者。
授權 Microsoft Grap API (合作夥伴) 在您的資源群組中建立合作夥伴主題。
具備 Microsoft 圖形 API 通知的運用知識。 作為學習的一部分,你可以使用 圖形 API Explorer 建立 圖形 API 訂閱。
了解合作夥伴事件概念。
識別您要接收系統狀態變更事件的 Microsoft 圖形 API 資源。 如需詳細資訊,請參閱 Microsoft 圖形 API 變更通知。 例如,要追蹤 Microsoft Entra ID 中使用者的變更,請使用使用者資源。 使用群組來追蹤使用者群組的變更。
在 Microsoft 365 租用戶上擁有租用戶系統管理員帳戶。 加入 Microsoft 365 開發人員計劃,免費取得開發租戶。
您會找到其他所選程式設計語言專屬的必要條件,以及您在下一節中所找到 Microsoft 圖形 API 範例連結中使用的開發環境。
重要事項
雖然詳細的實作說明可在「範例詳細說明」章節中找到,但請閱讀本文所有章節,因為其中包含更多關於使用 Event Grid 轉發 Microsoft 圖形 API 事件的重要資訊。
如何建立 Microsoft 圖形 API 訂用帳戶
當你建立 圖形 API 訂閱時,系統會為你建立一個合作夥伴主題。 你在 notificationUrl 參數中傳遞以下資訊,指定要建立並關聯到新 圖形 API 訂閱的合作夥伴主題:
- 合作夥伴主題名稱
- 合作夥伴主題的資源群組名稱
- 區域 (位置)
- Azure 訂用帳戶
這些程式代碼範例示範如何建立圖形 API 訂用帳戶。 它們包括建立訂用帳戶的範例,以便在建立、更新或刪除 Microsoft Entra ID 租用戶中的所有使用者時接收來自這些使用者的事件。
POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
"changeType": "Updated,Deleted",
"notificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
"lifecycleNotificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
"resource": "users",
"expirationDateTime": "2026-08-31T00:00:00Z",
"clientState": "secretClientValue"
}
changeType:您想要接收事件的資源變更類型。 有效值:Updated且Deleted(Created不支援 圖形 API;詳情請參閱 圖形 API 文件)。 您可以指定一或多個以逗號分隔的值。notificationUrl:用來定義要傳送事件的合作夥伴主題的 URI。 其必須符合下列模式:EventGrid:?azuresubscriptionid=<you-azure-subscription-id>&resourcegroup=<your-resource-group-name>&partnertopic=<the-name-for-your-partner-topic>&location=<the-Azure-region-name-where-you-want-the-topic-created>。 要取得該位置(也稱為 Azure 區域),name請執行指令az account list-locations。 請勿使用位置顯示名稱。 例如,請勿使用美國中西部。 請改用westcentralus。az account list-locationslifecycleNotificationUrl:用來定義合作夥伴主題的 URI,microsoft.graph.subscriptionReauthorizationRequired事件會傳送至該主題。 此事件會向您的應用程式發出圖形 API 訂用帳戶即將到期的訊號。 若使用 Event Grid 作為生命週期事件的目的地,URI 的模式與先前描述的 notificationUrl 相同。 在此情況下,合作夥伴主題應該與 notificationUrl 中所指定的主題相同。resource:產生宣告狀態變化事件的資源。expirationDateTime:訂閱到期時間,事件流程停止。 必須符合 徵求意見書(RFC)3339 中規定的格式。 您必須指定一個在 每種資源類型允許的最大訂閱期限內的到期時間。clientState:使用此選用屬性來驗證事件傳遞期間對事件處理程式的呼叫。 如需詳細資訊,請參閱圖形 API 訂用帳戶屬性。
重要事項
合作夥伴主題名稱在相同的 Azure 區域內必須是唯一的名稱。 每個租用戶應用程式識別碼組合最多可以建立 10 個唯一的合作夥伴主題。
在開發解決方案時,請留意特定圖形 API 資源的服務限制。
沒有
lifecycleNotificationUrl屬性的現有圖形 API 訂用帳戶不會接收到生命週期事件。 若要新增lifecycleNotificationUrl屬性,請刪除現有的訂閱,然後建立新的訂閱,並在建立訂閱時指定該屬性。
建立圖形 API 訂用帳戶之後,您就已在 Azure 上建立合作夥伴主題。
續約 Microsoft 圖形 API 訂用帳戶
請在 圖形 API 訂閱到期之前更新訂閱,以避免停止事件流。 為了協助自動化續約流程,Microsoft 圖形 API 支援應用程式可訂閱的生命週期通知事件。 目前,所有類型的 Microsoft 圖形 API 資源都支援該microsoft.graph.subscriptionReauthorizationRequired事件,當發生以下任一條件時會發送事件:
- 存取權快到期了。
- 圖形 API 訂閱即將到期。
- 租用戶系統管理員已撤銷應用程式讀取資源的權限。
如果圖形 API 訂用帳戶在到期後未更新,請建立新的 圖形 API 訂用帳戶。 只要該訂閱過期未滿 30 天,你就可以沿用該過期訂閱所使用的相同合作夥伴主題。 如果圖形 API 訂用帳戶已過期超過 30 天,您就無法重複使用現有的合作夥伴主題。 在這種情況下,你需要指定另一個合作夥伴主題名稱。 或者,您可以刪除現有的合作夥伴主題,以在建立圖形 API 訂用帳戶期間建立具有相同名稱的新合作夥伴主題。
如何續約 Microsoft 圖形 API 訂用帳戶
當你的應用程式收到microsoft.graph.subscriptionReauthorizationRequired事件時,應該會續約 圖形 API 訂閱:
如果你在建立 圖形 API 訂閱時,在 clientState 屬性中提供了客戶端秘密,事件中就會包含該客戶端秘密。 驗證事件的 clientState 符合您在建立圖形 API 訂用帳戶時所使用的值。
請確定應用程式具有有效的存取權杖,以採取下一個步驟。 接下來附 有詳細說明的範例 部分會提供更多資訊。
呼叫下列兩個 API 的其中一個。 如果 API 呼叫成功,就會繼續變更通知流程。
呼叫
/reauthorize動作,以重新授權訂閱,而不延長訂閱到期日。POST https://graph.microsoft.com/beta/subscriptions/{id}/reauthorize執行一般「續約」動作,以重新授權並同時續約訂閱。
PATCH https://graph.microsoft.com/beta/subscriptions/{id} Content-Type: application/json { "expirationDateTime": "2026-09-30T11:00:00.0000000Z" }如果應用程式不再被授權存取該資源,續約可能會失敗。 應用程式可能需要取得新的存取權代幣才能重新授權訂閱。
授權挑戰並不會取代在訂閱到期之前續約訂閱的需求。 存取權杖的生命週期和訂用帳戶到期並不相同。 存取權杖可能會在訂用帳戶之前到期。 請準備好定期重新授權你的終端,以刷新你的存取權杖。 重新授權端點不會續約您的訂用帳戶。 不過,續約訂用帳戶也會重新授權端點。
當你續約或重新授權 圖形 API 訂閱時,它會使用你在建立訂閱時指定的合作夥伴主題。
當你指定新的 到期日時間時,請確保它至少是從目前時間起三小時。 否則,應用程式可能會在續約後不久收到 microsoft.graph.subscriptionReauthorizationRequired 事件。
關於如何使用任何支援語言重新授權 圖形 API 訂閱的範例,請參見訂閱重新授權請求。
關於如何使用任何支援語言續約及重新授權 圖形 API 訂閱的範例,請參見「更新訂閱請求」。
包含詳細指示的範例
Microsoft 圖形 API 文件提供程式碼範例,並提供下列指示:
- 根據您使用的語言,透過特定指示來設定您的開發環境。 指示也包括如何取得 Microsoft 365 租用戶以供開發用途。
- 建立 圖形 API 訂閱。 要續訂訂閱,請使用「如何續約 圖形 API 訂閱」中的程式碼片段呼叫 圖形 API。
- 取得驗證權杖,以在呼叫 Microsoft 圖形 API 時加以使用。
附註
您可以使用 Microsoft 圖形 API Explorer 建立您的 圖形 API 訂閱。 您仍應將範例用於解決方案的其他重要層面,例如驗證和接收事件。
Web 應用程式範例提供下列語言版本:
- C# 範例。 這是一個最新的範例,其中包含如何建立及續約圖形 API 訂用帳戶,並逐步引導您完成一些步驟,以啟用事件流程。
- Java 範例
- Node.js 範例。
重要事項
您必須啟用在建立圖形 API 訂用帳戶時所建立的合作夥伴主題。 您也需要建立 Web 應用程式的事件方格事件訂用帳戶才能接收事件。 為此,您會使用 Web 應用程式中設定的 URL,以事件訂用帳戶中 Webhook 端點的形式接收事件。
重要事項
需要其他語言的範例程式代碼或有問題嗎? 電子郵件 ask-graph-and-grid@microsoft.com。
相關內容
要透過事件網格接收 Microsoft 圖形 API 事件,請完成以下兩個步驟: