Příručka pro vývojáře Java REST SDK (náhled)

Sadu Azure Maps Java SDK je možné integrovat s aplikacemi a knihovnami v Javě a vytvářet aplikace související s mapami a aplikacemi pracujícími s umístěním. Sada Azure Maps Java SDK obsahuje rozhraní API pro vyhledávání, trasu, vykreslení, geografickou polohu, provoz, časové pásmo a počasí. Tato rozhraní API podporují operace, jako je hledání adresy, směrování mezi různými souřadnicemi, získání geografického umístění konkrétní IP adresy atd.

Poznámka:

SDK Azure Maps pro Javu je založené na Javě 8, s testováním a podporou do budoucna až do nejnovějšího vydání s dlouhodobou podporou Javy (aktuálně Java 18). Seznam verzí Javy ke stažení najdete v tématu Standardní verze Javy.

Požadavky

Účet Azure Maps
Klíč předplatného nebo jiná forma ověřování
Java verze 8 nebo novější
Maven (libovolná verze). Další informace najdete v tématu Začínáme se sadou Azure SDK a Apache Mavenem.

Návod

Účet Azure Maps můžete vytvořit programově. Tady je příklad s využitím Azure CLI:

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

Vytvoření projektu Maven

Následující fragment kódu PowerShellu ukazuje, jak pomocí PowerShellu vytvořit projekt Maven. Nejprve spuštěním příkazu maven vytvořte projekt Maven:

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

Parametr	Popis
`-DGroupId`	ID skupiny jednoznačně identifikuje váš projekt ve všech projektech.
`-DartifactId`	Název projektu. Vytvoří se jako nová složka.
`-DarchetypeArtifactId`	typ projektu. `maven-archetype-quickstart` výsledky v ukázkovém projektu.
`-DinteractiveMode`	Nastavení na `false` má za následek prázdný projekt v Javě s výchozími možnostmi.

Instalace balíčků

Pokud chcete použít sadu Azure Maps Java SDK, musíte nainstalovat všechny požadované balíčky. Každá služba v Azure Maps je k dispozici ve vlastním balíčku. Mezi služby Azure Maps patří Search, Render, Traffic, Weather atd. Balíčky pro službu nebo služby používané v projektu potřebujete jenom nainstalovat.

Po vytvoření projektu Maven by měl existovat pom.xml soubor se základními informacemi, jako je ID skupiny, název, ID artefaktu. Dále přidejte závislost pro každou ze služeb Azure Maps, jak ukazuje následující příklad:

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

Spusťte mvn clean install projekt a pak vytvořte soubor Java s názvem demo.java a naimportujte do souboru to, co potřebujete, z Azure Maps:

cd DemoProject
New-Item demo.java

Návod

Pokud výsledkem spuštění mvn clean install je chyba, zkuste spustit mvn clean install -U.

Služby Azure Maps

Název služby	Balíček Maven	Vzorky
Hledat	azure-maps-search	ukázky hledání
Směrování	azure-maps-routing	směrovací ukázky
Vykreslování	azure-maps-rendering	ukázka vykreslování
Geografická poloha	azure-maps-geolocation	Ukázka geografické polohy
časové pásmo	azure-maps-timezone	ukázky časového pásma

Vytvořte a ověřte MapsSearchClient

Objekt klienta používaný pro přístup k rozhraním API služby Azure Maps Search vyžaduje buď AzureKeyCredential objekt pro autentizaci pomocí klíče předplatného Azure Maps, nebo objekt TokenCredential s ID klienta Azure Maps při autentizaci pomocí Microsoft Entra ID. Další informace o ověřování najdete v tématu Ověřování pomocí Azure Maps.

Použití přihlašovacích údajů Microsoft Entra

Ověřování pomocí Microsoft Entra ID můžete provést pomocí Azure Identity knihovny. Pokud chcete použít zprostředkovatele DefaultAzureCredential , musíte do souboru přidat závislost pom.xml mvn:

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

Musíte zaregistrovat novou aplikaci Microsoft Entra a udělit přístup ke službě Azure Maps přiřazením požadované role hlavnímu objektu služby. Další informace viz Hostování démona na prostředcích mimo Azure. Vrátí se ID aplikace (klienta), ID adresáře (tenanta) a tajný klíč klienta. Zkopírujte tyto hodnoty a uložte je na bezpečném místě. Budete je potřebovat v následujících krocích.

Nastavte hodnoty ID aplikace (klienta), ID adresáře (tenanta) a tajného klíče klienta vaší aplikace Microsoft Entra a ID klienta mapového prostředku jako proměnné prostředí:

Proměnná prostředí	Popis
AZURE_CLIENT_ID	ID aplikace (klienta) ve vaší registrované aplikaci
AZURE_CLIENT_SECRET	Hodnota klientského tajemství v registrované aplikaci
AZURE_TENANT_ID	ID adresáře (tenanta) ve vaší registrované aplikaci
MAPS_CLIENT_ID	ID klienta ve vašem účtu Azure Map

Teď můžete v PowerShellu vytvořit proměnné prostředí pro uložení těchto hodnot:

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

Po nastavení proměnných prostředí je můžete v programu použít k vytvoření instance AzureMapsSearch klienta:

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

Důležité

Další proměnné prostředí vytvořené v předchozím fragmentu kódu, i když se v ukázkovém kódu nepoužívají, jsou vyžadovány DefaultAzureCredential(). Pokud tyto proměnné prostředí nenastavíte správně pomocí stejných zásad vytváření názvů, zobrazí se chyby za běhu. Pokud například chybí nebo AZURE_CLIENT_ID je neplatný, zobrazí se InvalidAuthenticationTokenTenant chyba.

Použití údajů o předplatitelském klíči

Můžete se ověřit pomocí klíče předplatného Azure Maps. Klíč předplatného najdete v části Ověřování v účtu Azure Maps, jak je znázorněno na následujícím snímku obrazovky:

Teď můžete v PowerShellu vytvořit proměnné prostředí pro uložení klíče předplatného:

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

Jakmile je proměnná prostředí vytvořená, můžete k ní přistupovat v kódu:

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

Přibližné hledání entity

Následující úryvek kódu ukazuje, jak importovat balíček azure-maps-search v jednoduché konzolové aplikaci a provést přibližné vyhledávání "Starbucks" poblíž Seattlu:

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

Tento fragment kódu ukazuje, jak vytvořit MapsSearchClient objekt pomocí přihlašovacích údajů Azure. Začněte instancováním AzureKeyCredential pomocí klíče předplatného pro Azure Maps, a poté jeho předáním k instancování MapsSearchClient. MapsSearchClient metody, jako FuzzySearch mohou používat název místa zájmu (POI) "Starbucks" a souřadnice GeoPosition(-122.31, 47.61).

Spusťte program ze složky projektu na příkazovém řádku:

java .\demo.java

Měl by se zobrazit seznam adres a výsledků souřadnic 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)

Hledání adresy

Pomocí metody SearchAddress zjistíte souřadnice adresy. Upravte hlavní program z ukázky následujícím způsobem:

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

V této ukázce client.SearchAddress metoda vrátí výsledky seřazené podle skóre spolehlivosti a vytiskne souřadnice prvního výsledku.

Dávkové reverzní vyhledávání

Služba Azure Maps Search také poskytuje některé metody dávkového dotazu. Tyto metody vrací objekty LRO (Long Running Operations). Požadavky nemusí okamžitě vracet všechny výsledky, takže se uživatelé můžou rozhodnout čekat na dokončení nebo se na výsledek pravidelně dotazovat, jak je znázorněno v metodě dávkového zpětného vyhledávání:

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

Váš názor

Byla tato stránka užitečná?

Poslední aktualizace v 2026-09-17