Příručka pro vývojáře v sadě Java REST SDK (Preview)

Článek
10/18/2023

Sadu Azure Mapy Java SDK je možné integrovat s aplikacemi a knihovnami Javy a vytvářet aplikace související s mapami a aplikacemi pracujícími s umístěním. Sada Azure Mapy Java SDK obsahuje rozhraní API pro vyhledávání, trasu, vykreslování, 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:

Sada Azure Mapy Java SDK je založená na javě 8, přičemž testování a předávání podporuje až do nejnovější verze dlouhodobé podpory Javy (aktuálně Java 18). Seznam verzí Javy ke stažení najdete v tématu Standardní verze Javy.

Požadavky

Účet Azure Mapy
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.

Tip

Účet Azure Mapy 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í pro `false` výsledky v prázdném projektu v Javě s výchozími možnostmi

Instalace balíčků

Pokud chcete používat sadu Azure Mapy Java SDK, musíte nainstalovat všechny požadované balíčky. Každá služba v Azure Mapy je dostupná ve vlastním balíčku. Mezi služby Azure Mapy 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 službu Azure Mapy, 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>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>

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

Tip

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
Vyhledat	azure-maps-search	ukázky hledání
Směrování	azure-maps-routing	ukázky směrování
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ření a ověření Mapy SearchClient

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

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

Ověřování pomocí Microsoft Entra ID můžete provést pomocí knihovny identit Azure. 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 k Azure Mapy přiřazením požadované role k instančnímu objektu. Další informace najdete v tématu Hostování démona u prostředků 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 prostředku mapy jako proměnné prostředí:

Proměnná prostředí	Popis
AZURE_CLIENT_ID	ID aplikace (klienta) ve vaší registrované aplikaci
AZURE_CLIENT_SECRET	Hodnota tajného klíče klienta 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, které se v ukázce kódu nepoužívají, vyžadují .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í přihlašovacích údajů klíče předplatného

Pomocí klíče předplatného Azure Mapy můžete provést ověření. Klíč předplatného najdete v části Ověřování v účtu Azure Mapy, 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í fragment kódu ukazuje, jak v jednoduché konzolové aplikaci naimportovat azure-maps-search balíček a provést přibližné vyhledávání na "Apk" 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 vytvořením instance AzureKeyCredential klíče předplatného Azure Mapy a předáním přihlašovacích údajů k vytvoření instance MapsSearchClient. MapsSearchClient metody, jako FuzzySearch je například použití názvu poI (POI) a souřadnic 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 Společnosti Apk a koordinovat výsledky:

* 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

SearchAddress Voláním metody získáte souřadnici 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í

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

Sdílet prostřednictvím