快速入门 - 订阅 Azure 通信服务事件 - An Azure Communication Services quickstart

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

项目
10/28/2024

本文介绍了如何通过门户、Azure CLI、PowerShell 和 .NET SDK 订阅 Azure 通信服务中的事件。

可以通过 Azure 门户或 Azure CLI、PowerShell 或者使用 Azure 事件网格管理 SDK 为通信服务资源设置事件订阅。

本快速入门描述了将 Webhook 设置为 Azure 通信服务中短信事件的订阅者过程。有关事件的完整列表，请参阅 Azure 通信服务作为 Azure 事件网格源。

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
Azure 通信服务资源。
创建 Webhook 以接收事件。查看 Webhook 事件传送。

注册事件网格资源提供程序

本文介绍如何注册事件网格资源提供程序。如果之前在同一订阅中使用了事件网格，请跳到下一部分。

在 Azure 门户中，执行以下步骤：

在左侧菜单中选择“订阅”。
从订阅列表中选择要用于事件网格的订阅。
在“订阅”页左侧菜单的“设置”下，选择“资源提供程序”。
搜索 Microsoft.EventGrid，并确认“状态”为“未注册”。
在提供程序列表中选择“Microsoft.EventGrid”。
在命令栏上选择“注册”。
刷新以确保 Microsoft.EventGrid 的状态更改为“已注册”。

创建事件订阅

若要为 Azure 通信服务资源创建事件订阅，请首先登录到 Azure 门户。在页面左上角，选择通信服务资源。

在左侧菜单上选择“事件”选项卡。
选择“+ 事件订阅”。

在“创建事件订阅”页上执行以下步骤：
1. 输入事件订阅的名称。
2. 在“系统主题名称”中输入名称。
3. 选择要在事件订阅中接收的事件类型。
  
  有关详细信息，请参阅通信服务事件。
4. 选择“Web Hook”作为终结点类型。
5. 选择“配置终结点”
6. 输入 Webhook 的链接，然后选择“确认选择”。
7. 在“筛选器”选项卡中，添加要在订阅中筛选的事件类型的名称。添加要在订阅中使用的任何上下文属性筛选器。然后，在页面底部选择“下一步: 其他功能”。
8. 若要启用死信和自定义重试策略，请选择“其他功能”。
9. 完成后，选择“创建”。

更新事件订阅

本部分介绍如何更新 Azure 通信服务事件订阅，以更新想要通过 Webhook 接收的事件。

若要更新 Azure 通信服务资源事件订阅，请首先登录到 Azure 门户。在页面左上角，选择通信服务资源。

在左侧菜单上选择“事件”选项卡。
选择“事件订阅”，然后选择要更新的事件订阅。
在“事件订阅”页上，选择“筛选器”选项卡。选择要在事件订阅中接收的事件类型。
若要启用死信和自定义重试策略，请选择“其他功能”。
若要更新 Webhook 以接收事件，请选择 Webhook 链接旁边的“更改”，然后输入新的 Webhook 终结点。
完成后，选择“保存”。

删除事件订阅

若要删除 Azure 通信服务的事件订阅，请使用以下步骤。

若要删除 Azure 通信服务资源事件订阅，请首先登录到 Azure 门户。在页面左上角，选择通信服务资源。

在左侧菜单上选择“事件”选项卡。
选择“事件订阅”，然后选择要删除的事件订阅。
在“事件订阅”页上，从页面顶部选择“删除”。

后续步骤

有关通信服务事件的列表，请参阅通信服务事件。
有关支持的事件处理程序的列表，请参阅事件处理程序。
有关事件传送和重试的信息，请参阅事件网格消息传送和重试。
有关事件网格的介绍，请参阅关于事件网格。

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
安装 Azure CLI。
Azure 通信服务资源。
创建 Webhook 以接收事件。查看 Webhook 事件传送。

注册事件网格资源提供程序

本文介绍如何注册事件网格资源提供程序。如果之前在同一订阅中使用了事件网格，请跳到下一部分。

运行以下命令，注册提供程序：

az provider register --namespace Microsoft.EventGrid

完成注册可能需要一些时间。若要查看状态，请运行以下命令：
```
az provider show --namespace Microsoft.EventGrid --query "registrationState"
```
当 registrationState 为 Registered 后，即可继续。

创建事件订阅

若要为 Azure 通信服务资源创建事件订阅，请登录 Azure CLI。可以从终端运行 az login 命令并提供凭据进行登录。

若要使用 Azure CLI 创建事件订阅，请使用 az eventgrid event-subscription create 命令：

az eventgrid event-subscription create 
    --name EventsWebhookSubscription
    --source-resource-id /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>
    --included-event-types Microsoft.Communication.SMSReceived Microsoft.Communication.SMSDeliveryReportReceived
    --endpoint-type webhook 
    --endpoint https://azureeventgridviewer.azurewebsites.net/api/updates

有关通信服务事件的列表，请参阅通信服务事件。

列出事件订阅

若要使用 Azure CLI 列出为 Azure 通信服务资源设置的所有现有事件订阅，请使用 az eventgrid event-subscription list 命令。

az eventgrid event-subscription list 
    --source-resource-id /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>

更新事件订阅

若要使用 Azure CLI 更新现有事件订阅，请使用 az eventgrid event-subscription update 命令。

az eventgrid event-subscription update 
    --name EventsWebhookSubscription
    --source-resource-id /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>
    --included-event-types Microsoft.Communication.SMSReceived Microsoft.Communication.SMSDeliveryReportReceived Microsoft.Communication.ChatMessageReceived
    --endpoint-type webhook 
    --endpoint https://azureeventgridviewer.azurewebsites.net/api/updates

删除事件订阅

若要使用 Azure CLI 删除现有事件订阅，请使用 az eventgrid event-subscription delete 命令。

az eventgrid event-subscription delete 
    --name EventsWebhookSubscription 
    --source-resource-id /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>

后续步骤

有关其他命令的信息，请参阅 Azure 事件网格 CLI。

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
适用于操作系统的最新版本 .NET Core SDK。
最新版本的 .NET Microsoft Azure 事件网格管理 SDK。
最新版本的 Azure 标识库。
Azure 通信服务资源。

注册事件网格资源提供程序

本文介绍如何注册事件网格资源提供程序。如果之前在同一订阅中使用了事件网格，请跳到下一部分。

在 Azure 门户中，执行以下步骤：

在左侧菜单中选择“订阅”。
从订阅列表中选择要用于事件网格的订阅。
在“订阅”页左侧菜单的“设置”下，选择“资源提供程序”。
搜索 Microsoft.EventGrid，并确认“状态”为“未注册”。
在提供程序列表中选择“Microsoft.EventGrid”。
在命令栏上选择“注册”。
刷新以确保 Microsoft.EventGrid 的状态更改为“已注册”。

安装 SDK

首先，使用 NuGet 安装适用于 .NET 的 Microsoft Azure 事件网格管理库：

dotnet add package Azure.ResourceManager.EventGrid;

在 C# 项目中包括事件网格管理 SDK：

using Microsoft.Azure.Management.EventGrid;
using Microsoft.Azure.Management.EventGrid.Models;

使用 Azure 标识库进行身份验证

先决条件

创建 Microsoft Entra 应用程序和服务主体，并设置由证书颁发机构颁发的客户端机密或受信任的证书。按照“注册 Microsoft Entra 应用并创建服务主体”中的说明进行操作。
将机密或证书存储在 Azure Keyvault 中。
按照使用 Azure 门户授予用户对 Azure 资源的访问权限中的说明，向参与者或所有者授权访问该应用程序的订阅。
阅读有关授权访问事件网格资源的详细内容。

Azure 标识库为整个 Azure SDK 提供了 Microsoft Entra ID（旧称 Azure Active Directory）令牌身份验证支持。它提供了一组 TokenCredential 实现，可用于构造支持 Microsoft Entra 令牌身份验证的 Azure SDK 客户端。有关详细信息，请参阅适用于 .NET 的 Azure 标识客户端库。

使用 NuGet 包含适用于 .NET 的 Azure 标识客户端库。

dotnet add package Azure.Identity;
dotnet add package Azure.Security.KeyVault.Secrets

在 C# 项目中包含 Azure 标识库。

using Microsoft.Azure.Identity;
using Azure.Security.KeyVault.Secrets

可以根据服务主体的配置方式传递机密凭据或证书凭据来获取访问令牌。

使用机密凭据获取访问令牌

若要获取机密凭据，则需要使用 SecretClient 从先决条件 2 中创建的 Keyvault 中读取。

// Authenticate the Keyvault client with DefaultAzureCredential and get the secret.
SecretClient secretClient = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());
string clientSecret = await secretClient.GetSecretAsync(secretName).Value;

// Get access token using secret credentials
string[] scopes = { "https://management.azure.com/.default" };
var application = ConfidentialClientApplicationBuilder
                    .Create('your-servicePrincipal-appId')
                    .WithAuthority(authorityUri: new Uri(authority), validateAuthority: true)
                    .WithTenantId('your-tenant_id')
                    .WithClientSecret(clientSecret)
                    .Build();

var token = await application
                .AcquireTokenForClient(scopes)
                .ExecuteAsync();

使用证书凭据获取访问令牌。

若要获取证书凭据，则需要使用 CertificateClient 从先决条件 2 中创建的 Keyvault 中读取。

在应用程序配置选项中详细了解 Microsoft Entra 应用程序配置机构。

// Authenticate the certificate client with DefaultAzureCredential and get the certificate.
CertificateClient certificateClient = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());
X509Certificat2 cert = await certificateClient.DownloadCertificateAsync(certificateName);

// Get access token using certificate credentials
string[] scopes = { "https://management.azure.com/.default" };
string authority = "https://login.microsoftonline.com/<tenant>/";
var application = ConfidentialClientApplicationBuilder
                    .Create('<servicePrincipal-appId>')
                    .WithAuthority(authorityUri: new Uri(authority), validateAuthority: true)
                    .WithTenantId("<tenantId>")
                    .WithCertificate(cert)
                    .Build();

var token = await application
                .AcquireTokenForClient(scopes)
                .WithSendX5C(true)
                .ExecuteAsync();

使用机密或证书凭据通过访问令牌对 EventGridManagementClient 进行身份验证。

// Authenticate EventGridManagementClient with Microsoft Entra ID access token credential
eventGridClient = new EventGridManagementClient(new Uri("https://management.azure.com/"),
    new TokenCredentials(token.AccessToken));

eventGridClient.SubscriptionId = 'your_subscription_id';

创建事件订阅

此代码示例演示如何为 Webhook 订阅服务器终结点创建事件订阅。

string webhookUri = $"<webhookUri>";
string resourceId="/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>";
string[] includedEventTypes = new string[]{ "Microsoft.Communication.SMSReceived", 
                                            "Microsoft.Communication.SMSDeliveryReportReceived"
                                            };

EventSubscription eventSubscription = new EventSubscription(
    name: "<eventSubscriptionName>",
    eventDeliverySchema: "EventGridSchema",
    filter: new EventSubscriptionFilter(
    includedEventTypes: includedEventTypes),
    destination: new WebHookEventSubscriptionDestination(webhookUri));

await eventGridClient.EventSubscriptions.CreateOrUpdateAsync(
    scope: resourceId,
    eventSubscriptionName: "<eventSubscriptionName>",
    eventSubscriptionInfo: eventSubscription);

更新事件订阅

此代码示例演示了如何更新事件订阅以添加更多你希望在 Webhook 订阅服务器终结点上接收的事件。

string webhookUri = $"<webhookUri>";
string resourceId="/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>";
string[] additionalEventTypes = new string[]{ 
                                            "Microsoft.Communication.ChatMessageReceived"
                                        };

await eventGridClient.EventSubscriptions.UpdateAsync(
    scope: resourceId,
    eventSubscriptionName: "<eventSubscriptionName>",
    eventSubscriptionUpdateParameters: new EventSubscriptionUpdateParameters(
            filter: new EventSubscriptionFilter(includedEventTypes: additionalEventTypes)));

删除事件订阅

此代码示例演示如何删除 Webhook 订阅服务器终结点的事件订阅。

string webhookUri = $"<webhookUri>";
string resourceId="/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>";

await eventGridClient.EventSubscriptions.DeleteAsync(
    scope: resourceId,
    eventSubscriptionName: "<eventSubscriptionName>");

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
安装 Azure Az PowerShell 模块。
Azure 通信服务资源。
创建 Webhook 以接收事件。查看 Webhook 事件传送。

注册事件网格资源提供程序

本文介绍如何注册事件网格资源提供程序。如果之前在同一订阅中使用了事件网格，请跳到下一部分。

运行以下命令：

Register-AzResourceProvider -ProviderNamespace Microsoft.EventGrid

完成注册可能需要一些时间。若要检查状态，请运行：

Get-AzResourceProvider -ProviderNamespace Microsoft.EventGrid

当 RegistrationStatus 为 Registered 后，即可继续。

创建事件订阅

首先，使用以下命令安装 Azure 通信服务模块 Az.EventGrid。

PS C:\> Install-Module Az.EventGrid

使用 Connect-AzAccount 命令登录到 Azure 订阅，然后按屏幕说明操作。
```
Connect-AzAccount
```
如果你的标识已关联到多个订阅，请将你的活动订阅设置为要移动的 Web PubSub 资源的订阅。
```
$context = Get-AzSubscription -SubscriptionId <subscription-id>
Set-AzContext $context
```

若要使用 Azure PowerShell 创建事件订阅，请使用 New-AzEventGridSubscription 命令。

$includedEventTypes = "Microsoft.Communication.SMSReceived", "Microsoft.Communication.SMSDeliveryReportReceived"
New-AzEventGridSubscription 
    -EndpointType webhook
    -Endpoint https://azureeventgridviewer.azurewebsites.net/api/updates
    -EventSubscriptionName EventsWebhookSubscription 
    -IncludedEventType $includedEventTypes
    -ResourceId "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>"

有关通信服务事件的列表，请参阅通信服务事件。

列出事件订阅

若要使用 Azure PowerShell 列出为 Azure 通信服务资源设置的所有现有事件订阅，请使用 Get-AzEventGridSubscription 命令。

Get-AzEventGridSubscription 
    -ResourceId "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>"

更新事件订阅

若要使用 Azure PowerShell 更新现有事件订阅，请使用 Update-AzEventGridSubscription 命令。

$includedEventTypes = "Microsoft.Communication.SMSReceived", "Microsoft.Communication.SMSDeliveryReportReceived", "Microsoft.Communication.ChatMessageReceived"
Update-AzEventGridSubscription 
    -EventSubscriptionName ES2 
    -IncludedEventType $includedEventTypes
    -ResourceId "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>" 
    -Endpoint https://azureeventgridviewer2.azurewebsites.net/api/updates
    -SubjectEndsWith "phoneNumber"

删除事件订阅

若要使用 Azure PowerShell 删除现有事件订阅，请使用 Remove-AzEventGridSubscription 命令。

Get-AzResource 
    -ResourceId "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>" | Remove-AzEventGridSubscription -EventSubscriptionName ES2

后续步骤

有关其他命令的信息，请参阅 Az.EventGrid PowerShell 模块。

通过

先决条件

注册事件网格资源提供程序

创建事件订阅

更新事件订阅

删除事件订阅

后续步骤

先决条件

注册事件网格资源提供程序

创建事件订阅

列出事件订阅

更新事件订阅

删除事件订阅

后续步骤

先决条件

注册事件网格资源提供程序

安装 SDK

使用 Azure 标识库进行身份验证

先决条件

创建事件订阅

更新事件订阅

删除事件订阅

先决条件

注册事件网格资源提供程序

创建事件订阅

列出事件订阅

更新事件订阅

删除事件订阅

后续步骤

反馈

其他资源

通过

快速入门：订阅 Azure 通信服务事件

先决条件

注册事件网格资源提供程序

创建事件订阅

更新事件订阅

删除事件订阅

后续步骤

先决条件

注册事件网格资源提供程序

创建事件订阅

列出事件订阅

更新事件订阅

删除事件订阅

后续步骤

先决条件

注册事件网格资源提供程序

安装 SDK

使用 Azure 标识库进行身份验证

先决条件

创建事件订阅

更新事件订阅

删除事件订阅

先决条件

注册事件网格资源提供程序

创建事件订阅

列出事件订阅

更新事件订阅

删除事件订阅

后续步骤

反馈

其他资源