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

Artigo
02/03/2024

A API de Aprovisionamento do Gateway de Comunicações do Azure para operadores de telecomunicações permite-lhe aprovisionar os detalhes dos seus clientes e os números atribuídos aos mesmos no Gateway de Comunicações do Azure.

O aprovisionamento de informações de clientes e números no Gateway de Comunicações do Azure é obrigatório ao utilizar o Gateway de Comunicações do Azure para o Encaminhamento Direto do Microsoft Teams e o Peering da Cloud do Zoom Phone É opcional para o Operator Connect, mas permite-lhe configurar um cabeçalho SIP personalizado para faturação.

Não pode utilizar a API de Aprovisionamento para Telefone Teams Números de telemóvel.

Introdução

Pré-requisitos

Um inquilino com a aplicação Azure Communications Gateway implementada.
O nome de domínio completamente qualificado (FQDN) do Gateway de Comunicações do Azure para o qual pretende enviar consultas, conforme apresentado na página Descrição geral do recurso no portal do Azure. A API está disponível na porta 443 do provapi subdomínio deste domínio (provapi.<base-domain>:443).
Um computador com um endereço IP que permite o acesso à API, conforme configurado numa lista de permissões como parte da implementação do Gateway de Comunicações do Azure.

Autenticação e autorização

A API de Aprovisionamento utiliza o OAuth 2.0 para controlar o acesso aos recursos. A aplicação cliente tem de obter um token de portador de autenticação válido para aceder à API de Aprovisionamento. O token do portador indica que a aplicação está autorizada para um ou mais dos âmbitos (funções) da API de Aprovisionamento. Recomendamos que utilize o fluxo de credenciais do cliente (concebido para um processo do lado do servidor).

Os seguintes âmbitos estão disponíveis para a API de Aprovisionamento:

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 escrita (PUT, PATCH) na API.
ProvisioningAPI.Delete: capacidade de invocar qualquer operação de eliminação (DELETE) na API.

Para configurar um fluxo de credenciais de cliente:

Certifique-se de que a sua aplicação consegue suportar o fluxo de credenciais do cliente.

Quando a aplicação pede um token para a API de Aprovisionamento, tem de utilizar os seguintes campos.

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

A roles afirmação no token recebido especifica as funções (âmbitos) a que a aplicação cliente está autorizada a aceder.
Os pedidos para a Plataforma de Aprovisionamento do Gateway de Comunicações do Azure têm de ter um Authorization cabeçalho com este token de portador.
Veja a documentação do fluxo de credenciais do cliente para obter exemplos de utilização de tokens.

Utilize o portal do Azure para registar a aplicação no mesmo inquilino que a implementação do Gateway de Comunicações do Azure. Veja Início Rápido: Registar uma aplicação no plataforma de identidades da Microsoft - Microsoft Entra | Microsoft Learn.
Atribua-se como proprietário para o registo da aplicação. Veja Atribuir proprietário da aplicação.
Configure o registo de aplicações criado ao registar a aplicação com funções de aplicação que utilizam os âmbitos da API de Aprovisionamento, conforme descrito anteriormente.
- Veja Atribuir funções de aplicação a aplicações.
- A API para a qual precisa de atribuir permissões é AzureCommunicationsGateway, listada em APIs que a minha organização utiliza.
Como administrador do inquilino, permita que a aplicação utilize as funções de aplicação que atribuiu. Veja Conceder consentimento do administrador.

A API de Aprovisionamento utiliza cadeias de fidedignidade padrão da Microsoft para certificados de segurança.

Conceitos-chave

A Plataforma de Aprovisionamento do Gateway de Comunicações do Azure permite-lhe aprovisionar números para utilização com serviços como o Microsoft Teams Direct Routing ou o Zoom Provider Exchange. A Plataforma de Aprovisionamento tem dois recursos-chave que pode controlar: contas e números.

Os recursos da conta são descrições dos seus clientes (normalmente, uma empresa) e definições por cliente para o aprovisionamento de serviços.
Os recursos numéricos pertencem a uma conta. Descrevem números de telefone (TNs), os serviços que os números utilizam (por exemplo, o Encaminhamento Direto do Microsoft Teams) e qualquer configuração extra por número.

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

Importante

Tem de ativar o serviço na conta e nos números na conta.

Exemplos

Os exemplos seguintes mostram pedidos de exemplo para criar e gerir contas e números.

Criar uma conta para representar um cliente

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

No seguinte exemplo:

O Encaminhamento Direto está configurado.
A filtragem do ID do Autor da Chamada está ativada (a predefinição).
O subdomínio do cliente é contoso.
Os valores DNS TXT fornecidos pelo cliente necessários para configurar registos DNS estão nos region1Token campos e region2Token .

Pedido:

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\""
}

Ver os detalhes da conta

Utilize GET accounts/<accountName> no ponto final para obter os detalhes da conta e verifique se a configuração dos registos DNS para o subdomínio configurado foi bem-sucedida (apenas necessária para o Encaminhamento Direto do Microsoft Teams). A resposta inclui os seguintes campos:

directRoutingProvisioningState, representando o estado dos registos DNS. Este campo é incluído quando o parâmetro ?status=true de consulta é especificado no pedido e só é relevante para o Encaminhamento Direto.
Todas as configurações anteriormente definidas (ou a predefinição, se um campo não tiver sido definido).
Um ETag que representa o estado atual da conta. Pode utilizar o valor num cabeçalho de If-Match em pedidos de atualização subsequentes para garantir que não substitui as alterações efetuadas por outros utilizadores da API.

Pedido:

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

Utilize PUT no accounts/<accountName> ponto final para atualizar a configuração da conta. Para garantir que a atualização não substitui uma alteração efetuada por outro utilizador, adicione um cabeçalho If-Match com o ETag da resposta mais recente da conta.

Pedido:

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

Utilize PUT account/<accountName>/numbers/<phoneNumber> no ponto final para adicionar um número E.164 à conta, ativar um ou mais serviços de comunicações e adicionar qualquer configuração adicional. Os serviços de comunicações escolhidos também têm de ser configurados na conta. Utilize um cabeçalho If-None-Match para verificar se um recurso numérico com este número ainda não existe.

No seguinte exemplo:

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

Importante

O nome do cabeçalho personalizado é definido na configuração portal do Azure da API de Aprovisionamento. É 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\""
}

Configuração de atualização para um número

Utilize PUT no account/<accountName>/numbers/<phoneNumber> ponto final para atualizar a configuração de um número. Para garantir que a atualização não substitui uma alteração efetuada por outro utilizador, adicione um cabeçalho de If-Match com o ETag da resposta mais recente para o número.

Pedido:

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 múltiplos números ao mesmo tempo

Utilize POST no account/<accountName>/numbers:batch ponto final para somar até 100 números à conta de uma só vez. Este ponto final também pode ser utilizado para atualizar números na conta. Os números são adicionados transacionalmente: se alguma atualização falhar, todas as atualizações falham.

Pedido:

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

Utilize GET no account/<accountName>/numbers ponto final para obter todos os números na conta com a respetiva configuração. Utilize os skip parâmetros e maxpagesize de consulta para controlar a forma como a resposta é paginada. Se existirem mais números a devolver, a resposta irá conter um nextLink campo que indica o URL a pedir para obter a página seguinte dos resultados.

Pedido:

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"
}

Resolução de problemas

O Encaminhamento Direto do Teams não está a funcionar para números numa conta.
- Verifique se o token DNS foi validado ao enviar 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 utilizar o Encaminhamento Direto/Zoom, mas não parece estar a funcionar.
- Verifique se a conta está configurada para utilizar o Encaminhamento Direto/Zoom e se o número tem esta funcionalidade específica ativada.
Posso contactar a API, mas depois de fazer vários pedidos, as minhas ligações começam a exceder o tempo limite.
- A API de aprovisionamento é limitada à taxa. Veja Limites, quotas e restrições do Gateway de Comunicações do Azure para obter detalhes. Espaçar os seus pedidos ou utilizar o ponto final do batch para evitar ser limitado. O limite de taxa excederá eventualmente o limite de tempo e poderá ligar-se.

Passos seguintes

Comece a integrar com a API de Aprovisionamento do Gateway de Comunicações do Azure.

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

Introdução

Pré-requisitos

Autenticação e autorização

Conceitos-chave

Exemplos

Criar uma conta para representar um cliente

Ver os detalhes da conta

Atualizar a configuração da conta

Adicionar um número à conta

Configuração de atualização para um número

Adicionar ou atualizar múltiplos números ao mesmo tempo

Obter todos os números na conta

Resolução de problemas

Passos seguintes

Recursos adicionais