Bereitstellungs-API für Azure Communications Gateway

  • Artikel

Mit der Bereitstellungs-API von Azure Communications Gateway für Telekommunikationsbetreiber können Sie die Details Ihrer Kunden und die ihnen zugewiesenen Nummern in Azure Communications Gateway (ACG) bereitstellen. Die Bereitstellungs-API unterstützt auch die Flow-Through-Bereitstellung einiger Back-End-Kommunikationsdienste.

Die Bereitstellung von Kunden und Nummern ist (mit der Bereitstellungs-API oder dem browserbasierten Nummernverwaltungsportal) für alle Anwendungsfälle mit Ausnahme von Operator Connect und Teams Telefon Mobile obligatorisch. Für Operator Connect und Teams Telefon Mobile ist die Verwendung der Bereitstellungs-API und/oder des Nummernverwaltungsportals optional. Sie können stattdessen direkt in die Operator Connect-API integriert werden.

Erste Schritte

Voraussetzungen

  • Ein Mandant mit bereitgestellter Azure Communications Gateway-Anwendung.
  • Der vollqualifizierte Domänenname (Fully Qualified Domain Name, FQDN) für Ihr Azure Communications Gateway, der auf der Seite Übersicht für die Ressource im Azure-Portal angezeigt wird. Die API ist an Port 443 von provapi.<base-domain>verfügbar.
  • Ein Computer mit einer IP-Adresse, die den Zugriff auf die API ermöglicht, wie er im Rahmen der Bereitstellung von Azure Communications Gateway in einer Zulassungsliste konfiguriert ist.

Authentifizierung und Autorisierung

Die Bereitstellungs-API verwendet OAuth 2.0 , um den Zugriff auf Ressourcen zu steuern. Die Clientanwendung muss ein gültiges Authentifizierungs-Bearertoken abrufen, um auf die Bereitstellungs-API zuzugreifen. Das Bearertoken gibt an, dass die Anwendung für einen oder mehrere Bereiche (Rollen) für die Bereitstellungs-API autorisiert ist. Es wird empfohlen, den Clientanmeldeinformationen-Flow (für einen serverseitigen Prozess konzipiert) zu verwenden.

Die folgenden Bereiche sind für die Bereitstellungs-API verfügbar:

  • ProvisioningAPI.Admin: Möglichkeit, einen beliebigen Vorgang in der API aufzurufen.
  • ProvisioningAPI.Read: Möglichkeit zum Aufrufen eines beliebigen Lesevorgangs (GET) in der API.
  • ProvisioningAPI.Write: Möglichkeit, einen beliebigen Schreibvorgang (PUT, PATCH) in der API aufzurufen.
  • ProvisioningAPI.Delete: Möglichkeit, einen beliebigen Löschvorgang (DELETE) in der API aufzurufen.

So richten Sie einen Clientanmeldeinformationenflow ein:

  1. Stellen Sie sicher, dass Ihre Anwendung den Clientanmeldeinformationenflow unterstützen kann.

    • Wenn Ihre Anwendung ein Token für die Bereitstellungs-API anfordert, muss sie die folgenden Felder verwenden.

      Parameter Bedingung BESCHREIBUNG
      tenant required Der Verzeichnismandant, der das Azure Communications Gateway in guid- oder Domänennameform enthält.
      scope required Der Autorisierungsbereich für die Azure Communications Gateway-Ressourcen-ID. Für den hier beschriebenen Clientanmeldeinformationenflow sollte der Bereich sein https://func-voiceservice-rp-prod-eastuseuap.azurewebsites.net/.default.
      client_id Erforderlich Die Ihrer App zugewiesene Anwendungs-ID (Client-ID).

    • Der roles Anspruch im empfangenen Token gibt die Rollen (Bereiche) an, für die die Clientanwendung autorisiert ist.

    • Anforderungen an die Azure Communications Gateway Provisioning Platform müssen über einen Authorization Header mit diesem Bearertoken verfügen.

    • Beispiele für die Verwendung von Token finden Sie in der Dokumentation zum Ablauf von Clientanmeldeinformationen .

  2. Verwenden Sie die Azure-Portal, um die Anwendung im selben Mandanten wie Ihre Azure Communications Gateway-Bereitstellung zu registrieren. Siehe Schnellstart: Registrieren einer App im Microsoft Identity Platform – Microsoft Entra | Microsoft Learn.
  3. Weisen Sie sich als Besitzer für die App-Registrierung zu. Weitere Informationen finden Sie unter Zuweisen des Anwendungsbesitzers.
  4. Konfigurieren Sie die App-Registrierung, die durch Registrieren der Anwendung mit App-Rollen erstellt wird, die die Bereiche für die Bereitstellungs-API verwenden, wie weiter oben beschrieben.
    • Weitere Informationen finden Sie unter Zuweisen von App-Rollen zu Anwendungen.
    • Die API, für die Sie Berechtigungen zuweisen müssen, ist AzureCommunicationsGatewayunter APIs aufgeführt, die mein organization verwendet.
  5. Erlauben Sie als Administrator für den Mandanten, dass die Anwendung die app-Rollen verwendet, die Sie zugewiesen haben. Weitere Informationen finden Sie unter Erteilen der Administratoreinwilligung.

Die Bereitstellungs-API verwendet Standardmäßige Microsoft-Vertrauensketten für Sicherheitszertifikate.

Wichtige Begriffe

Die Bereitstellungsplattform verfügt über drei wichtige Ressourcen, die der Operator verwalten kann: Konten, Zahlen und Informationsanforderungen.

  • Kontoressourcen sind Beschreibungen von Operatorkunden (in der Regel ein Unternehmen) und kundenspezifische Einstellungen für die Dienstbereitstellung.
  • Zahlenressourcen gehören zu einem Konto. Sie beschreiben Zahlen, die Dienste (z. B. Microsoft Teams Direct Routing), die von den Zahlen verwendet werden, und jede zusätzliche Konfiguration pro Zahl.
  • Informationsanforderungsressourcen (Request for Information, RFI) sind Beschreibungen potenzieller Kunden für Betreiber, die ihr Interesse an einem Service vom Betreiber über bestimmte Back-End-Dienste zum Ausdruck bringen. Derzeit sind nur RFIs verfügbar, die von Operator Connect und Teams Telefon Mobile-Zustimmungen erstellt wurden.

Erstellen Sie beispielsweise eine Kontoressource mit der Bereitstellungs-API für Contoso, um einen Microsoft Teams Direct Routing-Dienst für einen Kunden bereitzustellen. Das Konto enthält eine Konfiguration für direct Routing (z. B. eine Unterdomäne und entsprechende Token, die zum Einrichten von DNS-Einträgen erforderlich sind, die Microsoft Teams zum Überprüfen der Konfiguration des Kunden verwenden kann). Anschließend müssen Sie dem Konto Nummernressourcen hinzufügen und jede Nummer für direct Routing aktivieren.

Tipp

Sie müssen den Dienst sowohl für das Konto als auch für die Nummern innerhalb des Kontos aktivieren.

Bereitstellen von Back-End-Diensten mit Back-End-Dienstsynchronisierung

Azure Communications Gateway muss Über Informationen zu den Nummern verfügen, für die es den Dienst bereitstellt, um Anrufe ordnungsgemäß verbinden zu können. Wir empfehlen die Bereitstellungs-API für Azure Communications Gateway, um diese Informationen für Azure Communications Gateway bereitzustellen, aber Sie können auch das Nummernverwaltungsportal verwenden. Die meisten Back-End-Dienste müssen auch mit Informationen zu den zu verwendenden Nummern und Konten bereitgestellt werden. Diese Anforderung bedeutet häufig, dass mehrere IT-Integrationsprojekte erforderlich sind, um neue Dienste zu ermöglichen. Die Azure Communications Gateway-Bereitstellungsplattform wurde in einige Back-End-Dienste vorintegriert, um sie für Sie bereitzustellen, wodurch Ihre IT-Integrationsanforderungen reduziert werden. Sie können diese Funktion verwenden, indem Sie die Back-End-Dienstsynchronisierung für die entsprechenden Dienste aktivieren. Dies bedeutet auch, dass jede IT-Integration in die Azure Communications Gateway-Bereitstellungsplattform für andere Back-End-Dienste wiederverwendbar ist.

Beispielsweise schreibt Operator Connect vor, dass alle Nummern über die Operator Connect-API hochgeladen werden. Wenn die Back-End-Dienstsynchronisierung für Operator Connect aktiviert ist, werden alle für Azure Communications Gateway bereitgestellten und für Operator Connect aktivierten Nummern automatisch in Operator Connect bereitgestellt, was bedeutet, dass Sie keine Integration in die Operator Connect-API benötigen.

Die Bereitstellung über die Azure Communications Gateway-Bereitstellungsplattform ist für einige Dienste optional, bei denen Azure Communications Gateway Informationen direkt aus dem Back-End abrufen kann. Einige Features wie das Hinzufügen von Kunden-SIP-Headern zu Abrechnungszwecken sind jedoch nicht verfügbar. Für Dienste, die die Back-End-Dienstsynchronisierung nicht unterstützen, ist möglicherweise eine andere IT-Integration direkt in den Back-End-Dienst erforderlich. Die status der Bereitstellungsunterstützung wird in der folgenden Tabelle beschrieben:

Back-End-Dienst Anforderung der Bereitstellung über ACG Provisioning Platform Bereitstellung des Back-End-Diensts unterstützt
Direct Routing Obligatorisch. ❌
Zoom Obligatorisch. ❌
Azure Operator Call Protection Obligatorisch. ❌
Telefonieanbieter Optional ✅
Teams Telefon Mobile Optional ✅

Die Synchronisierung mit Back-End-Diensten erfolgt asynchron, was bedeutet, dass Ihre Bereitstellungsanforderung möglicherweise erfolgreich ist, bevor der Back-End-Dienst bereitgestellt wurde. Dieser status wird in der API-Antwort mit dem auf pendingfestgelegten serviceProvisioningStatus Feld gekennzeichnet. Es wird empfohlen, das Objekt abzufragen, um dessen Bereitstellung status zu überprüfen, bis dieses Feld auf successfestgelegt ist. Alle Fehler bei der Bereitstellung des Back-End-Systems werden direkt in der Antwort zur Verfügung gestellt.

Beispiele

Die folgenden Beispiele zeigen Beispielanforderungen für die Verwaltung von RFIs, Konten und Zahlen.

Create ein Konto, das einen Kunden darstellt

Verwenden Sie PUT auf dem accounts/<accountName> Endpunkt, um ein Konto namens contoso für den Kunden Contoso zu erstellen und einen oder mehrere Kommunikationsdienste für das Konto zu konfigurieren. Verwenden Sie einen If-None-Match-Header, um zu überprüfen, ob noch keine Kontoressource mit diesem Namen vorhanden ist.

Siehe folgendes Beispiel:

  • Direct Routing ist konfiguriert.
  • Die Anrufer-ID-Überprüfung ist aktiviert (Standard).
  • Die Unterdomäne für den Kunden ist contoso.
  • Die vom Kunden bereitgestellten DNS TXT-Werte, die zum Einrichten von DNS-Einträgen benötigt werden, befinden sich in den region1Token Feldern und region2Token .

Anforderung:

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

Antwort:

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

Im folgenden Beispiel erstellen wir ein Konto nur für die Verwendung mit Teams Operator Connect, wobei die Back-End-Synchronisierung aktiviert ist, sodass Informationen zu diesem Konto (z. B. hochgeladene Zahlen) auch in Teams bereitgestellt werden:

Anforderung:

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

Antwort:

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

Anzeigen der Details des Kontos

Verwenden Sie GET auf dem accounts/<accountName> Endpunkt, um die Details des Kontos abzurufen. Die Antwort umfasst die folgenden Felder:

  • Alle Konfigurationen zuvor festgelegt (oder die Standardeinstellung, wenn ein Feld nicht festgelegt wurde).
  • Abonnentenanzahl für jeden der in ACG verfügbaren Dienste.
  • Der status der Back-End-Dienstbereitstellung, falls aktiviert.
  • subdomainStatus, die den Status der DNS-Datensatzbereitstellung darstellt und nur für direct Routing relevant ist.
  • Ein ETag Header, der den aktuellen Status des Kontos darstellt. Sie können den Wert in einem If-Match Header für nachfolgende Updateanforderungen verwenden, um sicherzustellen, dass Sie keine Änderungen überschreiben, die von anderen API-Benutzern vorgenommen wurden.

Anforderung:

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

Antwort:

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

Die entsprechende Anforderung, wenn für das Konto mehrere Dienste konfiguriert sind, wird wie folgt angezeigt:

Anforderung:

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

Antwort:

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

Aktualisieren der Konfiguration für das Konto

Verwenden Sie PUT auf dem accounts/<accountName> Endpunkt, um die Konfiguration für das Konto zu aktualisieren. Um sicherzustellen, dass das Update keine Von einem anderen Benutzer vorgenommene Änderung überschreibt, fügen Sie einen If-Match Header mit dem ETag aus der letzten Antwort für das Konto hinzu.

Anforderung:

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

Antwort:

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

Hinzufügen einer Nummer zum Konto

Verwenden Sie PUT auf dem account/<accountName>/numbers/<telephoneNumber> Endpunkt, um dem Konto eine Nummer hinzuzufügen, einen oder mehrere Kommunikationsdienste zu aktivieren und eine andere Konfiguration hinzuzufügen. Die ausgewählten Kommunikationsdienste müssen auch für das Konto konfiguriert werden. Verwenden Sie einen If-None-Match-Header, um zu überprüfen, ob noch keine Zahlenressource mit dieser Zahl vorhanden ist. Alle Zahlen müssen im E.164-Format erstellt werden.

Siehe folgendes Beispiel:

  • Die Zahl ist +123451.
  • Operator connect ist aktiviert.
  • Die zum Hochladen der Nummer in Operator Connect erforderliche Konfiguration wird bereitgestellt.
  • customSipHeader gibt an, dass Azure Communications Gateway einen Header mit dem Wert exampleHeaderContents zu Nachrichten hinzufügen soll, die an das Betreibernetzwerk gesendet werden. Der Name des Headers wird im Rahmen der Bereitstellung von Azure Communications Gateway festgelegt.
  • Das serviceProvisioningStatus Feld in der Antwort zeigt die status der Synchronisierung mit dem Back-End-Dienst an.
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"
  }
}

Antwort:

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

Überprüfen der Bereitstellung status nach einiger Zeit

Verwenden Sie GET für nach account/<accountName>/numbers/<telephoneNumber> einer Bereitstellungsaktion, um die status der Nummer zu überprüfen. Wenn die Nummer erfolgreich bereitgestellt wurde, wird das serviceProvisioningStatus Feld von in pendingsyncedaktualisiert.

Anforderung:

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

Antwort:

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

Fehler bei der Back-End-Dienstbereitstellung beim Hochladen einer Zahl

In diesem Beispiel tritt bei der Back-End-Bereitstellung beim Hochladen der Zahl ein Fehler auf, der in der Antwort wieder angezeigt wird. Fehlermeldungen werden transparent von Back-End-Diensten übergeben.

Hinweis

Bei der Bereitstellung einer Zahl wird pending zunächst status verwendet, die erneut abgefragt werden muss, um Erfolg/Fehler zu bestätigen.

Die ursprüngliche Anforderung, der ein Wert für das usage Feld fehlt:

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

Antwort der GET-Abfrage nach einiger Zeit:

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

Aktualisieren der Konfiguration für eine Zahl

Verwenden Sie PUT auf dem Endpunkt, um die account/<accountName>/numbers/<telephoneNumber> Konfiguration für eine Zahl zu aktualisieren. Um sicherzustellen, dass das Update keine Änderung überschreibt, die von einem anderen Benutzer vorgenommen wurde, fügen Sie einen If-Match-Header mit dem ETag aus der letzten Antwort für die Nummer hinzu.

Anforderung:

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

Antwort:

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

Auflisten der Informationsanforderungen

Verwenden Sie eine GET auf dem /teamsRequestsForInformation Endpunkt, um eine Liste der Teams-Zustimmungen abzurufen, die Ihnen von potenziellen Kunden übermittelt wurden.

Anforderung:

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

Antwort:

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

Aktualisieren einer Informationsanforderung

Verwenden Sie PATCH auf dem /teamsRequestsForInformation/<tenantID> Endpunkt, um die status der RFI zu aktualisieren, die im Back-End-Dienst widergespiegelt wird. Mit Operator Connect und Teams Telefon Mobile können Sie die status der Anforderung an den Endkunden zurückgeben, damit die aktualisierte status im Teams Admin Center des Kunden angezeigt wird.

Anforderung

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

Antwort

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

Auflisten aller Einem Konto zugewiesenen Nummern

Verwenden Sie eine GET-Anforderung für den /accounts/<accountName>/numbers Endpunkt, um eine Liste der Nummern abzurufen, die für dieses Konto bereitgestellt wurden.

Anforderung:

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

Antwort für ein Konto mit nur Operator Connect-Nummern:

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

Antwort für ein Konto mit bereitgestellten Operator Connect- und Direct Routing-Nummern:

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

Auflisten aller Notfallstandorte für ein bestimmtes Konto

Verwenden Sie eine GET-Anforderung für den /accounts/<accountName>/teamsCivicAddresses Endpunkt, um die vollständige Liste der Bürgeradressen abzurufen, die im Teams Admin Center für dieses Konto konfiguriert sind. Sie können die Auffüllung dieser Liste als die locationid verwenden, wenn Sie Nummern innerhalb des Kontos erstellen oder aktualisieren.

Anforderung:

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

Antwort:

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

Entfernen einer Nummer aus dem Konto

Verwenden Sie DELETE auf dem /accounts/<accountName>/numbers/<telephoneNumber> Endpunkt, um eine Nummer von einem Mandanten freizugeben. Dieser Vorgang hebt die Zuweisung einer Nummer von einem Benutzer auf, wenn sie zugewiesen ist, und gibt die Nummer dann vom Mandanten frei.

Anforderung:

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

Antwort:

204 Status Code

Problembehandlung

  • Direktes Routing von Teams funktioniert nicht für Zahlen in einem Konto.

    • Überprüfen Sie, ob das DNS-Token überprüft wurde, indem Sie ein GET für das Konto senden, das serviceDetails.teamsDirectRoutingsubdomainStatus gleich ist Provisioned.

  • Ich habe eine Zahl für die Verwendung von Direct Routing/Zoom konfiguriert, aber es scheint nicht zu funktionieren.

    • Vergewissern Sie sich, dass das Konto für die Verwendung von Direct Routing/Zoom konfiguriert wurde und dass für die Nummer dieses spezifische Feature aktiviert ist.

  • Ich habe es geschafft, die API zu kontaktieren, aber nach mehreren Anforderungen beginnen meine Verbindungen mit dem Timing.

    • Die Bereitstellungs-API ist ratenbeschränkt (auf eine angemessene Rate pro Sekunde). Stellen Sie Ihre Anforderungen auf, oder verwenden Sie den Batchendpunkt, um eine Ratenbegrenzung zu vermeiden. Das Ratenlimit kann schließlich zu einem Zeitlimit führen, und Sie können eine Verbindung herstellen.

Nächste Schritte

Beginnen Sie mit der Integration in die Bereitstellungs-API für Azure Communications Gateway.