Guia de desenvolvedores do Java REST SDK (visualização)

O SDK Java do Azure Maps pode ser integrado com aplicativos e bibliotecas Java para criar aplicativos relacionados a mapas e com reconhecimento de local. O SDK Java do Azure Maps contém APIs para Pesquisa, Rota, Renderização, Geolocalização, Tráfego, Fuso horário e Meteorologia. Essas APIs suportam operações como a busca por um endereço, roteamento entre diferentes coordenadas, obtenção da geolocalização de um endereço IP específico, etc.

Pré-requisitos

• Uma conta do Azure Maps
• Uma chave de subscrição ou outra forma de autenticação
• Java Versão 8 ou superior
• Maven (qualquer versão). Para obter mais informações, consulte Introdução ao SDK do Azure e ao Apache Maven.

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

Criar um projeto do Maven

O trecho de código do PowerShell a seguir demonstra como usar o PowerShell para criar um projeto maven. Primeiro, execute o comando maven para criar um projeto maven:

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

Instalar os pacotes

Para usar o SDK Java do Azure Maps, você precisa instalar todos os pacotes necessários. Cada serviço no Azure Maps está disponível em seu próprio pacote. Os serviços do Azure Maps incluem Pesquisa, Renderização, Tráfego, Meteorologia, etc. Você só precisa instalar os pacotes para o serviço ou serviços usados em seu projeto.

Uma vez que o projeto maven é criado, deve haver um pom.xml arquivo com informações básicas, como ID do grupo, nome, ID do artefato. Em seguida, adicione uma dependência para cada um dos serviços do Azure Maps, como demonstra o exemplo a seguir:

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

Execute mvn clean install em seu projeto e, em seguida, crie um arquivo java chamado demo.java e importe o que você precisa dos mapas do Azure para o arquivo:

cd DemoProject
New-Item demo.java

Serviços do Azure Maps

Criar e autenticar um MapsSearchClient

O objeto cliente usado para acessar as APIs de Pesquisa do Azure Maps requer um objeto para autenticação ao usar uma chave de assinatura do Azure Maps ou um AzureKeyCredential objeto TokenCredential com a ID do cliente do Azure Maps ao autenticar usando a ID do Microsoft Entra. Para obter mais informações sobre autenticação, consulte Autenticação com mapas do Azure.

Usando uma credencial do Microsoft Entra

Você pode autenticar com o Microsoft Entra ID usando a biblioteca de Identidade do Azure. Para usar o provedor DefaultAzureCredential , você precisa adicionar a dependência mvn no pom.xml arquivo:

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

Você precisa registrar o novo aplicativo Microsoft Entra e conceder acesso ao Azure Maps atribuindo a função necessária à sua entidade de serviço. Para obter mais informações, consulte Hospedar um daemon em recursos que não sejam do Azure. A ID do aplicativo (cliente), uma ID de diretório (locatário) e um segredo do cliente são retornados. Copie esses valores e armazene-os em um local seguro. Você precisa deles nas etapas a seguir.

Defina os valores da ID do aplicativo (cliente), da ID do diretório (locatário) e do segredo do cliente do seu aplicativo Microsoft Entra e da ID do cliente do recurso de mapa como variáveis de ambiente:

Agora você pode criar variáveis de ambiente no PowerShell para armazenar esses 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>"

Depois de configurar as variáveis de ambiente, você pode usá-las em seu programa para instanciar o AzureMapsSearch cliente:

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

Usando uma credencial de chave de assinatura

Pode autenticar-se com a sua chave de subscrição do Azure Maps. Sua chave de assinatura pode ser encontrada na seção Autenticação na conta do Azure Maps, conforme mostrado na captura de tela a seguir:

Agora você pode criar variáveis de ambiente no PowerShell para armazenar a chave de assinatura:

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

Depois que a variável de ambiente for criada, você poderá acessá-la em seu 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();
    }
}

Pesquisa difusa de uma entidade

O trecho de código a seguir demonstra como, em um aplicativo de console simples, importar o azure-maps-search pacote e executar uma pesquisa difusa em "Starbucks" perto 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 trecho de código demonstra como criar um objeto usando credenciais MapsSearchClient do Azure. Comece por instanciar utilizando a sua chave de subscrição do Azure Maps e, em seguida, passe as credenciais para instanciar AzureKeyCredential MapsSearchClient. MapsSearchClient métodos como FuzzySearch pode usar o nome do ponto de interesse (POI) "Starbucks" e coordenadas GeoPosition(-122.31, 47.61).

Execute o programa a partir da pasta do projeto na linha de comando:

java .\demo.java

Você deve ver uma lista de endereços da Starbucks e coordenar os resultados:

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

Procurar um endereço

Chame o SearchAddress método para obter a coordenada de um endereço. Modifique o programa principal do exemplo da seguinte maneira:

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

Neste exemplo, o método retorna os client.SearchAddress resultados ordenados pela pontuação de confiança e imprime as coordenadas do primeiro resultado.

Pesquisa reversa em lote

A Pesquisa do Azure Maps também fornece alguns métodos de consulta em lote. Esses métodos retornam objetos LRO (Long Running Operations). As solicitações podem não retornar todos os resultados imediatamente, para que os usuários possam optar por aguardar até a conclusão ou consultar o resultado periodicamente, conforme demonstrado no método de pesquisa reversa em lote:

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