你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

通过 Azure 事件网格接收 Microsoft Graph API 更改事件

2025-08-09

Microsoft图形 API 为Microsoft 365 服务中的资源提供更改通知，包括Microsoft Entra ID、Teams、Outlook 和 OneDrive。通过 Azure 事件网格订阅这些事件，可以生成事件驱动的应用程序来实时响应资源更改。

本文介绍如何执行以下操作：

创建将事件传送到 Azure 事件网格合作伙伴主题的 Microsoft Graph API 订阅。
使用自动续订管理订阅生命周期。
使用事件网格的筛选和路由功能将事件路由到多个目标。

相比于传统的基于 Webhook 的 Microsoft 图形 API 订阅，Azure 事件网格提供了诸多优势。

简化的路由：使用单个图形 API 订阅将事件发送到多个目标。
高级筛选：根据事件属性将特定事件类型路由到不同的应用程序。
标准符合性：接收 CloudEvents 格式的事件以提高互作性。
可靠性：内置的重试逻辑和死信队列可确保可靠的事件传递。

支持的事件源

下表列出了可通过 Graph API 获取其事件的事件源。对于大多数资源，支持宣布其创建、更新和删除的事件。有关为事件源引发事件的资源的详细信息，请参阅 Microsoft Graph API 更改通知支持的资源。

Microsoft 事件源	资源	可用事件类型
Microsoft Entra ID	用户、组	Microsoft Entra ID 事件类型
Microsoft Outlook	事件（日历会议）、消息（电子邮件）、联系人	Microsoft Outlook 事件类型
Microsoft Teams	ChatMessage、CallRecord（会议）	Microsoft Teams 事件类型
OneDrive	DriveItem	Microsoft OneDrive 事件
Microsoft SharePoint	列表	Microsoft SharePoint 事件
微软待办	待办任务	微软待办事件
安全警报	警报	Microsoft 安全警报事件
云打印	打印机、打印任务定义	Microsoft Cloud 打印事件
Microsoft对话	聊天	Microsoft 365 群组对话事件

创建 Microsoft Graph API 订阅，使 Graph API 事件能够流入合作伙伴主题。合作伙伴主题会在创建 Graph API 订阅时自动生成。使用该合作伙伴主题创建事件订阅，以将事件发送到最符合处理事件要求的任何受支持的事件处理程序。

重要说明

如果不熟悉 合作伙伴事件 功能，请参阅合作伙伴事件概述。

除了通过事件网格订阅Microsoft图形 API 事件外，还可以使用其他选项来接收类似的通知（而不是事件）。如果满足以下至少一项要求，请使用 Microsoft 图形 API 将事件传送到事件网格：

你正在开发一个事件驱动的解决方案，该解决方案使用来自 Microsoft Entra ID、Outlook 或 Teams 的事件来响应资源更改。需要事件网格提供的可靠事件驱动模型和发布-订阅功能。有关事件网格的概述，请参阅事件网格概念。
你想要使用事件网格通过单个 Graph API 订阅将事件路由到多个目标，并想要避免管理多个 Graph API 订阅。
需要根据事件中的某些属性将事件路由到不同的下游应用程序、Webhook 或 Azure 服务。例如，你可能想要将 Microsoft.Graph.UserCreated 和 Microsoft.Graph.UserDeleted 等事件类型路由到处理用户入职和离职手续的专用应用程序。例如，你可能还想要将 Microsoft.Graph.UserUpdated 事件发送到另一个用于同步联系人信息的应用程序。使用事件网格作为通知目标时，可以使用单个 Graph API 订阅来实现此目的。有关详细信息，请参阅事件筛选和事件处理程序。
互操作性对你而言非常重要。你想要使用云原生计算基础 (CNCF) CloudEvents 规范标准以标准方式转发和处理事件。
你重视 CloudEvents 提供的扩展性支持。例如，若要跨合规系统跟踪事件，请使用 CloudEvents 扩展分布式跟踪。详细了解 CloudEvents 扩展。
你使用行业采用的经过验证的事件驱动方法。

使 Graph API 事件能够流向合作伙伴主题

使用 Microsoft Graph API 软件开发工具包 (SDK) 创建 Microsoft Graph API 订阅，并 按照本节中提供的示例链接中的步骤，请求 Microsoft Graph API 将事件转发到 Event Grid 合作伙伴主题。有关可用的 SDK 支持，请参阅 Microsoft Graph API SDK 支持的语言。

常规先决条件

在实现应用程序以创建和续订Microsoft图形 API 订阅之前，请满足以下一般先决条件：

熟悉订阅合作伙伴事件的高级别步骤。如本文所述，在创建图形 API 订阅之前，应按照以下内容中的说明操作：
- 向 Azure 订阅注册事件网格资源提供程序。
- 授权 Microsoft Graph API（合作伙伴），以在资源组中创建合作伙伴主题。
了解 Microsoft Graph API 通知的工作知识。在学习过程中，可以使用图形 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://free.blessedness.top/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 中指定的格式。必须指定一个在资源类型允许的最大订阅长度范围内的过期时间。
客户端状态。此属性是可选的。它用于在事件传递期间验证对事件处理程序应用程序的调用。有关详细信息，请参阅 Graph API 订阅属性。

重要说明

合作伙伴主题名称在同一 Azure 区域中必须唯一。每个租户-应用程序 ID 组合最多可以创建 10 个唯一的合作伙伴主题。
开发解决方案时，请记住 Graph API 资源的某些服务限制。
没有 lifecycleNotificationUrl 属性的现有图形 API 订阅不会接收生命周期事件。要添加 lifecycleNotificationUrl 属性，应删除现有订阅并在创建订阅期间创建一个新订阅，用于指定该属性。

创建图形 API 订阅后，则已在 Azure 上创建合作伙伴主题。

续订 Microsoft Graph API 订阅

在图形 API 订阅过期之前续订，以避免停止事件流。为了帮助自动执行续订过程，Microsoft Graph API 支持应用程序可以订阅的 生命周期通知事件 。目前，所有类型的 Microsoft Graph API 资源都支持 microsoft.graph.subscriptionReauthorizationRequired，它会在以下任一情况发生时发送：

访问令牌即将过期。
图形 API 订阅即将过期。
租户管理员撤销了应用读取资源的权限。

如果图形 API 订阅在到期后未续订，请创建新的图形 API 订阅。只要订阅过期未超过 30 天，请引用在过期订阅中使用的同一合作伙伴主题。如果图形 API 订阅过期超过 30 天，则无法重用现有的合作伙伴主题。在这种情况下，需要指定另一个合作伙伴主题名称。也可以删除现有合作伙伴主题，以在创建图形 API 订阅期间创建具有相同名称的新合作伙伴主题。

如何续订 Microsoft Graph 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": "2024-04-30T11:00:00.0000000Z"
}
```
  如果应用不再有权访问资源，续订可能会失败。然后，应用可能需要获取新的访问令牌才能成功重新授权订阅。

授权质询不会取代在订阅过期之前续订订阅的需求。访问令牌和订阅过期的生命周期不同。访问令牌可能会在订阅之前过期。请务必准备好定期重新授权终结点以刷新访问令牌。重新授权终结点不会续订订阅。但续订订阅也会重新授权终结点。

续订和/或重新授权图形 API 订阅时，将会使用创建订阅时指定的同一合作伙伴主题。

在指定新的 expirationDateTime 时，请确保其至少比当前时间晚 3 小时。否则，应用程序可能会在续订后立即收到 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 示例
Node.js 示例。

重要说明

需要激活在创建图形 API 订阅的过程中创建的合作伙伴主题。还需要创建 Web 应用程序的事件网格事件订阅来接收事件。为此，请使用 Web 应用程序中配置的 URL 以事件订阅中的 Webhook 终结点形式接收事件。

重要说明

需要另一种语言的示例代码或有疑问？电子邮件 ask-graph-and-grid@microsoft.com。

按照以下两个步骤设置使用事件网格接收 Microsoft Graph API 事件：

激活在 Microsoft Graph API 设置期间创建的合作伙伴主题。
订阅事件，方法是为您的合作伙伴主题创建事件订阅。

反馈

此页面是否有帮助？

通过

通过 Azure 事件网格接收 Microsoft Graph API 更改事件

支持的事件源

为什么应通过事件网格订阅来自 Microsoft Graph API 源的事件？

使 Graph API 事件能够流向合作伙伴主题

常规先决条件

如何创建 Microsoft Graph API 订阅

续订 Microsoft Graph API 订阅

如何续订 Microsoft Graph API 订阅

包含详细说明的示例

相关内容

反馈

其他资源