API di provisioning di Gateway di comunicazione di Azure

  • Articolo

L'API di provisioning di Gateway di comunicazione di Azure per gli operatori di telecomunicazioni consente di effettuare il provisioning dei dettagli dei clienti e dei numeri assegnati ad essi in Azure Communications Gateway (ACG). L'API di provisioning supporta anche il provisioning di alcuni servizi di comunicazione back-end.

Il provisioning di clienti e numeri è obbligatorio (con l'API di provisioning o il portale di gestione dei numeri basato su browser) per tutti i casi d'uso, ad eccezione di Operator Connect e Telefono di Teams Mobile. Per Operator Connect e Telefono di Teams Mobile, l'uso dell'API di provisioning e/o del portale di gestione dei numeri è facoltativo ed è possibile integrarsi direttamente con l'API Operator Connect.

Introduzione

Prerequisiti

  • Un tenant con l'applicazione Gateway di comunicazione di Azure distribuita.
  • Nome di dominio completo (FQDN) per il gateway di comunicazione di Azure visualizzato nella pagina Panoramica della risorsa nel portale di Azure. L'API è disponibile sulla porta 443 di provapi.<base-domain>.
  • Un computer con un indirizzo IP che consente l'accesso all'API, come configurato in un elenco di elementi consentiti come parte della distribuzione di Gateway di comunicazione di Azure.

Autenticazione e autorizzazione

L'API di provisioning usa OAuth 2.0 per controllare l'accesso alle risorse. L'applicazione client deve ottenere un token di connessione di autenticazione valido per accedere all'API di provisioning. Il token di connessione indica che l'applicazione è autorizzata per uno o più ambiti (ruoli) per l'API di provisioning. È consigliabile usare il flusso delle credenziali client (progettato per un processo lato server).

Per l'API di provisioning sono disponibili gli ambiti seguenti:

  • ProvisioningAPI.Admin: possibilità di richiamare qualsiasi operazione nell'API.
  • ProvisioningAPI.Read: possibilità di richiamare qualsiasi operazione di lettura (GET) nell'API.
  • ProvisioningAPI.Write: possibilità di richiamare qualsiasi operazione di scrittura (PUT, PATCH) nell'API.
  • ProvisioningAPI.Delete: possibilità di richiamare qualsiasi operazione di eliminazione (DELETE) nell'API.

Per configurare un flusso di credenziali client:

  1. Assicurarsi che l'applicazione possa supportare il flusso delle credenziali client.

    • Quando l'applicazione richiede un token per l'API di provisioning, deve usare i campi seguenti.

      Parametro Condizione Descrizione
      tenant necessario Tenant di directory contenente il gateway di comunicazione di Azure, in formato GUID o nome di dominio.
      scope obbligatorio Ambito dell'autorizzazione rispetto all'ID risorsa del gateway di comunicazione di Azure. Per il flusso delle credenziali client descritto qui, l'ambito deve essere https://func-voiceservice-rp-prod-eastuseuap.azurewebsites.net/.default.
      client_id necessarie ID applicazione (client) assegnato all'app.

    • L'attestazione roles nel token ricevuto specifica i ruoli (ambiti) a cui l'applicazione client è autorizzata ad accedere.

    • Le richieste alla piattaforma di provisioning del gateway di comunicazione di Azure devono avere un'intestazione Authorization con questo token di connessione.

    • Per esempi di uso dei token, vedere la documentazione del flusso delle credenziali client .

  2. Usare il portale di Azure per registrare l'applicazione nello stesso tenant della distribuzione del gateway di comunicazione di Azure. Vedere Guida introduttiva: Registrare un'app nel Microsoft Identity Platform - Microsoft Entra | Microsoft Learn.
  3. Assegnarsi come proprietario per la registrazione dell'app. Vedere Assegnare il proprietario dell'applicazione.
  4. Configurare la registrazione dell'app creata registrando l'applicazione con i ruoli dell'app che usano gli ambiti per l'API di provisioning, come descritto in precedenza.
  5. Gli amministratori del tenant consentono all'applicazione di usare i ruoli dell'app assegnati. Vedere Concedere il consenso amministratore.

L'API di provisioning usa catene standard di attendibilità Microsoft per i certificati di sicurezza.

Concetti chiave

La piattaforma di provisioning dispone di tre risorse chiave che l'operatore può gestire: account, numeri e richieste di informazioni.

  • Le risorse dell'account sono descrizioni dei clienti degli operatori (in genere, un'organizzazione) e le impostazioni per cliente per il provisioning dei servizi.
  • Le risorse numerice appartengono a un account. Descrivono i numeri, i servizi (ad esempio, l'instradamento diretto di Microsoft Teams) usati dai numeri e qualsiasi configurazione aggiuntiva per numero.
  • Le risorse di richiesta di informazioni (RFI) sono descrizioni di potenziali clienti per gli operatori che esprimono interesse a ricevere il servizio dall'operatore tramite servizi back-end specifici. Attualmente sono disponibili solo le RFI prodotte da Operator Connect e Telefono di Teams consenso per dispositivi mobili.

Ad esempio, per fornire il servizio di routing diretto di Microsoft Teams a un cliente, Contoso, creare una risorsa account con l'API di provisioning per Contoso. L'account contiene la configurazione per l'instradamento diretto, ad esempio un sottodominio e i token corrispondenti, necessari per configurare i record DNS che Microsoft Teams può usare per convalidare la configurazione del cliente. È quindi necessario aggiungere risorse numerice all'account e abilitare ogni numero per l'instradamento diretto.

Suggerimento

È necessario abilitare il servizio sia nell'account che nei numeri all'interno dell'account.

Provisioning di servizi back-end con sincronizzazione del servizio back-end

Il gateway di comunicazione di Azure deve avere informazioni sui numeri a cui fornisce il servizio per connettersi correttamente alle chiamate. È consigliabile usare l'API di provisioning del gateway di comunicazione di Azure per fornire queste informazioni al gateway di comunicazione di Azure, ma è anche possibile usare il portale di gestione dei numeri. La maggior parte dei servizi back-end deve anche essere sottoposto a provisioning con informazioni sui numeri e sugli account da usare. Questo requisito spesso significa che sono necessari più progetti di integrazione IT per abilitare nuovi servizi. La piattaforma di provisioning di Gateway di comunicazione di Azure è stata preintegrata con alcuni servizi back-end per eseguirne il provisioning, riducendo i requisiti di integrazione IT. È possibile usare questa funzione abilitando la sincronizzazione del servizio back-end per i servizi pertinenti. Ciò significa anche che qualsiasi integrazione IT nella piattaforma di provisioning di Azure Communications Gateway è riutilizzabile per altri servizi back-end.

Ad esempio, Operator Connect impone che tutti i numeri vengano caricati tramite l'API Operator Connect. Se la sincronizzazione del servizio back-end è abilitata per Operator Connect, qualsiasi numero di cui è stato effettuato il provisioning nel gateway di comunicazione di Azure e abilitato per Operator Connect verrà eseguito automaticamente il provisioning in Operator Connect, ovvero non è necessario eseguire l'integrazione con l'API Operator Connect.

Il provisioning tramite la piattaforma di provisioning del gateway di comunicazione di Azure è facoltativo per alcuni servizi in cui Il gateway di comunicazione di Azure può ottenere informazioni direttamente dal back-end. Tuttavia, alcune funzionalità, ad esempio l'aggiunta di intestazioni SIP del cliente per scopi di fatturazione, non saranno disponibili. Per tutti i servizi che non supportano la sincronizzazione del servizio back-end, è possibile che sia necessaria un'altra integrazione IT direttamente al servizio back-end. Lo stato del supporto per il provisioning è descritto nella tabella seguente:

Servizio back-end Requisito di effettuare il provisioning tramite ACG Provisioning Platform Provisioning del servizio back-end supportato
Instradamento diretto Obbligatorio ❌
Zoom Obbligatorio ❌
Protezione delle chiamate degli operatori su Azure Obbligatorio ❌
Operatore Connect Facoltativo ✅
Telefono di Teams Mobile Facoltativo ✅

La sincronizzazione con i servizi back-end è asincrona, ovvero la richiesta di provisioning può avere esito positivo prima del provisioning del servizio back-end. Questo stato è indicato nella risposta dell'API usando il serviceProvisioningStatus campo impostato su pending. È consigliabile eseguire una query sull'oggetto per controllarne lo stato di provisioning fino a quando questo campo non è impostato su success. Eventuali errori derivanti dal provisioning del sistema back-end vengono resi disponibili direttamente nella risposta.

Esempio

Gli esempi seguenti illustrano le richieste di esempio per la gestione di RFI, account e numeri.

Create un account che rappresenta un cliente

Usare PUT nell'endpoint accounts/<accountName> per creare un account denominato contoso per il cliente Contoso e configurare uno o più servizi di comunicazione per l'account. Usare un'intestazione If-None-Match per verificare che una risorsa account con questo nome non esista già.

Nell'esempio seguente:

  • Il routing diretto è configurato.
  • Lo screening DELL'ID chiamante è abilitato (impostazione predefinita).
  • Il sottodominio per il cliente è contoso.
  • I valori TXT DNS forniti dal cliente necessari per configurare i record DNS si trovano nei region1Token campi e region2Token .

Richiesta:

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

Risposta:

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

Nell'esempio seguente viene creato un account per l'uso solo con Teams Operator Connect, con sincronizzazione back-end abilitata in modo che le informazioni su questo account (ad esempio tutti i numeri caricati) vengano eseguite anche in Teams:

Richiesta:

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

Risposta:

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

Visualizzare i dettagli dell'account

Usare GET nell'endpoint per ottenere i dettagli dell'account accounts/<accountName> . La risposta include i campi seguenti:

  • Tutte le configurazioni impostate in precedenza (o il valore predefinito, se un campo non è stato impostato).
  • Il sottoscrittore conta per ognuno dei servizi disponibili in ACG.
  • Stato del provisioning del servizio back-end, se abilitato.
  • subdomainStatus, che rappresenta lo stato del provisioning dei record DNS, solo rilevanti per il routing diretto.
  • Intestazione ETag che rappresenta lo stato corrente dell'account. È possibile usare il valore in un'intestazione If-Match nelle richieste di aggiornamento successive per assicurarsi di non sovrascrivere le modifiche apportate da altri utenti dell'API.

Richiesta:

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

Risposta:

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

La richiesta equivalente se l'account ha più servizi configurati viene visualizzato come segue:

Richiesta:

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

Risposta:

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

Aggiornare la configurazione per l'account

Usare PUT nell'endpoint accounts/<accountName> per aggiornare la configurazione per l'account. Per assicurarsi che l'aggiornamento non sovrascrivi una modifica apportata da un altro utente, aggiungere un'intestazione If-Match con ETag dalla risposta più recente per l'account.

Richiesta:

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

Risposta:

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

Aggiungere un numero all'account

Usare PUT sull'endpoint per aggiungere un numero all'account account/<accountName>/numbers/<telephoneNumber> , abilitare uno o più servizi di comunicazione e aggiungere qualsiasi altra configurazione. I servizi di comunicazione scelti devono essere configurati anche nell'account. Usare un'intestazione If-None-Match per verificare che una risorsa numerica con questo numero non esista già. Tutti i numeri devono essere creati in formato E.164.

Nell'esempio seguente:

  • Il numero è +123451.
  • La connessione dell'operatore è abilitata.
  • Viene fornita la configurazione necessaria per caricare il numero in Operator Connect
  • customSipHeader specifica che Il gateway di comunicazione di Azure deve aggiungere un'intestazione con il valore exampleHeaderContents ai messaggi inviati alla rete dell'operatore. Il nome dell'intestazione è impostato come parte della distribuzione del gateway di comunicazione di Azure.
  • Il serviceProvisioningStatus campo nella risposta mostra lo stato della sincronizzazione al servizio 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"
  }
}

Risposta:

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

Controllo dello stato del provisioning dopo un certo periodo di tempo

Usare GET nel account/<accountName>/numbers/<telephoneNumber> dopo un'azione di provisioning per controllare lo stato del numero. Se il numero è stato effettuato correttamente il provisioning, il serviceProvisioningStatus campo viene aggiornato da pending a synced.

Richiesta:

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

Risposta:

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

Errore nel provisioning del servizio back-end per il caricamento di un numero

In questo esempio, il provisioning back-end durante il caricamento del numero raggiunge un errore, che viene riflesso sulla risposta. I messaggi di errore vengono passati in modo trasparente dai servizi back-end.

Nota

Inizialmente quando si esegue il provisioning di un numero ha pending stato, che deve essere eseguito di nuovo una query per confermare l'esito positivo o l'errore.

Richiesta originale, mancante di un valore per il 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"
  }
}

Risposta dalla query GET dopo qualche 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"
  }

Aggiornare la configurazione per un numero

Usare PUT nell'endpoint per aggiornare la account/<accountName>/numbers/<telephoneNumber> configurazione per un numero. Per assicurarsi che l'aggiornamento non sovrascrive una modifica apportata da un altro utente, aggiungere un'intestazione If-Match con ETag dalla risposta più recente per il numero.

Richiesta:

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

Risposta:

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

Elencare le richieste di informazioni

Usare get nell'endpoint /teamsRequestsForInformation per ottenere un elenco dei consenso di Teams inviati da potenziali clienti.

Richiesta:

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

Risposta:

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

Aggiornare una richiesta di informazioni

Usare PATCH nell'endpoint /teamsRequestsForInformation/<tenantID> per aggiornare lo stato dell'rfi, che si riflette nel servizio back-end. L'operatore Connect e Telefono di Teams Mobile consente di indicare lo stato della richiesta al cliente finale in modo che lo stato aggiornato venga visualizzato nel Centro Amministrazione Teams del cliente.

Richiesta

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

Risposta

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

Elencare tutti i numeri assegnati a un account

Usare una richiesta GET nell'endpoint /accounts/<accountName>/numbers per ottenere un elenco dei numeri di cui è stato effettuato il provisioning per tale account.

Richiesta:

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

Risposta per un account con solo numeri di operatore 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"
}

Risposta per un account con numeri di routing diretto e Connetti operatore con provisioning:

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

Elencare tutte le posizioni di emergenza per un account specifico

Usare una richiesta GET nell'endpoint per ottenere l'elenco /accounts/<accountName>/teamsCivicAddresses completo degli indirizzi civici configurati nel Centro di Amministrazione Teams per tale account. È possibile usare la popolazione di questo elenco come locationid quando si creano o aggiornano i numeri all'interno dell'account.

Richiesta:

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

Risposta:

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

Rimuovere un numero dall'account

Usare DELETE nell'endpoint /accounts/<accountName>/numbers/<telephoneNumber> per rilasciare un numero da un tenant. Questa operazione annulla l'assegnazione di un numero da un utente se assegnato e quindi rilascia il numero dal tenant.

Richiesta:

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

Risposta:

204 Status Code

Risoluzione dei problemi

  • Il routing diretto di Teams non funziona per i numeri in un account.

    • Verificare che il token DNS sia stato convalidato inviando un GET nell'account, verificando che serviceDetails.teamsDirectRouting sia subdomainStatus uguale a Provisioned.

  • Ho configurato un numero per usare Routing diretto/Zoom, ma non sembra funzionare.

    • Verificare che l'account sia stato configurato per usare Routing diretto/Zoom e che il numero abbia questa funzionalità specifica abilitata.

  • Sono riuscito a contattare l'API, ma dopo aver effettuato più richieste, le connessioni iniziano a eseguire il timeout.

    • L'API di provisioning è limitata (a una velocità ragionevole al secondo). Spaziare le richieste o usare l'endpoint batch per evitare di essere limitato. Il timeout della frequenza alla fine sarà in grado di connettersi.

Passaggi successivi

Iniziare a integrare con l'API Provisioning del gateway di comunicazione di Azure.