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

  • Artigo

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 ACG (Gateway de Comunicação do Azure). A API de Provisionamento também dá suporte ao provisionamento de fluxo de alguns serviços de comunicação de back-end.

O provisionamento de clientes e números é obrigatório (com a API de Provisionamento ou o Portal de Gerenciamento de Números baseado em navegador) para todos os casos de uso, exceto para a Operator Connect e Telefonia do Teams Mobile. Para o Operator Connect e o Telefonia do Teams Mobile, o uso da API de Provisionamento e/ou do Portal de Gerenciamento de Números é opcional e você pode se integrar diretamente à API do Operator Connect.

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 que é exibido na página Visão geral do recurso no portal do Azure. A API está disponível na porta 443 do provapi.<base-domain>.
  • 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:

  1. 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.

  2. 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.
  3. Atribua a si mesmo como proprietário para o registro do aplicativo. Confira Atribuir proprietário do aplicativo.
  4. 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.
  5. 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 tem três recursos principais que o operador pode gerenciar: contas, números e solicitações de informações.

  • Os recursos da conta são descrições de clientes operadores (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, os serviços (por exemplo, o Roteamento Direto do Microsoft Teams) dos quais os números fazem uso e qualquer configuração extra por número.
  • Os recursos RFI (Solicitação de Informações) são descrições de clientes potenciais para operadores que estão expressando interesse em receber serviços do operador por meio de serviços de back-end específicos. Atualmente, apenas as RFIs produzidas a partir da Operator Connect e Telefonia do Teams Mobile estão disponíveis.

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.

Dica

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

Provisionando serviços de back-end com sincronização de serviço de back-end

O Gateway de Comunicações do Azure deve ter informações sobre os números aos quais está fornecendo serviço para conectar chamadas corretamente. Recomendamos a API de Provisionamento de Gateway de Comunicações do Azure para fornecer essas informações ao Gateway de Comunicações do Azure, mas você também pode usar o Portal de Gerenciamento de Números. A maioria dos serviços de back-end também precisa ser provisionada com informações sobre os números e contas a serem usados. Esse requisito geralmente significa que vários projetos de integração de TI são necessários para habilitar novos serviços. A plataforma de Provisionamento de Gateway de Comunicações do Azure foi pré-integrada a alguns serviços de back-end para provisioná-los para você, reduzindo seus requisitos de integração de TI. Você pode usar essa função habilitando a sincronização de serviço de back-end para os serviços relevantes. Isso também significa que qualquer integração de TI à plataforma de provisionamento do Gateway de Comunicação do Azure é reutilizável para outros serviços de back-end.

Por exemplo, a Conexão do Operador exige que todos os números sejam carregados por meio da API de Conexão do Operador. Se a sincronização do serviço de back-end estiver habilitada para o Operator Connect, qualquer número provisionado no Gateway de Comunicações do Azure e habilitado para o Operator Connect será provisionado automaticamente no Operator Connect, o que significa que você não precisa se integrar à API operator connect.

O provisionamento por meio da plataforma de provisionamento do Gateway de Comunicações do Azure é opcional para alguns serviços em que o Gateway de Comunicações do Azure pode obter informações diretamente do back-end. No entanto, alguns recursos, como a adição de cabeçalhos SIP do cliente para fins de cobrança, não estarão disponíveis. Para quaisquer serviços que não dão suporte à sincronização de serviço de back-end, outra integração de TI pode ser necessária diretamente para o serviço de back-end. A status de suporte ao provisionamento é descrita na tabela a seguir:

Serviço de back-end Requisito para provisionar por meio da Plataforma de Provisionamento ACG Provisionamento do serviço de back-end com suporte
Roteamento direto Obrigatório ❌
Zoom Obrigatório ❌
Proteção de Chamadas do Operador do Azure Obrigatório ❌
Conexão do operador Opcional ✅
Telefonia do Teams Mobile Opcional ✅

A sincronização com os serviços de back-end é assíncrona, o que significa que sua solicitação de provisionamento pode ter êxito antes que o serviço de back-end seja provisionado. Essa status é assinada na resposta da API usando o serviceProvisioningStatus campo definido pendingcomo . Recomendamos que você consulte o objeto para marcar seu status de provisionamento até que esse campo seja definido successcomo . Todos os erros de provisionamento do sistema de back-end são disponibilizados diretamente na resposta.

Exemplos

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

Create uma conta que representa 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=2024-02-29 HTTP/1.1
{
  "name": "contoso",
  "serviceDetails": {
    "teamsDirectRouting": {
      "syncEnabled": true,
      "enabled": true,
      "configuration": {
        "callScreening": true,
        "subdomain": "contoso",
        "subdomainTokens": {
          "region1Token": "region1TokenValue",
          "region2Token": "region2TokenValue"
        }
      }
    }
  }
}

Resposta:

{
  "serviceProvisioningStatus": "synced",
  "serviceProvisioningErrors": null,
  "name": "contoso",
  "serviceDetails": {
    "teamsDirectRouting": {
      "syncEnabled": true,
      "enabled": true,
      "numberCount": 0,
      "configuration": {
        "callScreening": true,
        "subdomain": "contoso",
        "subdomainTokens": {
          "region1Token": "region1TokenValue",
          "region2Token": "region2TokenValue"
        }
      },
      "subdomainStatus": "provisioned"
    },
  }
}

No exemplo a seguir, criamos uma conta para uso somente com o Operador do Teams Connect, com a sincronização de back-end habilitada para que as informações sobre essa conta (como todos os números carregados) também sejam provisionadas no Teams:

Solicitação:

PUT /accounts/contoso?api-version=2024-02-29 HTTP/1.1
{
  "name": "contoso",
  "serviceDetails": {
    "teamsTenantId": "tenantIdString",
    "teamsOperatorConnect": {
      "syncEnabled": true,
      "enabled": true
    },
  }
}

Resposta:

{
  "serviceProvisioningStatus": "pending",
  "serviceProvisioningErrors": null,
  "name": "contoso",
  "serviceDetails": {
    "teamsTenantId": "tenantIdString",
    "teamsOperatorConnect": {
      "syncEnabled": true,
      "enabled": true,
      "numberCount": 0
    }
  }
}

Exibir os detalhes da conta

Use GET no accounts/<accountName> ponto de extremidade para obter os detalhes da conta. A resposta inclui os seguintes campos:

  • Todas as configurações definidas anteriormente (ou o padrão, se um campo não tiver sido definido).
  • Contagens de assinantes para cada um dos serviços disponíveis no ACG.
  • O status do provisionamento de serviço de back-end, se habilitado.
  • subdomainStatus, que representa o estado do provisionamento de registros DNS, relevante apenas para Roteamento Direto.
  • Um ETag cabeçalho que representa o estado atual da conta. Você pode usar o valor em um If-Match cabeçalho 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=2024-02-29 HTTP/1.1

Resposta:

ETag: 12345
{
  "serviceProvisioningStatus": "synced",
  "serviceProvisioningErrors": null,
  "name": "contoso",
  "serviceDetails": {
    "teamsTenantId": "tenantIdString",
    "teamsOperatorConnect": {
      "syncEnabled": true,
      "enabled": true,
      "numberCount": 0
    },
  }
}

A solicitação equivalente se a conta tiver vários serviços configurados será exibida da seguinte maneira:

Solicitação:

GET /accounts/contoso?api-version=2024-02-29 HTTP/1.1

Resposta:

ETag: 12345
{
  "serviceProvisioningStatus": "synced",
  "serviceProvisioningErrors": null,
  "name": "contoso",
  "serviceDetails": {
    "teamsTenantId": "tenantIdString",
    "teamsOperatorConnect": {
      "syncEnabled": true,
      "enabled": true
    },
    "teamsDirectRouting": {
      "syncEnabled": true,
      "enabled": true,
      "numberCount": 0,
      "configuration": {
        "callScreening": true,
        "subdomain": "contoso",
        "subdomainTokens": {
          "region1Token": "region1",
          "region2Token": "region2"
        }
      },
      "subdomainStatus": "provisioned"
    },
  }
}

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 If-Match cabeçalho com a ETag da resposta mais recente para a conta.

Solicitação:

PUT /accounts/contoso?api-version=2024-02-29 HTTP/1.1
ETag: 12345
{
  "name": "contoso",
  "serviceDetails": {
    "teamsTenantId": "tenantIdString",
    "teamsOperatorConnect": {
      "syncEnabled": false,
      "enabled": true
    },
    "teamsDirectRouting": {
      "syncEnabled": true,
      "enabled": true,
      "numberCount": 0,
      "configuration": {
        "callScreening": true,
        "subdomain": "contoso",
        "subdomainTokens": {
          "region1Token": "region1",
          "region2Token": "region2"
        }
      },
      "subdomainStatus": "provisioned"
    },
  }
}

Resposta:

ETag: 56789
{
  "serviceProvisioningStatus": "pending",
  "serviceProvisioningErrors": null,
  "name": "contoso",
  "serviceDetails": {
    "teamsTenantId": "tenantIdString",
    "teamsOperatorConnect": {
      "syncEnabled": false,
      "enabled": true
    },
    "teamsDirectRouting": {
      "syncEnabled": true,
      "enabled": true,
      "numberCount": 0,
      "configuration": {
        "callScreening": true,
        "subdomain": "contoso",
        "subdomainTokens": {
          "region1Token": "region1",
          "region2Token": "region2"
        }
      },
      "subdomainStatus": "provisioned"
    },
  }
}

Adicionar um número à conta

Use PUT no account/<accountName>/numbers/<telephoneNumber> ponto de extremidade para adicionar um número à conta, habilitar um ou mais serviços de comunicação e adicionar qualquer outra configuração. 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. Todos os números devem ser criados no formato E.164.

No exemplo a seguir:

  • O número é +123451.
  • A conexão do operador está habilitada.
  • A configuração necessária para carregar o número no Operator Connect é fornecida
  • customSipHeader especifica que o Gateway de Comunicações do Azure deve adicionar um cabeçalho com o valor exampleHeaderContents às mensagens enviadas à rede do operador. O nome do cabeçalho é definido como parte da implantação do Gateway de Comunicações do Azure.
  • O serviceProvisioningStatus campo na resposta mostra o status da sincronização com o serviço de back-end.
PUT /accounts/contoso/numbers/+123451?api-version=2024-02-29 HTTP/1.1
{
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "configuration": {
        "usage": "CallingUserAssignment",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Resposta:

{
  "serviceProvisioningStatus": "pending",
  "serviceProvisioningErrors": null,
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "assignmentStatus": "assigned",
      "configuration": {
        "usage": "CallingUserAssignment",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Verificando status de provisionamento após algum tempo

Use GET no account/<accountName>/numbers/<telephoneNumber> após uma ação de provisionamento para marcar o status do número. Se o número tiver sido provisionado com êxito, o serviceProvisioningStatus campo será atualizado de pending para synced.

Solicitação:

GET /accounts/contoso/numbers/+123451?api-version=2024-02-29 HTTP/1.1

Resposta:

{
  "serviceProvisioningStatus": "synced",
  "serviceProvisioningErrors": null,
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "assignmentStatus": "assigned",
      "configuration": {
        "usage": "CallingUserAssignment",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Erro no provisionamento de serviço de back-end para carregar um número

Neste exemplo, o provisionamento de back-end ao carregar o número atinge um erro, que é refletido novamente na resposta. As mensagens de erro são passadas de forma transparente dos serviços de back-end.

Observação

Inicialmente, ao provisionar um número, ele tem pending status, que precisa ser consultado novamente para confirmar o êxito/falha.

A solicitação original, que não tem um valor para o usage campo :

PUT /accounts/contoso/numbers/+123451?api-version=2024-02-29 HTTP/1.1
{
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "configuration": {
        "usage": "",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Resposta da consulta GET após algum tempo:

{  
  "serviceProvisioningStatus": "failed",
  "serviceProvisioningErrors": [
    {
      "code": "InvalidRequest",
      "message": "Invalid/missing required configuration attributes: Usage",
      "target": "oc",
    }
  ],
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "assignmentStatus": "assigned",
      "configuration": {
        "usage": "",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }

Atualizar a configuração de um número

Use PUT no account/<accountName>/numbers/<telephoneNumber> 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 /accounts/contoso/numbers/+123451?api-version=2024-02-29 HTTP/1.1
ETag: 123
{
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "configuration": {
        "usage": "CallingUserAssignment",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling",
          "Mobile"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Resposta:

{
  "serviceProvisioningStatus": "pending",
  "serviceProvisioningErrors": null,
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "assignmentStatus": "assigned",
      "configuration": {
        "usage": "CallingUserAssignment",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling",
          "Mobile"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Listar as solicitações de informações

Use um GET no /teamsRequestsForInformation ponto de extremidade para obter uma lista dos consentimentos do Teams que foram enviados a você por clientes potenciais.

Solicitação:

GET /teamsRequestsForInformation?api-version=2024-02-29 HTTP/1.1

Resposta:

{
  "value": [
    {
      "serviceProvisioningStatus": "synced",
      "serviceProvisioningErrors": null,
      "id": "contoso",
      "tenantId": "contosoTenantId",
      "accountName": "contoso",
      "productContext": "teams",
      "operatorId": "string",
      "status": "active",
      "consentedOn": "2024-05-07T11:15:10.519Z",
      "lastModifiedOn": "2024-05-07T11:15:10.519Z",
      "consentedCountries": [
        "string"
      ],
      "contacts": [
        {
          "fullName": "Example Name",
          "email": "example@contoso.com",
          "telephoneNumber": "+1234567890",
          "companyName": "contoso",
          "companySize": "size"
        }
      ],
      "customerRelationship": {
        "status": "example status",
        "lastModifiedOn": "2024-05-07T11:15:10.520Z",
        "comment": "example comment"
      }
    },
    {
      "serviceProvisioningStatus": "synced",
      "serviceProvisioningErrors": null,
      "id": "contoso2",
      "tenantId": "contosoTenantId2",
      "accountName": "contoso2",
      "productContext": "teams",
      "operatorId": "string",
      "status": "active",
      "consentedOn": "2024-05-07T11:15:10.519Z",
      "lastModifiedOn": "2024-05-07T11:15:10.519Z",
      "consentedCountries": [
        "string"
      ],
      "contacts": [
        {
          "fullName": "Example Name2",
          "email": "example@contoso2.com",
          "telephoneNumber": "+1234567891",
          "companyName": "contoso2",
          "companySize": "size"
        }
      ],
      "customerRelationship": {
        "status": "example status",
        "lastModifiedOn": "2024-05-07T11:15:10.520Z",
        "comment": "example comment"
      }
    },
    ... // more RFIs
  ],
  "nextLink": "string"
}

Atualizar uma solicitação de informações

Use PATCH no /teamsRequestsForInformation/<tenantID> ponto de extremidade para atualizar o status do RFI, que é refletido no serviço de back-end. A operadora Connect e o Telefonia do Teams Mobile permitem que você indique o status da solicitação de volta ao cliente final para que a status atualizada apareça no Centro de Administração do Teams do cliente.

Solicitação

PATCH /teamsRequestsForInformation/contosoTenantId
{
  "customerRelationship": {
    "status": "new status",
    "comment": "new comment"
  }
}

Resposta

{
    {
      "serviceProvisioningStatus": "pending",
      "serviceProvisioningErrors": null,
      "id": "contoso",
      "tenantId": "contosoTenantId",
      "accountName": "contoso",
      "productContext": "teams",
      "operatorId": "string",
      "status": "active",
      "consentedOn": "2024-05-07T11:15:10.519Z",
      "lastModifiedOn": "2024-05-07T11:15:10.519Z",
      "consentedCountries": [
        "string"
      ],
      "contacts": [
        {
          "fullName": "Example Name",
          "email": "example@contoso.com",
          "telephoneNumber": "+1234567890",
          "companyName": "contoso",
          "companySize": "size"
        }
      ],
      "customerRelationship": {
        "status": "new status",
        "lastModifiedOn": "2024-05-07T12:15:10.520Z",
        "comment": "new comment"
      }
    }
}

Listar todos os números atribuídos a uma conta

Use uma solicitação GET no /accounts/<accountName>/numbers ponto de extremidade para obter uma lista dos números que foram provisionados para essa conta.

Solicitação:

GET /accounts/contoso/numbers?api-version=2024-02-29 HTTP/1.1

Resposta para uma conta com apenas números do Operator Connect:

{
  "value": [
    {
      "serviceProvisioningStatus": "pending",
      "serviceProvisioningErrors": null,
      "telephoneNumber": "+123451",
      "accountName": "contoso",
      "serviceDetails": {
        "teamsOperatorConnect": {
          "enabled": true,
          "assignmentStatus": "assigned",
          "configuration": {
            "usage": "CallingUserAssignment",
            "choosableCapabilities": [
              "InboundCalling",
              "OutboundCalling",
              "Mobile"
            ],
            "civicAddressId": "civicAddressIdString",
            "allowTenantAddressUpdate": true,
          }
        },
      },
      "configuration": {
        "customSipHeader": "exampleHeaderContents"
      }
    },
    ... // more OC numbers
  ],
  nextLink: "string"
}

Resposta para uma conta com números de Conexão de Operador e Roteamento Direto provisionados:

{
  "value": [
    {
      "serviceProvisioningStatus": "synced",
      "serviceProvisioningErrors": null,
      "telephoneNumber": "+123451",
      "accountName": "contoso",
      "serviceDetails": {
        "teamsOperatorConnect": {
          "enabled": true,
          "assignmentStatus": "assigned",
          "configuration": {
            "usage": "CallingUserAssignment",
            "choosableCapabilities": [
              "InboundCalling",
              "OutboundCalling",
              "Mobile"
            ],
            "civicAddressId": "civicAddressIdString",
            "allowTenantAddressUpdate": true,
          }
        },
      },
      "configuration": {
        "customSipHeader": "exampleHeaderContents"
      }
    },
    {
      "serviceProvisioningStatus": "synced",
      "serviceProvisioningErrors": null,
      "telephoneNumber": "+123452",
      "accountName": "contoso",
      "serviceDetails": {
        "teamsDirectRouting": {
          "enabled": true
        }
      },
      "configuration": {
        "customSipHeader": "exampleHeaderContents"
      }
    },
    ... // more DR and OC numbers
  ],
  nextLink: "string"
}

Listar todos os locais de emergência para uma conta específica

Use uma solicitação GET no /accounts/<accountName>/teamsCivicAddresses ponto de extremidade para obter a lista completa de Endereços Cívicos configurados no Centro de Administração do Teams para essa conta. Você pode usar a população dessa lista como o locationid ao criar ou atualizar números dentro da conta.

Solicitação:

GET /accounts/contoso/teamsCivicAddresses?api-version=2024-02-29 HTTP/1.1

Resposta:

{
  "value": [
    {
      "id": "string",
      "country": "string",
      "houseNumber": "string",
      "houseNumberSuffix": "string",
      "preDirectional": "string",
      "streetName": "string",
      "streetSuffix": "string",
      "postDirectional": "string",
      "stateOrProvince": "string",
      "countyOrDistrict": "string",
      "cityOrTown": "string",
      "cityOrTownAlias": "string",
      "postalOrZipCode": "string",
      "description": "string",
      "companyName": "string",
      "companyId": "string",
      "defaultLocationId": "string",
      "validationStatus": "notValidated",
      "tenantId": "string",
      "partnerId": "string",
      "locations": [
        {
          "id": "string",
          "civicAddressId": "string",
          "description": "string",
          "additionalInfo": "string",
          "isDefault": true,
          "elin": "string"
        }
      ],
      "latitude": "string",
      "longitude": "string"
    },
    ... // more locations
  ],
  "nextLink": "string"
}

Remover um número da conta

Use DELETE no /accounts/<accountName>/numbers/<telephoneNumber> ponto de extremidade para liberar um número de um locatário. Essa operação cancelará a atribuição de um número de um usuário se for atribuída e, em seguida, liberará o número do locatário.

Solicitação:

DELETE /accounts/contoso/numbers/+123451?api-version=2024-02-29 HTTP/1.1

Resposta:

204 Status Code

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, verificando se serviceDetails.teamsDirectRouting 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 foi configurada para usar o Roteamento Direto/Zoom e se o número tem esse recurso específico habilitado.

  • Consegui 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 (a uma taxa razoável por segundo). Espaçar suas solicitações ou usar o ponto de extremidade em lote para evitar que a taxa seja limitada. O limite de taxa atinge o tempo limite eventualmente e você poderá se conectar.

Próximas etapas

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