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

通过Azure 事件网格接收 Microsoft Graph API 更改事件（预览版）

  • 项目

本文介绍订阅 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 Graph API 将事件传送到事件网格：

  • 你正在开发一个事件驱动的解决方案，它需要使用来自 Microsoft Entra ID、Outlook、Teams 等的事件对资源更改做出反应。 需要事件网格提供的可靠事件模型和发布-订阅功能。 有关事件网格的概述，请参阅事件网格概念。
  • 你想要使用事件网格通过单个 Graph API 订阅将事件路由到多个目标，并想要避免管理多个 Graph API 订阅。
  • 需要根据事件中的某些属性将事件路由到不同的下游应用程序、Webhook 或 Azure 服务。 例如，你可能想要将事件类型（例如 Microsoft.Graph.UserCreated ）路由 Microsoft.Graph.UserDeleted 到处理用户加入和登机的专用应用程序。 你可能还希望将事件发送到 Microsoft.Graph.UserUpdated 同步联系人信息的另一个应用程序，例如。 使用事件网格作为通知目标时，可以使用单个 Graph API 订阅来实现此目的。 有关详细信息，请参阅事件筛选和事件处理程序。
  • 互操作性对你而言非常重要。 你想要使用NCF 的 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 中指定的主题相同。
  • 资源：生成用于报出状态更改的事件的资源。
  • expirationDateTime：订阅过期的过期时间和事件流停止的时间。 它必须符合 RFC 3339 中指定的格式。 必须指定每个资源类型允许的最大订阅长度内的过期时间。
  • 客户端状态。 此属性是可选的。 它用于在事件传递期间验证对事件处理程序应用程序的调用。 有关详细信息，请参阅 Graph API 订阅属性。

重要

  • 合作伙伴主题名称必须在同一 Azure 区域中是唯一的。 每个租户-应用程序 ID 组合最多可以创建 10 个唯一的合作伙伴主题。

  • 开发解决方案时，请记住 Graph 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 订阅过期后未续订，则需要创建新的图形 API 订阅。 只要订阅已过期不到 30 天，就可以引用在过期订阅中使用的同一合作伙伴主题。 如果图形 API 订阅已过期超过 30 天，则不能重复使用现有的合作伙伴主题。 在这种情况下，需要指定另一个合作伙伴主题名称。 或者，可以删除现有合作伙伴主题，以在创建图形 API 订阅期间创建具有相同名称的新合作伙伴主题。

如何续订 Microsoft Graph API 订阅

收到 microsoft.graph.subscriptionReauthorizationRequired 事件后，应用程序应通过执行以下操作续订图形 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 资源管理器创建图形 API 订阅。 你仍应将示例用于解决方案的其他重要方面，例如身份验证和接收事件。

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

  • C# 示例。 这是一个最新的示例，包括如何创建和续订图形 API 订阅，并指导你完成启用事件流的一些步骤。
  • Java 示例
    • GraphAPIController 包含用于创建、删除和续订 Graph API 订阅的示例代码。 它必须与上述 Java 示例应用程序一起使用。
  • NodeJS 示例。

重要

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

重要

是否需要其他语言的示例代码或有疑问？ 请向我们发送电子邮件，地址：ask-graph-and-grid@microsoft.com。

后续步骤

按照以下两个步骤中的说明完成设置，以使用事件网格接收 Microsoft Graph API 事件：

其他有用的链接：