快速入門 - 訂閱 Azure 通訊服務事件 - An Azure Communication Services quickstart

發行項
10/25/2024

本文說明如何透過入口網站、Azure CLI、PowerShell 和 .NET SDK 訂閱來自 Azure 通訊服務的事件。

您可以透過 Azure 入口網站、Azure CLI、PowerShell 或使用 Azure 事件方格管理 SDK 來設定通訊服務資源的事件訂用帳戶。

本快速入門說明將 Webhook 設定為來自 Azure 通訊服務 SMS 事件的訂閱者的程式。如需事件的完整清單，請參閱以 Azure 事件方格來源 Azure 通訊服務。

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
Azure 通訊服務資源。
建立 Webhook 來接收事件。請參閱 Webhook 事件傳遞。

註冊事件方格資源提供者

本文描述如何註冊事件方格資源提供者。如果您以前在相同的訂用帳戶中使用過事件方格，請跳至下一節。

在 Azure 入口網站中，執行下列步驟：

選取左側功能表上的 [訂用帳戶]。
從訂用帳戶清單中選取您要用於事件方格的訂用帳戶。
在 [訂用帳戶] 頁面上，在左側功能表的 [設定] 下方選取 [資源提供者]。
搜尋 [Microsoft.EventGrid]，並確認 [狀態] 為 [未註冊]。
在提供者清單中選取 [Microsoft.EventGrid]。
在命令列上選取 [註冊]。
重新整理以確定 Microsoft.EventGrid 的狀態已變更為已註冊。

建立事件訂閱

若要建立 Azure 通訊服務資源的事件訂用帳戶，請先登入 Azure 入口網站。在頁面的左上角，選取通訊服務資源。

從左側功能表中選取 [ 事件] 索引標籤。
選取 [+ 事件訂用帳戶]。

在 [建立事件訂閱] 頁面上，遵循下列步驟：
1. 輸入事件訂閱的名稱。
2. 輸入系統主題的名稱。
3. 選取您想要接收事件訂用帳戶的事件類型。
  
  如需詳細資訊，請參閱通訊服務事件。
4. 將 [端點類型] 選為 [Webhook]。
5. 選取 [設定端點]
6. 輸入 Webhook 的鏈接，然後選取 [ 確認選取專案]。
7. 在 [ 篩選] 索引標籤中，新增您想要在訂用帳戶中篩選的事件類型名稱。新增您想要在訂用帳戶中使用的任何內容屬性篩選。然後，選取頁面底部的 [下一步: 其他功能]。
8. 若要啟用無效信件功能及自訂重試原則，請選取 [其他功能]。
9. 完成後，請選取 [建立]。

更新事件訂閱

本節說明如何更新 Azure 通訊服務的事件訂用帳戶，以透過 Webhook 更新您要接收的事件。

若要更新 Azure 通訊服務資源的事件訂用帳戶，請先登入 Azure 入口網站。在頁面的左上角，選取通訊服務資源。

從左側功能表中選取 [ 事件] 索引標籤。
選取 [事件訂閱 ]，然後選取您要更新的事件訂用帳戶。
在 [ 事件訂閱] 頁面上，選取 [ 篩選] 索引標籤。選取您想要在事件訂閱上接收的事件類型。
若要啟用無效信件功能及自訂重試原則，請選取 [其他功能]。
若要更新 Webhook 以接收事件，請選取 Webhook 連結旁的 [變更 ]，然後輸入新的 Webhook 端點。
完成時，選取 [儲存]。

刪除事件訂閱

若要刪除 Azure 通訊服務的事件訂用帳戶，請遵循下列步驟。

若要刪除 Azure 通訊服務資源的事件訂用帳戶，請先登入 Azure 入口網站。在頁面的左上角，選取通訊服務資源。

從左側功能表中選取 [ 事件] 索引標籤。
選取 [事件訂閱 ]，然後選取您要刪除的事件訂用帳戶。
在 [事件訂閱] 頁面上，從頁面頂端選取 [刪除 ]。

下一步

如需通訊服務事件的清單，請參閱通訊服務事件。
如需支援的事件處理常式清單，請參閱事件處理常式。
如需事件傳遞和重試的相關信息，請參閱事件方格訊息傳遞和重試。
如需 Event Grid 的簡介，請參閱關於 Event Grid。

必要條件

具有有效訂用帳戶的 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 事件方格 Management 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_subscripiton_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 身分識別連結庫進行驗證

必要條件

建立事件訂閱

更新事件訂閱

刪除事件訂用帳戶

必要條件

註冊事件方格資源提供者

建立事件訂閱

列出事件訂用帳戶

更新事件訂閱

刪除事件訂閱

下一步

意見反應

其他資源