Guia de início rápido: criar e gerenciar recursos dos Serviços de Comunicação

Comece a usar os Serviços de Comunicação do Azure provisionando seu primeiro recurso de Serviços de Comunicação. Os recursos dos Serviços de Comunicação podem ser provisionados por meio do portal do Azure ou com o SDK de gerenciamento do .NET. O SDK de gerenciamento e o portal do Azure permitem que você crie, configure, atualize e exclua seus recursos e faça interface com o Azure Resource Manager, o serviço de implantação e gerenciamento do Azure. Todas as funções disponíveis nos SDKs estão disponíveis no portal do Azure.

Aviso

Observe que não é possível criar um grupo de recursos ao mesmo tempo que um recurso para os Serviços de Comunicação do Azure. Ao criar um recurso, um grupo de recursos que já foi criado deve ser usado.

Pré-requisitos

• Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.

Observe que, se você estiver planejando usar números de telefone, não poderá usar a conta de avaliação gratuita. Verifique se a sua subscrição cumpre todos os requisitos se planeia comprar números de telefone antes de criar o seu recurso.

Criar o recurso do Azure Communication Services

Para criar um recurso dos Serviços de Comunicação do Azure, primeiro entre no portal do Azure. No canto superior esquerdo da página, selecione + Criar um recurso.

Insira Comunicação na entrada Pesquisar no Marketplace ou na barra de pesquisa na parte superior do portal.

Selecione Serviços de Comunicação nos resultados e, em seguida, selecione Criar.

Agora você pode configurar seu recurso de Serviços de Comunicação. Na primeira página do processo de criação, ser-lhe-á pedido que especifique:

• A subscrição
• O grupo de recursos (você pode criar um novo ou escolher um grupo de recursos existente)
• O nome do recurso Serviços de Comunicação
• A geografia à qual o recurso estará associado

Na próxima etapa, você pode atribuir tags ao recurso. As tags podem ser usadas para organizar seus recursos do Azure. Consulte a documentação de marcação de recursos para obter mais informações sobre tags.

Finalmente, você pode revisar sua configuração e Criar o recurso. Observe que a implantação levará alguns minutos para ser concluída.

Gerenciar seu recurso de Serviços de Comunicação

Para gerir o seu recurso de Serviços de Comunicação, aceda ao portal do Azure e procure e selecione Serviços de Comunicação do Azure.

Na página Serviços de Comunicação, selecione o nome do seu recurso.

A página Visão geral do recurso contém opções para gerenciamento básico, como procurar, parar, iniciar, reiniciar e excluir. Você pode encontrar mais opções de configuração no menu esquerdo da sua página de recursos.

Pré-requisitos

• Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
• Instalar a CLI do Azure

Se você estiver planejando usar números de telefone, não poderá usar a conta de avaliação gratuita. Verifique se a sua subscrição cumpre todos os requisitos se planeia comprar números de telefone antes de criar o seu recurso.

Criar o recurso do Azure Communication Services

Para criar um recurso dos Serviços de Comunicação do Azure, entre na CLI do Azure. Você pode entrar executando o az login comando do terminal e fornecendo suas credenciais. Execute o seguinte comando para criar o recurso:

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

Se você quiser selecionar uma assinatura específica, você também pode especificar o --subscription sinalizador e fornecer o ID da assinatura.

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

Você pode configurar seu recurso de Serviços de Comunicação com as seguintes opções:

• O grupo de recursos
• O nome do recurso Serviços de Comunicação
• A geografia à qual o recurso estará associado

Na próxima etapa, você pode atribuir tags ao recurso. As tags podem ser usadas para organizar seus recursos do Azure. Para obter mais informações sobre tags, consulte a documentação de marcação de recursos.

Gerenciar seu recurso de Serviços de Comunicação

Para adicionar marcas ao recurso dos Serviços de Comunicação, execute os seguintes comandos. Você também pode segmentar uma assinatura específica.

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>"

Para obter informações sobre outros comandos, consulte CLI de Comunicação do Azure.

Pré-requisitos

• Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
• A versão mais recente do SDK do .NET Core para seu sistema operacional.
• Obtenha a versão mais recente do .NET Identity SDK.
• Obtenha a versão mais recente do SDK de Gerenciamento do .NET.

Observe que, se você estiver planejando usar números de telefone, não poderá usar a conta de avaliação gratuita. Verifique se a sua subscrição cumpre todos os requisitos se planeia comprar números de telefone antes de criar o seu recurso.

Instalando o SDK

Primeiro, inclua o SDK de Gerenciamento de Serviços de Comunicação em seu projeto C#:

using Azure.ResourceManager.Communication;

ID de Subscrição

Você precisará saber a ID da sua assinatura do Azure. Isto pode ser adquirido no portal:

1. Inicie sessão na sua conta do Azure
2. Selecione Subscrições na barra lateral esquerda
3. Selecione a assinatura necessária
4. Clique em Visão geral
5. Selecione o seu ID de Subscrição

Neste início rápido, assumiremos que você armazenou a ID da assinatura em uma variável de ambiente chamada AZURE_SUBSCRIPTION_ID.

Autenticação

Para se comunicar com os Serviços de Comunicação do Azure, você deve primeiro autenticar-se no Azure. Normalmente, você fará isso usando uma identidade de entidade de serviço.

Opção 1: Identidade gerenciada

Se seu código estiver sendo executado como um serviço no Azure, a maneira mais fácil de autenticar é adquirir uma identidade gerenciada do Azure. Saiba mais sobre identidades gerenciadas.

Serviços do Azure que suportam Identidades Geridas

Como usar identidades gerenciadas para o Serviço de Aplicativo e o Azure Functions

Identidade gerenciada atribuída pelo sistema

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());

Identidade gerenciada atribuída pelo usuário

ClientId da identidade gerenciada que você criou deve ser passado para o ManagedIdentityCredential explicitamente.

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);

Opção 2: Entidade de serviço

Em vez de usar uma identidade gerenciada, talvez você queira autenticar no Azure usando uma entidade de serviço que você mesmo gerencia. Saiba mais usando a documentação sobre como criar e gerenciar uma entidade de serviço no Microsoft Entra ID.

Depois de criar sua entidade de serviço, você precisará coletar as seguintes informações sobre ela no portal do Azure:

• ID de Cliente
• Segredo do Cliente
• ID do Inquilino

Armazene esses valores em variáveis de ambiente denominadas AZURE_CLIENT_ID, AZURE_CLIENT_SECRETe AZURE_TENANT_ID respectivamente. Em seguida, você pode criar um cliente de gerenciamento de Serviços de Comunicação como este:

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());

Opção 3: Identidade do usuário

Se quiser chamar o Azure em nome de um usuário interativo, em vez de usar uma identidade de serviço, você pode usar o código a seguir para criar um cliente de Gerenciamento de Serviços de Comunicação do Azure. Isso abrirá uma janela do navegador para solicitar ao usuário suas credenciais MSA ou Microsoft Entra.

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());

Gerenciando recursos de serviços de comunicação

Interagindo com recursos do Azure

Agora que você está autenticado, pode usar seu cliente de gerenciamento para fazer chamadas de API.

Para cada um dos exemplos a seguir, atribuiremos nossos recursos de Serviços de Comunicação a um grupo de recursos existente.

Se precisar de criar um grupo de recursos, pode fazê-lo utilizando o portal do Azure ou o SDK do Azure Resource Manager.

Criar e gerenciar um recurso de Serviços de Comunicação

Nossa instância do cliente SDK de Gerenciamento de Serviços de Comunicação (Azure.ResourceManager.Communication.CommunicationManagementClient) pode ser usada para executar operações em recursos do Serviço de Comunicação.

Criar um recurso do Communication Services

Ao criar um recurso dos Serviços de Comunicação, você especificará o nome do grupo de recursos e o nome do recurso. Observe que a Location propriedade sempre será global, e durante a visualização pública o DataLocation valor deve ser 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();

Atualizar um recurso dos Serviços de Comunicação

...
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();

Listar todos os recursos dos Serviços de Comunicação

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

Excluir um recurso dos Serviços de Comunicação

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

Gerenciando chaves e cadeias de conexão

Cada recurso dos Serviços de Comunicação tem um par de chaves de acesso e cadeias de conexão correspondentes. Essas chaves podem ser acessadas com o SDK de Gerenciamento e, em seguida, usadas por outros SDKs de Serviços de Comunicação para autenticar-se nos Serviços de Comunicação do Azure.

Obter chaves de acesso para um recurso dos Serviços de Comunicação

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

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

Regenerar uma chave de acesso para um recurso dos Serviços de Comunicação

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);

Pré-requisitos

• Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
• Instalar o módulo Azure Az PowerShell

Observe que, se você estiver planejando usar números de telefone, não poderá usar a conta de avaliação gratuita. Verifique se a sua subscrição cumpre todos os requisitos se planeia comprar números de telefone antes de criar o seu recurso.

Criar o recurso do Azure Communication Services

Para criar um recurso dos Serviços de Comunicação do Azure, entre na CLI do Azure. Você pode fazer isso através do terminal usando o Connect-AzAccount comando e fornecendo suas credenciais.

Primeiro, certifique-se de instalar o módulo Az.Communication Serviços de Comunicação do Azure usando o comando a seguir.

PS C:\> Install-Module Az.Communication

Execute o seguinte comando para criar o recurso:

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

Se você quiser selecionar uma assinatura específica, você também pode especificar o --subscription sinalizador e fornecer o ID da assinatura.

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

Você pode configurar seu recurso de Serviços de Comunicação com as seguintes opções:

• O grupo de recursos
• O nome do recurso Serviços de Comunicação
• A geografia à qual o recurso estará associado

Na próxima etapa, você pode atribuir tags ao recurso. As tags podem ser usadas para organizar seus recursos do Azure. Consulte a documentação de marcação de recursos para obter mais informações sobre tags.

Gerenciar seu recurso de Serviços de Comunicação

Para adicionar marcas ao recurso dos Serviços de Comunicação, execute os seguintes comandos. Você também pode segmentar uma assinatura específica.

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

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

Para listar todos os seus Recursos dos Serviços de Comunicação do Azure em uma determinada assinatura, use o seguinte comando:

PS C:\> Get-AzCommunicationService -SubscriptionId SubscriptionID

Para listar todas as informações sobre um determinado recurso, use o seguinte comando:

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

Acesse suas cadeias de conexão e pontos de extremidade de serviço

As cadeias de conexão permitem que os SDKs dos Serviços de Comunicação se conectem e se autentiquem no Azure. Você pode acessar suas cadeias de conexão e pontos de extremidade de serviço dos Serviços de Comunicação a partir do portal do Azure ou programaticamente com as APIs do Azure Resource Manager.

Depois de navegar até o recurso Serviços de Comunicação, selecione Chaves no menu de navegação e copie a Cadeia de conexão ou os valores de Ponto de Extremidade para uso pelos SDKs dos Serviços de Comunicação. Você tem acesso às chaves primária e secundária. Isso pode ser útil quando você deseja fornecer acesso temporário aos recursos dos Serviços de Comunicação a um ambiente de terceiros ou de preparação.

Acessar suas cadeias de conexão e pontos de extremidade de serviço usando a CLI do Azure

Você também pode acessar informações de chave usando a CLI do Azure, como seu grupo de recursos ou as chaves de um recurso específico.

Instale a CLI do Azure e use o seguinte comando para entrar. Você precisa fornecer suas credenciais para se conectar à sua conta do Azure.

az login

Agora você pode acessar informações importantes sobre seus recursos.

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

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

Se você quiser selecionar uma assinatura específica, você também pode especificar o --subscription sinalizador e fornecer o ID da assinatura.

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

az communication list-key --name "<acsResourceName>" --resource-group "<resourceGroup>" --subscription "<subscriptionId>"

Armazene sua cadeia de conexão

Os SDKs dos Serviços de Comunicação usam cadeias de conexão para autorizar solicitações feitas aos Serviços de Comunicação. Você tem várias opções para armazenar sua cadeia de conexão:

• Um aplicativo em execução na área de trabalho ou em um dispositivo pode armazenar a cadeia de conexão em um arquivo app.config ou web.config . Adicione a cadeia de conexão à seção AppSettings nesses arquivos.
• Um aplicativo em execução em um Serviço de Aplicativo do Azure pode armazenar a cadeia de conexão nas configurações do aplicativo do Serviço de Aplicativo. Adicione a cadeia de conexão à seção Cadeias de Conexão da guia Configurações do Aplicativo no portal.
• Você pode armazenar sua cadeia de conexão no Cofre da Chave do Azure.
• Se você estiver executando seu aplicativo localmente, convém armazenar sua cadeia de conexão em uma variável de ambiente.

Armazene sua cadeia de conexão em uma variável de ambiente

Para configurar uma variável de ambiente, abra uma janela do console e selecione seu sistema operacional nas guias abaixo. Substitua <yourconnectionstring> pela cadeia de conexão real.

Windows

Abra uma janela do console e digite o seguinte comando:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<yourConnectionString>"

Depois de adicionar a variável de ambiente, talvez seja necessário reiniciar todos os programas em execução que leem a variável de ambiente, incluindo a janela do console. Por exemplo, se você estiver usando o Visual Studio como editor, reinicie o Visual Studio antes de executar o exemplo.

macOS

Edite o seu .zshrce adicione a variável de ambiente:

export COMMUNICATION_SERVICES_CONNECTION_STRING="<yourConnectionString>"

Depois de adicionar a variável de ambiente, execute source ~/.zshrc a partir da janela da consola para que as alterações entrem em vigor. Se você criou a variável de ambiente com o IDE aberto, talvez seja necessário fechar e reabrir o editor, IDE ou shell para acessar a variável.

Linux

Edite o seu .bash_profilee adicione a variável de ambiente:

export COMMUNICATION_SERVICES_CONNECTION_STRING="<yourConnectionString>"

Depois de adicionar a variável de ambiente, execute source ~/.bash_profile a partir da janela da consola para que as alterações entrem em vigor. Se você criou a variável de ambiente com o IDE aberto, talvez seja necessário fechar e reabrir o editor, IDE ou shell para acessar a variável.

Clean up resources (Limpar recursos)

Se quiser limpar e remover uma assinatura dos Serviços de Comunicação, você pode excluir o recurso ou grupo de recursos. Você pode excluir seu recurso de comunicação executando o seguinte comando.

az communication delete --name "acsResourceName" --resource-group "resourceGroup"

A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele.

Se você tiver algum número de telefone atribuído ao seu recurso após a exclusão do recurso, os números de telefone serão automaticamente liberados do seu recurso ao mesmo tempo.

Nota

A exclusão de recursos é permanente e nenhum dado, incluindo filtros de grade de eventos, números de telefone ou outros dados vinculados ao seu recurso, pode ser recuperado se você excluir o recurso.

Próximos passos

Neste guia de início rápido, você aprendeu como:

• Criar um recurso do Communication Services
• Configurar a geografia e as tags de recursos
• Acessar as chaves desse recurso
• Excluir o recurso

Crie seus primeiros tokens de acesso de usuário