共用方式為

透過 Azure 事件方格接收 Microsoft Graph API 變更事件

  • 發行項

本文說明訂閱 Microsoft Graph API 所發佈事件的步驟。 下表列出可透過圖形 API 取得的事件來源。 對於大部分的資源，支援宣佈其建立、更新和刪除的事件。 如需事件來源引發事件的資源詳細資訊，請參閱 Microsoft Graph API 變更通知支援的資源。

Microsoft 事件來源 資源 可用的事件類型
Microsoft Entra ID 使用者、群組 Microsoft Entra 事件類型
Microsoft Outlook 事件 (行事曆會議)、訊息 (電子郵件)、聯絡人 Microsoft Outlook 事件類型
Microsoft Teams ChatMessage、CallRecord (會議) Microsoft Teams 事件類型
OneDrive DriveItem Microsoft OneDrive 事件
Microsoft SharePoint 清單​​ Microsoft SharePoint 事件
To Do 待辦工作 Microsoft ToDo 事件
安全性警訊 Alert Microsoft 安全性警示事件
雲端列印 印表機、列印工作定義 Microsoft Cloud 列印事件
Microsoft Conversations 交談 Microsoft 365 群組交談事件

您可以建立 Microsoft 圖形 API 訂閱，讓圖形 API事件流向合作夥伴主題。 合作夥伴主題會自動為您建立圖形 API 訂閱的一部分。 您可以使用該合作夥伴主題來建立事件訂閱，將您的事件傳送至任何最符合您處理事件需求的受支援事件處理常式。

重要

若您不熟悉合作夥伴事件功能，請參閱合作夥伴事件概觀。

為什麼應該透過事件方格訂閱 Microsoft Graph API 來源中的事件？

除了具備透過事件格線訂閱 Microsoft Graph API 事件的能力外，您還可以透過其他選項接收類似的通知 (不是事件)。 如果您至少有下列其中一項需求，請考慮使用 Microsoft Graph API 將事件傳遞至事件格線：

  • 您正在開發需要來自 Microsoft Entra ID、Outlook、Teams 等事件的事件驅動解決方案，以回應資源變更。 您需要事件格線所提供的強固事件模型和發佈訂閱功能。 如需事件格線的概觀，請參閱事件格線概念。
  • 您想要使用事件格線將事件傳送至使用單一圖形 API 的多個目的地，且您想要避免管理多個圖形 API 訂用帳戶。
  • 您必須根據事件中的某些屬性，將事件傳送至不同的下游應用程式、Webhook 或 Azure 服務。 例如，您可能需要將如 Microsoft.Graph.UserCreated 和 Microsoft.Graph.UserDeleted 等事件種類路由至處理使用者上線和下線的特殊應用程式。 例如，您也可以將 Microsoft.Graph.UserUpdated 事件傳送至另一個同步聯絡人資訊的應用程式。 若要使用事件格線作為通知目的地，您可以使用單一圖形 API 訂用帳戶來達成此目的。 如需詳細資訊，請參閱事件篩選和事件處理常式。
  • 互通性對您來說至關重要。 您想要使用雲端原生計算基礎 (CNCF) CloudEvents 規格標準，以標準方式轉送和處理事件。
  • 您會喜歡 CloudEvents 提供的擴充性支援。 例如，若您要跨符合規範的系統追蹤事件，則可以使用 CloudEvents 擴充功能分散式追蹤。 深入了解更多 CloudEvents 擴充功能。
  • 您想要使用業界廣泛採用，且經實證的事件驅動方法。

啟用 Graph API 事件以流向您的合作夥伴主題

您可以使用 Microsoft Graph API 軟體開發套件 (SDK) 建立圖形 API 訂用帳戶，並遵循本節中所提供範例連結中的步驟，要求 Microsoft Graph API 將事件轉送至事件方格合作夥伴主題。 如需可用的 SDK 支援，請參閱 Microsoft Graph API SDK 支援的語言。

一般必要條件

您應該先符合這些一般必要條件，然後再實作應用程式來建立及續約 Microsoft Graph API 訂用帳戶：

您會找到其他所選程式設計語言專屬的必要條件，以及您在下一節中所找到 Microsoft Graph API 範例連結中使用的開發環境。

重要

雖然您可在包含詳細指示的範例一節中找到實作應用程式的詳細指示，但您仍應閱讀本文中的所有章節，因為這些章節中包含使用事件方格轉送 Microsoft Graph API 事件的其他重要資訊。

如何建立 Microsoft Graph API 訂用帳戶

當您建立圖形 API 訂用帳戶時，隨即會為您建立合作夥伴主題。 您會在 notificationUrl 參數中傳遞下列資訊，以指定要建立並與新 Graph API 訂用帳戶相關聯的合作夥伴主題：

  • 合作夥伴主題名稱
  • 建立合作夥伴主題的資源群組名稱
  • 區域 (位置)
  • Azure 訂用帳戶

這些程式碼範例會示範如何建立圖形 API 訂用帳戶。 這些程式碼範例會顯示範例，說明如何建立訂用帳戶，以在建立、更新或刪除事件時，接收這些來自 Microsoft Entra ID 租用戶中所有使用者的事件。

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json

{
    "changeType": "Updated,Deleted,Created",
    "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": "2024-03-31T00:00:00Z",
    "clientState": "secretClientValue"
}
  • changeType：您想要接收事件的資源變更類型。 有效值：Updated、Deleted 和 Created。 您可以指定一或多個以逗號分隔的值。
  • 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>。 執行 az account list-locations 命令，即可取得位置 (也稱為 Azure 區域) name。 請勿使用位置顯示名稱。 例如，請勿使用美國中西部。 請改用 westcentralus。 
      az account list-locations
  • lifecycleNotificationUrl：用來定義要傳送microsoft.graph.subscriptionReauthorizationRequired事件的合作夥伴主題的 URI。 此事件會向您的應用程式發出圖形 API 訂用帳戶即將到期的訊號。 如果使用事件方格做為生命週期事件的目的地，則 URI 會遵循與上述 notificationUrl 相同的模式。 在此情況下，合作夥伴主題應該與 notificationUrl 中所指定的主題相同。
  • resource：產生事件以宣告狀態變更的資源。
  • expirationDateTime：訂閱到期且事件流程停止的到期時間。 它必須符合要求變更 （RFC） 3339 中指定的格式。 您必須指定到期時間，且該時間是在每個資源類型允許的最大訂閱時間長度內。
  • 用戶端狀態。 這個屬性為選擇性。 其用於驗證事件傳遞期間對事件處理常式應用程式的呼叫。 如需詳細資訊，請參閱圖形 API 訂用帳戶屬性。

重要

  • 合作夥伴主題名稱在相同的 Azure 區域內必須是唯一的名稱。 每個租用戶應用程式識別碼組合最多可以建立 10 個唯一的合作夥伴主題。

  • 在開發解決方案時，請留意特定圖形 API 資源的服務限制。

  • 沒有 lifecycleNotificationUrl 屬性的現有圖形 API 訂用帳戶不會接收到生命週期事件。 若要新增 lifecycleNotificationUrl 屬性，您應該刪除現有的訂用帳戶，並在建立訂閱期間建立指定屬性的新訂用帳戶。

建立圖形 API 訂用帳戶之後，您就已在 Azure 上建立合作夥伴主題。

續約 Microsoft Graph API 訂用帳戶

您必須在應用程式到期之前續約圖形 API 訂用帳戶，以避免中斷事件的流程。 為了協助您自動化續約流程，Microsoft Graph API 支援生命週期通知事件，可供您的應用程式訂閱。 目前，所有類型的 Microsoft Graph API 資源都支援 microsoft.graph.subscriptionReauthorizationRequired，這會在發生下列任一情況時加以傳送：

  • 存取權杖即將過期。
  • 圖形 API 訂用帳戶即將到期。
  • 租用戶系統管理員已撤銷應用程式讀取資源的權限。

如果您在圖形 API 訂用帳戶過期後未續約，則必須建立新的 Graph API 訂用帳戶。 只要訂閱過期未滿 30 天，就可以參考您在過期的訂用帳戶中所使用的相同合作夥伴主題。 如果圖形 API 訂用帳戶已過期超過 30 天，您就無法重複使用現有的合作夥伴主題。 在此情況下，您必須指定另一個合作夥伴主題名稱。 或者，您可以刪除現有的合作夥伴主題，以在建立圖形 API 訂用帳戶期間建立具有相同名稱的新合作夥伴主題。

如何續約 Microsoft Graph API 訂用帳戶

收到 microsoft.graph.subscriptionReauthorizationRequired 事件時，您的應用程式應該透過執行下列動作來續約 Graph API 訂用帳戶：

  1. 如果您在建立圖形 API 訂用帳戶時，在 clientState 屬性中提供了用戶端密碼，則該用戶端密碼會包含在事件中。 驗證事件的 clientState 符合您在建立圖形 API 訂用帳戶時所使用的值。

  2. 請確定應用程式具有有效的存取權杖，以採取下一個步驟。 隨後包含詳細指示的範例一節中提供更多詳細資訊。

  3. 呼叫下列兩個 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": "2024-04-30T11:00:00.0000000Z"
}

      如果應用程式不再獲得存取資源的授權，則續約可能會失敗。 然後，應用程式可能必須取得新的存取權杖，才能成功重新授權訂用帳戶。

授權挑戰並不會取代在訂閱到期之前續約訂閱的需求。 存取權杖的生命週期和訂用帳戶到期並不相同。 存取權杖可能會在訂用帳戶之前到期。 請務必準備定期重新授權端點，以重新整理存取權杖。 重新授權端點不會續約您的訂用帳戶。 不過，續約訂用帳戶也會重新授權端點。

續約和/或重新授權圖形 API 訂用帳戶時，會使用建立訂閱時所指定的相同合作夥伴主題。

指定新的 expirationDateTime 時，其必須至少距離目前時間三小時。 否則，應用程式可能會在續約後不久收到 microsoft.graph.subscriptionReauthorizationRequired 事件。

如需如何使用任何支援的語言來重新授權圖形 API 訂用帳戶的範例，請參閱訂閱重新授權要求。

如需如何使用任何支援的語言來續約及重新授權圖形 API 訂用帳戶的範例，請參閱更新訂閱要求。

包含詳細指示的範例

Microsoft Graph API 文件提供程式碼範例，並提供下列指示：

  • 根據您使用的語言，透過特定指示來設定您的開發環境。 指示也包括如何取得 Microsoft 365 租用戶以供開發用途。
  • 建立圖形 API 訂用帳戶。 若要續約訂用帳戶，您可以使用如何續約圖形 API 訂用帳戶中的程式碼片段，以呼叫圖形 API。
  • 取得驗證權杖，以在呼叫 Microsoft Graph API 時加以使用。

注意

您可以使用 Microsoft Graph API Explorer 來建立 Graph API 訂用帳戶。 您仍應將範例用於解決方案的其他重要層面，例如驗證和接收事件。

Web 應用程式範例提供下列語言版本：

  • C# 範例。 這是一個最新的範例，其中包含如何建立及續約圖形 API 訂用帳戶，並逐步引導您完成一些步驟，以啟用事件流程。
  • Java 範例
    • GraphAPIController 包含範例程式碼，可建立、刪除及續約圖形 API 訂用帳戶。 其必須與 JAVA 範例應用程式搭配使用。
  • NodeJS 範例.

重要

您必須啟用在建立圖形 API 訂用帳戶時所建立的合作夥伴主題。 您也需要建立 Web 應用程式的事件方格事件訂用帳戶才能接收事件。 為此，您會使用 Web 應用程式中設定的 URL，以事件訂用帳戶中 Webhook 端點的形式接收事件。 如需更多資訊，請參閱後續步驟。

重要

您需要其他語言的範例程式碼或有問題嗎？ 請傳送電子郵件至 ask-graph-and-grid@microsoft.com。

下一步

請遵循下列兩個步驟中的指示完成設定，以使用事件方格接收 Microsoft Graph API 事件：

其他實用的連結：