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

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

项目
05/22/2024

本文介绍订阅 Microsoft Graph API 发布的事件的步骤。下表列出了可通过 Graph 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 事件
微软待办	待办任务	微软待办事件
安全警报	Alert	Microsoft 安全警报事件
云打印	打印机、打印任务定义	Microsoft Cloud 打印事件
Microsoft Conversations	聊天	Microsoft 365 群组对话事件

你创建 Microsoft Graph API 订阅以使 Graph API 事件能够流入合作伙伴主题。作为 Graph API 订阅创建的一部分，会自动为你创建合作伙伴主题。你使用该合作伙伴主题来创建事件订阅，以将你的事件发送到最能满足你处理事件的要求的任何受支持的事件处理程序。

重要

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

除了可以通过事件网格订阅 Microsoft Graph API 事件之外，还可以通过其他选项接收类似的通知（非事件）。如果要满足下面的至少一个要求，请考虑使用 Microsoft Graph 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) 创建图形 API 订阅，并按照本部分中提供的示例链接中的步骤，请求 Microsoft Graph API 将事件转发到事件网格合作伙伴主题。有关可用的 SDK 支持，请参阅 Microsoft Graph API SDK 支持的语言。

一般先决条件

在实现应用程序以创建和续订 Microsoft Graph 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://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 中指定的格式。必须指定一个在资源类型允许的最大订阅长度范围内的过期时间。
客户端状态。此属性是可选的。它用于在事件传递期间验证对事件处理程序应用程序的调用。有关详细信息，请参阅 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 时，它必须至少为当前时间的三小时之后。否则，应用程序可能会在续订后立即收到 microsoft.graph.subscriptionReauthorizationRequired 事件。

有关如何使用任何支持语言重新授权图形 API 订阅的示例，请参阅订阅重新授权请求。

有关如何使用任何支持的语言续订和重新授权图形 API 订阅的示例，请参阅更新订阅请求。

包含详细说明的示例

Microsoft Graph API 文档提供了代码示例，其中包含以下相关说明：

根据所使用的语言，使用特定说明设置开发环境。说明还包括如何获取 Microsoft 365 租户以进行开发。
创建图形 API 订阅。要续订订阅，可以使用如何续订图形 API 订阅中的代码片段调用图形 API。
获取要在调用 Microsoft Graph API 时使用的身份验证令牌。

注意

可以使用 Microsoft Graph API 资源管理器创建图形 API 订阅。你仍应将示例用于解决方案的其他重要方面，例如身份验证和接收事件。

Web 应用程序示例适用于以下语言：

C# 示例。这是一个最新的示例，其中包括如何创建和续订图形 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 教程，其中介绍了如何使用图形 API。本文不一定包含将事件发送到事件网格的示例。

通过

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

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

一般先决条件

如何创建 Microsoft Graph API 订阅

续订 Microsoft Graph API 订阅

如何续订 Microsoft Graph API 订阅

包含详细说明的示例

后续步骤

反馈

其他资源

通过

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

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

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

一般先决条件

如何创建 Microsoft Graph API 订阅

续订 Microsoft Graph API 订阅

如何续订 Microsoft Graph API 订阅

包含详细说明的示例

后续步骤

反馈

其他资源