Java REST SDK 開発者ガイド (プレビュー)

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

Azure Maps Java SDK は、マップ関連のアプリケーションや位置情報認識アプリケーションを構築するために、Java アプリケーションやライブラリと統合できます。 Azure Maps Java SDK には、Search、Route、Render、Geolocation、Traffic、Timezone、Weather などの API が含まれています。これらの API は、アドレスの検索、異なる座標間のルーティング、特定の IP アドレスの地理的位置の取得などの操作をサポートします。

Note

Azure Maps Java SDK は Java 8 を基盤としており、最新の Java 長期サポートリリース (現在は Java 18) までテストと進展がサポートされます。ダウンロードできる Java バージョンの一覧については、Java Standard バージョンに関するページを参照してください。

前提条件

Azure Maps アカウント
サブスクリプションキーまたはその他の形式の認証
Java バージョン 8 以降
Maven (任意のバージョン)。詳細については、「Azure SDK と Apache Maven の概要」を参照してください。

ヒント

Azure Maps アカウントはプログラムで作成できます。Azure CLI を使用した例を次に示します。

az maps account create --kind "Gen2" --account-name "myMapAccountName" --resource-group "<resource group>" --sku "G2"

Maven プロジェクトを作成する

次の PowerShell コードスニペットは、PowerShell を使用して Maven プロジェクトを作成する方法を示しています。最初に、Maven コマンドを実行して Maven プロジェクトを作成します。

mvn archetype:generate "-DgroupId=groupId" "-DartifactId=DemoProject" "-DarchetypeArtifactId=maven-archetype-quickstart" "-DarchetypeVersion=1.4" "-DinteractiveMode=false"

パラメーター	説明
`-DGroupId`	グループ ID は、すべてのプロジェクト間でプロジェクトを一意に識別します
`-DartifactId`	プロジェクト名。これは、新しいフォルダーとして作成されます。
`-DarchetypeArtifactId`	プロジェクトの種類。 `maven-archetype-quickstart` により、サンプルプロジェクトが作成されます。
`-DinteractiveMode`	`false` に設定すると、既定のオプションを使用して空の Java プロジェクトが作成されます。

パッケージのインストール

Azure Maps Java SDK を使用するには、必要なすべてのパッケージをインストールする必要があります。 Azure Maps の各サービスは、専用のパッケージで入手できます。 Azure Maps サービスには、Search、Render、Traffic、Weather などが含まれます。インストールする必要があるのは、プロジェクトで使用される 1 つまたは複数のサービスのパッケージだけです。

Maven プロジェクトが作成されると、グループ ID、名前、成果物 ID などの基本情報を含む pom.xml ファイルが存在するはずです。次に、次の例で示されているように、各 Azure Maps サービスの依存関係を追加します。

<dependency> 
  <groupId>com.azure</groupId> 
  <artifactId>azure-maps-search</artifactId> 
  <version>1.0.0-beta.1</version> 
</dependency> 
<dependency> 
  <groupId>com.azure</groupId> 
  <artifactId>azure-maps-route</artifactId> 
  <version>1.0.0-beta.1</version> 
</dependency> 
<dependency> 
  <groupId>com.azure</groupId> 
  <artifactId>azure-maps-render</artifactId> 
  <version>1.0.0-beta.1</version> 
</dependency> 
<dependency> 
  <groupId>com.azure</groupId> 
  <artifactId>azure-maps-traffic</artifactId> 
  <version>1.0.0-beta.1</version> 
</dependency> 
<dependency> 
  <groupId>com.azure</groupId> 
  <artifactId>azure-maps-weather</artifactId> 
  <version>1.0.0-beta.1</version> 
</dependency> 
<dependency> 
  <groupId>com.azure</groupId> 
  <artifactId>azure-maps-timezone</artifactId> 
  <version>1.0.0-beta.1</version> 
</dependency>

プロジェクトで mvn clean install を実行し、demo.java という名前の Java ファイルを作成し、Azure Maps からそのファイルに必要な情報をインポートします。

cd DemoProject
New-Item demo.java

ヒント

mvn clean install を実行するとエラーが発生する場合、mvn clean install -U を実行してみてください。

Azure Maps サービス

[サービス名]	Maven パッケージ	サンプル
検索する	azure-maps-search	検索サンプル
ルーティング	azure-maps-routing	ルーティングサンプル
レンダリング	azure-maps-rendering	レンダリングサンプル
位置情報	azure-maps-geolocation	位置情報サンプル
タイムゾーン	azure-maps-timezone	timezone samples

MapsSearchClient の作成と認証

Azure Maps Search API へのアクセスに使用されるクライアントオブジェクトとして、Azure Maps サブスクリプションキーを使用して認証する場合には AzureKeyCredential オブジェクトが必要であり、Microsoft Entra ID を使用して認証する場合には TokenCredential オブジェクトと Azure Maps クライアント ID が必要です。認証の詳細については、「Azure Maps による認証」を参照してください。

Microsoft Entra 資格情報の使用

Azure ID ライブラリを使用して、Microsoft Entra ID で認証できます。 DefaultAzureCredential プロバイダーを使用するには、pom.xml ファイル内に mvn 依存関係を追加する必要があります。

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-identity</artifactId>
</dependency>

新しい Microsoft Entra アプリケーションを登録し、サービスプリンシパルに必要なロールを割り当てることによって Azure Maps へのアクセス権を付与する必要があります。詳細については、「Azure 以外のリソースでデーモンをホストする」を参照してください。アプリケーション (クライアント) ID、ディレクトリ (テナント) ID、クライアントシークレットが返されます。これらの値をコピーし、安全な場所に保存します。これらは、次の手順で必要になります。

次のように、Microsoft Entra アプリケーションのアプリケーション (クライアント) ID、ディレクトリ (テナント) ID、クライアントシークレット、さらに Map リソースのクライアント ID の値を環境変数として設定します。

環境変数	説明
AZURE_CLIENT_ID	登録したアプリケーションのアプリケーション (クライアント) ID
AZURE_CLIENT_SECRET	登録したアプリケーションのクライアントシークレットの値
AZURE_TENANT_ID	登録したアプリケーションのディレクトリ (テナント) ID
MAPS_CLIENT_ID	Azure Map アカウントのクライアント ID

次のように、PowerShell で環境変数を作成して、これらの値を保存できるようになりました。

$Env:AZURE_CLIENT_ID="<client-id>"
A$Env:AZURE_CLIENT_SECRET="<client-secret>"
$Env:AZURE_TENANT_ID="<tenant-id>"
$Env:MAPS_CLIENT_ID="<maps-client-id>"

環境変数を設定した後、次のようにプログラムでこれらの変数を使用して AzureMapsSearch クライアントをインスタンス化できます。

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.maps.search.MapsSearchClient;
import com.azure.maps.search.MapsSearchClientBuilder;

public class Demo {
    public static void main( String[] args) {
        MapsSearchClientBuilder builder = new MapsSearchClientBuilder();
        DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
        builder.credential(tokenCredential);
        builder.mapsClientId(System.getenv("MAPS_CLIENT_ID"));
        MapsSearchClient client = builder.buildClient();
    }
}

重要

前のコードスニペットで作成されたその他の環境変数は、このコードサンプルでは使用されていませんが、DefaultAzureCredential() で必要になります。同じ名前付け規則を使用してこれらの環境変数を正しく設定しないと、実行時エラーが発生します。たとえば、AZURE_CLIENT_ID が見つからないか無効な場合は、InvalidAuthenticationTokenTenant エラーが発生します。

サブスクリプションキー資格情報の使用

Azure Maps サブスクリプションキーを使用して認証できます。以下のスクリーンショットに示されているように、サブスクリプションキーは Azure Maps アカウントの [認証] セクションに表示されます。

次のように、PowerShell で環境変数を作成して、サブスクリプションキーを保存できるようになりました。

$Env:SUBSCRIPTION_KEY="<subscription-key>"

環境変数を作成したら、次のようにコードでアクセスできます。

import com.azure.core.credential.AzureKeyCredential;
import com.azure.maps.search.MapsSearchClient;
import com.azure.maps.search.MapsSearchClientBuilder;

public class Demo {
    public static void main( String[] args) {

        // Use Azure Maps subscription key authentication
        MapsSearchClientBuilder builder = new MapsSearchClientBuilder();
        AzureKeyCredential keyCredential = new AzureKeyCredential(System.getenv("SUBSCRIPTION_KEY"));
        builder.credential(keyCredential);
        MapsSearchClient client = builder.buildClient();
    }
}

エンティティのあいまい検索

次のコードスニペットは、単純なコンソールアプリケーションで azure-maps-search パッケージをインポートし、Seattle に近い "Starbucks" のあいまい検索を実行する方法を示しています。

import java.io.IOException;
import com.azure.core.credential.AzureKeyCredential;
import com.azure.core.models.GeoPosition;
// Enable the 2 imports below if you want to use AAD authentication 
// import com.azure.identity.DefaultAzureCredential;
// import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.maps.search.MapsSearchClient;
import com.azure.maps.search.MapsSearchClientBuilder;
import com.azure.maps.search.models.FuzzySearchOptions;
import com.azure.maps.search.models.SearchAddressResult;
import com.azure.maps.search.models.SearchAddressResultItem;

public class Demo {
    public static void main( String[] args) throws IOException {
    MapsSearchClientBuilder builder = new MapsSearchClientBuilder();
    
    // Instantiate with key credential. Get SUBSCRIPTION_KEY from environment variable: 
    AzureKeyCredential keyCredential = new AzureKeyCredential(System.getenv("SUBSCRIPTION_KEY"));
    builder.credential(keyCredential);
    
    // Or you can also instantiate with token credential: 
    // DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
    // builder.credential(tokenCredential);
    // builder.mapsClientId(System.getenv("MAPS_CLIENT_ID"));
    MapsSearchClient client = builder.buildClient();
    
    // Fuzzy search with options: 
    SearchAddressResult results = client.fuzzySearch(new FuzzySearchOptions("starbucks", new GeoPosition(-122.34255, 47.61010)));
    
    // Print the search results:
    for (SearchAddressResultItem item : results.getResults()) {
              MapsSearchAddress address = item.getAddress();
             GeoPosition coordinate = item.getPosition();
             System.out.format(
                 "* %s, %s\\n" +
                 "  %s %s %s\\n" +
                 "  Coordinate: (%.4f, %.4f)\\n",
                 address.getStreetNumber(), address.getStreetName(),
                 address.getMunicipality(), address.getCountryCode(), address.getPostalCode(),
                 coordinate.getLatitude(), coordinate.getLongitude());
        }
    }
}

このコードスニペットは、Azure 資格情報を使用して MapsSearchClient オブジェクトを作成する方法を示しています。最初に Azure Maps サブスクリプションキーを使用して AzureKeyCredential をインスタンス化し、次に資格情報を渡して MapsSearchClient をインスタンス化します。 FuzzySearch などの MapsSearchClient メソッドでは、目的地 (POI) 名 "Starbucks" と座標 GeoPosition(-122.31, 47.61) を使用できます。

コマンドラインでプロジェクトフォルダーからプログラムを実行します。

java .\demo.java

Starbucks アドレスと座標結果の一覧が表示されます。

* 1912, Pike Place
  Seattle US 98101
  Coordinate: (47.6102, -122.3425)
* 2118, Westlake Avenue
  Seattle US 98121
  Coordinate: (47.6173, -122.3378)
* 2601, Elliott Avenue
  Seattle US 98121
  Coordinate: (47.6143, -122.3526)
* 1730, Howell Street
  Seattle US 98101
  Coordinate: (47.6172, -122.3298)
* 220, 1st Avenue South
  Seattle US 98104
  Coordinate: (47.6003, -122.3338)
* 400, Occidental Avenue South
  Seattle US 98104
  Coordinate: (47.5991, -122.3328)
* 1600, East Olive Way
  Seattle US 98102
  Coordinate: (47.6195, -122.3251)
* 500, Mercer Street
  Seattle US 98109
  Coordinate: (47.6250, -122.3469)
* 505, 5Th Ave S
  Seattle US 98104
  Coordinate: (47.5977, -122.3285)
* 425, Queen Anne Avenue North
  Seattle US 98109
  Coordinate: (47.6230, -122.3571)

住所の検索

住所の座標を取得するには、SearchAddress メソッドを呼び出します。サンプルからの Main プログラムを次のように変更します。

import java.io.IOException;
import com.azure.core.credential.AzureKeyCredential;
import com.azure.core.models.GeoPosition;
// Enable the 2 imports below if you want to use AAD authentication 
// import com.azure.identity.DefaultAzureCredential;
// import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.maps.search.MapsSearchClient;
import com.azure.maps.search.MapsSearchClientBuilder;
import com.azure.maps.search.models.SearchAddressOptions;
import com.azure.maps.search.models.SearchAddressResult;
import com.azure.maps.search.models.SearchAddressResultItem;

public class Demo {
    public static void main( String[] args) throws IOException {
    MapsSearchClientBuilder builder = new MapsSearchClientBuilder();
    
    // Instantiate with key credential: 
    AzureKeyCredential keyCredential = new  
        AzureKeyCredential(System.getenv("SUBSCRIPTION_KEY"));
    builder.credential(keyCredential);
    
    // Or you can also instantiate with token credential: 
    // DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
    // builder.credential(tokenCredential);
    // builder.mapsClientId(System.getenv("MAPS_CLIENT_ID"));
    
    MapsSearchClient client = builder.buildClient();
    client.searchAddress(new SearchAddressOptions("15127 NE 24th Street, Redmond, WA 98052"));
    
    // Search address with options and return top 5 results: 
    SearchAddressResult results = client.searchAddress(new SearchAddressOptions("1  
        Main Street").setCoordinates(new GeoPosition(-74.011454,  
        40.706270)).setRadiusInMeters(40000).setTop(5));
    
    // Print results: 
    if (results.getResults().size() > 0) {
        SearchAddressResultItem item = results.getResults().get(0);
        System.out.format("The coordinates is (%.4f, %.4f)", 
            item.getPosition().getLatitude(), item.getPosition().getLongitude());
        }
    }
}

このサンプルでは、client.SearchAddress メソッドにより、信頼度スコアで並べ替えられた結果が返され、最初の結果の座標が出力されます。

バッチ逆引き検索

Azure Maps Search には、いくつかのバッチクエリメソッドも用意されています。これらのメソッドは、実行時間の長い操作 (LRO) オブジェクトを返します。要求のすべての結果がただちに返されない場合があるため、ユーザーは完了するまで待機するか、バッチ逆引き検索の方法で示されているように定期的に結果を照会するかを選択できます。

import java.util.ArrayList;
import java.util.List;
import com.azure.core.credential.AzureKeyCredential;
import com.azure.core.models.GeoPosition;
// Enable the 2 imports below if you want to use AAD authentication
// import com.azure.identity.DefaultAzureCredential;
// import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.maps.search.MapsSearchClient;
import com.azure.maps.search.MapsSearchClientBuilder;
import com.azure.maps.search.models.BatchReverseSearchResult;
import com.azure.maps.search.models.ReverseSearchAddressBatchItem;
import com.azure.maps.search.models.ReverseSearchAddressOptions;
import com.azure.maps.search.models.ReverseSearchAddressResultItem;

public class Demo{
    public static void main( String[] args) throws IOException {
        MapsSearchClientBuilder builder = new MapsSearchClientBuilder();
        
        // Instantiate with key credential:
        AzureKeyCredential keyCredential = new 
        AzureKeyCredential(System.getenv("SUBSCRIPTION_KEY"));
        builder.credential(keyCredential);
        
        // Or you can also instantiate with token credential: 
        // DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
        // builder.credential(tokenCredential);
        // builder.mapsClientId(System.getenv("MAPS_CLIENT_ID"));
        
        MapsSearchClient client = builder.buildClient();
        List<ReverseSearchAddressOptions> reverseOptionsList = new ArrayList<>();
        reverseOptionsList.add(new ReverseSearchAddressOptions(new GeoPosition(2.294911, 48.858561)));
        reverseOptionsList.add(new ReverseSearchAddressOptions(new GeoPosition(-122.34255, 47.61010)));
        reverseOptionsList.add(new ReverseSearchAddressOptions(new GeoPosition(-122.33817, 47.61559)).setRadiusInMeters(5000));
        BatchReverseSearchResult batchReverseSearchResult = 
        client.beginReverseSearchAddressBatch(reverseOptionsList).getFinalResult();
        for (ReverseSearchAddressBatchItem item : batchReverseSearchResult.getBatchItems()) {
            for (ReverseSearchAddressResultItem result : item.getResult().getAddresses()) {
                System.out.println(result.getAddress().getFreeformAddress());
            }
        }
    }
}

次の方法で共有

Java REST SDK 開発者ガイド (プレビュー)

前提条件

Maven プロジェクトを作成する

パッケージのインストール

Azure Maps サービス

MapsSearchClient の作成と認証

Microsoft Entra 資格情報の使用

サブスクリプションキー資格情報の使用

エンティティのあいまい検索

住所の検索

バッチ逆引き検索

フィードバック

その他のリソース

次の方法で共有

Java REST SDK 開発者ガイド (プレビュー)

前提条件

Maven プロジェクトを作成する

パッケージのインストール

Azure Maps サービス

MapsSearchClient の作成と認証

Microsoft Entra 資格情報の使用

サブスクリプション キー資格情報の使用

エンティティのあいまい検索

住所の検索

バッチ逆引き検索

フィードバック

その他のリソース

サブスクリプションキー資格情報の使用