Quickstart: Criar e gerir recursos dos Serviços de Comunicação

  • Artigo
  • 13 minutos para ler

Iniciou com Azure Communication Services a disponibilização do seu primeiro recurso de Serviços de Comunicação. Os recursos dos Serviços de Comunicação podem ser adcedidos através do portal do Azure ou com a SDK de gestão .NET. A gestão SDK e a portal do Azure permitem-lhe criar, configurar, atualizar e eliminar os seus recursos e interface com a Azure Resource Manager, o serviço de implementação e gestão da Azure. Todas as funcionalidades disponíveis nos SDKs estão disponíveis no portal do Azure.

Aviso

Note que não é possível criar um grupo de recursos ao mesmo tempo que um recurso para Azure Communication Services. Ao criar um recurso, um grupo de recursos que já foi criado, deve ser usado.

Pré-requisitos

Note que se estiver a planear usar números de telefone, não pode usar a conta de teste gratuita. Verifique se a sua subscrição satisfaz todos os requisitos se planeia adquirir números de telefone antes de criar o seu recurso.

Criar Azure Communication Services recurso

Para criar um recurso Azure Communication Services, inscreva-se pela primeira vez na portal do Azure. No canto superior esquerdo da página, selecione + Crie um recurso.

Screenshot realçando a criação de um botão de recursos no portal do Azure.

Introduza a Comunicação na entrada 'Pesquisar o Mercado' ou na barra de pesquisa no topo do portal.

Screenshot mostrando uma procura de serviços de comunicação na barra de pesquisa.

Selecione serviços de comunicação nos resultados e, em seguida, selecione Criar.

Screenshot mostrando o painel de Serviços de Comunicação, realçando o botão Criar.

Pode agora configurar o seu recurso de Serviços de Comunicação. Na primeira página do processo de criação, será solicitado que especifique:

  • A subscrição
  • O grupo de recursos (pode criar um novo ou escolher um grupo de recursos existente)
  • O nome do recurso serviços de comunicação
  • A geografia com que o recurso será associado

No próximo passo, pode atribuir etiquetas ao recurso. As etiquetas podem ser usadas para organizar os seus recursos Azure. Consulte a documentação de marcação de recursos para obter mais informações sobre etiquetas.

Finalmente, pode rever a sua configuração e criar o recurso. Note que a colocação levará alguns minutos para ser concluída.

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

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

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

A página 'Vista Geral' para o seu recurso contém opções para gestão básica como navegar, parar, iniciar, reiniciar e excluir. Pode encontrar mais opções de configuração no menu esquerdo da sua página de recursos.

Pré-requisitos

Se está a planear usar números de telefone, não pode usar a conta de teste gratuita. Verifique se a sua subscrição satisfaz todos os requisitos se planeia adquirir números de telefone antes de criar o seu recurso.

Criar Azure Communication Services recurso

Para criar um recurso Azure Communication Services, inscreva-se no Azure CLI. Pode iniciar singing no az login comando a partir do terminal e fornecer as suas credenciais. Executar 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 subscrição específica, também pode especificar a --subscription bandeira e fornecer o ID de subscrição.

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

Pode configurar o 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 com que o recurso será associado

No próximo passo, pode atribuir etiquetas ao recurso. As etiquetas podem ser usadas para organizar os seus recursos Azure. Para obter mais informações sobre etiquetas, consulte a documentação de marcação de recursos.

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

Para adicionar tags ao seu recurso serviços de comunicação, execute os seguintes comandos. Também pode direcionar uma subscrição 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 o CLI de Comunicação Azure.

Pré-requisitos

Note que se estiver a planear usar números de telefone, não pode usar a conta de teste gratuita. Verifique se a sua subscrição satisfaz todos os requisitos se planeia adquirir números de telefone antes de criar o seu recurso.

Instalação do SDK

Em primeiro lugar, inclua o SDK de Gestão de Serviços de Comunicação no seu projeto C#:

using Azure.ResourceManager.Communication;

ID da subscrição

Precisa de saber a identificação da sua assinatura Azure. Isto pode ser adquirido no portal:

  1. Faça login na sua conta Azure
  2. Selecione subscrições na barra lateral esquerda
  3. Selecione qualquer subscrição necessária
  4. Clique em Visão Geral
  5. Selecione o seu ID de subscrição

Neste arranque rápido, assumimos que guardou o ID de subscrição numa variável ambiental chamada AZURE_SUBSCRIPTION_ID.

Autenticação

Para comunicar com Azure Communication Services, primeiro deve autenticar-se ao Azure. Normalmente, fá-lo-ás usando uma identidade principal de serviço.

Opção 1: Identidade gerida

Se o seu código estiver a funcionar como um serviço em Azure, a forma mais fácil de autenticar é adquirir uma identidade gerida da Azure. Saiba mais sobre identidades geridas.

Serviços Azure que suportam Identidades Geridas

Como utilizar identidades geridas para Serviço de Aplicações e Funções do Azure

Identidade gerida 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 gerida atribuída pelo utilizador

Cliente da identidade gerida que 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: Diretor de serviço

Em vez de usar uma identidade gerida, pode querer autenticar a Azure usando um principal de serviço que gere a si mesmo. Saiba mais utilizando documentação sobre a criação e gestão de um diretor de serviços no Azure Ative Directory.

Depois de criar o seu principal de serviço, terá de recolher as seguintes informações sobre o mesmo a partir do portal do Azure:

  • ID de Cliente
  • Segredo do Cliente
  • ID do inquilino

Armazenar estes valores em variáveis ambientais denominadas AZURE_CLIENT_ID, AZURE_CLIENT_SECRETe AZURE_TENANT_ID respectivamente. Pode então criar um cliente de gestão 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 utilizador

Se quiser ligar para a Azure em nome de um utilizador interativo, em vez de utilizar uma identidade de serviço, pode utilizar o seguinte código para criar um cliente Azure Communication Services Management. Isto abrirá uma janela do navegador para solicitar ao utilizador as suas credenciais DE MSA ou Azure AD.

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

Gerir recursos de serviços de comunicação

Interagindo com os recursos da Azure

Agora que está autenticado, pode usar o seu cliente de gestão para fazer chamadas de API.

Para cada um dos seguintes exemplos, vamos atribuir os 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 Azure Resource Manager SDK.

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

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

Criar um recurso do Communication Services

Ao criar um recurso de Serviços de Comunicação, especificará o nome do grupo de recursos e o nome do recurso. Note que o Location imóvel será globalsempre , 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 de 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);
}

Eliminar um recurso de Serviços de Comunicação

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

Gestão de chaves e cadeias de ligação

Todos os recursos de Serviços de Comunicação têm um par de chaves de acesso e cadeias de conexão correspondentes. Estas teclas podem ser acedidas com o Management SDK e depois utilizadas por outros SDKs de Serviços de Comunicação para se autenticarem para Azure Communication Services.

Obtenha chaves de acesso para um recurso de 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 de 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

Note que se estiver a planear usar números de telefone, não pode usar a conta de teste gratuita. Verifique se a sua subscrição satisfaz todos os requisitos se planeia adquirir números de telefone antes de criar o seu recurso.

Criar Azure Communication Services recurso

Para criar um recurso Azure Communication Services, inscreva-se no Azure CLI. Pode fazê-lo através do terminal usando o Connect-AzAccount comando e fornecendo as suas credenciais.

Em primeiro lugar, certifique-se de instalar o módulo Az.Communication Azure Communication Services utilizando o seguinte comando.

PS C:\> Install-Module Az.Communication

Executar o seguinte comando para criar o recurso:

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

Se quiser selecionar uma subscrição específica, também pode especificar a --subscription bandeira e fornecer o ID de subscrição.

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

Pode configurar o 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 com que o recurso será associado

No próximo passo, pode atribuir etiquetas ao recurso. As etiquetas podem ser usadas para organizar os seus recursos Azure. Consulte a documentação de marcação de recursos para obter mais informações sobre etiquetas.

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

Para adicionar tags ao seu recurso serviços de comunicação, execute os seguintes comandos. Também pode direcionar uma subscrição 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 Azure Communication Services numa determinada subscrição, utilize o seguinte comando:

PS C:\> Get-AzCommunicationService -SubscriptionId SubscriptionID

Para listar todas as informações num dado recurso, utilize o seguinte comando:

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

Aceda às cordas de ligação e pontos finais de serviço

As cadeias de ligação permitem aos Serviços de Comunicação SDKs ligar e autenticar ao Azure. Pode aceder às cadeias de ligação dos serviços de comunicação e pontos finais de serviço a partir do portal do Azure ou programáticamente com APIs Resource Manager Azure.

Depois de navegar para o seu recurso serviços de comunicação, selecione Chaves do menu de navegação e copie os valores de cadeia de ligação ou ponto final para utilização pelos SDKs dos Serviços de Comunicação. Note que tem acesso a chaves primárias e secundárias. Isto pode ser útil em cenários em que gostaria de fornecer acesso temporário aos seus recursos de Serviços de Comunicação a terceiros ou ambiente de encenação.

Screenshot da página chave dos serviços de comunicação.

Aceda às cordas de ligação e pontos finais de serviço utilizando o Azure CLI

Também pode aceder a informações chave usando o Azure CLI, como o seu grupo de recursos ou as chaves para um recurso específico.

Instale o Azure CLI e utilize o seguinte comando para iniciar sessão. Terá de fornecer as suas credenciais para se conectar com a sua conta Azure.

az login

Agora pode aceder a informações importantes sobre os seus recursos.

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

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

Se quiser selecionar uma subscrição específica, também pode especificar a --subscription bandeira e fornecer o ID de subscrição.

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

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

Guarde a sua cadeia de ligação

Os Serviços de Comunicação SDKs utilizam cadeias de ligação para autorizar pedidos feitos aos Serviços de Comunicação. Tem várias opções para armazenar a sua cadeia de ligação:

  • Uma aplicação em execução no ambiente de trabalho ou num dispositivo pode armazenar a cadeia de ligação num ficheiroapp.config ou web.config . Adicione o fio de ligação à secção AppSettings nestes ficheiros.
  • Uma aplicação em execução numa Serviço de Aplicações do Azure pode armazenar o fio de ligação nas definições de aplicação Serviço de Aplicações. Adicione o fio de ligação à secção de cordas de ligação do separador Definições de Aplicação dentro do portal.
  • Pode armazenar a sua cadeia de ligação em Azure Key Vault.
  • Se estiver a executar a sua aplicação localmente, pode querer armazenar a sua cadeia de ligação numa variável ambiental.

Guarde a sua cadeia de conexão numa variável ambiental

Para configurar uma variável ambiental, abra uma janela da consola e selecione o seu sistema operativo a partir dos separadores abaixo. Substitua-a <yourconnectionstring> pela sua verdadeira cadeia de ligação.

Abra uma janela da consola e introduza o seguinte comando:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<yourConnectionString>"

Depois de adicionar a variável de ambiente, poderá ter de reiniciar todos os programas em execução que irão precisar de ler a variável de ambiente, incluindo a janela da consola. Por exemplo, se estiver a utilizar o Visual Studio como seu editor, reinicie o Visual Studio antes de executar o exemplo.

Limpar os recursos

Se pretender limpar e remover uma assinatura de Serviços de Comunicação, pode eliminar o grupo de recursos ou recursos. Pode eliminar o seu recurso de comunicação executando o comando abaixo.

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

A eliminação do grupo de recursos também elimina quaisquer outros recursos que lhe sejam associados.

Se tiver algum número de telefone atribuído ao seu recurso após a eliminação de recursos, os números de telefone serão libertados automaticamente do seu recurso ao mesmo tempo.

Nota

A eliminação de recursos é permanente e nenhum dado, incluindo filtros de grelha de eventos, números de telefone ou outros dados ligados ao seu recurso, pode ser recuperado se eliminar o recurso.

Passos seguintes

Neste arranque rápido aprendeste a:

  • Criar um recurso do Communication Services
  • Configurar geografia de recursos e etiquetas
  • Aceda às chaves desse recurso
  • Eliminar o recurso

Crie os seus primeiros tokens de acesso ao utilizador