Merge pull request #264437 from pgrandhi/AddEventsDocs

Adding Events documentation to quickstart

Author: Court72

articles/communication-services/quickstarts/events/includes/create-event-subscription-az-cli.md

@@ -0,0 +1,70 @@
+---
+author: pgrandhi
+ms.service: azure-communication-services
+ms.custom: devx-track-azurecli
+ms.topic: include
+ms.date: 01/27/2024
+ms.author: pgrandhi
+---
+
+## Prerequisites
+
+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/dotnet/).
+- Install [Azure CLI](/cli/azure/install-azure-cli-windows?tabs=azure-cli) 
+- An [Azure Communication Services resource](../../create-communication-resource.md)
+- Create a Webhook to receive events. [Webhook Event Delivery](../../../../../articles/event-grid/webhook-event-delivery.md)
+
+
+[!INCLUDE [register-provider-cli.md](register-provider-cli.md)]
+
+## Create event subscription
+
+To create event subscriptions for Azure Communication Services resource, [sign in to Azure CLI](/cli/azure/authenticate-azure-cli). You can sign in running the ```az login``` command from the terminal and providing your credentials. Run the following command to create the event subscription for the resource:
+
+To create an event subscription by using [the Azure CLI](/cli/azure/get-started-with-azure-cli), use the [`az eventgrid event-subscription create`](/cli/azure/eventgrid/event-subscription#az-eventgrid-event-subscription-create) command. 
+
+```azurecli-interactive
+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  
+```
+
+For a list of Communication Services events, see [Communication Services Events](../../../../../articles/event-grid/event-schema-communication-services.md).
+
+## List event subscriptions
+
+To list all the existing event subscriptions set up for an Azure Communication Services resource, by using [the Azure CLI](/cli/azure/get-started-with-azure-cli), use the [`az eventgrid event-subscription list`](/cli/azure/eventgrid/event-subscription#az-eventgrid-event-subscription-list) command. 
+
+```azurecli-interactive
+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
+```
+
+## Update event subscription
+
+To update an existing event subscription by using [the Azure CLI](/cli/azure/get-started-with-azure-cli), use the [`az eventgrid event-subscription update`](/cli/azure/eventgrid/event-subscription#az-eventgrid-event-subscription-update) command. 
+
+```azurecli-interactive
+az eventgrid event-subscription list 
+    --source-resource-id /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>    
+```
+
+## Delete event subscription
+
+To delete an existing event subscription by using [the Azure CLI](/cli/azure/get-started-with-azure-cli), use the [`az eventgrid event-subscription delete`](/cli/azure/eventgrid/event-subscription#az-eventgrid-event-subscription-delete) command. 
+
+```azurecli-interactive
+az eventgrid event-subscription delete 
+    --name EventsWebhookSubscription 
+    --source-resource-id /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>
+```
+
+## Next steps
+* For information on other commands, see [Azure Event Grid CLI](/cli/azure/eventgrid/event-subscription).

articles/communication-services/quickstarts/events/includes/create-event-subscription-azp.md

@@ -0,0 +1,103 @@
+---
+author: pgrandhi
+ms.service: azure-communication-services
+ms.topic: include
+ms.date: 01/26/2024
+ms.author: pgrandhi
+---
+
+## Prerequisites
+
+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/dotnet/).
+- An [Azure Communication Services resource](../../create-communication-resource.md).
+- Create a Webhook to receive events. [Webhook Event Delivery](/azure/event-grid/webhook-event-delivery).
+
+[!INCLUDE [register-event-grid-resource-provider.md](register-event-grid-resource-provider.md)]
+
+## Create event subscription
+
+To create an Event subscription for Azure Communication Services, use the following steps. This article shows how to create an Event subscription for Azure Communication Services to receive events via Webhook.
+
+To create an Event subscription for Azure Communication Services resource, first sign in to the [Azure portal](https://portal.azure.com). In the upper-left corner of the page, select the Communication Services resource. 
+* Select on the Events tab on the left menu.
+* Select on **+ Event Subscription**. 
+
+:::image type="content" source="../media/subscribe-through-portal/add-subscription.png" alt-text="Screenshot highlighting the create event subscription button in the Azure portal." lightbox="../media/subscribe-through-portal/add-subscription.png":::
+
+* On the **Create Event Subscription** page, follow these steps:
+1. Enter a name for the event subscription. 
+1. Enter a name for the System topic name.
+1. Select the event types that you want to receive on the event subscription.
+
+   :::image type="content" source="../media/subscribe-through-portal/select-event-types.png" alt-text="Screenshot that shows the selection of event types." lightbox="../media/subscribe-through-portal/select-event-types.png":::
+
+   For more information on Communication Services events, see [Communication Services Events](/azure/event-grid/event-schema-communication-services)
+
+1. Select the Endpoint Type as Web Hook.
+ 
+   :::image type="content" source="../media/subscribe-through-portal/select-endpoint-type.png" alt-text="Screenshot that shows the selection of endpoint type." lightbox="../media/subscribe-through-portal/select-endpoint-type.png":::
+
+1. Select **Configure an Endpoint**
+
+    :::image type="content" source="../media/subscribe-through-portal/create-event-subscription.png" alt-text="Screenshot highlighting the create event page in the Azure portal." lightbox="../media/subscribe-through-portal/create-event-subscription.png":::
+ 
+1. Enter the link to the webhook and Select **Confirm Selection**.
+
+    :::image type="content" source="../media/subscribe-through-portal/select-web-hook-endpoint.png" alt-text="Screenshot highlighting the select webhook endpoint page in the Azure portal." lightbox="../media/subscribe-through-portal/select-web-hook-endpoint.png":::
+
+1. In the **Filters** tab, add the names of the event types you want to filter in the subscription and add context attribute filters you want to use in the subscription. Then, select **Next: Additional features** at the bottom of the page.
+
+    :::image type="content" source="../media/subscribe-through-portal/create-event-filters.png" alt-text="Screenshot highlighting Event Grid create filters page in the Azure portal." lightbox="../media/subscribe-through-portal/create-event-filters.png":::
+
+1. To enable dead lettering and customize retry policies, select **Additional Features**.
+
+    :::image type="content" source="../media/subscribe-through-portal/select-additional-features.png" alt-text="Screenshot that shows the Additional features tab of the Create Event Subscription page." lightbox="../media/subscribe-through-portal/select-additional-features.png":::
+
+1. When done, select **Create**.
+
+
+## Update event subscription
+
+To update an Event subscription for Azure Communication Services, use the following steps. This section shows how to update an Event subscription for Azure Communication Services to update the events you want to receive via Webhook.
+
+To update an Event subscription for Azure Communication Services resource, first sign in to the [Azure portal](https://portal.azure.com). In the upper-left corner of the page, select the Communication Services resource. 
+
+1. Select the Events tab on the left menu.
+1. Select the **Event Subscriptions** and select on the Event subscription you want to update. 
+
+    :::image type="content" source="../media/subscribe-through-portal/event-subscriptions.png" alt-text="Screenshot highlighting the event subscription button in the Azure portal." lightbox="../media/subscribe-through-portal/event-subscriptions.png":::
+
+1. On the **Event Subscription** page, select on **Filters** tab. Select the event types that you want to receive on the event subscription.
+
+    :::image type="content" source="../media/subscribe-through-portal/update-event-types.png" alt-text="Screenshot that shows the selection of event types to update." lightbox="../media/subscribe-through-portal/update-event-types.png":::
+
+1. To enable dead lettering and customize retry policies, select **Additional Features**.
+
+    :::image type="content" source="../media/subscribe-through-portal/select-additional-features.png" alt-text="Screenshot that shows the Additional features tab of the Update Event Subscription page." lightbox="../media/subscribe-through-portal/select-additional-features.png":::
+
+1. To update the webhook to receive events, select on **Change** next to the webhook link and enter the new webhook endpoint. 
+     :::image type="content" source="../media/subscribe-through-portal/update-web-hook-endpoint.png" alt-text="Screenshot that shows the Change the webhook endpoint link in the Event Subscription page." lightbox="../media/subscribe-through-portal/update-web-hook-endpoint.png":::
+
+1. When done, select **Save**,
+     :::image type="content" source="../media/subscribe-through-portal/save-update.png" alt-text="Screenshot that shows the save button in the Azure portal." lightbox="../media/subscribe-through-portal/save-update.png":::
+
+## Delete event subscription
+
+To delete an Event subscription for Azure Communication Services, use the following steps.
+
+To delete an Event subscription for Azure Communication Services resource, first sign in to the [Azure portal](https://portal.azure.com). In the upper-left corner of the page, select the Communication Services resource. 
+
+1. Select on the Events tab on the left menu.
+1. Select on **Event Subscriptions** and Select on the Event subscription you want to delete. 
+
+    :::image type="content" source="../media/subscribe-through-portal/event-subscriptions.png" alt-text="Screenshot highlighting the event subscriptions button to access event subscription to be deleted in the Azure portal." lightbox="../media/subscribe-through-portal/event-subscriptions.png":::
+
+1. On the Event Subscription page, Select on **Delete** button at the top. 
+
+    :::image type="content" source="../media/subscribe-through-portal/delete-subscription.png" alt-text="Screenshot highlighting the delete button in the Azure portal." lightbox="../media/subscribe-through-portal/delete-subscription.png":::
+
+## Next steps
+* For a list of Communication Services events, see [Communication Services Events](/azure/event-grid/event-schema-communication-services).
+* For a list of supported event handlers, see [Event handlers](/azure/event-grid/event-handlers).
+* For information about event delivery and retries, [Event Grid message delivery and retry](/azure/event-grid/delivery-and-retry).
+* For an introduction to Event Grid, see [About Event Grid](/azure/event-grid/overview).

articles/communication-services/quickstarts/events/includes/create-event-subscription-net.md

@@ -0,0 +1,170 @@
+---
+author: pgrandhi
+ms.service: azure-communication-services
+ms.topic: include
+ms.date: 01/28/2024
+ms.author: pgrandhi
+---
+
+## Prerequisites
+
+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/dotnet/).
+- The latest version [.NET Core SDK](https://dotnet.microsoft.com/download/dotnet-core) for your operating system.
+- Get the latest version of the [.NET Microsoft Azure Event Grid Management SDK](/azure/event-grid/sdk-overview).
+- Get the latest version of the [Azure Identity](/dotnet/api/overview/azure/identity-readme) library.
+- An [Azure Communication Services resource](../../create-communication-resource.md).
+
+[!INCLUDE [register-event-grid-resource-provider.md](register-event-grid-resource-provider.md)]
+
+## Installing the SDK
+
+First, install the Microsoft Azure Event Grid Management library for .NET with [NuGet](https://www.nuget.org/):
+
+```csharp
+dotnet add package Azure.ResourceManager.EventGrid;
+```
+Include the Event Grid Management SDK in your C# project:
+
+```csharp
+using Microsoft.Azure.Management.EventGrid;
+using Microsoft.Azure.Management.EventGrid.Models;
+```
+
+## Authenticating with Azure Identity library
+
+### Prerequisites:
+1. Create a Microsoft Entra application and Service Principal and set up a client secret or trusted certificate issued by certificate authority by following the instructions [here](/entra/identity-platform/howto-create-service-principal-portal).
+1. Store the secret or the certificate in the Azure Keyvault. 
+1. Give contributor or owner access to the subscription to that application following the instructions [here](/azure/role-based-access-control/quickstart-assign-role-user-portal).
+1. Read more about authorizing access to Event Grid resources [here](/azure/event-grid/security-authorization). 
+
+The Azure Identity library provides Microsoft Entra ID (Formerly Azure Active Directory) token authentication support across the Azure SDK. It provides a set of TokenCredential implementations, which can be used to construct Azure SDK clients that support Microsoft Entra token authentication. You can read more about it [here](/dotnet/api/overview/azure/identity-readme).
+
+1. Include the Azure Identity client library for .NET with [NuGet](https://www.nuget.org/):
+
+```csharp
+dotnet add package Azure.Identity;
+dotnet add package Azure.Security.KeyVault.Secrets
+```
+2. Include the Azure Identity library in your C# project
+
+```csharp
+using Microsoft.Azure.Identity;
+using Azure.Security.KeyVault.Secrets
+```
+
+3. You can either pass the secret credentials or certificate credentials to get access token, based on how your Service Principal is configured.
+
+    * Get access token using secret credential
+
+        To get the secret credentials, you need to read it from the Keyvault you created in Prerequisite #2 using [SecretClient](/azure/key-vault/secrets/quick-create-net). 
+        
+        ```csharp
+        // 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();
+        ```
+
+    * Get access token using certificate credential
+
+        To get the certificate credentials, you need to read it from the Keyvault you created in Prerequisite #2 using [CertificateClient](/azure/key-vault/certificates/quick-create-net). 
+        
+        Read more about the Microsoft Entra application configuration authority [here](/entra/identity-platform/msal-client-application-configuration)
+        
+        ```csharp
+        // 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();
+        ```
+
+4. Authenticate EventGridManagementClient with access token using secret or certificate credentials
+
+
+```csharp
+// 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';
+```
+
+## Create Event Subscription
+This code sample shows how to create the event subscription for the webhook subscriber endpoint.
+
+```csharp
+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);
+```
+
+## Update event subscription
+This code sample shows how to update the event subscription to add more events, you want to receive on the webhook subscriber endpoint.
+
+```csharp
+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)));
+```
+
+## Delete event Subscription
+This code sample shows how to delete the event subscription for the webhook subscriber endpoint.
+
+```csharp
+string webhookUri = $"<webhookUri>";
+string resourceId="/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>";
+
+await eventGridClient.EventSubscriptions.DeleteAsync(
+    scope: resourceId,
+    eventSubscriptionName: "<eventSubscriptionName>");
+```
+