Java 用 Azure Communication Phone Numbers クライアントライブラリ - バージョン 1.1.7

[アーティクル]
10/21/2023

電話番号パッケージは、電話番号管理の機能を提供します。

購入した電話番号には、国、番号の種類、電話プランに応じて、多くの機能が用意されています。機能の例としては、SMS の受信と送信の使用状況、受信と送信の使用状況の呼び出しがあります。電話番号は、Webhook URL を使用してボットに割り当てることもできます。

ソースコード | パッケージ (Maven) | API リファレンスドキュメント | 製品ドキュメント

作業の開始

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
Java Development Kit (JDK) バージョン 8 以降。
Apache Maven。
デプロイ済みの Communication Services リソース。 Azure Portal またはAzure PowerShellを使用して設定できます。

パッケージを組み込む

BOM ファイルを含める

ライブラリの一般提供 (GA) バージョンに依存するには、azure-sdk-bom をプロジェクトに含めてください。次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 BOM の詳細については、 AZURE SDK BOM README に関するページを参照してください。

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

次に、バージョンタグのない依存関係セクションに直接依存関係を含めます。

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

直接依存関係を含める

BOM に存在しない特定のバージョンのライブラリに依存する場合は、次のように直接依存関係をプロジェクトに追加します。

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

主要な概念

この SDK には、管理と数値を簡単に管理 direct offer するための機能が用意されています direct routing 。

番号には direct offer 、地域と無料の 2 種類があります。地理的な電話プランは、電話番号のエリアコードが地理的な場所のエリアコードに関連付けられている場所に関連付けられている電話プランです。 Toll-Free 電話プランは、電話プランに関連付けられていない場所です。たとえば、米国では、フリーダイヤル番号には 800 や 888 などの市区地区コードが付属しています。これらは、を使用して管理されます。 PhoneNumbersClient

この direct routing 機能により、既存のテレフォニーインフラストラクチャを ACS に接続できます。構成は、を SipRoutingClient使用して管理されます。これにより、テレフォニーサブネットの呼び出しを適切に処理するために、SIP トランクと音声ルーティング規則を設定する方法が提供されます。

クライアントの初期化

クライアントは、Azure Active Directory 認証を使用して初期化できます。

// 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();

通信リソースのエンドポイントとアクセスキーを使用して認証することもできます。

// 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();

または、エンドポイントとアクセスキーを指定する代わりに、クライアントの connectionString() 関数を使用して、接続文字列全体を指定することもできます。

電話番号クライアント

電話番号の種類の概要

電話番号は 2 種類あります。地理的および無料。地理的な電話プランは、電話番号のエリアコードが地理的な場所のエリアコードに関連付けられている場所に関連付けられている電話プランです。 Toll-Free 電話プランは、電話プランに関連付けられていない場所です。たとえば、米国では、フリーダイヤル番号には 800 や 888 などの市区地区コードが付属しています。

番号の検索と購入とリリース

電話番号は、エリアコード、電話番号の数量、アプリケーションの種類、電話番号の種類、機能を提供することで、検索作成 API を使用して検索できます。指定された電話番号の数量は 10 分間予約され、この時間内に購入できます。検索が購入されていない場合、電話番号は 10 分後に他のユーザーが利用できるようになります。検索が購入された場合、電話番号は Azure リソース用に購入されます。

電話番号は、リリース API を使用して解放することもできます。

SIP ルーティングクライアント

ダイレクトルーティング機能を使用すると、顧客が提供するテレフォニーインフラストラクチャを Azure Communication Resources に接続できます。ルーティング構成を適切に設定するには、お客様は、呼び出しの SIP トランク構成と SIP ルーティング規則を指定する必要があります。 SIP ルーティングクライアントは、この構成を設定するために必要なインターフェイスを提供します。

呼び出しが到着すると、システムは宛先番号と定義されたルートの正規表現番号パターンとの照合を試みます。番号に一致する最初のルートが選択されます。正規表現一致の順序は、構成でのルートの順序と同じであるため、ルートの順序が重要です。ルートが一致すると、コールはルートのトランクリストの最初のトランクにルーティングされます。トランクが使用できない場合は、リスト内の次のトランクが選択されます。

例

PhoneNumbersClient

購入した電話番号を取得する

指定した購入した電話番号を取得します。

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

購入したすべての電話番号を取得する

購入したすべての電話番号を一覧表示します。

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());

実行時間の長い操作

電話番号クライアントは、以下に示す関数に対する無期限のポーリング時間を可能にする、実行時間の長いさまざまな操作をサポートしています。

利用可能な電話番号を検索する

エリアコード、割り当ての種類、電話番号の機能、電話番号の種類、数量を指定して、使用可能な電話番号を検索します。検索の結果を使用して、数値を購入できます。ただし、電話番号の種類が無料電話番号の場合、市外局番の指定は任意です。

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());
}

電話番号を購入する

電話番号の検索の結果は PhoneNumberSearchResult です。これは、を購入番号 API に渡 searchId すことによって、番号の詳細と購入番号を取得するために使用できます。

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

電話番号を解放する

購入した電話番号を解放します。

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

電話番号機能の更新

通話と SMS の電話番号機能を次のいずれかに更新します。

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

SIP トランクとルートを取得する

現在構成されているトランクまたはルートの一覧を取得します。

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()));
}

SIP トランクとルートを置き換える

現在構成されているトランクまたはルートの一覧を新しい値に置き換えます。

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>"))
));

単一トランクを取得する

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

単一トランクを設定する

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

1 つのトランクを削除する

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

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

トラブルシューティング

進行中です。

次の手順

Azure 通信サービス用の他のクライアントライブラリを確認する

インプレッション数

次の方法で共有

Java 用 Azure Communication Phone Numbers クライアントライブラリ - バージョン 1.1.7

作業の開始

前提条件

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

主要な概念

クライアントの初期化

電話番号クライアント

電話番号の種類の概要

番号の検索と購入とリリース

SIP ルーティングクライアント

例

PhoneNumbersClient

購入した電話番号を取得する

購入したすべての電話番号を取得する

実行時間の長い操作

利用可能な電話番号を検索する

電話番号を購入する

電話番号を解放する

電話番号機能の更新

SipRoutingClient

SIP トランクとルートを取得する

SIP トランクとルートを置き換える

単一トランクを取得する

単一トランクを設定する

1 つのトランクを削除する

共同作成

トラブルシューティング

次の手順

フィードバック

その他のリソース

次の方法で共有

Java 用 Azure Communication Phone Numbers クライアント ライブラリ - バージョン 1.1.7

作業の開始

前提条件

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

主要な概念

クライアントの初期化

電話番号クライアント

電話番号の種類の概要

番号の検索と購入とリリース

SIP ルーティング クライアント

例

PhoneNumbersClient

購入した電話番号を取得する

購入したすべての電話番号を取得する

実行時間の長い操作

利用可能な電話番号を検索する

電話番号を購入する

電話番号を解放する

電話番号機能の更新

SipRoutingClient

SIP トランクとルートを取得する

SIP トランクとルートを置き換える

単一トランクを取得する

単一トランクを設定する

1 つのトランクを削除する

共同作成

トラブルシューティング

次の手順

フィードバック

その他のリソース

Java 用 Azure Communication Phone Numbers クライアントライブラリ - バージョン 1.1.7

SIP ルーティングクライアント