Quickstart: Create and manage Communication Services resources

Get started with Azure Communication Services by provisioning your first Communication Services resource. Communication services resources can be provisioned through the Azure portal or with the .NET management SDK. The management SDK and the Azure portal allow you to create, configure, update and delete your resources and interface with Azure Resource Manager, Azure's deployment and management service. All functionality available in the SDKs is available in the Azure portal.

Warning

Note that while Communication Services is available in multiple geographies, in order to get a phone number the resource must have a data location set to 'US'. Also note that communication resources cannot be transferred to a different subscription during public preview.

Prerequisites

Create Azure Communication Resource

To create an Azure Communication Services resource, first sign in to the Azure portal. In the upper-left corner of the page, select + Create a resource.

Screenshot highlighting the create a resource button in the Azure portal.

Enter Communication into either the Search the Marketplace input or the search bar at the top of the portal.

Screenshot showing a search for communication services in the search bar.

Select Communication Services in the results, and then select Create.

Screenshot showing the Communication Services panel, highlighting the Create button.

You can now configure your Communication Services resource. On the first page in the create process, you'll be asked to specify:

  • The subscription
  • The resource group (you can create a new one or choose an existing resource group)
  • The name of the Communication Services resource
  • The geography the resource will be associated with

In the next step, you can assign tags to the resource. Tags can be used to organize your Azure resources. See the resource tagging documentation for more information about tags.

Finally, you can review your configuration and Create the resource. Note that the deployment will take a few minutes to complete.

Manage your Communication Services resource

To manage your Communication Services resource, go to the Azure portal, and search for and select Azure Communication Services.

On the Communication Services page, select the name of your resource.

The Overview page for your resource contains options for basic management like browse, stop, start, restart, and delete. You can find more configuration options in the left menu of your resource page.

Prerequisites

Create Azure Communication Resource

To create an Azure Communication Services resource, sign in to Azure CLI. You can do this through the terminal using the az login command and providing your credentials. Run the following command to create the resource:

az communication create --name "<communicationName>" --location "Global" --data-location "United States" --resource-group "<resourceGroup>"

If you would like to select a specific subscription you can also specify the --subscription flag and provide the subscription ID.

az communication create --name "<communicationName>" --location "Global" --data-location "United States" --resource-group "<resourceGroup> --subscription "<subscriptionID>"

You can configure your Communication Services resource with the following options:

  • The resource group
  • The name of the Communication Services resource
  • The geography the resource will be associated with

In the next step, you can assign tags to the resource. Tags can be used to organize your Azure resources. See the resource tagging documentation for more information about tags.

Manage your Communication Services resource

To add tags to your Communication Services resource, run the following commands. You can target a specific subscription as well.

az communication update --name "<communicationName>" --tags newTag="newVal1" --resource-group "<resourceGroup>"

az communication update --name "<communicationName>" --tags newTag="newVal2" --resource-group "<resourceGroup>" --subscription "<subscriptionID>"

az communication show --name "<communicationName>" --resource-group "<resourceGroup>"

az communication show --name "<communicationName>" --resource-group "<resourceGroup>" --subscription "<subscriptionID>"

For information on additional commands, see az communication.

Prerequisites

Installing the SDK

First, include the Communication Services Management SDK in your C# project:

using Azure.ResourceManager.Communication;

Subscription ID

You'll need to know the ID of your Azure subscription. This can be acquired from the portal:

  1. Login into your Azure account
  2. Select Subscriptions in the left sidebar
  3. Select whichever subscription is needed
  4. Click on Overview
  5. Select your Subscription ID

In this quickstart, we'll assume that you've stored the subscription ID in an environment variable called AZURE_SUBSCRIPTION_ID.

Authentication

To communicate with Azure Communication Services, you must first authenticate yourself to Azure. You'll usually do this using a service principal identity.

Option 1: Managed Identity

If your code is running as a service in Azure, the easiest way to authenticate is to acquire a managed identity from Azure. Learn more about managed identities.

Azure services that support Managed Identities

How to use managed identities for App Service and Azure Functions

System-assigned Managed Identity

using Azure.Identity;
using Azure.ResourceManager.Communication;
using Azure.ResourceManager.Communication.Models;
using System;
...
var subscriptionId = "AZURE_SUBSCRIPTION_ID";
var acsClient = new CommunicationManagementClient(subscriptionId, new ManagedIdentityCredential());

User-assigned Managed Identity

ClientId of the managed identity that you created must be passed to the ManagedIdentityCredential explicitly.

using Azure.Identity;
using Azure.ResourceManager.Communication;
using Azure.ResourceManager.Communication.Models;
using System;
...
var subscriptionId = "AZURE_SUBSCRIPTION_ID";
var managedIdentityCredential = new ManagedIdentityCredential("AZURE_CLIENT_ID");
var acsClient = new CommunicationManagementClient(subscriptionId, managedIdentityCredential);

Option 2: Service Principal

Instead of using a managed identity, you may want to authenticate to Azure using a service principal that you manage yourself. Learn more using documentation on creating and managing a service principal in Azure Active Directory.

After you've created your service principal, you'll need to collect the following information about it from the Azure portal:

  • Client ID
  • Client Secret
  • Tenant ID

Store these values in environment variables named AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID respectively. You can then create a Communication Services management client like this:

using Azure.Identity;
using Azure.ResourceManager.Communication;
using Azure.ResourceManager.Communication.Models;
using System;
...
var subscriptionId = Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID");
var acsClient = new CommunicationManagementClient(subscriptionId, new EnvironmentCredential());

Option 3: User Identity

If you want to call Azure on behalf of an interactive user, rather than using a service identity, you can use the following code to create an Azure Communication Services Management client. This will open a browser window to prompt the user for their MSA or Azure AD credentials.

using Azure.Identity;
using Azure.ResourceManager.Communication;
using Azure.ResourceManager.Communication.Models;
using System;
...
var subscriptionId = Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID");
var communicationServiceClient = new CommunicationManagementClient(subscriptionId, new InteractiveBrowserCredential());

Managing Communication Services Resources

Interacting with Azure resources

Now that you're authenticated, you can use your management client to make API calls.

For each of the following examples, we'll be assigning our Communication Services resources to an existing resource group.

If you need to create a resource group, you can do so by using the Azure portal or the Azure Resource Manager SDK.

Create and manage a Communication Services resource

Our instance of the Communication Services Management SDK client (Azure.ResourceManager.Communication.CommunicationManagementClient) can be used to perform operations on Communication Services resources.

Create a Communication Services resource

When creating a Communication Services resource, you'll specify the resource group name and resource name. Note that the Location property will always be global, and during public preview the DataLocation value must be UnitedStates.

var resourceGroupName = "myResourceGroupName";
var resourceName = "myResource";
var resource = new CommunicationServiceResource { Location = "Global", DataLocation = "UnitedStates"  };
var operation = await acsClient.CommunicationService.StartCreateOrUpdateAsync(resourceGroupName, resourceName, resource);
await operation.WaitForCompletionAsync();

Update a Communication Services resource

...
var resourceGroupName = "myResourceGroupName";
var resourceName = "myResource";
var resource = new CommunicationServiceResource { Location = "Global", DataLocation = "UnitedStates" };
resource.Tags.Add("environment","test");
resource.Tags.Add("department","tech");
// Use existing resource name and new resource object
var operation = await acsClient.CommunicationService.StartCreateOrUpdateAsync(resourceGroupName, resourceName, resource);
await operation.WaitForCompletionAsync();

List all Communication Services resources

var resources = acsClient.CommunicationService.ListBySubscription();
foreach (var resource in resources)
{
    Console.WriteLine(resource.Name);
}

Delete a Communication Services resource

var resourceGroupName = "myResourceGroupName";
var resourceName = "myResource";
await acsClient.CommunicationService.StartDeleteAsync(resourceGroupName, resourceName);

Managing keys and connection strings

Every Communication Services resource has a pair of access keys and corresponding connection strings. These keys can be accessed with the Management SDK and then used by other Communication Services SDKs to authenticate themselves to Azure Communication Services.

Get access keys for a Communication Services resource

var resourceGroupName = "myResourceGroupName";
var resourceName = "myResource";
var keys = await acsClient.CommunicationService.ListKeysAsync(resourceGroupName, resourceName);

Console.WriteLine(keys.Value.PrimaryConnectionString);
Console.WriteLine(keys.Value.SecondaryConnectionString);

Regenerate an access key for a Communication Services resource

var resourceGroupName = "myResourceGroupName";
var resourceName = "myResource";
var keyParams = new RegenerateKeyParameters { KeyType = KeyType.Primary };
var keys = await acsClient.CommunicationService.RegenerateKeyAsync(resourceGroupName, resourceName, keyParams);

Console.WriteLine(keys.Value.PrimaryKey);

Prerequisites

Create Azure Communication Resource

To create an Azure Communication Services resource, sign in to Azure CLI. You can do this through the terminal using the Connect-AzAccount command and providing your credentials. Run the following command to create the resource:

PS C:\> New-AzCommunicationService -ResourceGroupName ContosoResourceProvider1 -Name ContosoAcsResource1 -DataLocation UnitedStates -Location Global

If you would like to select a specific subscription you can also specify the --subscription flag and provide the subscription ID.

PS C:\> New-AzCommunicationService -ResourceGroupName ContosoResourceProvider1 -Name ContosoAcsResource1 -DataLocation UnitedStates -Location Global -SubscriptionId SubscriptionID

You can configure your Communication Services resource with the following options:

  • The resource group
  • The name of the Communication Services resource
  • The geography the resource will be associated with

In the next step, you can assign tags to the resource. Tags can be used to organize your Azure resources. See the resource tagging documentation for more information about tags.

Manage your Communication Services resource

To add tags to your Communication Services resource, run the following commands. You can target a specific subscription as well.

PS C:\> Update-AzCommunicationService -Name ContosoAcsResource1 -ResourceGroupName ContosoResourceProvider1 -Tag @{ExampleKey1="ExampleValue1"}

PS C:\> Update-AzCommunicationService -Name ContosoAcsResource1 -ResourceGroupName ContosoResourceProvider1 -Tag @{ExampleKey1="ExampleValue1"} -SubscriptionId SubscriptionID

To list all of your Azure Communication Services Resources in a given subscription use the following command:

PS C:\> Get-AzCommunicationService -SubscriptionId SubscriptionID

To list all the information on a given resource use the following command:

PS C:\> Get-AzCommunicationService -Name ContosoAcsResource1 -ResourceGroupName ContosoResourceProvider1

Access your connection strings and service endpoints

Connection strings allow the Communication Services SDKs to connect and authenticate to Azure. You can access your Communication Services connection strings and service endpoints from the Azure portal or programmatically with Azure Resource Manager APIs.

After navigating to your Communication Services resource, select Keys from the navigation menu and copy the Connection string or Endpoint values for usage by the Communication Services SDKs. Note that you have access to primary and secondary keys. This can be useful in scenarios where you would like to provide temporary access to your Communication Services resources to a third party or staging environment.

Screenshot of Communication Services Key page.

You can also access key information using Azure CLI, like your resource group or the keys for a specific resource.

Install Azure CLI and use the following command to login. You will need to provide your credentials to connect with your Azure account.

az login

Now you can access important information about your resources.

az communication list --resource-group "<resourceGroup>"

az communication list-key --name "<communicationName>" --resource-group "<resourceGroup>"

If you would like to select a specific subscription you can also specify the --subscription flag and provide the subscription ID.

az communication list --resource-group  "resourceGroup>"  --subscription "<subscriptionID>"

az communication list-key --name "<communicationName>" --resource-group "resourceGroup>" --subscription "<subscriptionID>"

Store your connection string

Communication Services SDKs use connection strings to authorize requests made to Communication Services. You have several options for storing your connection string:

  • An application running on the desktop or on a device can store the connection string in an app.config or web.config file. Add the connection string to the AppSettings section in these files.
  • An application running in an Azure App Service can store the connection string in the App Service application settings. Add the connection string to the Connection Strings section of the Application Settings tab within the portal.
  • You can store your connection string in Azure Key Vault.
  • If you're running your application locally, you may want to store your connection string in an environment variable.

Store your connection string in an environment variable

To configure an environment variable, open a console window and select your operating system from the below tabs. Replace <yourconnectionstring> with your actual connection string.

Open a console window and enter the following command:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<yourconnectionstring>"

After you add the environment variable, you may need to restart any running programs that will need to read the environment variable, including the console window. For example, if you are using Visual Studio as your editor, restart Visual Studio before running the example.

Clean up resources

If you want to clean up and remove a Communication Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it.

If you have any phone numbers assigned to your resource upon resource deletion, the phone numbers will be released from your resource automatically at the same time.

Next steps

In this quickstart you learned how to:

  • Create a Communication Services resource
  • Configure resource geography and tags
  • Access the keys for that resource
  • Delete the resource