Java REST SDK Geliştirici Kılavuzu (önizleme)

Azure Haritalar Java SDK'sı, haritalarla ilgili ve konum algılamalı uygulamalar oluşturmak için Java uygulamaları ve kitaplıklarıyla tümleştirilebilir. Azure Haritalar Java SDK'sı Arama, Yönlendirme, İşleme, Coğrafi Konum, Trafik, Saat Dilimi ve Hava Durumu API'lerini içerir. Bu API'ler adres arama, farklı koordinatlar arasında yönlendirme, belirli bir IP adresinin coğrafi konumunu alma gibi işlemleri destekler.

Uyarı

Azure Haritalar Java SDK'sı Java 8'de temel alınır ve en son Java uzun vadeli destek sürümüne (şu anda Java 18) kadar test ve iletme desteği sağlanır. İndirmek üzere Java sürümlerinin listesi için bkz. Java Standart Sürümleri.

Önkoşullar

Azure Haritalar hesabı
Abonelik anahtarı veya başka bir kimlik doğrulama biçimi
Java Sürüm 8 veya üzeri
Maven (herhangi bir sürüm). Daha fazla bilgi için bkz. Azure SDK ve Apache Maven'ı kullanmaya başlama.

Tavsiye

Program aracılığıyla bir Azure Haritalar hesabı oluşturabilirsiniz. Azure CLI'yı kullanan bir örnek aşağıda verilmiştir:

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

Maven projesi oluşturma

Aşağıdaki PowerShell kod parçacığı, Maven projesi oluşturmak için PowerShell'in nasıl kullanılacağını gösterir. İlk olarak maven komutunu çalıştırarak bir maven projesi oluşturun:

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

Parametre	Açıklama
`-DGroupId`	Grup Kimliği, projenizi tüm projelerde benzersiz olarak tanımlar
`-DartifactId`	Proje adı. Yeni bir klasör olarak oluşturulur.
`-DarchetypeArtifactId`	proje türü. `maven-archetype-quickstart` bir örnek projenin sonucudur.
`-DinteractiveMode`	Ayarlamanın `false` yapılması, varsayılan seçeneklerle boş bir Java projesinin oluşturulmasıyla sonuçlanır.

Paketleri yükleme

Azure Haritalar Java SDK'sını kullanmak için tüm gerekli paketleri yüklemeniz gerekir. Azure Haritalar'daki her hizmet kendi paketinde kullanılabilir. Azure Haritalar hizmetleri Arama, İşleme, Trafik, Hava Durumu vb. içerir. Yalnızca projenizde kullanılan hizmet veya hizmetler için paketleri yüklemeniz gerekir.

Maven projesi oluşturulduktan sonra grup kimliği, ad, yapıt kimliği gibi temel bilgileri içeren bir pom.xml dosya olmalıdır. Ardından, aşağıdaki örnekte gösterildiği gibi Azure Haritalar hizmetlerinin her biri için bir bağımlılık ekleyin:

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

Projenizde komutunu çalıştırın mvn clean install , adlı bir java dosyası demo.java oluşturun ve Azure Haritalar'dan ihtiyacınız olanı dosyaya aktarın:

cd DemoProject
New-Item demo.java

Tavsiye

Eğer mvn clean install çalıştırma bir hatayla sonuçlanırsa, mvn clean install -U çalıştırmayı deneyin.

Azure Haritalar hizmetleri

Hizmet adı	Maven paketi	Örnekler
Arama yap	azure-maps-search	arama örnekleri
Yönlendirme	azure-maps-routing	yönlendirme örnekleri
Renderleme	azure-maps-rendering	işleme örneği
Coğrafi Konum	azure-maps-geolocation	coğrafi konum örneği
Saat Dilimi	azure-maps-timezone	saat dilimi örnekleri

"MapsSearchClient" oluşturma ve kimlik doğrulama

Azure Haritalar Arama API'lerine erişmek için kullanılan istemci nesnesi, Azure Haritalar abonelik anahtarı kullanılırken kimlik doğrulaması için bir AzureKeyCredential nesne veya Microsoft Entra Id kullanarak kimlik doğrulaması yaparken Azure Haritalar istemci kimliğiyle tokenCredential nesnesi gerektirir. Kimlik doğrulaması hakkında daha fazla bilgi için bkz. Azure Haritalar ile kimlik doğrulaması.

Microsoft Entra kimlik bilgilerini kullanma

Azure Kimlik kitaplığını kullanarak Microsoft Entra Id ile kimlik doğrulaması yapabilirsiniz. DefaultAzureCredential sağlayıcısını kullanmak için dosyaya mvn bağımlılığını pom.xml eklemeniz gerekir:

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

Yeni Microsoft Entra uygulamasını kaydetmeniz ve hizmet sorumlunuza gerekli rolü atayarak Azure Haritalar erişimi vermeniz gerekir. Daha fazla bilgi için bkz . Azure dışı kaynaklarda daemon barındırma. Uygulama (istemci) kimliği, Dizin (kiracı) kimliği ve istemci gizli anahtarı geri döndürülür. Bu değerleri kopyalayın ve güvenli bir yerde depolayın. Aşağıdaki adımlarda bunlara ihtiyacınız vardır.

Microsoft Entra uygulamanızın Uygulama (istemci) kimliği, Dizin (kiracı) kimliği ve istemci gizli dizisi değerlerini ve eşleme kaynağının istemci kimliğini ortam değişkenleri olarak ayarlayın:

Ortam değişkeni	Açıklama
AZURE_CLIENT_ID	Kayıtlı uygulamanızdaki uygulama (istemci) kimliği
AZURE_CLIENT_SECRET	Kayıtlı uygulamanızdaki istemci gizli anahtarının değeri
AZURE_TENANT_ID	Kayıtlı uygulamanızdaki dizin (kiracı) kimliği
MAPS_CLIENT_ID	Azure Map hesabınızdaki istemci kimliği

Artık şu değerleri depolamak için PowerShell'de ortam değişkenleri oluşturabilirsiniz:

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

Ortam değişkenlerini ayarladıktan sonra bunları programınızda kullanarak istemcinin örneğini AzureMapsSearch oluşturabilirsiniz:

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

Önemli

Önceki kod parçacığında oluşturulan diğer ortam değişkenleri, kod örneğinde kullanılmasa da DefaultAzureCredential() tarafından gereklidir. Bu ortam değişkenlerini doğru ayarlamazsanız, aynı adlandırma kurallarını kullanarak çalışma zamanı hataları alırsınız. Örneğin, AZURE_CLIENT_ID eksik veya geçersizse, bir InvalidAuthenticationTokenTenant hatası alırsınız.

Abonelik anahtarı kimlik bilgilerini kullanma

Azure Haritalar abonelik anahtarınızla kimlik doğrulaması yapabilirsiniz. Abonelik anahtarınız, aşağıdaki ekran görüntüsünde gösterildiği gibi Azure Haritalar hesabının Kimlik Doğrulaması bölümünde bulunabilir:

Artık abonelik anahtarını depolamak için PowerShell'de ortam değişkenleri oluşturabilirsiniz:

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

Ortam değişkeniniz oluşturulduktan sonra bu değişkene kodunuzdan erişebilirsiniz:

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

Bir varlığı bulanık arama

Aşağıdaki kod parçacığı, basit bir konsol uygulamasında azure-maps-search paketini içeri aktarmayı ve Seattle yakınlarındaki "Starbucks" için benzer bir arama yapmayı gösterir.

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

Bu kod parçacığı, Azure kimlik bilgilerini kullanarak bir MapsSearchClient nesnenin nasıl oluşturulacağını gösterir. Başlangıç olarak AzureKeyCredential Azure Haritalar abonelik anahtarınızı kullanarak örneği oluşturarak başlayın, ardından kimlik bilgilerini geçirerek örneği oluşturma MapsSearchClient. MapsSearchClient gibi FuzzySearch yöntemler ilgi çekici nokta (POI) adını "Starbucks" olarak kullanabilir ve GeoPosition(-122.31, 47.61) koordinatlarını kullanabilir.

Programı komut satırındaki proje klasöründen yürütür:

java .\demo.java

Starbucks adresinin ve koordinat sonuçlarının listesini görmeniz gerekir:

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

Adres arama

Bir adresin SearchAddress koordinatını almak için yöntemini çağırın. Örnek programda ana programı aşağıda belirtilen şekilde değiştirin.

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

Bu örnekte yöntemi, güvenilirlik puanına client.SearchAddress göre sıralanmış sonuçları döndürür ve ilk sonucun koordinatlarını yazdırır.

Toplu ters arama

Azure Haritalar Arama bazı toplu sorgu yöntemleri de sağlar. Bu yöntemler Uzun Süre Çalışan İşlemler (LRO) nesneleri döndürür. İstekler tüm sonuçları hemen döndürmeyebilir, bu nedenle kullanıcılar toplu ters arama yönteminde gösterildiği gibi tamamlanmadan beklemeyi veya sonucu düzenli aralıklarla sorgulamayı seçebilir:

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

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-04-11