Compartilhar via

Início Rápido: Configurar o roteamento de voz programaticamente

  • Artigo

Configurar as regras de roteamento de voz de saída para roteamento direto dos Serviços de Comunicação do Azure.

Pré-requisitos

Observação

Você pode encontrar mais exemplos de uso para SipRoutingClient no GitHub.

Adicionar um controlador de borda de sessão

  1. No painel esquerdo, em Chamada de Voz – PSTN, selecione Roteamento direto. Em uma guia Controladores de Borda da Sessão, selecione Configurar.

  2. Insira um FQDN e uma porta de sinalização para o SBC. Os requisitos para o FQDN do SBC incluem:

    • A parte do domínio do FQDN deve ser verificada antes que você possa adicioná-la à configuração de roteamento direto, conforme mencionado anteriormente nos pré-requisitos.
    • O certificado SBC deve corresponder ao nome. Há suporte a certificados com caracteres curinga.
    • Você não pode usar os domínios *.onmicrosoft.com e *.azure.com para o FQDN.

    Para obter a lista completa de requisitos, confira os Requisitos da infraestrutura de roteamento direto do Azure.

    Screenshot of adding a session border controller on the panel for configuring direct routing.

  3. Selecione Avançar. Se tudo estiver configurado corretamente, você deverá ver o status do SBC como Ativo no portal do Azure.

    Screenshot of SBC connection properties.

Importante

Antes de fazer ou receber chamadas, verifique se o status SBC está Online

Criar regras de roteamento de voz

Screenshot of outgoing voice routing configuration.

Dê um nome à sua Rota de Voz, especifique o padrão numérico usando expressões regulares e selecione o SBC para esse padrão. Aqui estão alguns exemplos de expressões regulares básicas:

  • ^\+\d+$: corresponde a um número de telefone com um ou mais dígitos que começam com um sinal de mais.
  • ^\+1(\d{10})$: corresponde a um número de telefone com 10 dígitos depois de um +1.
  • ^\+1(425|206)(\d{7})$: corresponde a um número de telefone que começa com +1425 ou +1206 seguido por sete dígitos.
  • ^\+0?1234$: corresponde aos números de telefone +01234 e +1234.

Para saber mais sobre as expressões regulares, confira Visão geral das expressões regulares .NET.

Você pode selecionar vários SBCs para um único padrão. Em tal caso, o algoritmo de roteamento escolhe em ordem aleatória. Você também pode especificar o padrão de número exato mais de uma vez. A linha mais alta tem prioridade mais alta. Se todos os SBCs associados a essa linha não estiverem disponíveis, a próxima linha será selecionada. Dessa forma, você cria cenários de roteamento complexos.

Remover uma configuração de roteamento direto

Para excluir uma rota de voz:

  1. No painel esquerdo, em Chamada de Voz – PSTN, vá para Roteamento direto.
  2. Na guia Rotas de Voz, marque as caixas de seleção para a rota (ou rotas) que deseja excluir.
  3. Selecione Remover.

Para excluir um SBC:

  1. No painel esquerdo, em Chamada de Voz – PSTN, vá para Roteamento direto.
  2. Na guia Controladores de Borda da Sessão, selecione Configurar.
  3. Limpe os campos FQDN e porta do SBC que você deseja remover e selecione Avançar.
  4. Na guia Rotas de Voz, revise a configuração de roteamento de voz. Adicione os comentários que forem necessário e selecione Salvar.

Ao remover um SBC associado a uma rota de voz, você poderá escolher um SBC diferente para a rota na guia Rotas de Voz. A rota de voz sem um SBC será excluída.

Pré-requisitos

Código final

Encontre o código finalizado para este guia de início rápido no GitHub.

Você também pode encontrar mais exemplos de uso do SipRoutingClient no GitHub.

Criar um aplicativo C#

Em uma janela de console (como o prompt de comando, PowerShell ou Bash), use o comando dotnet new para criar um novo aplicativo de console:

    dotnet new console -o DirectRoutingQuickstart

Esse comando cria um projeto simples C# "Olá, Mundo" com um arquivo de origem único: Program.cs.

Altere o seu diretório para a pasta de aplicativo recém-criada e use o comando dotnet build para compilar o aplicativo:

    cd DirectRoutingQuickstart
    dotnet build

Instalar o pacote

Enquanto ainda estiver no diretório do aplicativo, instale o biblioteca de clientes de Números de Telefone da Comunicação do Azure para .NET usando o comando dotnet add package:

    dotnet add package Azure.Communication.PhoneNumbers --version 1.1.0

Adicione uma diretiva using à parte superior de Program.cs para incluir os namespaces:

using Azure.Communication.PhoneNumbers.SipRouting;

Autenticar o cliente

Autentique os clientes de número de telefone usando uma cadeia de conexão de recursos dos Serviços de Comunicação do Azure:

// Get a connection string to the Azure Communication Services resource.
var connectionString = "<connection_string>";
var client = new SipRoutingClient(connectionString);

Definir uma configuração de roteamento direto

Nos pré-requisitos, você verificou a propriedade do domínio. As próximas etapas são criar troncos (adicionar SBCs) e criar rotas de voz.

Criar ou atualizar troncos

O roteamento direto de Serviços de Comunicação do Azure permite apenas a comunicação com SBCs registrados. Para registrar um SBC, você precisa do FQDN e da porta dele:

// Register your SBCs by providing their fully qualified domain names and port numbers.
var usSbcFqdn = "sbc.us.contoso.com";
var euSbcFqdn = "sbc.eu.contoso.com";
var sbcPort = 5061;

var usTrunk = new SipTrunk(usSbcFqdn, sbcPort);
var euTrunk = new SipTrunk(euSbcFqdn, sbcPort);

await client.SetTrunksAsync(new List<SipTrunk> { usTrunk, euTrunk });

Criar ou atualizar rotas

Forneça regras de roteamento para chamadas de saída. Cada regra consiste em duas partes: um padrão regex que deve corresponder a um número de telefone discado e o FQDN de um tronco de voz registrado onde a chamada é roteada.

A ordem das rotas determina a prioridade das rotas. A primeira rota que corresponder ao regex será escolhida para uma chamada.

Neste exemplo, você cria uma rota para números que começam com +1 e uma segunda rota para números que começam apenas com +:

var usRoute = new SipTrunkRoute("UsRoute", "^\\+1(\\d{10})$", trunks: new List<string> { usSbcFqdn });
var defaultRoute = new SipTrunkRoute("DefaultRoute", "^\\+\\d+$", trunks: new List<string> { usSbcFqdn, euSbcFqdn });

await client.SetRoutesAsync(new List<SipTrunkRoute> { usRoute, defaultRoute });

Atualizar uma configuração de roteamento direto

Você pode atualizar as propriedades de um tronco específico substituindo o registro pelo mesmo FQDN. Por exemplo, você pode definir um novo valor na porta SBC:

var usTrunk = new SipTrunk("sbc.us.contoso.com", 5063);
await client.SetTrunkAsync(usTrunk);

Você usa o mesmo método para criar e atualizar regras de roteamento. Ao atualizar as rotas, envie todas elas em uma única atualização. A nova configuração de roteamento substitui totalmente a anterior.

Remover uma configuração de roteamento direto

Você não pode editar ou remover uma única rota de voz. Você deve substituir toda a configuração de roteamento de voz. Aqui está um exemplo de uma lista vazia que remove todas as rotas e troncos de voz:

//delete all configured voice routes
await client.SetRoutesAsync(new List<SipTrunkRoute>());

//delete all trunks
await client.SetTrunksAsync(new List<SipTrunk>());

Você pode usar o exemplo a seguir para excluir um único tronco (SBC), se nenhuma rota de voz o estiver usando. Se o SBC estiver listado em qualquer rota de voz, primeiro exclua essa rota.

await client.DeleteTrunkAsync("sbc.us.contoso.com");

Pré-requisitos

Código final

Encontre o código finalizado para este guia de início rápido no GitHub.

Você também pode encontrar mais exemplos de uso do SipRoutingClient no GitHub.

Criar um aplicativo Java

Abra o terminal ou a janela Comando. Vá até o diretório em que você deseja criar o aplicativo Java. Depois, execute o comando para gerar o projeto Java a partir do modelo maven-archetype-quickstart:

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

A tarefa generate criou um diretório com o mesmo nome do valor artifactId. Nesse diretório, o diretório src/main/java contém o código-fonte do projeto, o diretório src/test/java contém a fonte de teste e o arquivo pom.xml é o POM (Modelo de Objeto do Projeto) do projeto.

Instalar o pacote

Abra o arquivo pom.xml no seu editor de texto. Adicione os seguintes elementos de dependência ao grupo de dependências:

<dependencies>
	<dependency>
		<groupId>com.azure</groupId>
		<artifactId>azure-communication-phonenumbers</artifactId>
		<version>1.1.0</version>
	</dependency>
</dependencies>

Configurar o framework de aplicativos

No diretório do projeto:

  1. Vá para o diretório /src/main/java/com/communication/quickstart.
  2. Abra o arquivo App.java em seu editor.
  3. Substitua a instrução System.out.println("Hello world!");.
  4. Adicione as diretivas import.

Use o seguinte código para começar:

import com.azure.communication.phonenumbers.siprouting.SipRoutingAsyncClient;
import com.azure.communication.phonenumbers.siprouting.SipRoutingClientBuilder;
import com.azure.communication.phonenumbers.siprouting.models.SipTrunk;
import com.azure.communication.phonenumbers.siprouting.models.SipTrunkRoute;
import static java.util.Arrays.asList;

public class App
{
    public static void main( String[] args ) throws IOException
    {
        System.out.println("Azure Communication Services - Direct Routing Quickstart");
        // Quickstart code goes here
    }
}

Autenticar o cliente

Com SipRoutingClientBuilder, você pode usar a autenticação do Microsoft Entra:

// You can find your endpoint and access key from your resource in the Azure portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";

SipRoutingAsyncClient sipRoutingAsyncClient = new SipRoutingClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

Alternativamente, use o ponto de extremidade e a chave de acesso a partir do recurso de comunicação para autenticar:

// You can find your connection string from your resource in the Azure portal
String connectionString = "endpoint=https://<RESOURCE_NAME>.communication.azure.com/;accesskey=<ACCESS_KEY>";

SipRoutingAsyncClient sipRoutingAsyncClient = new SipRoutingClientBuilder()
    .connectionString(connectionString)
    .buildClient();

Definir uma configuração de roteamento direto

Nos pré-requisitos, você verificou a propriedade do domínio. As próximas etapas são criar troncos (adicionar SBCs) e criar rotas de voz.

Criar ou atualizar troncos

O roteamento direto de Serviços de Comunicação do Azure permite apenas a comunicação com SBCs registrados. Para registrar um SBC, você precisa do FQDN e da porta dele:

sipRoutingAsyncClient.setTrunksWithResponse(asList(
	new SipTrunk("sbc.us.contoso.com", 5061),
	new SipTrunk("sbc.eu.contoso.com", 5061)
)).block();

Criar ou atualizar rotas

Forneça regras de roteamento para chamadas de saída. Cada regra consiste em duas partes: um padrão regex que deve corresponder a um número de telefone discado e o FQDN de um tronco de voz registrado onde a chamada é roteada.

A ordem das rotas determina a prioridade das rotas. A primeira rota que corresponder ao regex será escolhida para uma chamada.

Neste exemplo, você cria uma rota para números que começam com +1 e uma segunda rota para números que começam apenas com +:

sipRoutingAsyncClient.setRoutes(asList(
	new SipTrunkRoute("UsRoute", "^\\+1(\\d{10})$").setTrunks(asList("sbc.us.contoso.com")),
	new SipTrunkRoute("DefaultRoute", "^\\+\\d+$").setTrunks(asList("sbc.us.contoso.com", "sbc.eu.contoso.com"))
)).block();

Atualizar uma configuração de roteamento direto

Você pode atualizar as propriedades de um tronco específico substituindo o registro pelo mesmo FQDN. Por exemplo, você pode definir um novo valor na porta SBC:

sipRoutingClient.setTrunk(new SipTrunk("sbc.us.contoso.com", 5063));

Você usa o mesmo método para criar e atualizar regras de roteamento. Ao atualizar as rotas, envie todas elas em uma única atualização. A nova configuração de roteamento substitui totalmente a anterior.

Remover uma configuração de roteamento direto

Você não pode editar ou remover uma única rota de voz. Você deve substituir toda a configuração de roteamento de voz. Aqui está o exemplo de uma lista vazia que remove todas as rotas e troncos de voz.

Adicione duas importações:

import java.util.Collections;
import java.util.List;

Use o código a seguir para excluir uma configuração de roteamento direto:

//delete all configured voice routes
System.out.println("Delete all routes");
List<SipTrunkRoute> routes = Collections.<SipTrunkRoute> emptyList();
sipRoutingAsyncClient.setRoutes(routes).block();

//delete all trunks
System.out.println("Delete all trunks");
List<SipTrunk> trunks = Collections.<SipTrunk> emptyList();
sipRoutingAsyncClient.setTrunksWithResponse(trunks).block();

Você pode usar o exemplo a seguir para excluir um único tronco (SBC), se nenhuma rota de voz o estiver usando. Se o SBC estiver listado em qualquer rota de voz, primeiro exclua essa rota.

sipRoutingClient.deleteTrunk("sbc.us.contoso.com");

Executar o código

Navegue até o diretório que contém o arquivo pom.xml e compile o projeto usando o seguinte comando mvn:

  mvn clean compile

Então, crie o pacote:

  mvn package

Execute o seguinte comando mvn para executar o aplicativo:

  mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false

Pré-requisitos

Código final

Encontre o código finalizado para este guia de início rápido no GitHub.

Você também pode encontrar mais exemplos de uso do SipRoutingClient no GitHub.

Criar um aplicativo do Node.js

Abra a janela Comando ou o terminal para criar um diretório para o seu aplicativo e acesse-o:

    mkdir direct-routing-quickstart && cd direct-routing-quickstart

Execute npm init -y para criar um arquivo package.json com as configurações padrão:

   npm init -y

Criar um arquivo chamado direct-routing-quickstart.js na raiz do diretório que você criou. Adicione o seguinte snippet a ele:

async function main() {
    // quickstart code will go here
}

main();

Instalar o pacote

Use o comando npm install para instalar a biblioteca de clientes de Números de Telefone dos Serviços de Comunicação do Azure para JavaScript:

   npm install @azure/communication-phone-numbers --save

A opção --save adiciona a biblioteca como uma dependência no arquivo package.json.

Autenticar o cliente

Importe o SipRoutingClient da biblioteca de clientes e crie uma instância dele com sua cadeia de conexão. O código recupera a cadeia de conexão para o recurso a partir de uma variável de ambiente chamada COMMUNICATION_SERVICES_CONNECTION_STRING. Saiba como gerenciar a cadeia de conexão do seu recurso.

Adicione o seguinte código ao direct-routing-quickstart.js:

const { SipRoutingClient } = require('@azure/communication-phone-numbers');

// This code demonstrates how to fetch your connection string
// from an environment variable.
const connectionString = process.env['COMMUNICATION_SERVICES_CONNECTION_STRING'];

// Instantiate the phone numbers client
const sipRoutingClient = new SipRoutingClient(connectionString);

Definir uma configuração de roteamento direto

Nos pré-requisitos, você verificou a propriedade do domínio. As próximas etapas são criar troncos (adicionar SBCs) e criar rotas de voz.

Criar ou atualizar troncos

O roteamento direto de Serviços de Comunicação do Azure permite apenas a comunicação com SBCs registrados. Para registrar um SBC, você precisa do FQDN e da porta dele:

  await client.setTrunks([
    {
      fqdn: 'sbc.us.contoso.com',
      sipSignalingPort: 5061
    },{
      fqdn: 'sbc.eu.contoso.com',
      sipSignalingPort: 5061
    }
  ]);

Criar ou atualizar rotas

Forneça regras de roteamento para chamadas de saída. Cada regra consiste em duas partes: um padrão regex que deve corresponder a um número de telefone discado e o FQDN de um tronco de voz registrado onde a chamada é roteada.

A ordem das rotas determina a prioridade das rotas. A primeira rota que corresponder ao regex será escolhida para uma chamada.

Neste exemplo, você cria uma rota para números que começam com +1 e uma segunda rota para números que começam apenas com +:

   await client.setRoutes([
    {
      name: "UsRoute",
      description: "route's description",
      numberPattern: "^\+1(\d{10})$",
      trunks: [ 'sbc.us.contoso.com' ]
    },{
      name: "DefaultRoute",
      description: "route's description",
      numberPattern: "^\+\d+$",
      trunks: [ 'sbc.us.contoso.com', 'sbc.eu.contoso.com']
    }
  ]);

Atualizar uma configuração de roteamento direto

Você pode atualizar as propriedades de um tronco específico substituindo o registro pelo mesmo FQDN. Por exemplo, você pode definir um novo valor na porta SBC:

  await client.setTrunk({
    fqdn: 'sbc.us.contoso.com',
    sipSignalingPort: 5063
  });

Você usa o mesmo método para criar e atualizar regras de roteamento. Ao atualizar as rotas, envie todas elas em uma única atualização. A nova configuração de roteamento substitui totalmente a anterior.

Remover uma configuração de roteamento direto

Você não pode editar ou remover uma única rota de voz. Você deve substituir toda a configuração de roteamento de voz. Aqui está um exemplo de uma lista vazia que remove todas as rotas e troncos de voz:

//delete all configured voice routes
console.log("Deleting all routes...");
await client.setRoutes([]);

//delete all trunks
console.log("Deleting all trunks...");
await client.setTrunks([]);

Você pode usar o exemplo a seguir para excluir um único tronco (SBC), se nenhuma rota de voz o estiver usando. Se o SBC estiver listado em qualquer rota de voz, primeiro exclua essa rota.

   await client.deleteTrunk('sbc.us.contoso.com');

Executar o código

Use o comando node para executar o código adicionado ao arquivo direct-routing-quickstart.js:

   node direct-routing-quickstart.js

Pré-requisitos

Código final

Encontre o código finalizado para este guia de início rápido no GitHub.

Você também pode encontrar mais exemplos de uso do SipRoutingClient no GitHub.

Criar um aplicativo Python

Abra o terminal ou a janela Comando. Crie um novo diretório para seu aplicativo e vá para ele:

mkdir direct-routing-quickstart && cd direct-routing-quickstart

Use um editor de texto para criar um arquivo chamado directory_routing_sample.py no diretório raiz do projeto e adicione o seguinte código:

import os
from azure.communication.phonenumbers.siprouting import SipRoutingClient, SipTrunk, SipTrunkRoute

try:
   print('Azure Communication Services - Direct Routing Quickstart')
   # Quickstart code goes here
except Exception as ex:
   print('Exception:')
   print(ex)

Você adiciona o restante do código de início rápido nas seções a seguir.

Instalar o pacote

Enquanto você ainda estiver no diretório do aplicativo, instale a biblioteca de clientes da Administração dos Serviços de Comunicação do Azure para Python usando o comando pip install:

pip install azure-communication-phonenumbers==1.1.0

Autenticar o cliente

Com SipRoutingClient, você pode usar a autenticação do Microsoft Entra. Usar o objeto DefaultAzureCredential é a maneira mais fácil de começar a usar o Microsoft Entra ID, e você pode instalá-lo usando o comando pip install:

pip install azure-identity

A criação de um objeto DefaultAzureCredential requer que você já tenha AZURE_CLIENT_ID, AZURE_CLIENT_SECRET e AZURE_TENANT_ID definidos como variáveis de ambiente com seus valores correspondentes do aplicativo Microsoft Entra registrado. Para obter uma maneira rápida de obter essas variáveis de ambiente, consulte Autenticar usando o Microsoft Entra ID.

Depois de instalar a biblioteca azure-identity, você pode continuar autenticando o cliente:

import os
from azure.communication.phonenumbers.siprouting import SipRoutingClient
from azure.identity import DefaultAzureCredential

# You can find your endpoint from your resource in the Azure portal
endpoint = 'https://<RESOURCE_NAME>.communication.azure.com'
try:
    print('Azure Communication Services - Direct Routing Quickstart')
    credential = DefaultAzureCredential()
    sip_routing_client = SipRoutingClient(endpoint, credential)
except Exception as ex:
    print('Exception:')
    print(ex)

Alternativamente, você pode usar o ponto de extremidade e a chave de acesso a partir do recurso de comunicação para autenticar:

import os
from azure.communication.phonenumbers.siprouting import SipRoutingClient

# You can find your connection string from your resource in the Azure portal
connection_string = 'https://<RESOURCE_NAME>.communication.azure.com/;accesskey=<YOUR_ACCESS_KEY>'
try:
    print('Azure Communication Services - Direct Routing Quickstart')
    sip_routing_client = SipRoutingClient.from_connection_string(connection_string)
except Exception as ex:
    print('Exception:')
    print(ex)

Definir uma configuração de roteamento direto

Nos pré-requisitos, você verificou a propriedade do domínio. As próximas etapas são criar troncos (adicionar SBCs) e criar rotas de voz.

Criar ou atualizar troncos

Registre seus SBCs fornecendo seus nomes de domínio totalmente qualificados e números de porta:

new_trunks = [SipTrunk(fqdn="sbc.us.contoso.com", sip_signaling_port=1234), SipTrunk(fqdn="sbc.eu.contoso.com", sip_signaling_port=1234)]
sip_routing_client.set_trunks(new_trunks)

Criar ou atualizar rotas

Forneça regras de roteamento para chamadas de saída. Cada regra consiste em duas partes: um padrão regex que deve corresponder a um número de telefone discado e o FQDN de um tronco de voz registrado onde a chamada é roteada.

A ordem das rotas determina a prioridade das rotas. A primeira rota que corresponder ao regex será escolhida para uma chamada.

Neste exemplo, você cria uma rota para números que começam com +1 e uma segunda rota para números que começam apenas com +:

us_route = SipTrunkRoute(name="UsRoute", description="Handle US numbers '+1'", number_pattern="^\\+1(\\d{10})$", trunks=["sbc.us.contoso.com"])
def_route = SipTrunkRoute(name="DefaultRoute", description="Handle all numbers", number_pattern="^\\+\\d+$", trunks=["sbc.us.contoso.com","sbc.eu.contoso.com"])
new_routes = [us_route, def_route]
sip_routing_client.set_routes(new_routes)

Atualizar uma configuração de roteamento direto

Você pode atualizar as propriedades de um tronco específico substituindo o registro pelo mesmo FQDN. Por exemplo, você pode definir um novo valor na porta SBC:

new_trunk = SipTrunk(fqdn="sbc.us.contoso.com", sip_signaling_port=5063)
sip_routing_client.set_trunk(new_trunk)

Você usa o mesmo método para criar e atualizar regras de roteamento. Ao atualizar as rotas, envie todas elas em uma única atualização. A nova configuração de roteamento substitui totalmente a anterior.

Remover uma configuração de roteamento direto

Você não pode editar ou remover uma única rota de voz. Você deve substituir toda a configuração de roteamento de voz. Aqui está um exemplo de uma lista vazia que remove todas as rotas e troncos de voz:

#delete all configured voice routes
print('Deleting all routes...')
sip_routing_client.set_routes([])

#delete all trunks
print('Deleting all trunks...')
sip_routing_client.set_trunks([])

Você pode usar o exemplo a seguir para excluir um único tronco (SBC), se nenhuma rota de voz o estiver usando. Se o SBC estiver listado em qualquer rota de voz, primeiro exclua essa rota.

sip_routing_client.delete_trunk("sbc.us.contoso.com")

Executar o código

Em um prompt de console, vá para o diretório que contém o arquivo direct_routing_sample.py . Em seguida, execute o seguinte comando Python para executar o aplicativo:

python direct_routing_sample.py

Limpar os recursos

Se quiser limpar e remover uma assinatura dos Serviços de Comunicação, exclua o recurso ou o grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele. Saiba mais sobre como limpar recursos.

Próximas etapas

Para obter mais informações, consulte os seguintes artigos: