Ontwikkelaarshandleiding voor Java REST SDK (preview)

Artikel
10/18/2023

De Azure Kaarten Java SDK kan worden geïntegreerd met Java-toepassingen en -bibliotheken voor het bouwen van kaarten gerelateerde en locatiebewuste toepassingen. De Azure Kaarten Java SDK bevat API's voor zoeken, route, render, geolocatie, verkeer, tijdzone en weer. Deze API's ondersteunen bewerkingen zoals het zoeken naar een adres, routering tussen verschillende coördinaten, het verkrijgen van de geografische locatie van een specifiek IP-adres, enzovoort.

Notitie

Azure Kaarten Java SDK is gebaseerd op Java 8, met test- en doorstuurondersteuning tot de nieuwste ondersteuningsrelease voor Java voor de lange termijn (momenteel Java 18). Zie Java Standard-versies voor de lijst met Java-versies die u kunt downloaden.

Vereisten

Een Azure Kaarten-account
Een abonnementssleutel of een andere vorm van verificatie
Java-versie 8 of hoger
Maven (elke versie). Zie Aan de slag met Azure SDK en Apache Maven voor meer informatie.

Tip

U kunt programmatisch een Azure Kaarten-account maken. Hier volgt een voorbeeld met behulp van de Azure CLI:

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

Een Maven-project maken

In het volgende PowerShell-codefragment ziet u hoe u PowerShell gebruikt om een maven-project te maken. Voer eerst de maven-opdracht uit om een maven-project te maken:

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

Parameter	Description
`-DGroupId`	Groeps-id identificeert uw project uniek in alle projecten
`-DartifactId`	Projectnaam. Deze wordt gemaakt als een nieuwe map.
`-DarchetypeArtifactId`	projecttype. `maven-archetype-quickstart` resulteert in een voorbeeldproject.
`-DinteractiveMode`	Instelling voor `false` resultaten in een leeg Java-project met standaardopties.

De pakketten installeren

Als u de Azure Kaarten Java SDK wilt gebruiken, moet u alle vereiste pakketten installeren. Elke service in Azure Kaarten is beschikbaar in een eigen pakket. De Azure Kaarten-services omvatten Zoeken, Renderen, Verkeer, Weer, enzovoort. U hoeft alleen de pakketten te installeren voor de service of services die in uw project worden gebruikt.

Zodra het maven-project is gemaakt, moet er een pom.xml bestand zijn met basisinformatie zoals groeps-id, naam, artefact-id. Voeg vervolgens een afhankelijkheid toe voor elk van de Azure Kaarten-services, zoals in het volgende voorbeeld wordt gedemonstreert:

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

Voer mvn clean install uit op uw project en maak vervolgens een Java-bestand met de naam demo.java en importeer wat u nodig hebt vanuit Azure Maps in het bestand:

cd DemoProject
New-Item demo.java

Tip

Als het uitvoeren mvn clean install resulteert in een fout, probeert u het uit te voeren mvn clean install -U.

Azure Maps Services

Servicenaam	Maven-pakket	Monsters
Zoeken	azure-maps-search	zoekvoorbeelden
Routering	azure-maps-routing	routeringsvoorbeelden
Rendering	azure-maps-rendering	renderingvoorbeeld
Geolocation	azure-maps-geolocation	voorbeeld van geolocatie
Tijdzone	azure-maps-tijdzone	tijdzonevoorbeelden

Een Kaarten SearchClient maken en verifiëren

Voor het clientobject dat wordt gebruikt voor toegang tot de Azure Kaarten Search-API's is een AzureKeyCredential object vereist om te verifiëren bij het gebruik van een Azure Kaarten-abonnementssleutel of een TokenCredential-object met de Client-id van Azure Kaarten bij het verifiëren met behulp van Microsoft Entra-id. Zie Verificatie met Azure Kaarten voor meer informatie over verificatie.

Een Microsoft Entra-referentie gebruiken

U kunt verifiëren met Microsoft Entra-id met behulp van de Azure Identity-bibliotheek. Als u de DefaultAzureCredential-provider wilt gebruiken, moet u de mvn-afhankelijkheid toevoegen in het pom.xml bestand:

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

U moet de nieuwe Microsoft Entra-toepassing registreren en toegang verlenen tot Azure Kaarten door de vereiste rol toe te wijzen aan uw service-principal. Zie Een daemon hosten voor niet-Azure-resources voor meer informatie. De toepassings-id (client), een map-id (tenant) en een clientgeheim worden geretourneerd. Kopieer deze waarden en sla ze op een veilige plaats op. U hebt ze nodig in de volgende stappen.

Stel de waarden in van de toepassings-id (client),map-id (tenant) en het clientgeheim van uw Microsoft Entra-toepassing en de client-id van de toewijzingsresource als omgevingsvariabelen:

Omgevingsvariabele	Beschrijving
AZURE_CLIENT_ID	Toepassings-id (client) in uw geregistreerde toepassing
AZURE_CLIENT_SECRET	De waarde van het clientgeheim in uw geregistreerde toepassing
AZURE_TENANT_ID	Map-id (tenant) in uw geregistreerde toepassing
MAPS_CLIENT_ID	De client-id in uw Azure Map-account

U kunt nu omgevingsvariabelen maken in PowerShell om deze waarden op te slaan:

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

Nadat u de omgevingsvariabelen hebt ingesteld, kunt u deze in uw programma gebruiken om de AzureMapsSearch client te instantiëren:

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

Belangrijk

De andere omgevingsvariabelen die zijn gemaakt in het vorige codefragment, terwijl ze niet worden gebruikt in het codevoorbeeld, zijn vereist door DefaultAzureCredential(). Als u deze omgevingsvariabelen niet correct instelt met dezelfde naamconventies, krijgt u runtimefouten. Als uw AZURE_CLIENT_ID bestand bijvoorbeeld ontbreekt of ongeldig is, krijgt u een InvalidAuthenticationTokenTenant foutmelding.

Een abonnementssleutelreferentie gebruiken

U kunt zich verifiëren met uw Azure Kaarten-abonnementssleutel. Uw abonnementssleutel vindt u in de sectie Verificatie in het Azure Kaarten-account, zoals wordt weergegeven in de volgende schermopname:

U kunt nu omgevingsvariabelen maken in PowerShell om de abonnementssleutel op te slaan:

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

Zodra uw omgevingsvariabele is gemaakt, kunt u deze openen in uw 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();
    }
}

Fuzzy zoeken in een entiteit

Het volgende codefragment laat zien hoe u in een eenvoudige consoletoepassing het azure-maps-search pakket importeert en een fuzzy zoekopdracht uitvoert op Starbucks in de buurt van 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());
        }
    }
}

Dit codefragment laat zien hoe u een MapsSearchClient object maakt met behulp van Azure-referenties. Begin met het instantiëren AzureKeyCredential van uw Azure Kaarten-abonnementssleutel en geef vervolgens de referenties door om te instantiërenMapsSearchClient. MapsSearchClient methoden zoals FuzzySearch het gebruik van de nuttige plaats (POI) naam "Starbucks" en coördinaten GeoPosition(-122.31, 47.61).

Voer het programma uit vanuit de projectmap op de opdrachtregel:

java .\demo.java

Als het goed is, ziet u een lijst met Starbucks-adressen en coördinaatresultaten:

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

Een adres zoeken

Roep de SearchAddress methode aan om de coördinaat van een adres op te halen. Wijzig het hoofdprogramma als volgt uit het voorbeeld:

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 dit voorbeeld retourneert de client.SearchAddress methode resultaten gesorteerd op betrouwbaarheidsscore en worden de coördinaten van het eerste resultaat afgedrukt.

Batch reverse search

Azure Kaarten Search biedt ook enkele batchquerymethoden. Deze methoden retourneren LRO-objecten (Long Running Operations). De aanvragen retourneren mogelijk niet onmiddellijk alle resultaten, zodat gebruikers ervoor kunnen kiezen om te wachten totdat het resultaat is voltooid of het resultaat periodiek op te vragen, zoals wordt gedemonstreerd in de batch reverse search-methode:

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

Delen via