Java REST SDK 開發人員指南 (預覽)

發行項
03/20/2024

Azure 地圖服務 Java SDK 可以整合 Java 應用程式和程式庫，以建置地圖相關和位置感知應用程式。 Azure 地圖服務 Java SDK 包含搜尋、路線、轉譯、地理位置、交通、時區和天氣的 API。這些 API 支援搜尋地址、不同座標之間的路線、取得特定 IP 位址的地理位置等作業。

注意

Azure 地圖服務 Java SDK 是以 Java 8 為基準，持續測試並轉送支援，直到最新的 Java 長期支援版本 (目前為 Java 18)。如需下載的 Java 版本清單，請參閱 Java 標準版本。

必要條件

Azure 地圖服務帳戶
訂用帳戶金鑰或其他形式的驗證
Java 第 8 版或更新版本
Maven (任何版本)。如需詳細資訊，請參閱開始使用 Azure SDK 和 Apache Maven。

提示

您可以透過程式設計方式建立 Azure 地圖服務帳戶，以下是使用 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`	群組識別碼可以在所有專案上唯一識別您的專案
`-DartifactId`	專案名稱。它會建立為新資料夾。
`-DarchetypeArtifactId`	專案類型。 `maven-archetype-quickstart` 會建立範例專案。
`-DinteractiveMode`	設定為 `false` 會建立含有預設選項的空白 Java 專案。

安裝套件

若要使用 Azure 地圖服務 Java SDK，您必須安裝所有必要套件。 Azure 地圖服務中的每個服務都可在各自的套件中取得。 Azure 地圖服務包括搜尋、轉譯、交通、天氣等。您只需要安裝專案所使用服務的適用套件即可。

建立 maven 專案之後，應該會有一個含有基本資訊 (例如群組識別碼、名稱、成品識別碼) 的 pom.xml 檔案。接下來，為每個 Azure 地圖服務新增相依性，如下列範例所示：

<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 地圖服務匯入檔案：

cd DemoProject
New-Item demo.java

提示

如果執行 mvn clean install 會導致錯誤，請試著執行 mvn clean install -U。

Azure 地圖服務

服務名稱	Maven 套件	範例
Search	azure-maps-search (英文)	搜尋樣本 (英文)
路由	azure-maps-routing (英文)	路由樣本 (英文)
轉譯	azure-maps-rendering (英文)	轉譯樣本 (英文)
地理位置	azure-maps-geolocation (英文)	地理位置樣本 (英文)
時區	azure-maps-timezone	時區樣本 (英文)

建立及驗證 MapsSearchClient

用來存取 Azure 地圖服務搜尋 API 的用戶端物件在使用 Azure 地圖服務訂用帳戶金鑰時，需要 AzureKeyCredential 物件來進行驗證，或在使用 Microsoft Entra ID 進行驗證時，需要具有 Azure 地圖服務用戶端識別碼的 TokenCredential 物件。如需關於驗證的詳細資訊，請參閱驗證 Azure 地圖服務。

使用 Microsoft Entra 認證

您可以使用 Azure 身分識別程式庫向 Microsoft Entra ID 進行驗證。若要使用 DefaultAzureCredential 提供者，您必須在 pom.xml 檔案中新增 mvn 相依性：

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

您必須註冊新的 Microsoft Entra 應用程式，並將所需的角色指派給服務主體，以授與對 Azure 地圖服務的存取權。如需詳細資訊，請參閱在非 Azure 資源上裝載精靈。系統會傳回應用程式 (用戶端) 識別碼、目錄 (租用戶) 識別碼，以及用戶端密碼。複製這些值，並將其儲存在安全的地方。在下列步驟中，您會需要用到這些資料。

將應用程式 (用戶端) 識別碼、目錄 (租用戶) 識別碼和 Microsoft Entra 應用程式用戶端密碼的值，以及地圖資源的用戶端識別碼的值設定為環境變數：

環境變數	描述
AZURE_CLIENT_ID	已註冊應用程式中的應用程式 (用戶端) 識別碼
AZURE_CLIENT_SECRET	已註冊應用程式中用戶端密碼的值
AZURE_TENANT_ID	已註冊應用程式中的目錄 (租用戶) 識別碼
MAPS_CLIENT_ID	Azure 地圖服務帳戶中的用戶端識別碼

現在您可以在 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 地圖服務訂用帳戶金鑰進行驗證。您可以在 Azure 地圖服務帳戶的 [驗證] 區段中找到您的訂用帳戶金鑰，如下列螢幕擷取畫面所示：

現在您可以在 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 套件，並執行西雅圖附近「星巴克」的模糊搜尋：

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 地圖服務訂用帳戶金鑰將 AzureKeyCredential 執行個體化，然後傳遞認證以建立 MapsSearchClient 執行個體。 MapsSearchClient 方法 (例如 FuzzySearch) 可以使用興趣點 (POI) 名稱「星巴克」，並設定座標 GeoPosition (-122.31,47.61)。

在命令列中，從專案資料夾執行程式：

java .\demo.java

您應該會看到一份星巴克地址與座標結果的清單：

* 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 地圖服務搜尋也會提供一些批次查詢方法。這些方法會傳回長時間執行作業 (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());
            }
        }
    }
}

共用方式為