クイックスタート: Azure Communication Services Events にサブスクライブする - An Azure Communication Services quickstart

[アーティクル]
10/28/2024

この記事では、ポータル、Azure CLI、PowerShell、.NET SDK を介して、Azure Communication Services からイベントにサブスクライブする方法について説明します。

Communication Services リソースのイベントサブスクリプションは、Azure portal、Azure CLI、PowerShell、あるいは Azure Event Grid Management SDK を介して設定することができます。

このクイックスタートでは、SMS イベントのサブスクライバーとして、 Webhook の設定を、Azure Communication Services から行なうプロセスについて説明します。イベントの完全な一覧については、「Azure Event Grid ソースとしての Azure Communication Services」のページを参照してください。

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
Azure Communication Services リソース。
イベントを受信する Webhook を作成します。「Webhook のイベント配信」に関するページを参照してください。

Event Grid リソースプロバイダーを登録する

このアーティクルでは、Azure Event Grid リソースプロバイダーを登録する方法について説明します。同じサブスクリプションで以前に Event Grid を使用している場合は、次のセクションにスキップしてください。

Azure portal で、次の手順を実行します。

左側のメニューで [サブスクリプション] を選択します。
サブスクリプションのリストから、Event Grid に使用するサブスクリプションを選択します。
[サブスクリプション] ページで、左側のメニューの [設定] の下の [リソースプロバイダー] を選択します。
Microsoft.EventGrid を検索し、[状態] が [未登録] であることを確認します。
プロバイダーの一覧で [Microsoft.EventGrid] を選択します。
コマンドバーの [登録] を選択します。
最新の情報に更新して、Microsoft.EventGrid の状態が [登録済み] に変更されたことを確認します。

イベントサブスクリプションの作成

Azure Communication Services リソースのイベントサブスクリプションを作成するには、まず Azure portal にサインインします。ページの左上隅で、Communication Services リソースを選択します。

左側のメニューで [イベント] タブを選択します。
[+ イベントサブスクリプション] を選択します。

[イベントサブスクリプションの作成] ページで、次の手順に従います。
1. イベントサブスクリプションの名前を入力します。
2. システムトピックの名前を入力します。
3. イベントサブスクリプションで受信するイベントの種類を選択します。
  
  詳細については、Communication Services のイベントに関するページを参照してください。
4. エンドポイントの種類として [Webhook] を選択します。
5. [エンドポイントの構成] を選択します
6. Webhook へのリンクを入力し、[選択内容の確認] を選択します。
7. [フィルター] タブに、サブスクリプションでフィルター処理するイベントの種類の名前を追加します。サブスクリプションで使用するコンテキスト属性フィルターを追加します。次に、ページの下部にある [次へ: 追加の機能] を選択します。
8. 配信不能レタリングを有効にして、再試行ポリシーをカスタマイズするには、 [追加の機能] を選択します。
9. 完了したら、 [作成] を選択します。

イベントサブスクリプションの更新

このセクションでは、Azure Communication Services のイベントサブスクリプションを更新して、Webhook 経由で受信するイベントを更新する方法について説明します。

Azure Communication Services リソースのイベントサブスクリプションを更新するには、まず Azure portal にサインインします。ページの左上隅で、Communication Services リソースを選択します。

左側のメニューで [イベント] タブを選択します。
[イベントサブスクリプション] を選択した後、更新する Event サブスクリプションを選択します。
[イベントサブスクリプション] ページで、[フィルター] タブを選択します。イベントサブスクリプションで受信するイベントの種類を選択します。
配信不能レタリングを有効にして、再試行ポリシーをカスタマイズするには、 [追加の機能] を選択します。
イベントを受信するように Webhook を更新するには、Webhook リンクの隣にある [変更] を選択し、新しいWebhook エンドポイントを入力します。
操作が完了したら、[保存] をクリックします。

イベントサブスクリプションの削除

Azure Communication Services のイベントサブスクリプションを削除するには、これらの手順に従います。

Azure Communication Services リソースのイベントサブスクリプションを削除するには、まず Azure portal にサインインします。ページの左上隅で、Communication Services リソースを選択します。

左側のメニューで [イベント] タブを選択します。
[イベントサブスクリプション] を選択し、削除するイベントサブスクリプションを選択します。
[イベントサブスクリプション] ページで、ページの上部にある [削除] を選択します。

次のステップ

Communication Services イベントのリストについては、「Communication Services イベント」を参照してください。
サポートされているイベントハンドラーの一覧については、「イベントハンドラー」を参照してください。
イベント配信と再試行については、「Event Grid によるメッセージの配信と再試行」をご覧ください。
Event Grid の概要については、Event Grid の紹介に関する記事を参照してください。

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
Azure CLI をインストールします。
Azure Communication Services リソース。
イベントを受信する Webhook を作成します。「Webhook のイベント配信」に関するページを参照してください。

Event Grid リソースプロバイダーを登録する

以下のプロバイダーを登録するコマンドを実行します。
```
az provider register --namespace Microsoft.EventGrid
```
登録完了まで少し時間がかかることがあります。状態を確認するには、次のコマンドを実行します。
```
az provider show --namespace Microsoft.EventGrid --query "registrationState"
```
registrationState が Registered になったら、次に進めることができます。

イベントサブスクリプションの作成

Azure Communication Services リソースのイベントサブスクリプションを作成するには、 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

Communication Services イベントのリストについては、「Communication Services イベント」を参照してください。

イベントサブスクリプションをリストする

Azure CLI を使用して、Azure Communication Services リソース用に設定されているすべての既存のイベントサブスクリプションを一覧表示するには、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 Event Grid CLI」を参照してください。

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
お使いのオペレーティングシステムに対応した最新バージョンの .NET Core SDK。
.NET Microsoft Azure Event Grid Management SDK の最新バージョン。
Azure ID ライブラリの最新バージョン。
Azure Communication Services リソース。

Event Grid リソースプロバイダーを登録する

Azure portal で、次の手順を実行します。

左側のメニューで [サブスクリプション] を選択します。
サブスクリプションのリストから、Event Grid に使用するサブスクリプションを選択します。
[サブスクリプション] ページで、左側のメニューの [設定] の下の [リソースプロバイダー] を選択します。
Microsoft.EventGrid を検索し、[状態] が [未登録] であることを確認します。
プロバイダーの一覧で [Microsoft.EventGrid] を選択します。
コマンドバーの [登録] を選択します。
最新の情報に更新して、Microsoft.EventGrid の状態が [登録済み] に変更されたことを確認します。

SDK のインストール

まず、NuGet を使用して、.NET 用の Microsoft Azure Event Grid Management ライブラリをインストールします。

dotnet add package Azure.ResourceManager.EventGrid;

C# プロジェクトに Event Grid Management SDK をインクルードします。

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

Azure ID ライブラリを使用した認証

前提条件

Microsoft Entra アプリケーションとサービスプリンシパルを作成し、証明機関によって発行されたクライアントシークレットまたは信頼された証明書を設定します。「Microsoft Entra アプリを登録し、サービスプリンシパルを作成する」の手順に従います。
Azure Keyvault に、シークレットまたは証明書を保存します。
「Azure portal を使用して Azure リソースへのアクセス権をユーザーに付与する」の手順に従って、そのアプリケーションのサブスクリプションへの共同作成者または所有者のアクセス権を付与します。
詳細については、「Event Grid リソースへのアクセスの承認」を参照してください。

Azure ID ライブラリは、Azure SDK 全体で、Microsoft Entra ID (以前の Azure Active Directory) トークンの認証をサポートしています。ここで提供されている一連の TokenCredential 実装は、Microsoft Entra トークン認証をサポートする Azure SDK クライアントをコンストラクトするために使用できます。詳細については、.NET 用 Azure Identity クライアントライブラリに関するページを参照してください。

NuGet を使用して .NET 用 Azure ID クライアントライブラリを含めます。

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

お使いの C# プロジェクトに Azure ID ライブラリを含めます。

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

ユーザーは、サービスプリンシパルでの構成に基づいて、シークレット資格情報または証明書資格情報を渡して、アクセストークンを取得できます。

シークレット資格情報を使用してアクセストークンを取得する

シークレット資格情報を取得するには、前提条件 2 で SecretClient を使用して作成した 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();

証明書資格情報を使用してアクセストークンを取得する。

証明書の資格情報を取得するには、前提条件 2 で CertificateClient を使用して作成した 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 Communication Services リソース。
イベントを受信する Webhook を作成します。「Webhook のイベント配信」に関するページを参照してください。

Event Grid リソースプロバイダーを登録する

このアーティクルでは、Event Grid リソースプロバイダーを登録する方法について説明します。同じサブスクリプションで以前に Event Grid を使用している場合は、次のセクションにスキップしてください。

次のコマンドを実行します。

Register-AzResourceProvider -ProviderNamespace Microsoft.EventGrid

登録完了まで少し時間がかかることがあります。状態をチェックするには、次を実行します。

Get-AzResourceProvider -ProviderNamespace Microsoft.EventGrid

RegistrationStatus が Registered になったら、次に進めることができます。

イベントサブスクリプションの作成

まず、次のコマンドを実行して、Azure Communication Services モジュール Az.EventGrid をインストールします。

PS C:\> Install-Module Az.EventGrid

Connect-AzAccount コマンドを使用して Azure サブスクリプションにサインインし、画面上の指示に従います。
```
Connect-AzAccount
```
自分の ID が複数のサブスクリプションに関連付けられている場合は、アクティブなサブスクリプションを、移動する 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>"

Communication Services イベントのリストについては、「Communication Services イベント」を参照してください。

イベントサブスクリプションをリストする

Azure Communication Services リソース用に設定されているすべての既存のイベントサブスクリプションをリストするには、Azure PowerShell で 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 モジュール」を参照してください。

次の方法で共有

前提条件

Event Grid リソースプロバイダーを登録する

イベントサブスクリプションの作成

イベントサブスクリプションの更新

イベントサブスクリプションの削除

次のステップ

前提条件

Event Grid リソースプロバイダーを登録する

イベントサブスクリプションの作成

イベントサブスクリプションをリストする

イベントサブスクリプションの更新

イベントサブスクリプションの削除

次のステップ

前提条件

Event Grid リソースプロバイダーを登録する

SDK のインストール

Azure ID ライブラリを使用した認証

前提条件

イベントサブスクリプションを作成する

イベントサブスクリプションの更新

イベントサブスクリプションの削除

前提条件

Event Grid リソースプロバイダーを登録する

イベントサブスクリプションの作成

イベントサブスクリプションをリストする

イベントサブスクリプションの更新

イベントサブスクリプションの削除

次のステップ

フィードバック

その他のリソース

次の方法で共有

クイック スタート: Azure Communication Services のイベントにサブスクライブする

前提条件

Event Grid リソース プロバイダーを登録する

イベント サブスクリプションの作成

イベント サブスクリプションの更新

イベント サブスクリプションの削除

次のステップ

前提条件

Event Grid リソース プロバイダーを登録する

イベント サブスクリプションの作成

イベント サブスクリプションをリストする

イベント サブスクリプションの更新

イベント サブスクリプションの削除

次のステップ

前提条件

Event Grid リソース プロバイダーを登録する

SDK のインストール

Azure ID ライブラリを使用した認証

前提条件

イベント サブスクリプションを作成する

イベント サブスクリプションの更新

イベント サブスクリプションの削除

前提条件

Event Grid リソース プロバイダーを登録する

イベント サブスクリプションの作成

イベント サブスクリプションをリストする

イベント サブスクリプションの更新

イベント サブスクリプションの削除

次のステップ

フィードバック

その他のリソース

クイックスタート: Azure Communication Services のイベントにサブスクライブする

Event Grid リソースプロバイダーを登録する

イベントサブスクリプションの作成

イベントサブスクリプションの更新

イベントサブスクリプションの削除

Event Grid リソースプロバイダーを登録する

イベントサブスクリプションの作成

イベントサブスクリプションをリストする

イベントサブスクリプションの更新

イベントサブスクリプションの削除

Event Grid リソースプロバイダーを登録する

イベントサブスクリプションを作成する

イベントサブスクリプションの更新

イベントサブスクリプションの削除

Event Grid リソースプロバイダーを登録する

イベントサブスクリプションの作成

イベントサブスクリプションをリストする

イベントサブスクリプションの更新

イベントサブスクリプションの削除