Краткое руководство. Создание приложения Android с помощью Azure Карты

Статья
03/24/2023

В этой статье показано, как добавить Azure Maps в Android-приложение. В этом руководстве описывается:

Настройте среду разработки.
создание учетной записи службы Azure Maps;
получение первичного ключа Azure Maps для использования в приложении;
ссылка на библиотеки Azure Maps из проекта;
добавление в приложение элемента управления Azure Maps.

Примечание.

Прекращение использования пакета SDK для Android для Azure Карты

Пакет SDK для машинного кода Azure для Android Карты теперь устарел и будет прекращен 3.31.25. Чтобы избежать сбоев в работе служб, перейдите в веб-пакет SDK для Azure Карты на 3.31.25. Дополнительные сведения см. в руководстве по миграции пакета SDK для Android Карты Azure.

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

Подписка на Microsoft Azure. Если у вас нет подписки Azure, создайте бесплатную учетную запись, прежде чем приступить к работе.
Android Studio. Если у вас нет Android Studio, вы можете бесплатно получить его от Google.

Примечание.

Многие инструкции в этом кратком руководстве были созданы с помощью Android Studio Arctic Fox (2020.3.1). Если вы используете другую версию Android Studio, действия, характерные для Android Studio, могут отличаться.

Создайте учетную запись службы Azure Maps.

Создайте учетную запись службы Azure Maps с помощью приведенных ниже действий.

В верхнем левом углу окна портала Azure щелкните Создать ресурс.
В поле Поиск в Marketplace введите Azure Maps, а затем выберите Azure Maps в результатах поиска.
Выберите кнопку Создать.
На странице Создание учетной записи Azure Maps введите следующие значения:
- Подписку, которую необходимо использовать для этой учетной записи.
- Имя группы ресурсов для этой учетной записи. Вы создать новую или использовать существующую группу ресурсов.
- Имя новой учетной записи.
- Ценовая категория этой учетной записи. Выберите Gen2 (2-е поколение).
- Ознакомьтесь с условиями и установите флажок, чтобы подтвердить, что вы прочитали и согласны с лицензионным соглашением и заявлением о конфиденциальности.
- Нажмите кнопку Просмотреть и создать.
- Убедившись, что все правильно на странице проверки и создания , нажмите кнопку "Создать ".

Получение ключа подписки для учетной записи.

После успешного создания учетной записи Azure Карты получите ключ подписки, который позволяет запрашивать API Карты.

Откройте учетную запись службы Azure Maps на портале.
В левой области выберите Проверка подлинности.
Скопируйте первичный ключ и сохраните его локально, чтобы использовать далее в этом руководстве.

Примечание.

В целях безопасности рекомендуется чередовать первичный и вторичный ключи. Для этого обновите приложение, чтобы использовать вторичный ключ, разверните его, а затем нажмите кнопку цикла/обновления рядом с первичным ключом, чтобы создать первичный ключ. Старый первичный ключ будет отключен. Дополнительные сведения о смене ключей см. в статье Настройка Azure Key Vault с помощью смены ключей и аудита.

Создание проекта в Android Studio

Выполните следующие действия, чтобы создать новый проект с пустым действием в Android Studio.

Запустите Android Studio и выберите в меню Файл пункты Создать и Новый проект…
На экране Новый проект выберите Телефон и планшет в списке Шаблоны в левой части экрана.
Выберите Пустое действие в списке шаблонов, а затем нажмите кнопку Далее.
На экране "Пустое действие" введите значения для следующих полей:
- Имя. Введите AzureMapsApp.
- Имя пакета. Используйте значение по умолчанию com.example.azuremapsapp.
- Путь для сохранения. Используйте значение по умолчанию или выберите новое расположение для сохранения файлов проекта. Не используйте пробелы в пути или имени файла из-за потенциальных проблем с инструментами NDK.
- Язык. Выберите Kotlin или Java.
- Минимальный пакет Minimum SDK. Выберите API 21: Android 5.0.0 (Lollipop) в качестве минимального пакета SDK. Это самая ранняя версия, поддерживаемая пакетом SDK для Azure Карты Android.
Нажмите кнопку Готово, чтобы создать новый проект.

Дополнительные сведения об установке Android Studio и создании проекта см. в документации по Android Studio.

Настройка виртуального устройства

Android Studio позволяет настроить виртуальное устройство Android на вашем компьютере. Это позволит тестировать приложение во время разработки.

Чтобы настроить виртуальное устройство Android (AVD), выполните следующие действия.

Выберите Диспетчер AVD в меню Инструменты.
Появится виртуальная диспетчер устройств Android. Выберите Создание виртуального устройства.
В категории Phones (Телефоны) выберите Nexus 5X и щелкните Next (Далее).

Дополнительные сведения о настройке AVD см. в статье "Создание виртуальных устройств и управление ими" в документации по Android Studio.

Снимок экрана: экран выбора оборудования в диспетчере виртуальных устройств Android при создании виртуального устройства.

Установка пакета SDK для Android для Azure Maps

Следующим шагом при создании приложения является установка пакета SDK для Android для Azure Maps. Чтобы установить этот пакет SDK, выполните следующие действия.

Откройте файл параметров проекта settings.gradle и добавьте следующий код в раздел Репозитории:
```
maven {url "https://atlas.microsoft.com/sdk/android"}
```
В том же файле параметров проекта settings.gradle измените параметр repositoriesMode на PREFER_SETTINGS:
```
repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
```
Теперь файл параметров проекта должен выглядеть следующим образом:
Откройте файл gradle.properties проекта, убедитесь, что android.useAndroidX для android.enableJetifier этого задано trueзначение .

Если файл gradle.properties не содержит android.useAndroidX и android.enableJetifierдобавьте следующие две строки в конец файла:
```
android.useAndroidX=true
android.enableJetifier=true
```
Откройте файл build.gradle приложения и выполните следующие действия.
1. Убедитесь, что для параметра проекта minSdk установлено значение 21 или больше.
2. Убедитесь, что compileOptions в разделе Android выглядят следующим образом:
```
compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
}
```
3. Обновите блок зависимостей и добавьте новую зависимость реализации для последнего пакета SDK для Android в Azure Maps:
```
implementation 'com.azure.android:azure-maps-control:1.+'
```
4. Выберите Синхронизировать проект с файлами Gradle в меню Файл.
Добавьте фрагмент карты в основное действие:
```
<com.azure.android.maps.control.MapControl
    android:id="@+id/mapcontrol"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    />
```
Чтобы обновить основное действие, выберите app > res > layout >activity_main.xml в Навигаторе проекта.

В файле MainActivity.java:

Добавьте операции импорта для пакета SDK в Azure Maps.
Настройте сведения об аутентификации Azure Maps.
Получите экземпляр элемента управления картой в методе onCreate.

Совет

Если задать сведения о проверке подлинности глобально в классе AzureMaps с помощью методов setSubscriptionKey или setAadProperties, не нужно будет добавлять эти сведения в каждое представление.

Элемент управления картой содержит собственные методы жизненного цикла для управления жизненным циклом OpenGL Android. Они должны вызываться непосредственно из содержащего их действия. Чтобы правильно вызвать методы жизненного цикла элемента управления картой, переопределите следующие методы жизненного цикла в действии, который содержит элемент управления картой, а затем вызовите соответствующий метод управления картой.

onCreate(Bundle)
onDestroy()
onLowMemory()
onPause()
onResume()
onSaveInstanceState(Bundle)
onStart()
onStop()

Измените файл MainActivity.java следующим образом:

package com.example.azuremapsapp;

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import com.azure.android.maps.control.AzureMaps;
import com.azure.android.maps.control.MapControl;
import com.azure.android.maps.control.layer.SymbolLayer;
import com.azure.android.maps.control.options.MapStyle;
import com.azure.android.maps.control.source.DataSource;

public class MainActivity extends AppCompatActivity {

static {
    AzureMaps.setSubscriptionKey("<Your-Azure-Maps-Primary-Subscription-Key>");

    //Alternatively use Azure Active Directory authenticate.
    //AzureMaps.setAadProperties("<Your-AAD-clientId>", "<Your-AAD-appId>", "<Your-AAD-tenant>");
}

MapControl mapControl;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    mapControl = findViewById(R.id.mapcontrol);

    mapControl.onCreate(savedInstanceState);

    //Wait until the map resources are ready.
    mapControl.onReady(map -> {

        //Add your post map load code here.

    });
}

@Override
public void onResume() {
    super.onResume();
    mapControl.onResume();
}

@Override
protected void onStart(){
    super.onStart();
    mapControl.onStart();
}

@Override
public void onPause() {
    super.onPause();
    mapControl.onPause();
}

@Override
public void onStop() {
    super.onStop();
    mapControl.onStop();
}

@Override
public void onLowMemory() {
    super.onLowMemory();
    mapControl.onLowMemory();
}

@Override
protected void onDestroy() {
    super.onDestroy();
    mapControl.onDestroy();
}

@Override
protected void onSaveInstanceState(Bundle outState) {
    super.onSaveInstanceState(outState);
    mapControl.onSaveInstanceState(outState);
}}

В файле MainActivity.kt:

добавить операции импорта для пакета SDK в Azure Maps;
настроить сведения о проверке подлинности Azure Maps;
получить экземпляр элемента управления картой в методе onCreate.

Совет

Элемент управления картой содержит собственные методы жизненного цикла для управления жизненным циклом OpenGL Android. Они должны вызываться непосредственно из содержащего их действия. Чтобы правильно вызвать методы жизненного цикла элемента управления картой, переопределите следующие методы жизненного цикла в действии, который содержит элемент управления картой. Необходимо вызывать соответствующий метод элемента управления картой.

onCreate(Bundle)
onDestroy()
onLowMemory()
onPause()
onResume()
onSaveInstanceState(Bundle)
onStart()
onStop()

Измените файл MainActivity.kt следующим образом:

package com.example.azuremapsapp;

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import com.azure.android.maps.control.AzureMap
import com.azure.android.maps.control.AzureMaps
import com.azure.android.maps.control.MapControl
import com.azure.android.maps.control.events.OnReady

class MainActivity : AppCompatActivity() {

    companion object {
        init {
            AzureMaps.setSubscriptionKey("<Your-Azure-Maps-Primary-Subscription-Key>");

            //Alternatively use Azure Active Directory authenticate.
            //AzureMaps.setAadProperties("<Your-AAD-clientId>", "<Your-AAD-appId>", "<Your-AAD-tenant>");
        }
    }

    var mapControl: MapControl? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        mapControl = findViewById(R.id.mapcontrol)

        mapControl?.onCreate(savedInstanceState)

        //Wait until the map resources are ready.
        mapControl?.onReady(OnReady { map: AzureMap -> })
    }

    public override fun onStart() {
        super.onStart()
        mapControl?.onStart()
    }

    public override fun onResume() {
        super.onResume()
        mapControl?.onResume()
    }

    public override fun onPause() {
        mapControl?.onPause()
        super.onPause()
    }

    public override fun onStop() {
        mapControl?.onStop()
        super.onStop()
    }

    override fun onLowMemory() {
        mapControl?.onLowMemory()
        super.onLowMemory()
    }

    override fun onDestroy() {
        mapControl?.onDestroy()
        super.onDestroy()
    }

    override fun onSaveInstanceState(outState: Bundle) {
        super.onSaveInstanceState(outState)
        mapControl?.onSaveInstanceState(outState)
    }
}

Нажмите на панели инструментов кнопку выполнения, как показано на следующем рисунке (или нажмите Control + R на компьютере Mac), чтобы выполнить сборку приложения.

Android Studio занимает несколько секунд, чтобы создать приложение. После этого вы сможете протестировать приложение на эмулированном устройстве Android. Должна отобразиться карта примерно следующего вида.

Снимок экрана: Azure Maps в приложении Android.

Совет

По умолчанию Android перезагрузит действие, если ориентация изменяется или клавиатура скрыта. Это приводит к сбросу состояния карты (перезагрузите карту, которая сбрасывает представление и перезагружает данные в начальное состояние). Чтобы предотвратить это, добавьте следующее в mainfest: android:configChanges="orientation|keyboardHidden" Это приведет к остановке перезагрузки и вместо этого вызовет onConfigurationChanged() , когда ориентация изменилась или клавиатура скрыта.

Очистка ресурсов

Предупреждение

В следующих учебниках в разделе Дальнейшие действия подробно описывается использование и настройка службы Azure Maps с помощью учетной записи. Если вы намерены перейти к их изучению, не удаляйте ресурсы, созданные при работе с этим кратким руководством.

Если вы не намерены продолжать изучение учебников, выполните следующие действия, чтобы удалить ресурсы.

Закройте Android Studio и удалите созданное приложение.
Если вы тестировали приложение на внешнем устройстве, удалите приложение с этого устройства.

Если вы не планируете продолжать разработку с помощью пакета SDK для Android для Azure Maps:

Перейдите на страницу портала Azure. На главной странице портала выберите Все ресурсы.
Выберите свою учетную запись службы Azure Maps. В верхней части страницы выберите команду Удалить.
Кроме того, если вы не планируете продолжать разработку приложений для Android, удалите Android Studio.

Дополнительные примеры кода см. в следующих руководствах:

Следующие шаги

В этом кратком руководстве вы создали учетную запись службы Azure Maps и запустили демоверсию приложения. Сведения об Azure Maps см. в этих руководствах:

Руководство. Загрузка данных GeoJSON в пакет SDK для Android для Azure Карты

Краткое руководство. Создание приложения Android с помощью Azure Карты

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

Создайте учетную запись службы Azure Maps.

Получение ключа подписки для учетной записи.

Создание проекта в Android Studio

Настройка виртуального устройства

Установка пакета SDK для Android для Azure Maps

Очистка ресурсов

Следующие шаги

Дополнительные ресурсы