Руководство разработчиков ПАКЕТА SDK для Java (предварительная версия)

Статья
10/18/2023

Пакет SDK для Java Карты Azure можно интегрировать с приложениями и библиотеками Java для создания приложений, связанных с картами и расположениями. Пакет SDK для Java для Azure Карты содержит API для поиска, маршрутизации, отрисовки, географического расположения, трафика, часового пояса и погоды. Эти API поддерживают такие операции, как поиск адреса, маршрутизация между различными координатами, получение географического расположения определенного IP-адреса и т. д.

Примечание.

Пакет SDK для Java для Карты Azure используется для Java 8 с тестированием и пересылкой поддержки до последнего выпуска долгосрочной поддержки Java (в настоящее время Java 18). Список версий Java для скачивания см. в разделе "Стандартные версии Java".

Необходимые компоненты

Учетная запись Azure Карты
Ключ подписки или другая форма проверки подлинности
Java версии 8 или более поздней
Maven (любая версия). Дополнительные сведения см. в статье "Начало работы с пакетом SDK Azure" и Apache Maven.

Совет

Вы можете создать учетную запись Azure Карты программным способом. Ниже приведен пример с помощью Azure CLI:

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

Создание проекта Maven

В следующем фрагменте кода PowerShell показано, как использовать PowerShell для создания проекта maven. Сначала выполните команду maven, чтобы создать проект maven:

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

Параметр	Описание
`-DGroupId`	Идентификатор группы однозначно идентифицирует проект во всех проектах
`-DartifactId`	Имя проекта. Она создается в качестве новой папки.
`-DarchetypeArtifactId`	тип проекта. `maven-archetype-quickstart` приводит к примеру проекта.
`-DinteractiveMode`	Параметр для `false` получения результатов в пустом проекте Java с параметрами по умолчанию.

Установка пакетов

Чтобы использовать пакет SDK для Java для Azure Карты, необходимо установить все необходимые пакеты. Каждая служба в Azure Карты доступна в собственном пакете. Службы Azure Карты включают поиск, отрисовку, трафик, погоду и т. д. Необходимо установить только пакеты для службы или служб, используемых в проекте.

После создания проекта maven должен быть pom.xml файл с основными сведениями, такими как идентификатор группы, имя, идентификатор артефакта. Затем добавьте зависимость для каждой из служб Azure Карты, как показано в следующем примере:

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

Запустите mvn clean install проект, а затем создайте файл Java с именем demo.java и импортируйте необходимые данные из Azure maps в файл:

cd DemoProject
New-Item demo.java

Совет

Если выполнение mvn clean install приводит к ошибке, попробуйте выполнить команду mvn clean install -U.

Службы Azure Maps

Имя службы	Пакет Maven	Образцы
Поиск	azure-maps-search	Примеры поиска
Маршрутизация	маршрутизация azure-maps	Примеры маршрутизации
Отрисовка	отрисовка azure-maps	Пример отрисовки
Геопозиционирование	azure-maps-geolocation	Пример географического расположения
Часовой пояс	часовой пояс azure-maps	Примеры часового пояса

Создание и проверка подлинности Карты SearchClient

Клиентский объект, используемый для доступа к API поиска Azure Карты, требуетAzureKeyCredential, чтобы объект прошел проверку подлинности при использовании ключа подписки Azure Карты или объекта TokenCredential с идентификатором клиента Azure Карты при проверке подлинности с помощью идентификатора Microsoft Entra. Дополнительные сведения о проверке подлинности см. в статье "Проверка подлинности с помощью Azure Карты".

Использование учетных данных Microsoft Entra

Вы можете пройти проверку подлинности с помощью идентификатора Microsoft Entra с помощью библиотеки удостоверений Azure. Чтобы использовать поставщик DefaultAzureCredential , необходимо добавить зависимость mvn в pom.xml файл:

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

Необходимо зарегистрировать новое приложение Microsoft Entra и предоставить доступ к Azure Карты, назначив необходимую роль субъекту-службе. Дополнительные сведения см. в статье "Размещение управляющей программы" в ресурсах, отличных от Azure. Возвращаются идентификатор приложения (клиента), идентификатор каталога (клиента) и секрет клиента. Скопируйте эти значения и сохраните их в безопасном месте. Вам потребуется выполнить следующие действия.

Задайте значения идентификатора приложения (клиента), идентификатор каталога (клиента) и секрет клиента приложения Microsoft Entra и идентификатор клиента карты в качестве переменных среды:

Переменная среды	Description
AZURE_CLIENT_ID	Идентификатор приложения (клиента) в зарегистрированном приложении
AZURE_CLIENT_SECRET	Значение секрета клиента в зарегистрированном приложении
AZURE_TENANT_ID	Идентификатор каталога (клиента) в зарегистрированном приложении
MAPS_CLIENT_ID	Идентификатор клиента в учетной записи Azure Map

Теперь можно создать переменные среды в PowerShell для хранения следующих значений:

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

После настройки переменных среды их можно использовать в программе для создания экземпляра AzureMapsSearch клиента:

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

Важно!

Другие переменные среды, созданные в предыдущем фрагменте кода, не используемые в примере кода, требуются.DefaultAzureCredential() Если эти переменные среды не заданы правильно, используя те же соглашения об именовании, вы получите ошибки во время выполнения. Например, если AZURE_CLIENT_ID отсутствует или недопустимая InvalidAuthenticationTokenTenant ошибка.

Использование учетных данных ключа подписки

Вы можете пройти проверку подлинности с помощью ключа подписки Azure Карты. Ключ подписки можно найти в разделе "Проверка подлинности" в учетной записи azure Карты, как показано на следующем снимке экрана:

Теперь можно создать переменные среды в PowerShell для хранения ключа подписки:

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

После создания переменной среды вы можете получить доступ к ней в коде:

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

Нечеткий поиск сущности

В следующем фрагменте кода показано, как в простом консольном приложении azure-maps-search импортировать пакет и выполнить нечеткий поиск в "Starbucks" недалеко от Сиэтла:

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

В этом фрагменте кода показано, как создать MapsSearchClient объект с помощью учетных данных Azure. Сначала создайте AzureKeyCredential экземпляр с помощью ключа подписки azure Карты, а затем передает учетные данные для создания экземпляровMapsSearchClient. MapsSearchClient такие методы, как FuzzySearch можно использовать имя "Starbucks" и координаты GeoPosition(-122.31, 47.61).

Выполните программу из папки проекта в командной строке:

java .\demo.java

Вы увидите список адресов и координат Starbucks:

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

Поиск адреса

SearchAddress Вызовите метод, чтобы получить координату адреса. Измените основную программу из примера следующим образом:

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

В этом примере метод возвращает результаты, client.SearchAddress упорядоченные по оценке достоверности, и выводит координаты первого результата.

Пакетный обратный поиск

Поиск Карты Azure также предоставляет некоторые методы пакетного запроса. Эти методы возвращают объекты Long Running Operations (LRO). Запросы могут не сразу возвращать все результаты, чтобы пользователи могли ждать завершения или периодически запрашивать результат, как показано в методе обратного поиска пакетной службы:

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

Share via