Guide du développeur sur le SDK REST Java (préversion)

Article
10/19/2023

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

Notes

Le SDK Java Azure Maps a Java 8 comme base de référence, avec test et support du transfert jusqu’à la version la plus récente du support à long terme de Java (actuellement Java 18). Pour obtenir la liste des versions de Java disponibles pour le téléchargement, consultez Versions standard de Java.

Prérequis

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 Bien démarrer avec le SDK Azure et Apache Maven.

Conseil

Vous pouvez créer un compte Azure Maps par programmation. Voici un exemple qui utilise Azure CLI :

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

Création d’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"

Paramètre	Description
`-DGroupId`	L’ID de groupe identifie de manière unique votre projet dans tous les projets
`-DartifactId`	Nom du projet. Il est créé en tant que nouveau dossier.
`-DarchetypeArtifactId`	Type de projet. `maven-archetype-quickstart` génère un exemple de projet.
`-DinteractiveMode`	La définition sur `false` génère un projet Java vide avec les options par défaut.

Installer les packages

Pour utiliser le 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 sont notamment la recherche, le rendu, le trafic, la météo, etc. Vous devez uniquement installer les packages du ou des services utilisés dans votre projet.

Une fois le projet Maven créé, il doit y avoir un fichier pom.xml avec des informations de base telles que l’ID de groupe, le nom et l’ID d’artefact. Ensuite, ajoutez une dépendance pour chacun des services Azure Maps, comme le montre 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 mvn clean install sur votre projet, puis créez un fichier Java nommé demo.java et importez-y ce dont vous avez besoin à partir d’Azure Maps :

cd DemoProject
New-Item demo.java

Conseil

Si l’exécution mvn clean install génère une erreur, essayez d’exécuter mvn clean install -U.

Services Azure Maps

Nom du service	Package Maven	Exemples
action	azure-maps-search	exemples de recherches
Routage	azure-maps-routing	exemples de routages
Rendu	azure-maps-rendering	exemples de rendus
Géolocalisation	azure-maps-geolocation	exemple de géolocalisation
Fuseau horaire	azure-maps-timezone	exemples de fuseaux horaires

Créer et authentifier un objet MapsSearchClient

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

Utilisation des informations d'identification Microsoft Entra

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

<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 de répertoire (tenant) et de la clé secrète client de votre application Microsoft Entra, ainsi que l’ID client de la ressource de carte en tant que variables d’environnement :

Variable d’environnement	Description
AZURE_CLIENT_ID	ID d’application (client) dans votre application inscrite
AZURE_CLIENT_SECRET	Valeur de la clé secrète client dans votre application inscrite
AZURE_TENANT_ID	ID d’annuaire (locataire) dans votre application inscrite
MAPS_CLIENT_ID	ID client dans votre compte Azure Map

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

Important

Les autres variables d'environnement créées dans l’extrait de code précédent, bien que non utilisées dans l'exemple de code ici, sont requises par DefaultAzureCredential(). Si vous ne définissez pas ces variables d’environnement correctement, en utilisant les mêmes conventions de nommage, vous obtiendrez des erreurs d’exécution. Par exemple, si votre AZURE_CLIENT_ID est manquant ou invalide, vous obtiendrez une erreur InvalidAuthenticationTokenTenant.

Utilisation d’informations d’identification de clé d’abonnement

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 package azure-maps-search et effectuer une recherche approximative sur les « Starbucks » situés à proximité 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 objet MapsSearchClient à l’aide des 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. Les méthodes MapsSearchClient telles que FuzzySearch peuvent utiliser le nom de point d’intérêt « Starbucks » et les coordonnées 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 Main de l’exemple de la façon suivante :

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 méthode client.SearchAddress retourne des résultats classés par score de confiance et imprime les coordonnées du premier résultat.

Recherche inversée par lots

La Recherche Azure Maps fournit également des méthodes de requête par lots. Ces méthodes retournent des objets LRO (opérations durable). Il est possible que les requêtes ne retournent pas tous les résultats immédiatement. Les utilisateurs peuvent donc choisir d’attendre la fin de la requête ou interroger les résultats régulièrement, comme indiqué 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());
            }
        }
    }
}

Partager via