Guía para desarrolladores del SDK de REST de Java (versión preliminar)

Artículo
10/25/2023

El SDK de Java de Azure Maps se puede integrar con las aplicaciones y bibliotecas de Java para crear aplicaciones relacionadas con mapas y con la ubicación. El SDK de Java de Azure Maps contiene API para búsqueda, enrutamiento, representación, geolocalización, tráfico, zona horaria y tiempo. Estas API admiten operaciones como la búsqueda de una dirección, el enrutamiento entre diferentes coordenadas y la obtención de la ubicación geográfica de una dirección IP específica, entre otras.

Nota

El SDK de Java de Azure Maps se basa en Java 8, con pruebas y compatibilidad hasta la versión de soporte técnico a largo plazo más reciente de Java (actualmente, Java 18). Para obtener la lista de versiones de Java para su descarga, consulte Versiones estándar de Java.

Requisitos previos

Una cuenta de Azure Maps
Una clave de suscripción u otra forma de autenticación
Java versión 8 o posteriores
Maven (cualquier versión). Para obtener más información, consulte Introducción al SDK de Azure y Apache Maven.

Sugerencia

Puede crear una cuenta de Azure Maps mediante programación. A continuación se muestra un ejemplo mediante la CLI de Azure:

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

Creación de un proyecto de Maven

El fragmento de código de PowerShell siguiente muestra cómo usar PowerShell para crear un proyecto de Maven. En primer lugar, ejecute el comando maven para crear un proyecto de maven:

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

Parámetro	Descripción
`-DGroupId`	El identificador de grupo identifica de forma única el proyecto en todos los proyectos.
`-DartifactId`	Nombre del proyecto. Se crea como una carpeta nueva.
`-DarchetypeArtifactId`	Tipo de proyecto. `maven-archetype-quickstart` da como resultado un proyecto de ejemplo.
`-DinteractiveMode`	Establecerlo en `false` da como resultado un proyecto de Java en blanco con opciones predeterminadas.

Instalación de los paquetes

Para usar el SDK de Java de Azure Maps, debe instalar todos los paquetes necesarios. Cada servicio de Azure Maps está disponible en su propio paquete. Los servicios de Azure Maps incluyen la búsqueda, representación, tráfico, tiempo, etc. Solo tiene que instalar los paquetes del servicio o servicios que se van a usar en el proyecto.

Después de crear el proyecto de maven, debe haber un archivo pom.xml con información básica, como el identificador de grupo, el nombre y el identificador de artefacto. A continuación, agregue una dependencia para cada uno de los servicios de Azure Maps, como se muestra en el ejemplo siguiente:

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

Ejecute mvn clean install en el proyecto y, a continuación, cree un archivo Java denominado demo.java e importe lo que necesita de Azure Maps en el archivo:

cd DemoProject
New-Item demo.java

Sugerencia

Si la ejecución de mvn clean install produce un error, intente ejecutar mvn clean install -U.

Servicios de Azure Maps

Nombre del servicio	Paquete Maven	Ejemplos
Búsqueda	azure-maps-search	ejemplos de búsqueda
Enrutamiento	azure-maps-routing	ejemplos de enrutamiento
Representación	azure-maps-rendering	ejemplo de representación
Geolocalización	azure-maps-geolocation	ejemplo de geolocalización
Zona horaria	azure-maps-timezone	timezone samples

Creación y autenticación de un objeto MapsSearchClient

El objeto de cliente que se usa para acceder a las API de búsqueda de Azure Maps requiere que un objeto AzureKeyCredential se autentique al usar una clave de suscripción de Azure Maps o un objeto con el id. de cliente de Azure Maps al autenticarse mediante Microsoft Entra ID. Para obtener más información sobre la autenticación, consulte Autenticación con Azure Maps.

Uso de la credencial de Microsoft Entra

Puede autenticarse con Microsoft Entra ID mediante la biblioteca de identidades de Azure. Para usar el proveedor DefaultAzureCredential, deberá agregar la dependencia mvn en el archivo pom.xml:

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

Debe registrar la nueva aplicación Microsoft Entra y conceder acceso a Azure Maps mediante la asignación del rol necesario a la entidad de servicio. Para más información, consulte Hospedaje de un demonio en recursos que no son de Azure. Se devuelve el id. de aplicación (cliente), un id. de directorio (inquilino) y un secreto de cliente. Copie estos valores y guárdelos en lugar seguro. Los necesitará en los pasos siguientes.

Establezca los valores del identificador de aplicación (cliente), el identificador de directorio (inquilino) y el secreto de cliente de la aplicación de Microsoft Entra, así como el identificador de cliente del recurso de asignación, como variables de entorno:

Variable de entorno	Descripción
AZURE_CLIENT_ID	Identificador de aplicación (cliente) de la aplicación registrada
AZURE_CLIENT_SECRET	Valor del secreto de cliente de la aplicación registrada
AZURE_TENANT_ID	Identificador de directorio (inquilino) de la aplicación registrada
MAPS_CLIENT_ID	Identificador de cliente de la cuenta de Azure Maps

Ahora puede crear variables de entorno en PowerShell para almacenar estos valores:

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

Después de configurar las variables de entorno, puede usarlas en el programa para crear instancias del cliente 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();
    }
}

Importante

Las demás variables de entorno creadas en el fragmento de código anterior, aunque no se usan en el ejemplo de código, son necesarias para DefaultAzureCredential(). Si no establece correctamente estas variables de entorno, con las mismas convenciones de nomenclatura, obtendrá errores en tiempo de ejecución. Por ejemplo, si AZURE_CLIENT_ID falta o no es válido, obtendrá un error InvalidAuthenticationTokenTenant.

Uso de una credencial de clave de suscripción

Puede autenticarse con la clave de suscripción de Azure Maps. Encontrará la clave de suscripción en la sección Autenticación de la cuenta de Azure Maps, como se muestra en la captura de pantalla siguiente:

Ahora puede crear variables de entorno en PowerShell para almacenar la clave de suscripción:

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

Una vez que se haya creado la variable de entorno, puede acceder a ella en el código:

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

Búsqueda aproximada de una entidad

En el siguiente fragmento de código se muestra cómo importar, en una aplicación de consola simple, el paquete azure-maps-search y realizar una búsqueda aproximada de "Starbucks" cerca de 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());
        }
    }
}

Este fragmento de código muestra cómo crear un objeto MapsSearchClient con credenciales de Azure. Para empezar, cree una instancia de AzureKeyCredential mediante la clave de suscripción de Azure Maps y, a continuación, pase las credenciales para crear una instancia de MapsSearchClient. Los métodos MapsSearchClient como FuzzySearch pueden usar el nombre de punto de interés (POI) "Starbucks" y coordenadas GeoPosition(-122.31, 47.61).

Ejecute el programa desde la carpeta del proyecto en la línea de comandos:

java .\demo.java

Debería ver una lista de direcciones y resultados de coordenadas de 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)

Búsqueda de una dirección

Llame al método SearchAddress para obtener las coordenadas de una dirección. Modifique el programa Main del ejemplo de la siguiente manera:

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

En este ejemplo, el método client.SearchAddress devuelve los resultados ordenados por puntuación de confianza e imprime las coordenadas del primer resultado.

Búsqueda inversa por lotes

La búsqueda de Azure Maps también proporciona algunos métodos de consulta por lotes. Estos métodos devolverán objetos de operaciones de larga duración (LRO). Es posible que las solicitudes no devuelvan todos los resultados inmediatamente, por lo que los usuarios pueden optar por esperar hasta que terminen o consultar el resultado periódicamente, tal como se muestra en el método de búsqueda inversa por lotes:

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

Compartir a través de