Inrichtings-API voor Azure Communications Gateway

Artikel
05/15/2024

Met de inrichtings-API van Azure Communications Gateway voor telecommunicatieoperators kunt u de details van uw klanten en de nummers die aan hen zijn toegewezen inrichten in Azure Communications Gateway (ACG). De inrichtings-API biedt ook ondersteuning voor flowthrough-inrichting van sommige back-endcommunicatieservices.

Het inrichten van klanten en nummers is verplicht (met de inrichtings-API of de browsergebaseerde nummerbeheerportal) voor alle gebruiksscenario's, met uitzondering van Operator Connect en Teams Telefoon Mobile. Voor Operator Connect en Teams Telefoon Mobile is het gebruik van de Inrichtings-API en/of De Portal voor nummerbeheer optioneel en kunt u in plaats daarvan rechtstreeks integreren met de Operator Connect-API.

Aan de slag

Vereisten

Een tenant met de Azure Communications Gateway-toepassing geïmplementeerd.
De FQDN (Fully Qualified Domain Name) voor uw Azure Communications Gateway die wordt weergegeven op de pagina Overzicht voor de resource in de Azure Portal. De API is beschikbaar op poort 443 van provapi.<base-domain>.
Een machine met een IP-adres dat toegang tot de API toestaat, zoals geconfigureerd in een acceptatielijst als onderdeel van de implementatie van Azure Communications Gateway.

Verificatie en autorisatie

De inrichtings-API gebruikt OAuth 2.0 om de toegang tot resources te beheren. De clienttoepassing moet een geldig verificatie bearer-token verkrijgen om toegang te krijgen tot de inrichtings-API. Het bearer-token geeft aan dat de toepassing is geautoriseerd voor een of meer van de bereiken (rollen) voor de inrichtings-API. U wordt aangeraden de stroom voor clientreferenties te gebruiken (ontworpen voor een proces aan de serverzijde).

De volgende bereiken zijn beschikbaar voor de inrichtings-API:

ProvisioningAPI.Admin: Mogelijkheid om bewerkingen in de API aan te roepen.
ProvisioningAPI.Read: Mogelijkheid om een leesbewerking (GET) aan te roepen in de API.
ProvisioningAPI.Write: Mogelijkheid om schrijfbewerkingen (PUT, PATCH) aan te roepen in de API.
ProvisioningAPI.Delete: Mogelijkheid om een delete-bewerking (DELETE) aan te roepen in de API.

Een stroom voor clientreferenties instellen:

Zorg ervoor dat uw toepassing de stroom voor clientreferenties kan ondersteunen.

Wanneer uw toepassing een token aanvraagt voor de Inrichtings-API, moeten de volgende velden worden gebruikt.

Parameter	Voorwaarde	Description
tenant	vereist	De maptenant die de Azure Communications Gateway bevat, in guid- of domeinnaamvorm.
scope	vereist	Het bereik van de autorisatie op basis van de resource-id van De Azure Communications Gateway. Voor de clientreferentiestroom die hier wordt beschreven, moet het bereik zijn `https://func-voiceservice-rp-prod-eastuseuap.azurewebsites.net/.default`.
client_id	vereist	De toepassings-id (client) die is toegewezen aan uw app.

De roles claim in het ontvangen token geeft de rollen (bereiken) aan waartoe de clienttoepassing toegang heeft.
Aanvragen voor het Azure Communications Gateway Provisioning Platform moeten een Authorization header met dit bearer-token hebben.
Zie de documentatie over de clientreferentiestroom voor voorbeelden van het gebruik van tokens.

Gebruik de Azure Portal om de toepassing te registreren in dezelfde tenant als uw Azure Communications Gateway-implementatie. Zie Quickstart: Een app registreren in de Microsoft identity platform - Microsoft Entra | Microsoft Learn.
Wijs uzelf toe als eigenaar voor de app-registratie. Zie Toepassingseigenaar toewijzen.
Configureer de app-registratie die is gemaakt door de toepassing te registreren met app-rollen die gebruikmaken van de bereiken voor de inrichtings-API, zoals eerder beschreven.
- Zie App-rollen toewijzen aan toepassingen.
- De API waarvoor u machtigingen moet toewijzen, is AzureCommunicationsGateway, vermeld onder API's die mijn organisatie gebruikt.
Als beheerder voor de tenant staat u toe dat de toepassing de app-rollen gebruikt die u hebt toegewezen. Zie Beheerderstoestemming verlenen.

De inrichtings-API maakt gebruik van standaard Vertrouwensketens van Microsoft voor beveiligingscertificaten.

Belangrijkste concepten

Het inrichtingsplatform heeft drie belangrijke resources die de operator kan beheren: accounts, nummers en informatieaanvragen.

Accountresources zijn beschrijvingen van operatorklanten (meestal een onderneming) en instellingen per klant voor serviceinrichting.
Nummerresources behoren tot een account. Ze beschrijven getallen, de services (bijvoorbeeld Microsoft Teams Direct Routing) waarvan de nummers gebruikmaken en eventuele extra configuratie per nummer.
RFI-resources (Request for Information) zijn beschrijvingen van potentiële klanten voor operators die interesse tonen in het ontvangen van service van de operator via specifieke back-endservices. Momenteel zijn alleen RFI's die zijn geproduceerd via Operator Connect en Teams Telefoon Mobile-toestemmingen beschikbaar.

Als u bijvoorbeeld de directe routeringsservice van Microsoft Teams wilt bieden aan een klant, Contoso, maakt u een accountresource met de inrichtings-API voor Contoso. Het account bevat configuratie voor directe routering (bijvoorbeeld een subdomein en bijbehorende tokens, die nodig zijn voor het instellen van DNS-records die Microsoft Teams kan gebruiken om de configuratie van de klant te valideren). Vervolgens moet u nummerresources toevoegen aan het account en elk nummer inschakelen voor directe routering.

Tip

U moet service inschakelen voor zowel het account als de nummers in het account.

Back-endservices inrichten met back-endservicesynchronisatie

Azure Communications Gateway moet informatie hebben over de nummers aan wie de service wordt aangeboden om oproepen correct te kunnen verbinden. We raden de Inrichtings-API van Azure Communications Gateway aan voor het verstrekken van deze informatie aan Azure Communications Gateway, maar u kunt ook de Portal voor nummerbeheer gebruiken. De meeste back-endservices moeten ook worden ingericht met informatie over de nummers en accounts die moeten worden gebruikt. Deze vereiste betekent vaak dat er meerdere IT-integratieprojecten nodig zijn om nieuwe services mogelijk te maken. Het inrichtingsplatform van Azure Communications Gateway is vooraf geïntegreerd met een aantal back-endservices om deze voor u in te richten, waardoor uw IT-integratievereisten worden verminderd. U kunt deze functie gebruiken door back-endservicesynchronisatie in te schakelen voor de relevante services. Dit betekent ook dat elke IT-integratie met het Azure Communications Gateway-inrichtingsplatform herbruikbaar is voor andere back-endservices.

Operator Connect vereist bijvoorbeeld dat alle getallen worden geüpload via de Operator Connect-API. Als back-endservicesynchronisatie is ingeschakeld voor Operator Connect, wordt elk nummer dat is ingericht voor Azure Communications Gateway en ingeschakeld voor Operator Connect, automatisch ingericht in Operator Connect, wat betekent dat u niet hoeft te integreren met de Operator Connect-API.

Inrichten via het Azure Communications Gateway-inrichtingsplatform is optioneel voor sommige services waarbij Azure Communications Gateway informatie rechtstreeks van de back-end kan verkrijgen. Sommige functies, zoals het toevoegen van SIP-headers van klanten voor factureringsdoeleinden, zijn echter niet beschikbaar. Voor services die geen ondersteuning bieden voor back-endservicesynchronisatie, is mogelijk andere IT-integratie rechtstreeks met de back-endservice vereist. De status van de ondersteuning voor inrichting wordt beschreven in de volgende tabel:

Back-endservice	Vereiste voor inrichting via ACG-inrichtingsplatform	Inrichting van back-endservice ondersteund
Directe routering	Verplicht	❌
Zoom	Verplicht	❌
Azure Operator Oproepbeveiliging	Verplicht	❌
Operator Connect	Optioneel	✅
Teams Telefoon Mobile	Optioneel	✅

Synchronisatie met back-endservices is asynchroon, wat betekent dat uw inrichtingsaanvraag kan slagen voordat de back-endservice is ingericht. Deze status wordt opgegeven in het API-antwoord met behulp van het serviceProvisioningStatus veld dat is ingesteld op pending. U wordt aangeraden een query uit te voeren op het object om de inrichtingsstatus te controleren totdat dit veld is ingesteld op success. Eventuele fouten bij het inrichten van het back-endsysteem worden rechtstreeks beschikbaar gemaakt in het antwoord.

Voorbeelden

In de volgende voorbeelden ziet u voorbeeldaanvragen voor het beheren van RFI's, accounts en nummers.

een account Creatie dat een klant vertegenwoordigt

Gebruik PUT op het accounts/<accountName> eindpunt om een account te maken met de naam contoso voor de klant Contoso en een of meer communicatieservices voor het account te configureren. Gebruik een If-None-Match-header om te controleren of er nog geen accountresource met deze naam bestaat.

In het volgende voorbeeld:

Directe routering is geconfigureerd.
Screening van nummerweergave is ingeschakeld (de standaardinstelling).
Het subdomein voor de klant is contoso.
De door de klant opgegeven DNS TXT-waarden die nodig zijn voor het instellen van DNS-records, bevinden zich in de region1Token velden en region2Token .

Aanvraag:

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

Reactie:

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

In het volgende voorbeeld maken we een account voor gebruik met alleen Teams Operator Connect, waarbij back-endsynchronisatie is ingeschakeld, zodat informatie over dit account (zoals geüploade nummers) ook worden ingericht in Teams:

Aanvraag:

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

Reactie:

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

De details van het account weergeven

Gebruik GET op het accounts/<accountName> eindpunt om de details van het account op te halen. Het antwoord bevat de volgende velden:

Alle configuraties die eerder zijn ingesteld (of de standaardinstelling als een veld niet is ingesteld).
Aantal abonnees voor elk van de services die beschikbaar zijn op ACG.
De status van het inrichten van back-endservices, indien ingeschakeld.
subdomainStatus, die de status van het inrichten van DNS-records vertegenwoordigt, alleen relevant voor directe routering.
Een ETag header die de huidige status van het account weergeeft. U kunt de waarde in een If-Match header gebruiken bij volgende updateaanvragen om ervoor te zorgen dat u geen wijzigingen van andere API-gebruikers overschrijft.

Aanvraag:

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

Reactie:

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

De equivalente aanvraag als voor het account meerdere services zijn geconfigureerd, wordt als volgt weergegeven:

Aanvraag:

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

Reactie:

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

De configuratie voor het account bijwerken

Gebruik PUT op het accounts/<accountName> eindpunt om de configuratie voor het account bij te werken. Om ervoor te zorgen dat de update een wijziging van een andere gebruiker niet overschrijft, voegt u een If-Match header toe met de ETag uit het meest recente antwoord voor het account.

Aanvraag:

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

Reactie:

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

Eén nummer toevoegen aan het account

Gebruik PUT op het account/<accountName>/numbers/<telephoneNumber> eindpunt om een nummer toe te voegen aan het account, een of meer communicatieservices in te schakelen en een andere configuratie toe te voegen. De gekozen communicatieservices moeten ook worden geconfigureerd voor het account. Gebruik een If-None-Match-header om te controleren of er nog geen nummerresource met dit nummer bestaat. Alle getallen moeten worden gemaakt in de E.164-indeling.

In het volgende voorbeeld:

Het getal is +123451.
Operatorverbinding is ingeschakeld.
De configuratie die is vereist voor het uploaden van het nummer naar Operator Connect is opgegeven
customSipHeader geeft aan dat Azure Communications Gateway een header met de waarde exampleHeaderContents moet toevoegen aan berichten die naar het netwerk van de operator worden verzonden. De naam van de header wordt ingesteld als onderdeel van de implementatie van Azure Communications Gateway.
Het serviceProvisioningStatus veld in het antwoord toont de status van de synchronisatie met de back-endservice.

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

Reactie:

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

Inrichtingsstatus na enige tijd controleren

Gebruik GET op de account/<accountName>/numbers/<telephoneNumber> na een inrichtingsactie om de status van het nummer te controleren. Als het nummer is ingericht, wordt het serviceProvisioningStatus veld bijgewerkt van pending naar synced.

Aanvraag:

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

Reactie:

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

Fout bij het inrichten van back-endservices voor het uploaden van een nummer

In dit voorbeeld treedt bij het inrichten van de back-end bij het uploaden van het nummer een fout op, die wordt weerspiegeld in het antwoord. Foutberichten worden transparant doorgegeven vanuit back-endservices.

Notitie

In eerste instantie heeft pending het bij het inrichten van een getal de status, die opnieuw moet worden opgevraagd om te bevestigen dat het is gelukt of mislukt.

In de oorspronkelijke aanvraag ontbreekt een waarde voor het usage veld:

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

Reactie van GET-query na enige tijd:

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

Configuratie voor een getal bijwerken

Gebruik PUT op het eindpunt om de account/<accountName>/numbers/<telephoneNumber> configuratie voor een getal bij te werken. Voeg een If-Match-header toe met de ETag uit het meest recente antwoord voor het nummer om ervoor te zorgen dat de update een wijziging van een andere gebruiker niet overschrijft.

Aanvraag:

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

Reactie:

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

De verzoeken om informatie weergeven

Gebruik een GET op het /teamsRequestsForInformation eindpunt om een lijst te verkrijgen met de Teams-toestemmingen die aan u zijn verzonden door potentiële klanten.

Aanvraag:

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

Reactie:

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

Een aanvraag voor informatie bijwerken

Gebruik PATCH op het /teamsRequestsForInformation/<tenantID> eindpunt om de status van de RFI bij te werken, wat wordt weergegeven in de back-endservice. Met Operator Connect en Teams Telefoon Mobile kunt u de status van de aanvraag aan de eindklant aangeven, zodat de bijgewerkte status wordt weergegeven in het Teams Beheer Center van de klant.

Aanvraag

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

Antwoord

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

Alle nummers weergeven die aan een account zijn toegewezen

Gebruik een GET-aanvraag op het /accounts/<accountName>/numbers eindpunt om een lijst op te halen met de getallen die voor dat account zijn ingericht.

Aanvraag:

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

Antwoord voor een account met alleen Operator Connect-nummers:

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

Antwoord voor een account met zowel Operator Connect- als Directe routeringsnummers ingericht:

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

Alle locaties voor noodgevallen voor een specifiek account weergeven

Gebruik een GET-aanvraag op het /accounts/<accountName>/teamsCivicAddresses eindpunt om de volledige lijst met Civic-adressen te verkrijgen die zijn geconfigureerd in het Teams Beheer Center voor dat account. U kunt de populatie van deze lijst als de gebruiken bij het locationid maken of bijwerken van getallen in het account.

Aanvraag:

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

Reactie:

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

Een nummer uit het account verwijderen

Gebruik DELETE op het /accounts/<accountName>/numbers/<telephoneNumber> eindpunt om een getal uit een tenant vrij te geven. Met deze bewerking wordt een nummer van een gebruiker ingetrokken als deze is toegewezen en wordt vervolgens het nummer van de tenant vrijgegeven.

Aanvraag:

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

Reactie:

204 Status Code

Problemen oplossen

Directe routering van Teams werkt niet voor getallen in een account.
- Controleer of het DNS-token is gevalideerd door een GET voor het account te verzenden, waarbij wordt serviceDetails.teamsDirectRouting gecontroleerd of het gelijk is subdomainStatus aan Provisioned.
Ik heb een nummer geconfigureerd voor het gebruik van directe routering/zoom, maar het lijkt niet te werken.
- Controleer of het account is geconfigureerd voor het gebruik van directe routering/zoom en of deze specifieke functie is ingeschakeld voor het nummer.
Ik heb contact gemaakt met de API, maar nadat ik meerdere aanvragen heb ingediend, treedt er een time-out op voor mijn verbindingen.
- De inrichtings-API is beperkt (tot een redelijk tarief per seconde). Maak ruimte voor uw aanvragen of gebruik het batch-eindpunt om te voorkomen dat de snelheid wordt beperkt. De snelheidslimiet treedt uiteindelijk op en u kunt verbinding maken.

Volgende stappen

Begin met de integratie met de Inrichtings-API van Azure Communications Gateway.

Delen via

Inrichtings-API voor Azure Communications Gateway

Aan de slag

Vereisten

Verificatie en autorisatie

Belangrijkste concepten

Back-endservices inrichten met back-endservicesynchronisatie

Voorbeelden

een account Creatie dat een klant vertegenwoordigt

De details van het account weergeven

De configuratie voor het account bijwerken

Eén nummer toevoegen aan het account

Inrichtingsstatus na enige tijd controleren

Fout bij het inrichten van back-endservices voor het uploaden van een nummer

Configuratie voor een getal bijwerken

De verzoeken om informatie weergeven

Een aanvraag voor informatie bijwerken

Alle nummers weergeven die aan een account zijn toegewezen

Alle locaties voor noodgevallen voor een specifiek account weergeven

Een nummer uit het account verwijderen

Problemen oplossen

Volgende stappen

Aanvullende resources