Entwicklerhandbuch für das REST SDK (Vorschau)

Artikel
10/24/2023

Das Java SDK von Azure Maps kann in Java-Anwendungen und -Bibliotheken integriert werden, um karten- und standortbezogene Anwendungen zu erstellen. Das Java-SDK von Azure Maps enthält APIs für Suche, Routen, Rendern, Geolocation, Verkehr, Zeitzone und Wetter. Diese APIs unterstützen Vorgänge wie Adresssuche, Routing zwischen verschiedenen Koordinaten und Abrufen des geografischen Standorts einer bestimmten IP-Adresse.

Hinweis

Das Java SDK von Azure Maps basiert auf Java 8 mit Test- und Weiterleitungsunterstützung bis zum neuesten Java-Release für langfristige Unterstützung (derzeit Java 18). Eine Liste der Java-Versionen zum Herunterladen finden Sie unter Java-Standardversionen.

Voraussetzungen

Ein Azure Maps-Konto
Ein Abonnementschlüssel oder eine andere Form der Authentifizierung
Java, Version 8 oder höher
Maven (beliebige Version). Weitere Informationen finden Sie unter Erste Schritte mit dem Azure SDK und Apache Maven.

Tipp

Sie können ein Azure Maps-Konto programmgesteuert erstellen. Hier sehen Sie ein Beispiel unter Verwendung der Azure CLI:

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

Erstellen eines Maven-Projekts

Der folgende PowerShell-Codeschnipsel veranschaulicht die Verwendung von PowerShell zum Erstellen eines Maven-Projekts. Führen Sie zunächst den Maven-Befehl aus, um ein Maven-Projekt zu erstellen:

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

Parameter	BESCHREIBUNG
`-DGroupId`	Die Gruppen-ID identifiziert Ihr Projekt in allen Projekten eindeutig.
`-DartifactId`	Der Projektname. Er wird als neuer Ordner erstellt.
`-DarchetypeArtifactId`	Der Projekttyp. `maven-archetype-quickstart` führt zu einem Beispielprojekt.
`-DinteractiveMode`	Das Festlegen auf `false` führt zu einem leeren Java-Projekt mit Standardoptionen.

Installieren der Pakete

Um das Java SDK von Azure Maps verwenden zu können, müssen Sie alle erforderlichen Pakete installieren. Jeder Dienst in Azure Maps ist in einem eigenen Paket verfügbar. Zu den Diensten in Azure Maps gehören Suche, Rendern, Verkehr, Wetter usw. Sie müssen nur die Pakete für Dienste installieren, die in Ihrem Projekt verwendet werden.

Nach dem Erstellen des Maven-Projekts sollte eine Datei pom.xml mit grundlegenden Informationen wie Gruppen-ID, Name und Artefakt-ID vorhanden sein. Fügen Sie als Nächstes eine Abhängigkeit für jeden der Azure Maps-Dienste hinzu, wie im folgenden Beispiel veranschaulicht:

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

Führen Sie mvn clean install für Ihr Projekt aus, erstellen Sie dann eine Java-Datei mit dem Namen demo.java, und importieren Sie die benötigten Elemente aus Azure Maps in die Datei:

cd DemoProject
New-Item demo.java

Tipp

Wenn die Ausführung von mvn clean install zu einem Fehler führt, versuchen Sie, mvn clean install -U auszuführen.

Azure Maps-Dienste

Dienstname	Maven-Paket	Beispiele
Suchen	azure-maps-search	Beispiele für Suchen
Routing	azure-maps-routing	Beispiele für das Routing
Darstellung	azure-maps-rendering	Beispiel für das Rendering
Geolocation	azure-maps-geolocation	Beispiel für Geolocation
Zeitzone	azure-maps-timezone	Beispiele für die Zeitzone

Erstellen und Authentifizieren eines MapsSearchClient-Elements

Das Clientobjekt, das für den Zugriff auf die Such-APIs von Azure Maps verwendet wird, erfordert entweder ein AzureKeyCredential-Objekt zur Authentifizierung, wenn ein Azure Maps-Abonnementschlüssel verwendet wird, oder ein TokenCredential-Objekt mit der Client-ID von Azure Maps, wenn die Authentifizierung mit Microsoft Entra ID erfolgt. Weitere Informationen zur Authentifizierung finden Sie unter Authentifizierung bei Azure Maps.

Verwenden von Microsoft Entra-Anmeldeinformationen

Sie können sich mithilfe der Azure Identity-Bibliothek bei Microsoft Entra ID authentifizieren. Um den DefaultAzureCredential-Anbieter zu verwenden, müssen Sie die mvn-Abhängigkeit in der Datei pom.xml hinzufügen:

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

Sie müssen die neue Microsoft Entra-Anwendung registrieren und ihr Zugriff auf Azure Maps gewähren, indem Sie Ihrem Dienstprinzipal die erforderliche Rolle zuweisen. Weitere Informationen finden Sie unter Hosten eines Daemons für Nicht-Azure-Ressourcen. Zurückgegeben werden die Anwendungs-ID (Client), eine Verzeichnis-ID (Mandant) und ein geheimer Clientschlüssel. Kopieren Sie diese Werte, und speichern Sie sie an einem sicheren Ort. Sie benötigen diese in den folgenden Schritten.

Legen Sie die Werte der Anwendungs-ID (Client-ID), der Verzeichnis-ID (Mandanten-ID) und des geheimen Clientschlüssels Ihrer Microsoft Entra-Anwendung sowie der Client-ID der Kartenressource als Umgebungsvariablen fest:

Umgebungsvariable	BESCHREIBUNG
AZURE_CLIENT_ID	Anwendungs-ID (Client-ID) in Ihrer registrierten Anwendung
AZURE_CLIENT_SECRET	Der Wert des geheimen Clientschlüssels in Ihrer registrierten Anwendung
AZURE_TENANT_ID	Verzeichnis-ID (Mandanten-ID) in Ihrer registrierten Anwendung
MAPS_CLIENT_ID	Die Client-ID in Ihrem Azure Map-Konto

Sie können nun Umgebungsvariablen in PowerShell erstellen, um diese Werte zu speichern:

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

Nach dem Einrichten der Umgebungsvariablen können Sie sie in Ihrem Programm verwenden, um den AzureMapsSearch-Client zu instanziieren:

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

Wichtig

Die anderen, im vorherigen Codeschnipsel erstellten Umgebungsvariablen werden zwar im Codebeispiel nicht verwendet, sind aber für DefaultAzureCredential() erforderlich. Wenn Sie diese Umgebungsvariablen nicht richtig festlegen und dieselben Benennungskonventionen verwenden, treten Laufzeitfehler auf. Wenn AZURE_CLIENT_ID beispielsweise fehlt oder ungültig ist, erhalten Sie den Fehler InvalidAuthenticationTokenTenant.

Verwenden von Abonnementschlüssel-Anmeldeinformationen

Sie können sich mit Ihrem Azure Maps-Abonnementschlüssel authentifizieren. Ihren Abonnementschlüssel finden Sie im Abschnitt Authentifizierung im Azure Maps-Konto, wie im folgenden Screenshot gezeigt:

Sie können nun Umgebungsvariablen in PowerShell erstellen, um den Abonnementschlüssel zu speichern:

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

Nachdem Ihre Umgebungsvariable erstellt wurde, können Sie in Ihrem Code darauf zugreifen:

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

Ermitteln einer Entität mit der Fuzzysuche

Der folgende Codeschnipsel veranschaulicht, wie Sie in einer einfachen Konsolenanwendung das azure-maps-search-Paket importieren und eine Fuzzysuche nach „Starbucks“ in der Nähe von Seattle ausführen:

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

Dieser Codeschnipsel veranschaulicht, wie Sie ein MapsSearchClient-Objekt mit Azure-Anmeldeinformationen erstellen. Beginnen Sie mit der Instanziierung von AzureKeyCredential mithilfe Ihres Azure Maps-Abonnementschlüssels, und übergeben Sie dann den zu instanziierenden MapsSearchClient. MapsSearchClient-Methoden wie FuzzySearch können den Point of Interest-Namen (POI) „Starbucks“ und die Koordinaten GeoPosition(-122.31, 47.61) verwenden.

Führen Sie das Programm aus dem Projektordner in der Befehlszeile aus:

java .\demo.java

Es sollte eine Ergebnisliste mit Starbucks-Adressen und Koordinaten angezeigt werden:

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

Suchen nach einer Adresse

Rufen Sie die SearchAddress-Methode auf, um die Koordinaten einer Adresse zu erhalten. Ändern Sie das Hauptprogramm aus dem Beispiel wie folgt:

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

In diesem Beispiel gibt die client.SearchAddress-Methode Ergebnisse nach Konfidenzbewertung geordnet zurück und gibt die Koordinaten des ersten Ergebnisses aus.

Umgekehrte Batchsuche

Die Suche in Azure Maps bietet auch eine Reihe von Batchabfragemethoden. Diese Methoden geben LRO-Objekte (Long Running Operations, zeitintensive Vorgänge) zurück. Durch die Anforderungen werden möglicherweise nicht alle Ergebnisse sofort zurückgegeben. Daher können Benutzer bis zum Abschluss des Vorgangs warten oder das Ergebnis in regelmäßigen Abständen abfragen, wie in der Methode für Batchrückwärtssuche gezeigt:

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

Freigeben über