Azure Communication Phone Numbers-Clientbibliothek für Java– Version 1.1.7

Artikel
10/21/2023

Das Telefonnummernpaket bietet Funktionen für die Verwaltung von Telefonnummern.

Erworbene Telefonnummern können je nach Land, Nummerntyp und Telefonplan viele Funktionen enthalten. Beispiele für Funktionen sind die ein- und ausgehende SMS-Nutzung, das Aufrufen der eingehenden und ausgehenden Nutzung. Telefonnummern können einem Bot auch über eine Webhook-URL zugewiesen werden.

Quellcode | Paket (Maven) | API-Referenzdokumentation | Produktdokumentation

Erste Schritte

Voraussetzungen

Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
Java Development Kit (JDK), Version 8 oder höher.
Apache Maven.
Eine bereitgestellte Communication Services-Ressource. Sie können das Azure-Portal oder die Azure PowerShell zum Einrichten verwenden.

Einschließen des Pakets

BOM-Datei einfügen

Fügen Sie azure-sdk-bom in Ihr Projekt ein, um von der Allgemeinverfügbarkeitsversion der Bibliothek abhängig zu sein. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur BOM finden Sie in der INFODATEI FÜR AZURE SDK-STÜCKLISTEN.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

und fügen Sie dann die direkte Abhängigkeit ohne Versions-Tag in den Abschnitt „Abhängigkeit“ ein.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-phonenumbers</artifactId>
  </dependency>
</dependencies>

Direkte Abhängigkeiten einfügen

Wenn Sie eine Abhängigkeit von einer bestimmten Version der Bibliothek annehmen möchten, die nicht in der BoM vorhanden ist, fügen Sie die direkte Abhängigkeit wie folgt zu Ihrem Projekt hinzu.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-communication-phonenumbers</artifactId>
  <version>1.1.7</version>
</dependency>

Wichtige Begriffe

Dieses SDK bietet Funktionen zum einfachen Verwalten direct offer von Und direct routing Zahlen.

Die direct offer Zahlen sind in zwei Arten verfügbar: geografisch und gebührenfrei. Geografische Telefonpläne sind Telefonpläne, die einem Standort zugeordnet sind, dessen Telefonnummern mit der Ortsvorwahl eines geografischen Standorts verknüpft sind. Toll-Free Telefontarife sind Telefonpläne, die nicht dem Standort zugeordnet sind. In den USA können beispielsweise gebührenfreie Nummern mit Ortsvorwahlen wie 800 oder 888 kommen. Sie werden mithilfe der PhoneNumbersClient

Das direct routing Feature ermöglicht das Verbinden Ihrer vorhandenen Telefonieinfrastruktur mit ACS. Die Konfiguration wird mithilfe von SipRoutingClientverwaltet, das Methoden zum Einrichten von SIP-Trunks und VoIP-Routingregeln bereitstellt, um Anrufe für Ihr Telefonsubnetz ordnungsgemäß zu verarbeiten.

Initialisieren des Clients

Clients können mithilfe der Azure Active Directory-Authentifizierung initialisiert werden.

// You can find your endpoint and access key from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

PhoneNumbersClient phoneNumberClient = new PhoneNumbersClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .httpClient(httpClient)
    .buildClient();

// You can find your endpoint and access key from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

SipRoutingClient sipRoutingClient = new SipRoutingClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .httpClient(httpClient)
    .buildClient();

Die Verwendung des Endpunkts und des Zugriffsschlüssels aus der Kommunikationsressource zur Authentifizierung ist ebenfalls möglich.

// You can find your endpoint and access token from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
AzureKeyCredential keyCredential = new AzureKeyCredential("SECRET");

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

PhoneNumbersClient phoneNumberClient = new PhoneNumbersClientBuilder()
    .endpoint(endpoint)
    .credential(keyCredential)
    .httpClient(httpClient)
    .buildClient();

// You can find your endpoint and access token from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
AzureKeyCredential keyCredential = new AzureKeyCredential("SECRET");

// Create an HttpClient builder of your choice and customize it
HttpClient httpClient = new NettyAsyncHttpClientBuilder().build();

SipRoutingClient sipRoutingClient = new SipRoutingClientBuilder()
    .endpoint(endpoint)
    .credential(keyCredential)
    .httpClient(httpClient)
    .buildClient();

Alternativ können Sie den gesamten Verbindungszeichenfolge mithilfe der connectionString()-Funktion des Clients bereitstellen, anstatt den Endpunkt und den Zugriffsschlüssel bereitzustellen.

Telefonnummern-Client

Übersicht über Telefonnummerntypen

Telefonnummern gibt es in zwei Arten; Geografisch und gebührenfrei. Geografische Telefonpläne sind Telefonpläne, die einem Standort zugeordnet sind, dessen Telefonnummern mit der Ortsvorwahl eines geografischen Standorts verknüpft sind. Toll-Free Telefontarife sind Telefonpläne, die nicht dem Standort zugeordnet sind. In den USA können beispielsweise gebührenfreie Nummern mit Ortsvorwahlen wie 800 oder 888 kommen.

Suchen und Kaufen und Freigeben von Nummern

Telefonnummern können über die Sucherstellungs-API durchsucht werden, indem eine Ortsvorwahl, anzahl von Telefonnummern, Anwendungstyp, Telefonnummerntyp und Funktionen angegeben werden. Die angegebene Anzahl von Telefonnummern wird für zehn Minuten reserviert und kann innerhalb dieser Zeit erworben werden. Wenn die Suche nicht gekauft wird, werden die Telefonnummern nach zehn Minuten für andere Personen verfügbar. Wenn die Suche erworben wird, werden die Telefonnummern für die Azure-Ressourcen erworben.

Telefonnummern können auch mithilfe der Release-API veröffentlicht werden.

SIP-Routingclient

Das Feature "Direct Routing" ermöglicht das Verbinden der vom Kunden bereitgestellten Telefonieinfrastruktur mit Azure Communication Resources. Um die Routingkonfiguration ordnungsgemäß einzurichten, muss der Kunde die SIP-Trunkkonfiguration und SIP-Routingregeln für Anrufe angeben. Der SIP-Routingclient stellt die erforderliche Schnittstelle zum Festlegen dieser Konfiguration bereit.

Wenn der Anruf eingeht, versucht das System, die Zielnummer mit regex-Nummernmustern von definierten Routen abzugleichen. Die erste Route, die mit der Nummer übereinstimmt, wird ausgewählt. Die Reihenfolge des RegEx-Abgleichs ist identisch mit der Reihenfolge der Routen in der Konfiguration, daher ist die Reihenfolge der Routen wichtig. Sobald eine Route abgeglichen wurde, wird der Anruf an den ersten Trunk in der Trunkliste der Route weitergeleitet. Wenn der Trunk nicht verfügbar ist, wird der nächste Trunk in der Liste ausgewählt.

Beispiele

PhoneNumbersClient

Erworbene Telefonnummer abrufen

Ruft die angegebene erworbene Telefonnummer ab.

PurchasedPhoneNumber phoneNumber = phoneNumberClient.getPurchasedPhoneNumber("+18001234567");
System.out.println("Phone Number Value: " + phoneNumber.getPhoneNumber());
System.out.println("Phone Number Country Code: " + phoneNumber.getCountryCode());

Abrufen aller erworbenen Telefonnummern

Listet alle erworbenen Telefonnummern auf.

PagedIterable<PurchasedPhoneNumber> phoneNumbers = createPhoneNumberClient().listPurchasedPhoneNumbers(Context.NONE);
PurchasedPhoneNumber phoneNumber = phoneNumbers.iterator().next();
System.out.println("Phone Number Value: " + phoneNumber.getPhoneNumber());
System.out.println("Phone Number Country Code: " + phoneNumber.getCountryCode());

Vorgänge mit langer Ausführungsdauer

Der Telefonnummernclient unterstützt eine Vielzahl von Vorgängen mit langer Ausführungsdauer, die eine unbegrenzte Abrufzeit für die unten aufgeführten Funktionen ermöglichen.

Suchen nach verfügbaren Telefonnummern

Suchen Sie nach verfügbaren Telefonnummern, indem Sie die Ortsvorwahl, den Zuweisungstyp, die Telefonnummernfunktionen, den Telefonnummerntyp und die Menge angeben. Das Ergebnis der Suche kann dann verwendet werden, um die Nummern zu erwerben. Beachten Sie, dass die Angabe der Vorwahl für gebührenfreie Telefonnummern nicht zwingend ist.

PhoneNumbersClient phoneNumberClient = createPhoneNumberClient();
PhoneNumberCapabilities capabilities = new PhoneNumberCapabilities()
    .setCalling(PhoneNumberCapabilityType.INBOUND)
    .setSms(PhoneNumberCapabilityType.INBOUND_OUTBOUND);
PhoneNumberSearchOptions searchOptions = new PhoneNumberSearchOptions().setAreaCode("800").setQuantity(1);

SyncPoller<PhoneNumberOperation, PhoneNumberSearchResult> poller = phoneNumberClient
    .beginSearchAvailablePhoneNumbers("US", PhoneNumberType.TOLL_FREE, PhoneNumberAssignmentType.APPLICATION, capabilities, searchOptions, Context.NONE);
PollResponse<PhoneNumberOperation> response = poller.waitForCompletion();
String searchId = "";

if (LongRunningOperationStatus.SUCCESSFULLY_COMPLETED == response.getStatus()) {
    PhoneNumberSearchResult searchResult = poller.getFinalResult();
    searchId = searchResult.getSearchId();
    System.out.println("Searched phone numbers: " + searchResult.getPhoneNumbers());
    System.out.println("Search expires by: " + searchResult.getSearchExpiresBy());
    System.out.println("Phone number costs:" + searchResult.getCost().getAmount());
}

Kaufen von Telefonnummern

Das Ergebnis der Suche nach Telefonnummern ist ein PhoneNumberSearchResult. Dies kann verwendet werden, um die Details der Nummern und Einkaufsnummern abzurufen, indem sie an searchId die Einkaufsnummern-API übergeben.

PollResponse<PhoneNumberOperation> purchaseResponse =
    phoneNumberClient.beginPurchasePhoneNumbers(searchId, Context.NONE).waitForCompletion();
System.out.println("Purchase phone numbers is complete: " + purchaseResponse.getStatus());

Freigeben einer Telefonnummer

Gibt eine erworbene Telefonnummer frei.

PollResponse<PhoneNumberOperation> releaseResponse =
    phoneNumberClient.beginReleasePhoneNumber("+18001234567", Context.NONE).waitForCompletion();
System.out.println("Release phone number is complete: " + releaseResponse.getStatus());

Aktualisieren von Telefonnummernfunktionen

Updates Telefonnummernfunktionen für Anrufe und SMS an eine von:

PhoneNumberCapabilityValue.NONE
PhoneNumberCapabilityValue.INBOUND
PhoneNumberCapabilityValue.OUTBOUND
PhoneNumberCapabilityValue.INBOUND_OUTBOUND

PhoneNumberCapabilities capabilities = new PhoneNumberCapabilities();
capabilities
    .setCalling(PhoneNumberCapabilityType.INBOUND)
    .setSms(PhoneNumberCapabilityType.INBOUND_OUTBOUND);

SyncPoller<PhoneNumberOperation, PurchasedPhoneNumber> poller = phoneNumberClient.beginUpdatePhoneNumberCapabilities("+18001234567", capabilities, Context.NONE);
PollResponse<PhoneNumberOperation> response = poller.waitForCompletion();

if (LongRunningOperationStatus.SUCCESSFULLY_COMPLETED == response.getStatus()) {
    PurchasedPhoneNumber phoneNumber = poller.getFinalResult();
    System.out.println("Phone Number Calling capabilities: " + phoneNumber.getCapabilities().getCalling()); //Phone Number Calling capabilities: inbound
    System.out.println("Phone Number SMS capabilities: " + phoneNumber.getCapabilities().getSms()); //Phone Number SMS capabilities: inbound+outbound
}

SipRoutingClient

Abrufen von SIP-Trunks und -Routen

Rufen Sie die Liste der derzeit konfigurierten Trunks oder Routen ab.

PagedIterable<SipTrunk> trunks = sipRoutingClient.listTrunks();
PagedIterable<SipTrunkRoute> routes = sipRoutingClient.listRoutes();
for (SipTrunk trunk : trunks) {
    System.out.println("Trunk " + trunk.getFqdn() + ":" + trunk.getSipSignalingPort());
}
for (SipTrunkRoute route : routes) {
    System.out.println("Route name: " + route.getName());
    System.out.println("Route description: " + route.getDescription());
    System.out.println("Route number pattern: " + route.getNumberPattern());
    System.out.println("Route trunks: " + String.join(",", route.getTrunks()));
}

Ersetzen von SIP-Trunks und -Routen

Ersetzen Sie die Liste der aktuell konfigurierten Trunks oder Routen durch neue Werte.

sipRoutingClient.setTrunks(asList(
    new SipTrunk("<first trunk fqdn>", 12345),
    new SipTrunk("<second trunk fqdn>", 23456)
));
sipRoutingClient.setRoutes(asList(
    new SipTrunkRoute("route name1", ".*9").setTrunks(asList("<first trunk fqdn>", "<second trunk fqdn>")),
    new SipTrunkRoute("route name2", ".*").setTrunks(asList("<second trunk fqdn>"))
));

Abrufen eines einzelnen Trunks

String fqdn = "<trunk fqdn>";
SipTrunk trunk = sipRoutingClient.getTrunk(fqdn);
if (trunk != null) {
    System.out.println("Trunk " + trunk.getFqdn() + ":" + trunk.getSipSignalingPort());
} else {
    System.out.println("Trunk not found. " + fqdn);
}

Festlegen eines einzelnen Trunks

sipRoutingClient.setTrunk(new SipTrunk("<trunk fqdn>", 12345));

Löschen eines einzelnen Trunks

sipRoutingClient.deleteTrunk("<trunk fqdn>");

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Für die meisten Beiträge ist die Zustimmung zu einer Lizenzvereinbarung für Mitwirkende (Contributor License Agreement, CLA) erforderlich, in der Sie erklären, dass Sie dazu berechtigt sind, uns die Rechte für die Nutzung Ihres Beitrags zu erteilen, und dies auch tun.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Problembehandlung

Läuft.

Nächste Schritte

Sehen Sie sich andere Clientbibliotheken für den Azure-Kommunikationsdienst an.

Aufrufe

Freigeben über