Guida per sviluppatori di Java REST SDK (anteprima)

L'SDK Java Mappe di Azure può essere integrato con applicazioni e librerie Java per creare applicazioni correlate alle mappe e in grado di riconoscerne la posizione. Il Mappe di Azure Java SDK contiene API per la ricerca, il routing, il rendering, la georilevazione, il traffico, il fuso orario e il meteo. Queste API supportano operazioni come la ricerca di un indirizzo, il routing tra coordinate diverse, l'acquisizione della posizione geografica di un indirizzo IP specifico e così via.

Prerequisiti

• Un account Mappe di Azure
• Una chiave di sottoscrizione o un'altra forma di autenticazione
• Java versione 8 o successiva
• Maven (qualsiasi versione). Per altre informazioni, vedere Introduzione ad Azure SDK e Apache Maven.

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

Creare un progetto Maven

Il frammento di codice di PowerShell seguente illustra come usare PowerShell per creare un progetto maven. Eseguire prima di tutto il comando maven per creare un progetto maven:

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

Installare i pacchetti

Per usare Mappe di Azure Java SDK, è necessario installare tutti i pacchetti necessari. Ogni servizio in Mappe di Azure è disponibile nel proprio pacchetto. I servizi Mappe di Azure includono Ricerca, Rendering, Traffico, Meteo e così via. È sufficiente installare i pacchetti per il servizio o i servizi usati nel progetto.

Dopo aver creato il progetto maven, dovrebbe essere presente un pom.xml file con informazioni di base, ad esempio ID gruppo, nome, ID artefatto. Aggiungere quindi una dipendenza per ognuno dei servizi Mappe di Azure, come illustrato nell'esempio seguente:

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

Eseguire mvn clean install nel progetto, quindi creare un file Java denominato demo.java e importare gli elementi necessari da Mappe di Azure nel file:

cd DemoProject
New-Item demo.java

Servizi di Mappe di Azure

Creare ed autenticare un Mappe SearchClient

L'oggetto client usato per accedere alle API di ricerca di Mappe di Azure richiede l'autenticazione di un AzureKeyCredential oggetto quando si usa una chiave di sottoscrizione Mappe di Azure o un oggetto TokenCredential con l'ID client Mappe di Azure durante l'autenticazione tramite Microsoft Entra ID. Per altre informazioni sull'autenticazione, vedere Autenticazione con Mappe di Azure.

Uso delle credenziali di Microsoft Entra

È possibile eseguire l'autenticazione con Microsoft Entra ID usando la libreria di identità di Azure. Per usare il provider DefaultAzureCredential , è necessario aggiungere la dipendenza mvn nel pom.xml file:

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

È necessario registrare la nuova applicazione Microsoft Entra e concedere l'accesso a Mappe di Azure assegnando il ruolo necessario all'entità servizio. Per altre informazioni, vedere Ospitare un daemon in risorse non di Azure. Vengono restituiti l'ID applicazione (client), un ID directory (tenant) e un segreto client. Copiare questi valori e archiviarli in un luogo sicuro. Sono necessari nei passaggi seguenti.

Impostare i valori dell'ID applicazione (client), dell'ID directory (tenant) e del segreto client dell'applicazione Microsoft Entra e dell'ID client della risorsa di mapping come variabili di ambiente:

A questo punto è possibile creare variabili di ambiente in PowerShell per archiviare questi valori:

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

Dopo aver configurato le variabili di ambiente, è possibile usarle nel programma per creare un'istanza del AzureMapsSearch client:

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

Uso delle credenziali della chiave di sottoscrizione

È possibile eseguire l'autenticazione con la chiave di sottoscrizione Mappe di Azure. La chiave di sottoscrizione è disponibile nella sezione Autenticazione dell'account Mappe di Azure, come illustrato nello screenshot seguente:

A questo punto è possibile creare variabili di ambiente in PowerShell per archiviare la chiave di sottoscrizione:

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

Dopo aver creato la variabile di ambiente, è possibile accedervi nel codice:

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

Ricerca fuzzy in un'entità

Il frammento di codice seguente illustra come, in una semplice applicazione console, importare il azure-maps-search pacchetto ed eseguire una ricerca fuzzy su "Starbucks" vicino a 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());
        }
    }
}

Questo frammento di codice illustra come creare un MapsSearchClient oggetto usando le credenziali di Azure. Iniziare creando AzureKeyCredential un'istanza usando la chiave di sottoscrizione Mappe di Azure, quindi passa le credenziali per creare MapsSearchClientun'istanza di . MapsSearchClient metodi come FuzzySearch possono usare il nome punto di interesse (POI) "Starbucks" e coordinate GeoPosition(-122.31, 47.61).

Eseguire il programma dalla cartella del progetto nella riga di comando:

java .\demo.java

Verrà visualizzato un elenco di indirizzi Starbucks e i risultati delle coordinate:

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

Cercare un indirizzo

Chiamare il SearchAddress metodo per ottenere la coordinata di un indirizzo. Modificare il programma Main dall'esempio come segue:

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

In questo esempio, il client.SearchAddress metodo restituisce i risultati ordinati in base al punteggio di attendibilità e stampa le coordinate del primo risultato.

Ricerca inversa in batch

Mappe di Azure Search fornisce anche alcuni metodi di query batch. Questi metodi restituiscono oggetti LRO (Long Running Operations). Le richieste potrebbero non restituire immediatamente tutti i risultati, quindi gli utenti possono scegliere di attendere il completamento o eseguire periodicamente query sul risultato, come illustrato nel metodo di ricerca inversa batch:

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