Utvecklarguide för Java REST SDK (förhandsversion)

Artikel
10/18/2023

Azure Kartor Java SDK kan integreras med Java-program och -bibliotek för att skapa kartrelaterade och platsmedvetna program. Azure Kartor Java SDK innehåller API:er för Search, Route, Render, Geolocation, Traffic, Timezone och Weather. Dessa API:er stöder åtgärder som att söka efter en adress, dirigera mellan olika koordinater, hämta geo-platsen för en specifik IP-adress osv.

Kommentar

Azure Kartor Java SDK är baslinjebaserat på Java 8, med testning och vidarebefordrad support fram till den senaste java-versionen av långsiktig support (för närvarande Java 18). Listan över Java-versioner för nedladdning finns i Java Standard-versioner.

Förutsättningar

Ett Azure Kartor-konto
En prenumerationsnyckel eller annan form av autentisering
Java version 8 eller senare
Maven (valfri version). Mer information finns i Komma igång med Azure SDK och Apache Maven.

Dricks

Du kan skapa ett Azure Kartor-konto programmatiskt. Här är ett exempel med Hjälp av Azure CLI:

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

Skapa ett Maven-projekt

Följande PowerShell-kodfragment visar hur du använder PowerShell för att skapa ett maven-projekt. Kör först maven-kommandot för att skapa ett maven-projekt:

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

Parameter	Description
`-DGroupId`	Grupp-ID identifierar ditt projekt unikt i alla projekt
`-DartifactId`	Projektnamn. Den skapas som en ny mapp.
`-DarchetypeArtifactId`	projekttyp. `maven-archetype-quickstart` resulterar i ett exempelprojekt.
`-DinteractiveMode`	Om du anger till `false` resulterar det i ett tomt Java-projekt med standardalternativ.

Installera paketen

Om du vill använda Azure Kartor Java SDK måste du installera alla nödvändiga paket. Varje tjänst i Azure Kartor är tillgänglig i sitt eget paket. Azure Kartor-tjänsterna omfattar Sök, Rendera, Trafik, Väder osv. Du behöver bara installera paketen för tjänsten eller tjänsterna som används i projektet.

När maven-projektet har skapats bör det finnas en pom.xml fil med grundläggande information som grupp-ID, namn, artefakt-ID. Lägg sedan till ett beroende för var och en av Azure Kartor-tjänsterna, vilket visas i följande exempel:

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

Kör mvn clean install i projektet och skapa sedan en Java-fil med namnet demo.java och importera det du behöver från Azure Maps till filen:

cd DemoProject
New-Item demo.java

Dricks

Om körningen mvn clean install resulterar i ett fel kan du prova att köra mvn clean install -U.

Azure Maps-tjänster

Tjänstnamn	Maven-paket	Prover
Sök	azure-maps-search	sökexempel
Routning	azure-maps-routning	routningsexempel
Rendering	azure-maps-rendering	renderingsexempel
Geolocation	azure-maps-geolocation	geoplatsexempel
Tidszon	azure-maps-timezone	tidszonsexempel

Skapa och autentisera en Kartor SearchClient

Klientobjektet som används för att komma åt API:erna för Azure Kartor Search kräver antingen ett AzureKeyCredential objekt för att autentisera när du använder en Azure Kartor-prenumerationsnyckel eller ett TokenCredential-objekt med Azure Kartor-klient-ID när du autentiserar med Microsoft Entra-ID. Mer information om autentisering finns i Autentisering med Azure Kartor.

Använda en Microsoft Entra-autentiseringsuppgift

Du kan autentisera med Microsoft Entra-ID med hjälp av Azure Identity-biblioteket. Om du vill använda DefaultAzureCredential-providern måste du lägga till mvn-beroendet i pom.xml filen:

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

Du måste registrera det nya Microsoft Entra-programmet och bevilja åtkomst till Azure Kartor genom att tilldela den roll som krävs till tjänstens huvudnamn. Mer information finns i Host a daemon on non-Azure resources (Värd för en daemon för icke-Azure-resurser). Program-ID(klient)-ID, ett katalog-ID (klient)-ID och en klienthemlighet returneras. Kopiera dessa värden och lagra dem på en säker plats. Du behöver dem i följande steg.

Ange värdena för program-ID,katalog-ID (klient)-ID och klienthemlighet för ditt Microsoft Entra-program och mappningsresursens klient-ID som miljövariabler:

Miljövariabel	beskrivning
AZURE_CLIENT_ID	Program-ID (klient) i ditt registrerade program
AZURE_CLIENT_SECRET	Värdet för klienthemligheten i ditt registrerade program
AZURE_TENANT_ID	Katalog-ID (klientorganisation) i ditt registrerade program
MAPS_CLIENT_ID	Klient-ID:t i ditt Azure Map-konto

Nu kan du skapa miljövariabler i PowerShell för att lagra följande värden:

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

När du har konfigurerat miljövariablerna kan du använda dem i programmet för att instansiera AzureMapsSearch klienten:

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

Viktigt!

De andra miljövariablerna som skapades i föregående kodfragment, men som inte används i kodexemplet, krävs av .DefaultAzureCredential() Om du inte ställer in dessa miljövariabler korrekt får du körningsfel med samma namngivningskonventioner. Om du AZURE_CLIENT_ID till exempel saknar eller är ogiltig får du ett InvalidAuthenticationTokenTenant fel.

Använda en prenumerationsnyckelautentiseringsuppgifter

Du kan autentisera med din Azure Kartor-prenumerationsnyckel. Din prenumerationsnyckel finns i avsnittet Autentisering i Azure Kartor-kontot enligt följande skärmbild:

Nu kan du skapa miljövariabler i PowerShell för att lagra prenumerationsnyckeln:

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

När miljövariabeln har skapats kan du komma åt den i koden:

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-sökning i en entitet

Följande kodfragment visar hur du i ett enkelt konsolprogram importerar azure-maps-search paketet och utför en fuzzy-sökning på "Starbucks" nära 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());
        }
    }
}

Det här kodfragmentet visar hur du skapar ett MapsSearchClient objekt med azure-autentiseringsuppgifter. Börja med att instansiera AzureKeyCredential med din Azure Kartor-prenumerationsnyckel och skicka sedan autentiseringsuppgifterna för att instansiera MapsSearchClient. MapsSearchClient metoder som FuzzySearch kan använda intressepunktsnamnet (POI) "Starbucks" och koordinaterna GeoPosition(-122.31, 47.61).

Kör programmet från projektmappen på kommandoraden:

java .\demo.java

Du bör se en lista över Starbucks-adresser och koordinatresultat:

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

Sök efter en adress

SearchAddress Anropa metoden för att hämta koordinaten för en adress. Ändra main-programmet från exemplet på följande sätt:

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

I det här exemplet client.SearchAddress returnerar metoden resultat ordnade efter konfidenspoäng och skriver ut koordinaterna för det första resultatet.

Omvänd batchsökning

Azure Kartor Search innehåller även några batchfrågemetoder. Dessa metoder returnerar LRO-objekt (Long Running Operations). Begärandena kanske inte returnerar alla resultat omedelbart, så användarna kan välja att vänta tills de är klara eller köra frågor mot resultatet regelbundet, vilket visas i metoden för omvänd batchsökning:

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

Dela via