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

Artigo
05/15/2024

A API de Aprovisionamento dos operadores de telecomunicações do Azure Communications Gateway permite-lhe aprovisionar os detalhes dos seus clientes e os números atribuídos aos mesmos no Azure Communications Gateway (ACG). A API de Aprovisionamento também suporta o aprovisionamento flow-through de alguns serviços de comunicações de back-end.

O aprovisionamento de clientes e números é obrigatório (com a API de Aprovisionamento ou o Portal de Gestão de Números baseado no browser) para todos os casos de utilização, exceto o Operador Connect e o Telefone Teams Mobile. Para o Operador Connect e Telefone Teams Mobile, a utilização da API de Aprovisionamento e/ou do Portal de Gestão de Números é opcional e pode ser integrada diretamente com a API de Ligação do Operador.

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 que é apresentado na página Descrição geral do recurso no portal do Azure. A API está disponível na porta 443 de provapi.<base-domain>.
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 de portador indica que a aplicação está autorizada para um ou mais âmbitos (funções) para a API de Aprovisionamento. Recomendamos que utilize o fluxo de credenciais do cliente (concebido para um processo do lado do servidor).

Estão disponíveis os seguintes âmbitos 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 aplicação suporta 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 relativamente ao 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 a si próprio como proprietário para o registo de aplicações. Veja Atribuir o 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 confiança padrão da Microsoft para certificados de segurança.

Conceitos-chave

A Plataforma de Aprovisionamento tem três recursos principais que o operador pode gerir: contas, números e pedidos de informações.

Os recursos da conta são descrições de clientes operadores (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, os serviços (por exemplo, o Encaminhamento Direto do Microsoft Teams) que os números utilizam e qualquer configuração adicional por número.
Os recursos do Pedido de Informação (RFI) são descrições de potenciais clientes para operadores que estão a manifestar interesse em receber o serviço do operador através de serviços de back-end específicos. Atualmente, só estão disponíveis AS RFIs produzidas a partir do Operador Connect e do Telefone Teams Mobile.

Por exemplo, para fornecer o Serviço de Encaminhamento Direto do Microsoft Teams a um cliente, 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.

Dica

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

Aprovisionar serviços de back-end com a sincronização do serviço de back-end

O Azure Communications Gateway tem de ter informações sobre os números aos quais está a fornecer serviço para ligar corretamente as chamadas. Recomendamos a API de Aprovisionamento do Gateway de Comunicações do Azure para fornecer estas informações ao Gateway de Comunicações do Azure, mas também pode utilizar o Portal de Gestão de Números. A maioria dos serviços de back-end também precisa de ser aprovisionada com informações sobre os números e contas a utilizar. Este requisito geralmente significa que são necessários vários projetos de integração de TI para ativar novos serviços. A plataforma de Aprovisionamento do Gateway de Comunicações do Azure foi pré-intuida com alguns serviços de back-end para os aprovisionar automaticamente, reduzindo os seus requisitos de integração de TI. Pode utilizar esta função ao ativar a sincronização do serviço de back-end para os serviços relevantes. Isto também significa que qualquer integração de TI na plataforma de aprovisionamento do Gateway de Comunicações do Azure é reutilizável para outros serviços de back-end.

Por exemplo, o Operator Connect determina que todos os números são carregados através da API de Ligação do Operador. Se a sincronização do serviço de back-end estiver ativada para o Operator Connect, qualquer número aprovisionado no Gateway de Comunicações do Azure e ativado para o Operator Connect será aprovisionado automaticamente no Operator Connect, o que significa que não precisa de integrar com a API de Ligação do Operador.

O aprovisionamento através da plataforma de aprovisionamento 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 a partir do back-end. No entanto, algumas funcionalidades, como a adição de cabeçalhos SIP do cliente para fins de faturação, não estarão disponíveis. Para quaisquer serviços que não suportem a sincronização do serviço de back-end, poderá ser necessária outra integração de TI diretamente no serviço de back-end. O estado do suporte de aprovisionamento está descrito na tabela seguinte:

Serviço de Back-end	Requisito para aprovisionar através da Plataforma de Aprovisionamento ACG	Aprovisionamento do serviço de back-end suportado
Encaminhamento Direto	Obrigatório	❌
Zoom	Obrigatório	❌
Proteção de Chamada do Operador Azure	Obrigatório	❌
Ligação do Operador	Opcional	✅
Telefone Teams Mobile	Opcional	✅

A sincronização com os serviços de back-end é assíncrona, o que significa que o pedido de aprovisionamento pode ser bem-sucedido antes de o serviço de back-end ter sido aprovisionado. Este estado é justificado na resposta da API com o serviceProvisioningStatus campo definido como pending. Recomendamos que consulte o objeto para verificar o respetivo estado de aprovisionamento até que este campo esteja definido como success. Quaisquer erros do aprovisionamento do sistema de back-end são disponibilizados diretamente na resposta.

Exemplos

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

Create uma conta que representa um cliente

Utilize PUT no accounts/<accountName> ponto final para criar uma conta com o nome contoso para o 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=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 seguinte, criamos uma conta para utilização apenas com o Operador do Teams Connect, com a sincronização de back-end ativada para que as informações sobre esta conta (como quaisquer números carregados) também sejam aprovisionadas no Teams:

Pedido:

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

Ver os detalhes da conta

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

Todas as configurações anteriormente definidas (ou a predefinição, se um campo não tiver sido definido).
O subscritor conta para cada um dos serviços disponíveis no ACG.
O estado do aprovisionamento do serviço de back-end, se ativado.
subdomainStatus, representando o estado do aprovisionamento de registos DNS, apenas relevante para o Encaminhamento Direto.
Um ETag cabeçalho que representa o estado atual da conta. Pode utilizar o valor num If-Match cabeçalho 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=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
    },
  }
}

O pedido equivalente se a conta tiver vários serviços configurados é apresentado da seguinte forma:

Pedido:

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

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

Pedido:

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

Utilize PUT account/<accountName>/numbers/<telephoneNumber> no ponto final para adicionar um número à conta, ativar um ou mais serviços de comunicações e adicionar qualquer outra configuração. 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. Todos os números têm de ser criados no formato E.164.

No seguinte exemplo:

O número é +123451.
A ligação do operador está ativada.
É fornecida a configuração necessária para carregar o número para o Operador Connect
customSipHeader especifica que o Gateway de Comunicações do Azure deve adicionar um cabeçalho com o valor exampleHeaderContents às mensagens enviadas para a rede do operador. O nome do cabeçalho é definido como parte da implementação do Gateway de Comunicações do Azure.
O serviceProvisioningStatus campo na resposta mostra o estado 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"
  }
}

Verificar o estado de aprovisionamento após algum tempo

Utilize GET no account/<accountName>/numbers/<telephoneNumber> após uma ação de aprovisionamento para verificar o estado do número. Se o número tiver sido aprovisionado com êxito, o serviceProvisioningStatus campo é atualizado de pending para synced.

Pedido:

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 aprovisionamento do serviço de back-end para carregar um número

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

Nota

Inicialmente, ao aprovisionar um número, tem pending de ser novamente consultado para confirmar o êxito/falha.

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

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

Utilize PUT no account/<accountName>/numbers/<telephoneNumber> 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 /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 os Pedidos de Informações

Utilize um GET no /teamsRequestsForInformation ponto final para obter uma lista dos consentimentos do Teams que lhe foram submetidos por potenciais clientes.

Pedido:

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 um Pedido de Informações

Utilize PATCH /teamsRequestsForInformation/<tenantID> no ponto final para atualizar o estado do RFI, que se reflete no serviço de back-end. O Operador Connect e o Telefone Teams Mobile permitem-lhe indicar o estado do pedido de volta ao cliente final para que o estado atualizado seja apresentado no Teams Administração Center do cliente.

Pedir

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

Utilize um pedido GET no /accounts/<accountName>/numbers ponto final para obter uma lista dos números que foram aprovisionados para essa conta.

Pedido:

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 Ligação do Operador e Encaminhamento Direto aprovisionados:

{
  "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 todas as localizações de emergência para uma conta específica

Utilize um pedido GET no /accounts/<accountName>/teamsCivicAddresses ponto final para obter a lista completa de Endereços Cívicos configurados no Teams Administração Center para essa conta. Pode utilizar a população desta lista como quando locationid criar ou atualizar números na conta.

Pedido:

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

Utilize DELETE no /accounts/<accountName>/numbers/<telephoneNumber> ponto final para libertar um número de um inquilino. Esta operação irá anular a atribuição de um número de um utilizador, se atribuído e, em seguida, libertar o número do inquilino.

Pedido:

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

Resposta:

204 Status Code

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, verificando se serviceDetails.teamsDirectRouting tem subdomainStatus igual a Provisioned.
Configurei um número para utilizar o Direct Routing/Zoom, mas não parece estar a funcionar.
- Verifique se a conta foi configurada para utilizar o Encaminhamento Direto/Zoom e se o número tem esta funcionalidade específica ativada.
Consegui 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 (a uma taxa razoável por segundo). Espaçar os seus pedidos ou utilizar o ponto final do batch para evitar ser limitado. O limite de taxa excede o limite de tempo eventualmente e poderá ligar-se.

Passos seguintes

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

Partilhar via

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

Introdução

Pré-requisitos

Autenticação e autorização

Conceitos-chave

Aprovisionar serviços de back-end com a sincronização do serviço de back-end

Exemplos

Create uma conta que representa um cliente

Ver os detalhes da conta

Atualizar a configuração da conta

Adicionar um número à conta

Verificar o estado de aprovisionamento após algum tempo

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

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

Listar os Pedidos de Informações

Atualizar um Pedido de Informações

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

Listar todas as localizações de emergência para uma conta específica

Remover um número da conta

Resolução de problemas

Passos seguintes

Recursos adicionais