透過 Azure 事件方格接收 Microsoft Graph API 變更事件 (預覽)

發行項
03/11/2024

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

重要

Microsoft Graph API 將事件傳送至 Azure 事件方格的功能目前為公開預覽。如果您有問題或需要支援，請傳送電子郵件給我們：ask-graph-and-grid@microsoft.com。

Microsoft 事件來源	可用的事件類型
Microsoft Entra ID	Microsoft Entra 事件類型
Microsoft Outlook	Microsoft Outlook 事件類型
Microsoft 365 群組交談
Microsoft Teams	Microsoft Teams 事件類型
Microsoft SharePoint 和 OneDrive
Microsoft SharePoint
安全性警訊
Microsoft Conversations
Microsoft 通用列印

重要

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

除了具備透過事件格線訂閱 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 訂用帳戶：

熟悉高階步驟，以訂閱合作夥伴事件。如該文章所述，在建立圖形 API 訂用帳戶之前，您應該遵循下列的指示：
- 使用您的 Azure 訂用帳戶註冊事件方格資源提供者。
- 授權 Microsoft Grap API (合作夥伴) 在您的資源群組中建立合作夥伴主題。
具備 Microsoft Graph API 通知的運用知識。您在學習期間，可以使用 Graph API 總管來建立圖形 API 訂用帳戶。
了解合作夥伴事件概念。
識別您要接收系統狀態變更事件的 Microsoft Graph API 資源。如需詳細資訊，請參閱 Microsoft Graph API 通知。例如，若要追蹤使用者 Microsoft Entra ID 中的變更，您應該使用使用者資源。使用群組來追蹤使用者群組的變更。
在 Microsoft 365 租用戶上擁有租用戶系統管理員帳戶。您可以加入 Microsoft 365 開發人員計劃，免費取得開發租用戶。

您會找到其他所選程式設計語言專屬的必要條件，以及您在下一節中所找到 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"
}

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Subscription
{
	ChangeType = "updated,deleted,created",
	NotificationUrl = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=youPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    LifecycleNotificationUrl = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
	Resource = "users",
	ExpirationDateTime = DateTimeOffset.Parse("2024-03-31T18:23:45.9356913Z"),
	ClientState = "secretClientValue",
};

// To initialize your graphClient, see `https://learn.microsoft.com/graph/sdks/create-client?from=snippets&tabs=csharp`
var result = await graphClient.Subscriptions.PostAsync(requestBody);

mgc subscriptions create --body '{\
   "changeType": "updated,deleted,created",\
   "notificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=youPartnerTopic&location=theNameOfAzureRegionFortheTopic",\
   "lifecycleNotificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",\
   "resource": "users",\
   "expirationDateTime":"2024-03-31T18:23:45.9356913Z",\
   "clientState": "secretClientValue"\
}\
'

import (
	  "context"
	  "time"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodels.NewSubscription()
changeType := "updated,deleted,created"
requestBody.SetChangeType(&changeType) 
notificationUrl := "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic"
requestBody.SetNotificationUrl(&notificationUrl)
lifecycleNotificationUrl := "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic"
requestBody.SetLifecycleNotificationUrl(&lifecycleNotificationUrl)
resource := "users"
requestBody.SetResource(&resource) 
expirationDateTime , err := time.Parse(time.RFC3339, "2024-03-31T18:23:45.9356913Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 
clientState := "secretClientValue"
requestBody.SetClientState(&clientState) 

subscriptions, err := graphClient.Subscriptions().Post(context.Background(), requestBody, nil)

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

Subscription subscription = new Subscription();
subscription.changeType = "updated,deleted,created";
subscription.notificationUrl = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic";
subscription.lifecycleNotificationUrl = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic";
subscription.resource = "users";
subscription.expirationDateTime = OffsetDateTimeSerializer.deserialize("2024-03-31T18:23:45.9356913Z");
subscription.clientState = "secretClientValue";

graphClient.subscriptions()
	.buildRequest()
	.post(subscription);

const options = {
	authProvider,
};

const client = Client.init(options);

const subscription = {
   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-31T18:23:45.9356913Z',
   clientState: 'secretClientValue'
};

await client.api('/subscriptions')
	.post(subscription);

<?php

// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Subscription();
$requestBody->setChangeType('updated,deleted,created');
$requestBody->setNotificationUrl('EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic');
$requestBody->setLifecycleNotificationUrl('EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic');
$requestBody->setResource('users');
$requestBody->setExpirationDateTime(new \DateTime('2024-03-31T18:23:45.9356913Z'));
$requestBody->setClientState('secretClientValue');

$result = $graphServiceClient->subscriptions()->post($requestBody)->wait();

Import-Module Microsoft.Graph.ChangeNotifications

$params = @{
	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 = [System.DateTime]::Parse("2024-03-31T18:23:45.9356913Z")
	clientState = "secretClientValue"
}

New-MgSubscription -BodyParameter $params

graph_client = GraphServiceClient(credentials, scopes)

request_body = Subscription(
	change_type = "updated,deleted,created",
	notification_url = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    lifecycle_notification_url = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
	resource = "users",
	expiration_date_time = "2024-03-31T18:23:45.9356913Z",
	client_state = "secretClientValue"
)

result = await graph_client.subscriptions.post(request_body)

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 屬性，您應該刪除現有的訂用帳戶，並在建立訂閱期間建立指定屬性的新訂用帳戶。

注意

如果您的應用程式使用標頭 x-ms-enable-features 且您要求在個人預覽版期間建立圖形 API 訂用帳戶，則您應該將其移除因為已不再需要。

建立圖形 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 訂用帳戶：

如果您在建立圖形 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": "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 事件：

在建立 Microsoft Graph API 時建立啟用合作夥伴主題。
在合作夥伴主題建立一個事件訂用帳戶來訂閱事件。

其他實用的連結：

Azure 事件格線 - 合作夥伴事件概觀
Microsoft Graph API 的相關資訊。
Microsoft Graph API Webhook
使用 Microsoft Graph API 的最佳做法
Microsoft Graph API SDK
Microsoft Graph API 教學課程，當中示範如何使用 Graph API。本文未必包含將事件傳送至事件方格的範例。