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 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 usando 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 interface usando o novo serviço de implantação e gerenciamento: Azure Resource Manager. Todas as funções disponíveis nos SDKs estão disponíveis no portal do Azure.
Aviso
Observe que você não pode criar um grupo de recursos e um recurso ao mesmo tempo nos Serviços de Comunicação do Azure. Antes de criar um recurso, primeiro você precisa criar um grupo de recursos.
Pré-requisitos
- Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
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.
Insira Comunicação na entrada Pesquisar o 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 o seu recurso dos Serviços de Comunicação. Na primeira página do processo de criação, você precisa 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 associada ao recurso
Na próxima etapa, você pode atribuir marcas ao recurso. Você pode usar marcas para organizar seus recursos do Azure. Para saber mais sobre tags, confira Usar tags para organizar os recursos do Azure e a hierarquia de gerenciamento.
Por fim, você pode examinar a sua configuração e Criar o recurso. A implantação leva 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, entre no 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. Para obter mais opções de configuração, consulte o menu à esquerda da página de recursos.
Pré-requisitos
- Uma conta do Azure com uma assinatura 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 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 associada ao recurso
Na próxima etapa, você pode atribuir marcas ao recurso. Você pode usar marcas para organizar seus recursos do Azure. Para saber mais sobre tags, confira Usar tags para organizar os recursos do Azure e a hierarquia de gerenciamento.
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
- Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
- A versão mais recente do SDK do .NET Core para o seu sistema operacional.
- Obtenha a última versão do SDK de Identidade do .NET.
- Obtenha a última versão do SDK do Gerenciamento do .NET.
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ê precisa saber a ID da sua assinatura do Azure. Isso pode ser adquirido no portal:
- Entre na sua conta no portal do Azure.
- Na barra lateral esquerda, selecione Assinaturas.
- Selecione a assinatura que deseja usar.
- Clique em Visão Geral.
- Selecione a sua ID de Assinatura.
Para que os exemplos neste início rápido funcionem, você precisa armazenar sua ID de 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. Para saber mais, veja:
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. Para obter mais informações, consulte criando e gerenciando 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 como 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 abre 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, atribuímos 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
Você pode usar a instância do cliente do SDK de Gerenciamento de Serviços de Comunicação (Azure.ResourceManager.Communication.CommunicationManagementClient) para executar operações em recursos dos 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. A propriedade Location é sempre global e, durante a visualização pública, o valor de DataLocation 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);
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. Você pode acessar essas chaves usando o SDK de Gerenciamento e disponibilizá-las para outros SDKs dos Serviços de Comunicação para se autenticarem 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 assinatura ativa. Crie uma conta gratuitamente.
- Instalar o Módulo do PowerShell Azure Az
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. Você pode criar um recurso 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 para associar ao recurso
Na próxima etapa, você pode atribuir marcas ao recurso. Você pode usar marcas para organizar seus recursos do Azure. Para saber mais, confira Usar marcas para organizar os recursos do Azure e a hierarquia de gerenciamento.
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 para 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.
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. Além disso, você pode gerenciar com segurança sua cadeia de conexão.
- 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 a seguir. 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. Para excluir o recurso do de comunicação, execute o comando a seguir.
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