API de Provisionamento de Gateway de Comunicações do Azure

Artigo
02/03/2024

A API de Provisionamento do Gateway de Comunicações do Azure para operadores de telecomunicações permite provisionar os detalhes de seus clientes e os números atribuídos a eles no Gateway de Comunicações do Azure.

O provisionamento de informações de cliente e número no Gateway de Comunicações do Azure é obrigatório ao usar o Gateway de Comunicações do Azure para Roteamento Direto do Microsoft Teams e o Emparelhamento de Nuvem de Telefone zoom É opcional para o Operator Connect, mas permite configurar um cabeçalho SIP personalizado para cobrança.

Não é possível usar a API de Provisionamento para Telefonia do Teams Números móveis.

Introdução

Pré-requisitos

Um locatário com o aplicativo Gateway de Comunicações do Azure implantado.
O FQDN (nome de domínio totalmente qualificado) para o Gateway de Comunicações do Azure para o qual você gostaria de enviar consultas, conforme exibido na página Visão geral do recurso no portal do Azure. A API está disponível na porta 443 do provapi subdomínio desse domínio (provapi.<base-domain>:443).
Um computador com um endereço IP que permite o acesso à API, conforme configurado em uma lista de permitidos como parte da implantação do Gateway de Comunicações do Azure.

Autenticação e autorização

A API de Provisionamento usa o OAuth 2.0 para controlar o acesso aos recursos. O aplicativo cliente deve obter um token de portador de autenticação válido para acessar a API de Provisionamento. O token de portador indica que o aplicativo está autorizado para um ou mais dos escopos (funções) para a API de Provisionamento. É recomendável usar o fluxo de credenciais do cliente (projetado para um processo do lado do servidor).

Os seguintes escopos estão disponíveis para a API de Provisionamento:

ProvisioningAPI.Admin: capacidade de invocar qualquer operação na API.
ProvisioningAPI.Read: capacidade de invocar qualquer operação de leitura (GET) na API.
ProvisioningAPI.Write: capacidade de invocar qualquer operação de gravação (PUT, PATCH) na API.
ProvisioningAPI.Delete: capacidade de invocar qualquer operação delete (DELETE) na API.

Para configurar um fluxo de credenciais do cliente:

Verifique se o aplicativo pode dar suporte ao fluxo de credenciais do cliente.

Quando o aplicativo solicita um token para a API de Provisionamento, ele deve usar os campos a seguir.

Parâmetro	Condição	Descrição
locatário	obrigatório	O locatário do diretório que contém o Gateway de Comunicações do Azure, no formato guid ou nome de domínio.
scope	obrigatório	O escopo da autorização em relação à ID do recurso do Gateway de Comunicações do Azure. Para o fluxo de credenciais do cliente descrito aqui, o escopo deve ser `https://func-voiceservice-rp-prod-eastuseuap.azurewebsites.net/.default`.
client_id	obrigatório	A ID do aplicativo (cliente) atribuída ao seu aplicativo.

A roles declaração no token recebido especifica as funções (escopos) que o aplicativo cliente está autorizado a acessar.
As solicitações para a Plataforma de Provisionamento de Gateway de Comunicações do Azure devem ter um Authorization cabeçalho com esse token de portador.
Consulte a documentação de fluxo de credenciais do cliente para obter exemplos de como usar tokens.

Use o portal do Azure para registrar o aplicativo no mesmo locatário que a implantação do Gateway de Comunicações do Azure. Confira Início Rápido: Registrar um aplicativo no plataforma de identidade da Microsoft – Microsoft Entra | Microsoft Learn.
Atribua a si mesmo como proprietário para o registro do aplicativo. Confira Atribuir proprietário do aplicativo.
Configure o registro de aplicativo criado registrando o aplicativo com funções de aplicativo que usam os escopos para a API de Provisionamento, conforme descrito anteriormente.
- Confira Atribuir funções de aplicativo a aplicativos.
- A API para a qual você precisa atribuir permissões é AzureCommunicationsGateway, listada em APIs que minha organização usa.
Como administrador do locatário, permita que o aplicativo use as funções de aplicativo que você atribuiu. Confira Conceder consentimento do administrador.

A API de Provisionamento usa cadeias de confiança padrão da Microsoft para certificados de segurança.

Principais conceitos

A Plataforma de Provisionamento de Gateway de Comunicações do Azure permite provisionar números para uso com serviços como o Roteamento Direto do Microsoft Teams ou o Exchange do Provedor de Zoom. A Plataforma de Provisionamento tem dois recursos principais que você pode controlar: contas e números.

Os recursos da conta são descrições de seus clientes (normalmente, uma empresa) e configurações por cliente para provisionamento de serviços.
Os recursos numéricos pertencem a uma conta. Eles descrevem números de telefone (TNs), os serviços dos quais os números usam (por exemplo, Roteamento Direto do Microsoft Teams) e qualquer configuração extra por número.

Por exemplo, para fornecer o serviço de Roteamento Direto do Microsoft Teams a um cliente, a Contoso, crie um recurso de conta com a API de Provisionamento para Contoso. A conta contém a configuração de Roteamento Direto (por exemplo, um subdomínio e tokens correspondentes, necessários para configurar registros DNS que o Microsoft Teams pode usar para validar a configuração do cliente). Em seguida, você deve adicionar recursos numéricos à conta e habilitar cada número para Roteamento Direto. O Zoom Phone Cloud Peering também requer recursos de conta e número, mas as contas de Zoom não contêm a mesma configuração para subdomínio e tokens correspondentes.

Importante

Você deve habilitar o serviço na conta e nos números dentro da conta.

Exemplos

Os exemplos a seguir mostram solicitações de exemplo para criar e gerenciar contas e números.

Criar uma conta para representar um cliente

Use PUT no accounts/<accountName> ponto de extremidade para criar uma conta chamada contoso para o cliente Contoso e configurar um ou mais serviços de comunicação para a conta. Use um cabeçalho If-None-Match para verificar se um recurso de conta com esse nome ainda não existe.

No exemplo a seguir:

O Roteamento Direto está configurado.
A triagem de ID do chamador está habilitada (o padrão).
O subdomínio do cliente é contoso.
Os valores DNS TXT fornecidos pelo cliente necessários para configurar registros DNS estão nos region1Token campos e region2Token .

Solicitação:

PUT /accounts/contoso?api-version=2023-10-01 HTTP/1.1

If-None-Match: *
Content-Type: application/json

{
  "directRouting": {
    "callScreening": true,
    "subdomain": "contoso",
    "subdomainTokens": {
      "region1Token": "exampleToken1",
      "region2Token": "exampleToken2"
    }
  }
}

Resposta:

HTTP/1.1 201 Created

{
  "name": "contoso",
  "details": {
    "directRouting": {
      "callScreening": true,
      "subdomain": "contoso",
      "subdomainTokens": {
        "region1Token": "exampleToken1",
        "region2Token": "exampleToken2"
      }
    }
  },
  "etag": "\"0000241f-0000-0700-0000-650845140000\""
}

Exibir os detalhes da conta

Use GET no accounts/<accountName> ponto de extremidade para obter os detalhes da conta e marcar que a configuração de registros DNS para o subdomínio configurado foi bem-sucedida (necessária apenas para o Roteamento Direto do Microsoft Teams). A resposta inclui os seguintes campos:

directRoutingProvisioningState, que representa o estado dos registros DNS. Esse campo é incluído quando o parâmetro ?status=true de consulta é especificado na solicitação e só é relevante para o Roteamento Direto.
Todas as configurações definidas anteriormente (ou o padrão, se um campo não tiver sido definido).
Uma ETag que representa o estado atual da conta. Você pode usar o valor em um cabeçalho If-Match em solicitações de atualização subsequentes para garantir que você não substitua as alterações feitas por outros usuários da API.

Solicitação:

GET /accounts/contoso?api-version=2023-10-01&status=true HTTP/1.1

Resposta:

HTTP/1.1 200 OK

ETag: "0000241f-0000-0700-0000-650845140000"

{
  "directRoutingProvisioningState": {
    "subdomainStatus": "Provisioned"
  },
  "name": "contoso",
  "details": {
    "directRouting": {
      "callScreening": true,
      "subdomain": "contoso",
      "subdomainTokens": {
        "region1Token": "exampleToken1",
        "region2Token": "exampleToken2"
      }
    }
  },
  "etag": "\"0000241f-0000-0700-0000-650845140000\""
}

Atualizar a configuração da conta

Use PUT no accounts/<accountName> ponto de extremidade para atualizar a configuração da conta. Para garantir que a atualização não substitua uma alteração feita por outro usuário, adicione um cabeçalho If-Match com a ETag da resposta mais recente para a conta.

Solicitação:

PUT /accounts/contoso?api-version=2023-10-01 HTTP/1.1

If-Match: "0000241f-0000-0700-0000-650845140000"
Content-Type: application/json

{
  "directRouting": {
    "callScreening": false,
    "subdomain": "contoso",
    "subdomainTokens": {
      "region1Token": "exampleTokenNew1",
      "region2Token": "exampleTokenNew2"
    }
  }
}

Resposta:

HTTP/1.1 200 OK

{
  "name": "contoso",
  "details": {
    "directRouting": {
      "callScreening": false,
      "subdomain": "contoso",
      "subdomainTokens": {
        "region1Token": "exampleTokenNew1",
        "region2Token": "exampleTokenNew2"
      }
    }
  },
  "etag": "\"0000351f-0000-0700-0000-65084a810000\""
}

Adicionar um número à conta

Use PUT no account/<accountName>/numbers/<phoneNumber> ponto de extremidade para adicionar um número E.164 à conta, habilitar um ou mais serviços de comunicação e adicionar qualquer configuração extra. Os serviços de comunicação escolhidos também devem ser configurados na conta. Use um cabeçalho If-None-Match para verificar se um recurso numérico com esse número ainda não existe.

No exemplo a seguir:

O número é +123451.
O Roteamento Direto está habilitado.
customSipHeader especifica que o Gateway de Comunicações do Azure deve adicionar um cabeçalho com o valor exampleHeaderContents às mensagens enviadas à sua rede.

Importante

O nome do cabeçalho personalizado é definido na configuração portal do Azure para a API de Provisionamento. É o mesmo para todas as mensagens.

PUT /account/contoso/numbers/%2B123451?api-version=2023-10-01 HTTP/1.1

If-None-Match: *
Content-Type: application/json

{
  "services": {
    "teamsDrEnabled": true,
    "teamsOcEnabled": false,
    "zoomEnabled": false
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Resposta:

HTTP/1.1 201 Created

{
  "phoneNumber": "+123451",
  "accountName": "contoso",
  "details": {
    "services": {
      "teamsDrEnabled": true,
      "teamsOcEnabled": false,
      "zoomEnabled": false
    },
    "configuration": {
      "customSipHeader": "exampleHeaderContents"
    }
  },
  "etag": "\"19004107-0000-0700-0000-65084ad60000\""
}

Atualizar a configuração de um número

Use PUT no account/<accountName>/numbers/<phoneNumber> ponto de extremidade para atualizar a configuração de um número. Para garantir que a atualização não substitua uma alteração feita por outro usuário, adicione um cabeçalho If-Match com a ETag da resposta mais recente para o número.

Solicitação:

PUT /account/contoso/numbers/%2B123451?api-version=2023-10-01 HTTP/1.1

If-Match: "19004107-0000-0700-0000-65084ad60000"
Content-Type: application/json

{
  "services": {
    "teamsDrEnabled": true,
    "teamsOcEnabled": false,
    "zoomEnabled": false
  },
  "configuration": {
    "customSipHeader": "exampleNewHeader"
  }
}

Resposta:

HTTP/1.1 200 OK

{
  "phoneNumber": "+123451",
  "accountName": "contoso",
  "details": {
    "services": {
      "teamsDrEnabled": true,
      "teamsOcEnabled": false,
      "zoomEnabled": false
    },
    "configuration": {
      "customSipHeader": "exampleNewHeader"
    }
  },
  "etag": "\"19007a0a-0000-0700-0000-65084ca00000\""
}

Adicionar ou atualizar vários números ao mesmo tempo

Use POST no account/<accountName>/numbers:batch ponto de extremidade para adicionar até 100 números à conta ao mesmo tempo. Esse ponto de extremidade também pode ser usado para atualizar números na conta. Os números são adicionados transacionalmente: se alguma atualização falhar, todas as atualizações falharão.

Solicitação:

POST /account/contoso/numbers:batch?api-version=2023-10-01 HTTP/1.1

Content-Type: application/json

{
  "numbers": [
    {
      "phoneNumber": "+123452",
      "details": {
        "services": {
          "teamsDrEnabled": true,
          "teamsOcEnabled": false,
          "zoomEnabled": false
        },
        "configuration": {
          "customSipHeader": "exampleHeaderContents"
        }
      }
    },
    {
      "phoneNumber": "+123453",
      "details": {
        "services": {
          "teamsDrEnabled": true,
          "teamsOcEnabled": false,
          "zoomEnabled": false
        },
        "configuration": {
          "customSipHeader": "exampleHeaderContents"
        }
      }
    }
  ]
}

Resposta:

HTTP/1.1 200 OK

{
  "numbers": [
    {
      "phoneNumber": "+123452",
      "accountName": "contoso",
      "details": {
        "services": {
          "teamsDrEnabled": true,
          "teamsOcEnabled": false,
          "zoomEnabled": false
        },
        "configuration": {
          "customSipHeader": "exampleHeaderContents"
        }
      },
      "etag": "\"19002b0c-0000-0700-0000-65084d900000\""
    },
    {
      "phoneNumber": "+123453",
      "accountName": "contoso",
      "details": {
        "services": {
          "teamsDrEnabled": true,
          "teamsOcEnabled": false,
          "zoomEnabled": false
        },
        "configuration": {
          "customSipHeader": "exampleHeaderContents"
        }
      },
      "etag": "\"19002c0c-0000-0700-0000-65084d900000\""
    }
  ]
}

Obter todos os números na conta

Use GET no account/<accountName>/numbers ponto de extremidade para obter todos os números na conta com sua configuração. Use os skip parâmetros de consulta e maxpagesize para controlar como a resposta é paginada. Se houver mais números a serem retornados, a resposta conterá um nextLink campo que indica a URL a ser solicitada para obter a próxima página de resultados.

Solicitação:

GET /account/contoso/numbers?api-version=2023-10-01&skip=0&maxpagesize=2 HTTP/1.1

Resposta:

HTTP/1.1 200 OK

{
  "value": [
    {
      "phoneNumber": "+123451",
      "accountName": "contoso",
      "details": {
        "services": {
          "teamsDrEnabled": true,
          "teamsOcEnabled": false,
          "zoomEnabled": false
        },
        "configuration": {
          "customSipHeader": "exampleNewHeader"
        }
      },
      "etag": "\"19007a0a-0000-0700-0000-65084ca00000\""
    },
    {
      "phoneNumber": "+123452",
      "accountName": "contoso",
      "details": {
        "services": {
          "teamsDrEnabled": true,
          "teamsOcEnabled": false,
          "zoomEnabled": false
        },
        "configuration": {
          "customSipHeader": "exampleHeaderContents"
        }
      },
      "etag": "\"19002b0c-0000-0700-0000-65084d900000\""
    }
  ],
  "nextLink": "https://<api-fqdn>/account/contoso/numbers?api-version=2023-10-01&skip=2&maxpagesize=2"
}

Solução de problemas

O Roteamento Direto do Teams não está funcionando para números em uma conta.
- Verifique se o token DNS foi validado enviando um GET na conta com o ?status=true parâmetro de consulta e verifique se o directRoutingProvisioningState tem subdomainStatus igual a Provisioned.
Configurei um número para usar o Roteamento Direto/Zoom, mas ele não parece estar funcionando.
- Verifique se a conta está configurada para usar o Roteamento Direto/Zoom e se o número tem esse recurso específico habilitado.
Posso entrar em contato com a API, mas depois de fazer várias solicitações, minhas conexões começam a atingir o tempo limite.
- A API de provisionamento é limitada por taxa. Confira Limites, cotas e restrições do Gateway de Comunicações do Azure para obter detalhes. Espaçar suas solicitações ou usar o ponto de extremidade em lote para evitar que a taxa seja limitada. O limite de taxa atingirá o tempo limite eventualmente e você poderá se conectar.

Próximas etapas

Comece a integrar-se à API de Provisionamento de Gateway de Comunicações do Azure.

API de Provisionamento de Gateway de Comunicações do Azure

Introdução

Pré-requisitos

Autenticação e autorização

Principais conceitos

Exemplos

Criar uma conta para representar um cliente

Exibir os detalhes da conta

Atualizar a configuração da conta

Adicionar um número à conta

Atualizar a configuração de um número

Adicionar ou atualizar vários números ao mesmo tempo

Obter todos os números na conta

Solução de problemas

Próximas etapas

Recursos adicionais