可通过不同方式向订阅者传送更改通知。如果更改通知的主要传送模式是 Webhook,则对于高吞吐量场景或当接收方无法公开公用的通知 URL 时,利用 Webhooks 可能很困难。
此更改通知传递模式可用于支持 Microsoft Graph 更改通知的所有资源。
高吞吐量场景的恰当例子包括订阅大量资源的应用程序、订阅频繁变更的资源的应用程序以及跨大量组织订阅资源的多租户应用程序。
使用 Azure 事件中心接收更改通知
Azure 事件中心是专为大规模部署而构建的常用实时事件引入和分发服务。 你可以使用 Azure 事件中心而不是传统 Webhook 来接收更改通知。
使用 Azure 事件中心接收更改通知与 Webhook 在某些方面有所不同,包括:
- 不依赖公开显示的通知 URL。 事件中心 SDK 会将通知转发到你的应用程序。
- 无需恢复通知 URL 验证。 可忽略收到的验证消息。
- 需要预配 Azure 事件中心。
- 需要预配 Azure 密钥保管库。
设置 Azure 密钥保管库和 Azure 事件中心
本节将指导你完成所需的 Azure 服务设置。
选项 1:使用 Azure CLI
Azure CLI 允许你在 Azure 中编写脚本并自动执行管理任务。 可以在本地计算机上安装 CLI 或直接从 Azure Cloud Shell 运行。
# --------------
# TODO: update the following values
#sets the name of the resource group
resourcegroup=rg-graphevents-dev
#sets the location of the resources
location='uk south'
#sets the name of the Azure Event Hubs namespace
evhamespacename=evh-graphevents-dev
#sets the name of the hub under the namespace
evhhubname=graphevents
#sets the name of the access policy to the hub
evhpolicyname=grapheventspolicy
#sets the name of the Azure KeyVault
keyvaultname=kv-graphevents
#sets the name of the secret in Azure KeyVault that will contain the connection string to the hub
keyvaultsecretname=grapheventsconnectionstring
# --------------
az group create --location $location --name $resourcegroup
az eventhubs namespace create --name $evhamespacename --resource-group $resourcegroup --sku Basic --location $location
az eventhubs eventhub create --name $evhhubname --namespace-name $evhamespacename --resource-group $resourcegroup --partition-count 2 --message-retention 1
az eventhubs eventhub authorization-rule create --name $evhpolicyname --eventhub-name $evhhubname --namespace-name $evhamespacename --resource-group $resourcegroup --rights Send
evhprimaryconnectionstring=`az eventhubs eventhub authorization-rule keys list --name $evhpolicyname --eventhub-name $evhhubname --namespace-name $evhamespacename --resource-group $resourcegroup --query "primaryConnectionString" --output tsv`
az keyvault create --name $keyvaultname --resource-group $resourcegroup --location $location --enable-soft-delete true --sku standard --retention-days 90
az keyvault secret set --name $keyvaultsecretname --value $evhprimaryconnectionstring --vault-name $keyvaultname --output none
graphspn=`az ad sp list --display-name 'Microsoft Graph Change Tracking' --query "[].appId" --output tsv`
az keyvault set-policy --name $keyvaultname --resource-group $resourcegroup --secret-permissions get --spn $graphspn --output none
keyvaulturi=`az keyvault show --name $keyvaultname --resource-group $resourcegroup --query "properties.vaultUri" --output tsv`
domainname=`az ad signed-in-user show --query 'userPrincipalName' | cut -d '@' -f 2 | sed 's/\"//'`
notificationUrl="EventHub:${keyvaulturi}secrets/${keyvaultsecretname}?tenantId=${domainname}"
echo "Notification Url:\n${notificationUrl}"
注意: 此处提供的脚本与基于 Linux 的 命令行管理程序、Windows WSL 和 Azure Cloud Shell 兼容。 它要求在 Windows 命令行管理程序中运行某些更新。
选项 2:使用 Azure 门户
配置 Azure 事件中心
在本节中,你将:
- 创建 Azure 事件中心命名空间。
- 将中心添加到将转发和传送通知的该命名空间。
- 添加共享访问策略,它将允许你获取新创建的中心的连接字符串。
步骤:
- 打开浏览器以访问 Azure 门户。
- 选择“创建资源”。
- 在搜索栏中键入“事件中心”。
- 选择“事件中心”建议。 此时将加载“创建事件中心”页面。
- 在“创建事件中心”页面上,单击“创建”。
- 填写事件中心命名空间创建详细信息,然后单击“创建”。
- 预配事件中心命名空间后,转到该命名空间的页面。
- 单击“事件中心”和“+ 事件中心”。
- 为新事件中心命名,然后单击“创建”。
- 创建事件中心后,单击事件中心的名称,然后单击“共享访问策略”和“+ 添加”以添加新策略。
- 为策略命名,选中“发送”,然后单击“创建”。
- 创建策略后,单击策略名称以打开“详细信息”面板,然后复制“连接字符串-主键”值。请将其记下,下一步将需要使用该值。
配置 Azure 密钥保管库
为了安全地访问事件中心并允许密钥轮换,Microsoft Graph 将通过 Azure 密钥保管库获取事件中心的连接字符串。
在本节中,你将:
- 创建 Azure 密钥保管库以存储密钥。
- 将连接字符串作为密钥添加到事件中心。
- 为 Microsoft Graph 添加访问策略以访问密钥。
步骤:
- 打开浏览器以访问 Azure 门户。
- 选择“创建资源”。
- 在搜索栏中键入“密钥保管库”。
- 选择“密钥保管库”建议。 此时将加载“创建密钥保管库”页面。
- 在“创建密钥保管库”页面上,单击“创建”。
- 填写密钥保管库创建详细信息,然后单击“审阅 + 创建”和“创建”。
- 使用通知中的“转到资源”来转到新创建的密钥保管库。
- 复制 DNS 名称;在下一步中你需要使用它。
- 转到“密钥”,然后单击“+ 生成/导入”。
- 为密钥命名,并保留名称供以后使用,在下一步中你需要使用它。 对于该值,请粘贴在“事件中心”步骤中生成的连接字符串。 单击“创建”。
- 单击“访问策略”和“+ 添加访问策略”。
- 对于“机密权限”,选择“获取”;对于“选择主体”,选择“Microsoft Graph 更改跟踪”。单击“添加”。
创建订阅并接收通知
创建所需的 Azure 密钥保管库和 Azure 事件中心服务后,你将能够创建订阅并开始通过 Azure 事件中心接收更改通知。
创建订阅
使用事件中心订阅更改通知与使用 Webhook 订阅更改通知几乎相同。 主要区别在于前者依赖事件中心来传送通知。 所有其他操作都类似,包括创建订阅。
创建订阅期间的主要区别是 notificationUrl。 必须将其设置为 EventHub:https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname>,并使用以下值:
azurekeyvaultname- 创建密钥保管库时为其提供的名称。 可在 DNS 名称中找到它。secretname- 创建密钥时为其提供的名称。 可在 Azure 密钥保管库的“密钥”页面上找到它。domainname- 租户的名称;例如,consto.onmicrosoft.com 或 contoso.com。 由于此域将用于访问 Azure 密钥保管库,因此请务必使其与包含 Azure 密钥保管库的 Azure 订阅所使用的域相匹配。 若要获取此信息,可转到你创建的 Azure 密钥保管库的概述页面,并单击该订阅。 域名将显示在“目录”字段下。
接收通知
事件现在将通过事件中心传送到你的应用程序中。 有关详细信息,请参阅事件中心文档中的接收事件。
在应用程序中接收通知之前,你需要创建另一个具有“侦听”权限的共享访问策略并获取连接字符串,类似于配置 Azure 事件中心中列出的步骤。
注意: 为应用程序创建单独的策略来侦听事件中心消息,而不是重用在 Azure 密钥保管库中设置的相同连接字符串。 这可确保解决方案的每个组件仅具有所需的权限,并遵循最低权限安全原则。
注意: 应用程序会在每次创建新订阅时收到验证消息。 应忽略这些通知。 下面的示例表示验证消息的正文。
{
"value":[
{
"subscriptionId":"NA",
"subscriptionExpirationDateTime":"NA",
"clientState":"NA",
"changeType":"Validation: Testing client application reachability for subscription Request-Id: 522a8e7e-096a-494c-aaf1-ac0dcfca45b7",
"resource":"NA",
"resourceData":{
"@odata.type":"NA",
"@odata.id":"NA",
"id":"NA"
}
}
]
}
如果缺少Microsoft Graph 更改跟踪应用程序,会发生什么情况?
租户中可能缺少 Microsoft Graph 更改跟踪 服务主体,这取决于租户的创建时间和管理操作。 要解决此问题,请在 Microsoft Graph 浏览器 中运行 以下查询。
查询详细信息: 0bf30f3b-4a52-48df-9a82-234910c4a086 是Microsoft Graph 更改跟踪应用程序的全局 appId。
POST https://graph.microsoft.com/v1.0/servicePrincipals
{
"appId": "0bf30f3b-4a52-48df-9a82-234910c4a086"
}
注意: 运行此查询会导致访问被拒绝。 在这种情况下,请选择左上角帐户名称旁边的齿轮图标。 然后选择“选择权限”并搜索 Application.ReadWrite.All。 检查权限,然后选择“同意”。 同意此新权限后,再次运行请求。
注意: 此 API 仅适用于学校或工作帐户,而不适用于个人帐户。 请确保使用域中的帐户登录。
或者,可以使用 Microsoft Graph PowerShell 中的 New-MgServicePrincipal cmdlet 添加缺少的服务主体。以下是示例脚本。
Connect-Graph -Scopes "Application.ReadWrite.All"
New-MgServicePrincipal -AppId "0bf30f3b-4a52-48df-9a82-234910c4a086"
后续步骤
请参阅下面的 Azure 事件中心快速入门:
历史资料。此文对应 2023-02-03 的中文文档快照,适用产品版本和命令行为以原文为准。
来源与署名:Microsoft 和文档贡献者(原始作者元数据 Jumaodhiss)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。
