Java REST SDK fejlesztői útmutató (előzetes verzió)

Az Azure Térképek Java SDK integrálható Java-alkalmazásokkal és kódtárakkal térképekkel és helyérzékeny alkalmazásokkal. Az Azure Térképek Java SDK keresési, útvonal-, renderelési, földrajzi helymeghatározási, forgalmi, időzónás és időjárási API-kat tartalmaz. Ezek az API-k olyan műveleteket támogatnak, mint a cím keresése, a különböző koordináták közötti útválasztás, egy adott IP-cím földrajzi helyének lekérése stb.

Előfeltételek

• Azure-Térképek-fiók
• Előfizetési kulcs vagy más hitelesítési mód
• Java 8-es vagy újabb verzió
• Maven (bármely verzió). További információ: Ismerkedés az Azure SDK-val és az Apache Mavennel.

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

Maven-projekt létrehozása

Az alábbi PowerShell-kódrészlet bemutatja, hogyan hozhat létre maven-projektet a PowerShell használatával. Először futtassa a maven parancsot egy maven-projekt létrehozásához:

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

A csomagok telepítése

Az Azure Térképek Java SDK használatához telepítenie kell az összes szükséges csomagot. Az Azure Térképek minden szolgáltatása saját csomagban érhető el. Az Azure Térképek szolgáltatásai közé tartozik a keresés, a renderelés, a forgalom, az időjárás stb. Csak a projektben használt szolgáltatáshoz vagy szolgáltatásokhoz szükséges csomagokat kell telepítenie.

A maven-projekt létrehozása után létre kell hozni egy pom.xml olyan fájlt, amely alapvető információkat tartalmaz, például csoportazonosítót, nevet, összetevő-azonosítót. Ezután adjon hozzá függőséget az Egyes Azure Térképek-szolgáltatásokhoz, ahogy az alábbi példa is mutatja:

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

Futtassa mvn clean install a projektet, majd hozzon létre egy Java-fájlt, és demo.java importálja a szükséges adatokat az Azure Mapsből a fájlba:

cd DemoProject
New-Item demo.java

Azure Maps-szolgáltatások

Térképek SearchClient létrehozása és hitelesítése

Az Azure Térképek Search API-k eléréséhez használt ügyfélobjektumnak vagy egy AzureKeyCredential objektumnak kell hitelesítenie az Azure Térképek-előfizetési kulccsal, vagy egy TokenCredential objektumot az Azure Térképek-ügyfélazonosítóval a Microsoft Entra ID használatával történő hitelesítéskor. A hitelesítéssel kapcsolatos további információkért lásd: Hitelesítés az Azure Térképek.

Microsoft Entra hitelesítő adatok használata

Az Azure Identity-kódtár használatával hitelesíthet a Microsoft Entra-azonosítóval. A DefaultAzureCredential szolgáltató használatához hozzá kell adnia az mvn-függőséget a pom.xml fájlhoz:

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

Regisztrálnia kell az új Microsoft Entra-alkalmazást, és hozzáférést kell adnia az Azure Térképek, ha hozzárendeli a szükséges szerepkört a szolgáltatásnévhez. További információ: Démon gazdagépe nem Azure-erőforrásokon. A rendszer visszaadja az alkalmazás (ügyfél) azonosítóját, a címtár (bérlő) azonosítóját és az ügyfél titkos kódját. Másolja ki ezeket az értékeket, és tárolja őket biztonságos helyen. Az alábbi lépésekben szüksége lesz rájuk.

Állítsa be az alkalmazás (ügyfél) azonosítójának, a Címtár (bérlő) azonosítójának és a Microsoft Entra-alkalmazás ügyféltitkának értékeit, valamint a leképezési erőforrás ügyfélazonosítóját környezeti változóként:

Most már létrehozhat környezeti változókat a PowerShellben az alábbi értékek tárolásához:

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

A környezeti változók beállítása után használhatja őket a programban az AzureMapsSearch ügyfél példányosítására:

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

Előfizetési kulcs hitelesítő adatainak használata

Az Azure Térképek-előfizetési kulccsal hitelesíthet. Az előfizetési kulcs az Azure Térképek-fiók Hitelesítés szakaszában található az alábbi képernyőképen látható módon:

Most létrehozhat környezeti változókat a PowerShellben az előfizetési kulcs tárolásához:

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

A környezeti változó létrehozása után a következő kódban érheti el:

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 search an entity

Az alábbi kódrészlet bemutatja, hogy egy egyszerű konzolalkalmazásban hogyan importálhatja a azure-maps-search csomagot, és hogyan végezhet homályos keresést a Seattle-hez közeli Starbuckson:

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

Ez a kódrészlet bemutatja, hogyan hozhat létre objektumot MapsSearchClient Azure-hitelesítő adatokkal. Először az Azure Térképek-előfizetési kulccsal történő példányosítássalAzureKeyCredential, majd a példányosításhoz MapsSearchClientadja át a hitelesítő adatokat. MapsSearchClient metódusok, például FuzzySearch használhatják a "Starbucks" nevű pont (POI) nevet, és a GeoPosition(-122.31, 47.61) koordinátáit.

Hajtsa végre a programot a parancssor projektmappájából:

java .\demo.java

Megjelenik a Starbucks címének és a koordináta-eredményeknek a listája:

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

Cím keresése

Hívja meg a SearchAddress metódust egy cím koordinátájának lekéréséhez. Módosítsa a fő programot a mintából az alábbiak szerint:

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

Ebben a mintában a metódus megbízhatósági client.SearchAddress pontszám alapján rendezett eredményeket ad vissza, és kinyomtatja az első eredmény koordinátáit.

Kötegelt fordított keresés

Az Azure Térképek Search emellett kötegelt lekérdezési módszereket is biztosít. Ezek a metódusok hosszú ideig futó (LRO) objektumokat adnak vissza. Előfordulhat, hogy a kérések nem minden eredményt adnak vissza azonnal, ezért a felhasználók dönthetnek úgy, hogy megvárják a befejezést, vagy rendszeresen lekérdezik az eredményt a kötegelt fordított keresési módszer szerint:

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