Przewodnik dla programistów Java REST SDK (wersja wstępna)

SDK Azure Maps for Java można zintegrować z aplikacjami i bibliotekami Java, aby tworzyć aplikacje powiązane z mapami i świadome lokalizacji. Azure Maps Java SDK zawiera interfejsy API do wyszukiwania, tras, renderowania, geolokalizacji, ruchu, stref czasowych i pogody. Te interfejsy API obsługują operacje takie jak wyszukiwanie adresu, planowanie trasy między różnymi współrzędnymi, uzyskiwanie geolokalizacji konkretnego adresu IP itp.

Wymagania wstępne

• Konto usługi Azure Maps
• A Subscription key or other form of authentication
• Java w wersji 8 lub nowszej
• Maven (any version). Aby uzyskać więcej informacji, zobacz Rozpoczęcie pracy z Azure SDK i Apache Maven.

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

Tworzenie projektu Maven

Następujący fragment kodu PowerShell demonstruje, jak używać PowerShell do utworzenia projektu maven. Najpierw uruchom polecenie maven, aby utworzyć projekt maven.

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

Instalowanie pakietów

Aby używać Azure Maps Java SDK, należy zainstalować wszystkie wymagane pakiety. Each service in Azure Maps is available in its own package. The Azure Maps services include Search, Render, Traffic, Weather, etc. You only need to install the packages for the service or services used in your project.

Po utworzeniu projektu Maven powinien istnieć plik pom.xml zawierający podstawowe informacje, takie jak identyfikator grupy, nazwa, identyfikator artefaktu. Następnie dodaj zależność dla każdej z usług Azure Maps, 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

Usługi Azure Maps

Utwórz i uwierzytelnij klienta MapsSearchClient

Obiekt klienta używany do uzyskiwania dostępu do interfejsów API wyszukiwania Azure Maps wymaga albo obiektu AzureKeyCredential do uwierzytelniania przy użyciu klucza subskrypcji Azure Maps, albo obiektu TokenCredential z identyfikatorem klienta Azure Maps przy uwierzytelnianiu za pomocą Microsoft Entra ID. Aby uzyskać więcej informacji na temat uwierzytelniania, zobacz Authentication with Azure Maps (Uwierzytelnianie za pomocą usługi Azure Maps).

Używanie poświadczeń entra firmy Microsoft

Możesz uwierzytelnić się przy użyciu Microsoft Entra ID, korzystając z biblioteki Azure Identity. Aby użyć dostawcy DefaultAzureCredential, musisz dodać zależność mvn w pliku pom.xml.

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

You need to register the new Microsoft Entra application and grant access to Azure Maps by assigning the required role to your service principal. Aby uzyskać więcej informacji, zobacz Hostowanie demona w zasobach spoza platformy Azure. The Application (client) ID, a Directory (tenant) ID, and a client secret are returned. Skopiuj te wartości i zapisz je w bezpiecznym miejscu. Są one potrzebne w poniższych krokach.

Set the values of the Application (client) ID, Directory (tenant) ID, and client secret of your Microsoft Entra application, and the map resource's client ID as environment variables:

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

Używanie poświadczenia klucza subskrypcji

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

Teraz możesz tworzyć zmienne środowiskowe w 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();
    }
}

Wyszukiwanie przybliżone jednostki

Poniższy fragment kodu pokazuje, jak w prostej aplikacji konsolowej zaimportować pakiet azure-maps-search i przeprowadzić przybliżone wyszukiwanie "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 demonstruje, jak utworzyć obiekt MapsSearchClient przy użyciu poświadczeń Azure. Rozpocznij od stworzenia instancji AzureKeyCredential używając klucza subskrypcji Azure Maps, następnie przekaż dane uwierzytelniające, aby stworzyć instancję MapsSearchClient. MapsSearchClient metody takie jak FuzzySearch mogą używać nazwy punktu zainteresowania (POI) "Starbucks" oraz współrzędnych GeoPosition(-122.31, 47.61).

Uruchom program z folderu projektu w wierszu poleceń.

java .\demo.java

Powinieneś zobaczyć listę adresów i wyników współrzędnych 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)

Wyszukaj adres

Wywołaj metodę , SearchAddress aby uzyskać współrzędną adresu. Zmodyfikuj główny program 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 metoda client.SearchAddress zwraca wyniki uporządkowane według wskaźnika pewności i wydrukowuje współrzędne pierwszego wyniku.

Wyszukiwanie wsteczne w partii

Usługa Azure Maps 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 od razu, więc użytkownicy mogą wybrać, czy chcą poczekać na zakończenie procesu, czy okresowo odpytywać o wynik, jak pokazano w metodzie wyszukiwania wstecznego w trybie wsadowym.

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