Guide des développeurs du SDK REST Java (préversion)

Le Kit de développement logiciel (SDK) Java Azure Maps peut être intégré aux applications et bibliothèques Java pour créer des applications prenant en charge les cartes et l’emplacement. Le Kit de développement logiciel (SDK) Java Azure Maps contient des API pour la recherche, l’itinéraire, le rendu, la géolocalisation, le trafic, le fuseau horaire et la météo. Ces API prennent en charge les opérations telles que la recherche d’une adresse, le routage entre différentes coordonnées, l’obtention de l’emplacement géographique d’une adresse IP spécifique, etc.

Conditions préalables

• Un compte Azure Maps
• Une clé d’abonnement ou une autre forme d’authentification
• Java Version 8 ou ultérieure
• Maven (n’importe quelle version). Pour plus d’informations, consultez Prise en main du Kit de développement logiciel (SDK) Azure et d’Apache Maven.

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

Créer un projet Maven

L’extrait de code PowerShell suivant montre comment utiliser PowerShell pour créer un projet maven. Tout d’abord, exécutez la commande maven pour créer un projet maven :

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

Installer les packages

Pour utiliser le Kit de développement logiciel (SDK) Java Azure Maps, vous devez installer tous les packages requis. Chaque service dans Azure Maps est disponible dans son propre package. Les services Azure Maps incluent la recherche, le rendu, le trafic, la météo, etc. Vous devez uniquement installer les packages pour le service ou les services utilisés dans votre projet.

Une fois le projet maven créé, il doit y avoir un pom.xml fichier avec des informations de base telles que l’ID de groupe, le nom, l’ID d’artefact. Ensuite, ajoutez une dépendance pour chacun des services Azure Maps, comme l’illustre l’exemple suivant :

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

Exécutez votre projet, puis créez mvn clean install un fichier Java nommé demo.java et importez ce dont vous avez besoin à partir d’Azure Maps dans le fichier :

cd DemoProject
New-Item demo.java

Services Azure Maps

Créer et authentifier un MapsSearchClient

L’objet client utilisé pour accéder aux API Recherche Azure Maps nécessite l’authentification d’un AzureKeyCredential objet lors de l’utilisation d’une clé d’abonnement Azure Maps ou d’un objet TokenCredential avec l’ID client Azure Maps lors de l’authentification à l’aide de l’ID Microsoft Entra. Pour plus d’informations sur l’authentification, consultez Authentification avec Azure Maps.

Utilisation des identifiants Microsoft Entra

Vous pouvez vous authentifier auprès de Microsoft Entra ID à l’aide de la bibliothèque d’identités Azure . Pour utiliser le fournisseur DefaultAzureCredential , vous devez ajouter la dépendance mvn dans le pom.xml fichier :

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

Vous devez inscrire la nouvelle application Microsoft Entra et accorder l’accès à Azure Maps en attribuant le rôle nécessaire à votre principal de service. Pour plus d’informations, consultez Héberger un démon sur des ressources non-Azure. L’ID d’application (client), un ID de répertoire (locataire) et une clé secrète client sont retournés. Copiez ces valeurs et stockez-les dans un endroit sécurisé. Vous en aurez besoin dans les étapes qui suivent.

Définissez les valeurs de l’ID d’application (client), de l’ID d’annuaire (locataire) et de la clé secrète client de votre application Microsoft Entra et de l’ID client de la ressource map en tant que variables d’environnement :

Vous pouvez maintenant créer des variables d’environnement dans PowerShell pour stocker ces valeurs :

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

Après avoir configuré les variables d'environnement, vous pouvez les utiliser dans votre programme pour instancier le client 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();
    }
}

Utilisation d'une clé d'abonnement comme identifiant

Vous pouvez vous authentifier avec votre clé d’abonnement Azure Maps. Votre clé d’abonnement se trouve dans la section Authentification du compte Azure Maps, comme illustré dans la capture d’écran suivante :

Vous pouvez maintenant créer des variables d’environnement dans PowerShell pour stocker la clé d’abonnement :

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

Une fois votre variable d’environnement créée, vous pouvez y accéder dans votre code :

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

Recherche approximative d’une entité

L’extrait de code suivant montre comment, dans une application console simple, importer le azure-maps-search package et effectuer une recherche approximative sur « Starbucks » près 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());
        }
    }
}

Cet extrait de code montre comment créer un MapsSearchClient objet à l’aide d’informations d’identification Azure. Commencez par instancier AzureKeyCredential à l’aide de votre clé d’abonnement Azure Maps, puis passez les informations d’identification pour instancier MapsSearchClient. MapsSearchClient méthodes telles que FuzzySearch peuvent utiliser le nom de point d’intérêt (POI) « Starbucks » et coordonne GeoPosition(-122.31, 47.61).

Exécutez le programme à partir du dossier du projet dans la ligne de commande :

java .\demo.java

Vous devez normalement voir la liste des adresses Starbucks avec leurs coordonnées :

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

Rechercher une adresse

Appelez la méthode SearchAddress pour obtenir les coordonnées d’une adresse. Modifiez le programme principal à partir de l’exemple comme suit :

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

Dans cet exemple, la client.SearchAddress méthode retourne les résultats classés par score de confiance et imprime les coordonnées du premier résultat.

Recherche inversée par lot

La Recherche Azure Maps fournit également des méthodes de requête par lots. Ces méthodes retournent des objets LRO (Long Running Operations). Les requêtes peuvent ne pas renvoyer tous les résultats immédiatement, de sorte que les utilisateurs peuvent choisir d’attendre l’achèvement ou d’interroger régulièrement le résultat, comme illustré dans la méthode de recherche inversée par lot :

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