Przewodnik dla deweloperów zestawu SDK REST języka Java (wersja zapoznawcza)

Artykuł
10/18/2023

Zestaw Azure Mapy Java SDK można zintegrować z aplikacjami i bibliotekami Java w celu tworzenia aplikacji obsługujących mapy i lokalizacje. Zestaw SDK platformy Azure Mapy Java zawiera interfejsy API wyszukiwania, trasy, renderowania, geolokalizacji, ruchu, strefy czasowej i pogody. Te interfejsy API obsługują operacje, takie jak wyszukiwanie adresu, routing między różnymi współrzędnymi, uzyskiwanie geograficznej lokalizacji określonego adresu IP itp.

Uwaga

Zestaw Java SDK platformy Azure Mapy jest oparty na środowisku Java 8, z testowaniem i przekazywaniem do najnowszej wersji długoterminowej pomocy technicznej języka Java (obecnie Java 18). Aby uzyskać listę wersji języka Java do pobrania, zobacz Java Standard Versions (Wersje języka Java w warstwie Standardowa).

Wymagania wstępne

Konto usługi Azure Mapy
Klucz subskrypcji lub inna forma uwierzytelniania
Java w wersji 8 lub nowszej
Maven (dowolna wersja). Aby uzyskać więcej informacji, zobacz Rozpoczynanie pracy z zestawem Azure SDK i narzędziem Apache Maven.

Napiwek

Możesz programowo utworzyć konto usługi Azure Mapy. Oto przykład przy użyciu interfejsu wiersza polecenia platformy Azure:

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

Tworzenie projektu Maven

Poniższy fragment kodu programu PowerShell przedstawia sposób tworzenia projektu maven przy użyciu programu PowerShell. Najpierw uruchom polecenie maven, aby utworzyć projekt maven:

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

Parametr	Opis
`-DGroupId`	Identyfikator grupy jednoznacznie identyfikuje projekt we wszystkich projektach
`-DartifactId`	Nazwa projektu. Jest on tworzony jako nowy folder.
`-DarchetypeArtifactId`	typ projektu. `maven-archetype-quickstart` wyniki w przykładowym projekcie.
`-DinteractiveMode`	Ustawienie powoduje `false` wyświetlenie pustego projektu Java z opcjami domyślnymi.

Instalowanie pakietów

Aby użyć zestawu Azure Mapy Java SDK, należy zainstalować wszystkie wymagane pakiety. Każda usługa w usłudze Azure Mapy jest dostępna we własnym pakiecie. Usługi azure Mapy obejmują wyszukiwanie, renderowanie, ruch, pogoda itp. Wystarczy zainstalować pakiety dla usługi lub usług używanych w projekcie.

Po utworzeniu projektu maven powinien istnieć pom.xml plik z podstawowymi informacjami, takimi jak identyfikator grupy, nazwa, identyfikator artefaktu. Następnie dodaj zależność dla każdej usługi Azure Mapy, jak pokazano w poniższym przykładzie:

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

Uruchom polecenie mvn clean install w projekcie, a następnie utwórz plik java o nazwie demo.java i zaimportuj potrzebne elementy z usługi Azure Maps do pliku:

cd DemoProject
New-Item demo.java

Napiwek

Jeśli uruchomienie powoduje mvn clean install błąd, spróbuj uruchomić polecenie mvn clean install -U.

Usługi Azure Maps

Nazwa usługi	Pakiet Maven	Próbki
Wyszukaj	azure-maps-search	wyszukiwanie przykładów
Routing	azure-maps-routing	przykłady routingu
Renderowanie	azure-maps-rendering	renderowanie przykładu
Geolokalizacja	azure-maps-geolokalizacja	przykład geolokalizacji
Strefa czasowa	azure-maps-timezone	przykłady strefy czasowej

Tworzenie i uwierzytelnianie Mapy SearchClient

Obiekt klienta używany do uzyskiwania dostępu do interfejsów API usługi Azure Mapy Search wymaga AzureKeyCredential uwierzytelnienia obiektu podczas korzystania z klucza subskrypcji usługi Azure Mapy lub obiektu TokenCredential przy użyciu identyfikatora klienta usługi Azure Mapy podczas uwierzytelniania przy użyciu identyfikatora entra firmy Microsoft. Aby uzyskać więcej informacji na temat uwierzytelniania, zobacz Authentication with Azure Mapy (Uwierzytelnianie przy użyciu usługi Azure Mapy).

Używanie poświadczeń entra firmy Microsoft

Możesz uwierzytelnić się przy użyciu identyfikatora Entra firmy Microsoft przy użyciu biblioteki tożsamości platformy Azure. Aby użyć dostawcy DefaultAzureCredential , należy dodać zależność mvn w pom.xml pliku:

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

Musisz zarejestrować nową aplikację Firmy Microsoft Entra i udzielić dostępu do usługi Azure Mapy, przypisując wymaganą rolę do jednostki usługi. Aby uzyskać więcej informacji, zobacz Hostowanie demona w zasobach spoza platformy Azure. Zwracany jest identyfikator aplikacji (klienta), identyfikator katalogu (dzierżawy) i klucz tajny klienta. Skopiuj te wartości i zapisz je w bezpiecznym miejscu. Są one potrzebne w poniższych krokach.

Ustaw wartości identyfikatora aplikacji (klienta), identyfikatora katalogu (dzierżawy) i wpisu tajnego klienta aplikacji Microsoft Entra oraz identyfikator klienta zasobu mapy jako zmienne środowiskowe:

Zmienna środowiskowa	opis
AZURE_CLIENT_ID	Identyfikator aplikacji (klienta) w zarejestrowanej aplikacji
AZURE_CLIENT_SECRET	Wartość wpisu tajnego klienta w zarejestrowanej aplikacji
AZURE_TENANT_ID	Identyfikator katalogu (dzierżawy) w zarejestrowanej aplikacji
MAPS_CLIENT_ID	Identyfikator klienta na koncie usługi Azure Map

Teraz możesz utworzyć zmienne środowiskowe w programie PowerShell, aby przechowywać następujące wartości:

$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 skonfigurowaniu zmiennych środowiskowych możesz użyć ich w programie, aby utworzyć wystąpienie 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();
    }
}

Ważne

Inne zmienne środowiskowe utworzone w poprzednim fragmencie kodu, choć nie są używane w przykładzie kodu, są wymagane przez DefaultAzureCredential()program . Jeśli te zmienne środowiskowe nie zostaną poprawnie ustawione, użyjesz tych samych konwencji nazewnictwa, wystąpią błędy czasu wykonywania. Jeśli na przykład brakuje lub jest on nieprawidłowy, AZURE_CLIENT_ID zostanie wyświetlony InvalidAuthenticationTokenTenant błąd.

Używanie poświadczeń klucza subskrypcji

Możesz uwierzytelnić się przy użyciu klucza subskrypcji usługi Azure Mapy. Klucz subskrypcji można znaleźć w sekcji Uwierzytelnianie na koncie usługi Azure Mapy, jak pokazano na poniższym zrzucie ekranu:

Teraz możesz utworzyć zmienne środowiskowe w programie PowerShell, aby przechowywać klucz subskrypcji:

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

Po utworzeniu zmiennej środowiskowej możesz uzyskać do niej dostęp w kodzie:

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

Rozmyte wyszukiwanie jednostki

Poniższy fragment kodu pokazuje, jak w prostej aplikacji konsolowej zaimportować azure-maps-search pakiet i wykonać rozmyte wyszukiwanie w "Starbucks" w pobliżu Seattle:

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

Ten fragment kodu pokazuje, jak utworzyć MapsSearchClient obiekt przy użyciu poświadczeń platformy Azure. Zacznij od utworzenia wystąpienia AzureKeyCredential przy użyciu klucza subskrypcji usługi Azure Mapy, a następnie przekazanie poświadczeń w celu utworzenia wystąpienia MapsSearchClientelementu . MapsSearchClient metody takie jak FuzzySearch mogą używać nazwy punktu orientacyjnego (POI) "Starbucks" i współrzędnych GeoPosition(-122.31, 47.61).

Wykonaj program z folderu projektu w wierszu polecenia:

java .\demo.java

Powinna zostać wyświetlona lista adresów Starbucks i wyników współrzędnych:

* 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)

Wyszukiwanie adresu

Wywołaj metodę , SearchAddress aby uzyskać współrzędną adresu. Zmodyfikuj program Main z przykładu w następujący sposób:

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

W tym przykładzie client.SearchAddress metoda zwraca wyniki uporządkowane według wyniku ufności i wyświetla współrzędne pierwszego wyniku.

Wyszukiwanie odwrotne wsadowe

Usługa Azure Mapy Search udostępnia również niektóre metody zapytań wsadowych. Te metody zwracają obiekty Long Running Operations (LRO). Żądania mogą nie zwracać wszystkich wyników natychmiast, więc użytkownicy mogą wybrać okresowe oczekiwanie na ukończenie lub wykonanie zapytania względem wyniku, jak pokazano w metodzie wyszukiwania odwrotnego wsadowego:

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

Udostępnij za pośrednictwem