Início Rápido: Criar e gerenciar recursos dos Serviços de Comunicação

  • Artigo

Comece a usar os Serviços de Comunicação do Azure provisionando o seu primeiro recurso dos 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 criar, configurar, atualizar e excluir seus recursos e a interagir 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 e um recurso ao mesmo tempo nos Serviços de Comunicação do Azure. Na criação de um recurso, é obrigatório usar um grupo de recursos já criado.

Pré-requisitos

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

Criar recurso dos Serviços de Comunicação do Azure

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.

Captura de tela com realce no botão criar um recurso no portal do Azure.

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

Captura de tela que mostra uma pesquisa dos serviços de comunicação na barra de pesquisa.

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

Captura de tela mostrando o painel Serviços de Comunicação, destacando o botão Criar.

Agora você pode configurar o seu recurso dos Serviços de Comunicação. Na primeira página do processo de criação, você será solicitado a especificar:

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

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

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

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

Para gerenciar o recurso dos Serviços de Comunicação, acesse o portal do Azure e pesquise e selecione os 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 à esquerda da página de recursos.

Pré-requisitos

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

Criar recurso dos Serviços de Comunicação do Azure

Para criar um recurso dos Serviços de Comunicação do Azure, entre na CLI do Azure. Para se conectar, execute o comando az login no terminal e forneça 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 quiser selecionar uma assinatura específica, você também poderá especificar o sinalizador --subscription e fornecer a ID da assinatura.

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

Configure o recurso dos Serviços de Comunicação com as seguintes opções:

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

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

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

Para adicionar marcas ao recurso dos Serviços de Comunicação, execute os comandos a seguir. Você também pode direcionar 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 a CLI de comunicação do Azure.

Pré-requisitos

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

Instalando o SDK

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

using Azure.ResourceManager.Communication;

ID da assinatura

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

  1. Fazer logon na sua conta do Azure
  2. Selecione Assinaturas na barra lateral à esquerda
  3. Selecione qualquer assinatura necessária
  4. Clique em Visão Geral
  5. Selecione a sua ID de Assinatura

Neste guia de início rápido, vamos pressupor 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, primeiro você precisa se autenticar no Azure. Normalmente, você faz isso usando uma identidade de entidade de serviço.

Opção 1: Identidade Gerenciada

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

Serviços do Azure com suporte a Identidades Gerenciadas

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

O ClientId da identidade gerenciada que você criou precisa ser passado para 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-se no Azure usando uma entidade de serviço que você mesmo gerencia. Saiba mais usando a documentação sobre criar e gerenciar uma entidade de serviço no Microsoft Entra ID.

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

  • ID do Cliente
  • Segredo do Cliente
  • ID do locatário

Armazene esses valores em variáveis de ambiente chamadas AZURE_CLIENT_ID, AZURE_CLIENT_SECRET e 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 você quiser chamar o Azure em nome de um usuário interativo, em vez de usar uma identidade de serviço, poderá usar o código a seguir para criar um cliente de Gerenciamento dos 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());

Como gerenciar os recursos dos Serviços de Comunicação

Interação com os recursos do Azure

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

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

Se precisar criar um grupo de recursos, você poderá fazer isso usando o portal do Azure ou o SDK do Azure Resource Manager.

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

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

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

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 propriedade Location sempre será global e, durante a versão prévia pública, o valor DataLocation precisa 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);

Como gerenciar 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 podem ser usadas por outros SDKs dos Serviços de Comunicação para se autenticarem aos 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

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

Criar recurso dos Serviços de Comunicação do Azure

Para criar um recurso dos Serviços de Comunicação do Azure, entre na CLI do Azure. Faça isso por meio do terminal usando o comando Connect-AzAccount e fornecendo suas credenciais.

Primeiro, instale o módulo Az.Communication dos 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 quiser selecionar uma assinatura específica, você também poderá especificar o sinalizador --subscription e fornecer a ID da assinatura.

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

Configure o recurso dos Serviços de Comunicação com as seguintes opções:

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

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

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

Para adicionar marcas ao recurso dos Serviços de Comunicação, execute os comandos a seguir. Você também pode direcionar 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 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 em um determinado recurso, use o seguinte comando:

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

Acessar as 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 com o Azure e sejam autenticados nele. Você pode acessar as suas cadeias de conexão dos Serviços de Comunicação e pontos de extremidade de serviço no portal do Azure ou de maneira programática com as APIs do Azure Resource Manager.

Depois de navegar até o recurso dos Serviços de Comunicação, selecione Chaves no menu de navegação e copie os valores Cadeia de conexão ou 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 seus recursos dos Serviços de Comunicação para um ambiente de preparo ou de terceiros.

Captura de tela da página Chave dos Serviços de Comunicação.

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

Você também pode acessar informações importantes 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 comando a seguir para se conectar. 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 quiser selecionar uma assinatura específica, você também poderá especificar o sinalizador --subscription e fornecer a ID da assinatura.

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

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

Armazenar a 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 diferentes para armazenar a 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 de 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 a cadeia de conexão no Azure Key Vault.
  • Caso você esteja executando o seu aplicativo localmente, talvez queira armazenar a cadeia de conexão em uma variável de ambiente.

Armazenar a 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 o sistema operacional nas guias abaixo. Substitua <yourconnectionstring> pela cadeia de conexão real.

Abra uma janela do console e insira 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 estiver usando o Visual Studio como seu editor, reinicie-o antes de executar o exemplo.

Limpar os recursos

Se quiser limpar e remover uma assinatura dos Serviços de Comunicação, exclua o recurso ou o grupo de recursos. Exclua o recurso de comunicação executando o comando abaixo.

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

Excluir o grupo de recursos também exclui todos os recursos associados a ele.

Se você tiver números de telefone atribuídos ao recurso no momento da exclusão de recursos, os números de telefone serão liberados do recurso automaticamente ao mesmo tempo.

Observação

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

Próximas etapas

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

  • Criar um recurso dos Serviços de Comunicação
  • Configurar a geografia e as marcas do recurso
  • Acessar as chaves desse recurso
  • Excluir o recursos

Criar os seus primeiros tokens de acesso de usuário