你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Java REST SDK 开发人员指南（预览版）

项目
10/19/2023

Azure Maps Java SDK 可与 Java 应用程序和库集成，以生成与地图相关的位置感知应用程序。 Azure Maps Java SDK 包含用于搜索、路线规划、呈现、地理定位、交通、时区和天气的 API。这些 API 支持搜索地址、在不同坐标之间规划路线、获取特定 IP 地址的地理位置等操作。

注意

Azure Maps Java SDK 以 Java 8 为基线，在最新 Java 长期支持版本（目前为 Java 18）推出之前可供测试并提供前向支持。有关可供下载的 Java 版本列表，请参阅 Java 标准版本。

先决条件

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 服务包括搜索、呈现、交通、天气等。只需安装你要在项目中使用的服务的包即可。

创建 maven 项目后，应会出现一个 pom.xml 文件，其中包含组 ID、名称、工件 ID 等基本信息。接下来，为每项 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 服务

Service name	Maven 包	示例
搜索	azure-maps-search	搜索示例
路由	azure-maps-routing	路由示例
呈现	azure-maps-rendering	呈现示例
地理位置	azure-maps-geolocation	地理位置示例
时区	azure-maps-timezone	时区示例

创建 MapsSearchClient 并对其进行身份验证

使用 Azure Maps 订阅密钥时，用于访问 Azure Maps 搜索 API 的客户端对象需要使用一个 AzureKeyCredential 对象进行身份验证；在使用 Microsoft Entra ID 进行身份验证时，它需要一个包含 Azure Maps 客户端 ID 的 TokenCredential 对象。有关身份验证的详细信息，请参阅向 Azure Maps 进行身份验证。

使用 Microsoft Entra 凭据

可以使用 Azure 标识库对 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 和客户端机密的值以及映射资源的客户端 ID 设置为环境变量：

环境变量	描述
AZURE_CLIENT_ID	已注册的应用程序中的应用程序（客户端）ID
AZURE_CLIENT_SECRET	已注册的应用程序中客户端密码的值
AZURE_TENANT_ID	已注册的应用程序中的目录（租户）ID
MAPS_CLIENT_ID	Azure Maps 帐户中的客户端 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 搜索还提供了一些批量查询方法。这些方法将返回长时间运行的操作 (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());
            }
        }
    }
}

通过