Ontwikkelaarshandleiding voor Java REST SDK (preview)
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
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());
}
}
}
}
Feedback
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie: https://aka.ms/ContentUserFeedback.
Feedback verzenden en weergeven voor