Guia de Desenvolvedores do SDK REST do Java (versão prévia)

Artigo
10/20/2023

O SDK do Java do Azure Mapas pode ser integrado a aplicativos e bibliotecas Java para criar aplicativos relacionados a mapas e com reconhecimento de localização. O SDK do Java do Azure Mapas contém APIs para Pesquisa, Rota, Renderização, Elevação, Geolocalização, Tráfego, Fuso Horário e Clima. Essas APIs dão suporte a operações como pesquisa de endereço, roteamento entre coordenadas diferentes, obtenção da geolocalização de um endereço IP específico etc.

Observação

O SDK do Java do Azure Mapas tem como linha de base o Java 8, com suporte para teste e encaminhamento até a versão mais recente de suporte de longo prazo do Java (atualmente, o Java 18). Para obter a lista de versões do Java para download, confira Versões Padrão do Java.

Pré-requisitos

Uma Conta do Azure Mapas
Uma Chave de assinatura ou outra forma de autenticação
Java versão 8 ou posterior
Maven (qualquer versão). Para obter mais informações, consulte Introdução ao SDK do Azure e ao Apache Maven.

Dica

Você pode criar uma conta Azure Mapas programaticamente. Aqui está um exemplo usando a CLI do Azure:

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

Criar um projeto Maven

O snippet de código do PowerShell a seguir demonstra como usar o PowerShell para criar um projeto maven. Para começar, 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"

Parâmetro	Descrição
`-DGroupId`	A ID do grupo identifica exclusivamente seu projeto entre todos os projetos
`-DartifactId`	Nome do projeto. Ele é criado como uma nova pasta.
`-DarchetypeArtifactId`	Tipo de projeto. `maven-archetype-quickstart` resulta em um projeto de exemplo.
`-DinteractiveMode`	Definir como `false` resulta em um projeto Java em branco com opções padrão.

Instalar os pacotes

Para usar o SDK Java do Azure Mapas, você precisará instalar todos os pacotes necessários. Cada serviço no Azure Mapas está disponível no próprio pacote. Os serviços do Azure Mapas incluem Pesquisa, Renderização, Tráfego, Clima etc. Você só precisa instalar os pacotes do serviço ou dos serviços que usará no projeto.

Depois de criar o projeto maven, deve haver um arquivo pom.xml com informações básicas, como ID do grupo, nome e ID do artefato. Em seguida, adicione uma dependência para cada um dos serviços do Azure Mapas, 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 no projeto, crie um arquivo java chamado demo.java e importe o que você precisa do Azure Mapas para o arquivo:

cd DemoProject
New-Item demo.java

Dica

Se a execução de mvn clean install resultar em um erro, tente executar mvn clean install -U.

Serviços do Azure Mapas

Nome do serviço	Pacote do Maven	Exemplos
Pesquisa	azure-maps-search	exemplos de pesquisas
Roteamento	azure-maps-routing	exemplos de roteamentos
Renderização	azure-maps-rendering	exemplo de renderização
Geolocalização	azure-maps-geolocation	exemplo de geolocalização
TimeZone	azure-maps-timezone	exemplos de fusos horários

Criar e autenticar um MapsSearchClient

O objeto cliente usado para acessar as APIs de Pesquisa do Azure Mapas exige que um objeto AzureKeyCredential seja autenticado ao usar uma chave de assinatura do Azure Mapas ou um objeto TokenCredential com a ID do cliente do Azure Mapas ao autenticar usando o Microsoft Entra ID. Para obter mais informações sobre autenticação, confira Autenticação no Azure Mapas.

Como usar 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ê precisará adicionar a dependência mvn ao arquivo pom.xml:

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

Você precisará registrar o novo aplicativo do Microsoft Entra e permitir acesso ao Azure Mapas atribuindo a função necessária à entidade de serviço. Para obter mais informações, confira Hospedar um daemon em recursos que não são 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ê precisará 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 aplicativo do Microsoft Entra e a ID do cliente do recurso de mapa como variáveis de ambiente:

Variável de ambiente	Descrição
AZURE_CLIENT_ID	ID do aplicativo (cliente) no aplicativo registrado
AZURE_CLIENT_SECRET	O valor do segredo do cliente no aplicativo registrado
AZURE_TENANT_ID	ID do diretório (locatário) no aplicativo registrado
MAPS_CLIENT_ID	A ID do cliente na conta do Azure Mapas

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

As outras variáveis de ambiente criadas no snippet de código anterior, embora não sejam usadas no exemplo de código, são exigidas pela DefaultAzureCredential(). Se você não definir essas variáveis de ambiente corretamente, usando as mesmas convenções de nomenclatura, receberá erros em tempo de execução. Por exemplo, se o AZURE_CLIENT_ID for ignorado ou inválido, você receberá um erro InvalidAuthenticationTokenTenant.

Usando uma credencial de chave de assinatura

Você pode autenticar com sua chave de assinatura do Azure Mapas. Sua chave de assinatura pode ser encontrada na seção Autenticação na conta do Azure Mapas, conforme mostrado na seguinte captura de tela:

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

Pesquisar difusamente uma entidade

O seguinte snippet de código demonstra como, em um aplicativo de console simples, importar o pacote azure-maps-search e realizar uma pesquisa difusa de "Starbucks" na área 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());
        }
    }
}

Esse snippet de código demonstra como criar um objeto MapsSearchClient usando credenciais do Azure. Comece criando uma instância de AzureKeyCredential usando sua chave de assinatura do Azure Mapas e passe as credenciais para criar uma instância de MapsSearchClient. Métodos MapsSearchClient como FuzzySearch podem usar o nome do POI (ponto de interesse) "Starbucks" e as coordenadas GeoPosition(-122.31, 47.61).

Execute o programa na pasta do projeto na linha de comando:

java .\demo.java

Você deve ver uma lista de resultados de endereços e coordenadas da 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)

Pesquisar um endereço

Chame o método SearchAddress 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 client.SearchAddress retorna os resultados ordenados pela pontuação de confiança e imprime as coordenadas do primeiro resultado.

Pesquisa inversa do lote

A Pesquisa do Azure Mapas também fornece alguns métodos de consulta em lote. Esses métodos retornarão objetos LRO (operações de execução prolongada). As solicitações podem não retornar todos os resultados imediatamente, portanto, os usuários podem 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());
            }
        }
    }
}

Compartilhar via