你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：使用 Azure Maps 创建 Android 应用

项目
04/08/2024

本文介绍如何将 Azure Maps 添加到 Android 应用。本文演示如何完成以下基本步骤：

设置开发环境。
创建自己的 Azure Maps 帐户。
获取主 Azure Maps 密钥以在应用中使用。
从项目中引用 Azure Maps 库。
将 Azure Maps 控件添加到应用。

注意

Azure Maps Android SDK 停用

适用于 Android 的 Azure Maps 本机 SDK 现已弃用，将于 2025 年 3 月 31 日停用。为了避免服务中断，请在 2025 年 3 月 31 日之前迁移到 Azure Maps Web SDK。有关详细信息，请参阅 Azure Maps Android SDK 迁移指南。

先决条件

Microsoft Azure 订阅。如果还没有 Azure 订阅，可以在开始前创建一个免费帐户。
Android Studio。如果没有 Android Studio，可以从 Google 免费获取。

注意

本快速入门中的许多说明都是使用 Android Studio Arctic Fox (2020.3.1) 创建的。如果使用不同版本的 Android Studio，则 Android Studio 的具体步骤可能会有所不同。

创建 Azure Maps 帐户

使用以下步骤创建新的 Azure Maps 帐户：

在 Azure 门户的左上角选择“创建资源”。
在“在市场中搜索”框中，键入“Azure Maps”，然后从搜索结果中选择“Azure Maps”。
选择“创建”按钮。
在“创建 Maps 帐户”页上，输入以下值：
- 要用于此帐户的订阅。
- 此帐户的资源组名称。可以选择新建或使用现有的资源组。
- 新帐户的名称。
- 此帐户的定价层。选择“Gen2”。
- 阅读条款，并选中复选框以确认已阅读并同意许可和隐私声明。
- 选择“查看 + 创建”按钮。
- 确保“审阅 + 创建”页中所有内容正确后，选择“创建”按钮。

获取帐户的订阅密钥

成功创建 Azure Maps 帐户后，请检索支持你查询 Maps API 的订阅密钥。

在门户中打开 Azure Maps 帐户。
在左窗格中，选择“身份验证”。
辅助主密钥，并在本地保存它以便稍后在本教程中使用。

注意

出于安全考虑，建议轮换使用主密钥和辅助密钥。若要轮换密钥，请更新应用以使用辅助密钥、进行部署，然后按主密钥旁边的循环/刷新按钮以生成新的主密钥。将禁用旧的主密钥。有关密钥轮换的详细信息，请参阅使用密钥轮换和审核功能设置 Azure Key Vault。

在 Android Studio 中创建项目

完成以下步骤，以在 Android Studio 中创建一个包含空活动的新项目：

启动 Android Studio 并从“文件”菜单中选择“新建”，然后选择“新项目...”
在“新项目”屏幕中，从屏幕左侧的“模板”列表中选择“手机和平板电脑”。
从模板列表中选择“空活动”，然后选择“下一步”。
在“空活动”屏幕中，需要输入以下字段的值：
- 名称。输入“AzureMapsApp”。
- 包名。使用默认的“com.example.azuremapsapp”。
- 保存位置。使用默认值或选择一个新位置来保存项目文件。由于 NDK 工具可能存在问题，请避免在路径或文件名中使用空格。
- 语言。选择 Kotlin 或 Java。
- 最低 SDK。选择 API 21: Android 5.0.0 (Lollipop) 作为最低 SDK。这是 Azure Maps Android SDK 支持的最旧版本。
选择“完成”以创建新项目。

安装 Android Studio 和创建新项目时如需更多帮助，请参阅 Android Studio 文档。

设置虚拟设备

Android Studio 可让你在计算机上设置 Android 虚拟设备。这样做有助于在开发期间测试应用程序。

要设置 Android 虚拟设备 (AVD)，请执行以下操作：

在“工具”菜单中选择“AVD 管理器”。
将会显示“Android 虚拟设备管理器”。选择“创建虚拟设备”。
在“Phones”（手机）类别中选择“Nexus 5X”，然后选择“Next”（下一步）。

有关设置 AVD 的详细信息，请参阅 Android Studio 文档中的创建和管理虚拟设备。

创建新虚拟设备时，显示 Android 虚拟设备管理器中“选择硬件”屏幕的屏幕截图。

安装 Azure Maps Android SDK

生成应用程序的下一步是安装 Azure Maps Android SDK。请完成以下步骤来安装该 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. 确保在 Android 部分中的 compileOptions 如下所示：
```
compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
}
```
3. 更新依赖项块，并为最新 Azure Maps Android SDK 添加新的实现依赖项：
```
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"
    />
```
要更新主活动，请在“项目导航器”中选择“应用”>“存储库”>“布局”>“activity_main.xml”：

在 MainActivity.java 文件中：

为 Azure Maps SDK 添加 import 语句。
设置 Azure Maps 身份验证信息。
在 onCreate 方法中获取地图控件实例。

提示

使用 setSubscriptionKey 或 setAadProperties 方法在 AzureMaps 类中全局设置身份验证信息后，无需在每个视图中添加身份验证信息。

地图控件包含自身的生命周期方法用于管理 Android 的 OpenGL 生命周期。必须直接从包含活动调用这些生命周期方法。要正确调用地图控件的生命周期方法，请在包含地图控件的活动中替代以下生命周期方法，并调用相应的地图控制方法。

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 文件中：

添加 Azure Maps SDK 的 import 语句
设置 Azure Maps 身份验证信息
在 onCreate 方法中获取地图控件实例

提示

使用 setSubscriptionKey 或 setAadProperties 方法在 AzureMaps 类中全局设置身份验证信息后，无需在每个视图中添加身份验证信息。

地图控件包含自身的生命周期方法用于管理 Android 的 OpenGL 生命周期。必须直接从包含活动调用这些生命周期方法。要正确调用地图控件的生命周期方法，请在包含地图控件的活动中替代以下生命周期方法。并且，必须调用相应的地图控件方法。

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

如下图所示，选择工具栏中的“运行”按钮（或者在 Mac 上按 Control + R）来生成应用程序。

Android Studio 将花费几秒钟时间来生成应用程序。生成完成后，可在 Android 仿真设备中测试应用程序。应会看到如下所示的地图：

在 Android 应用程序中显示 Azure Maps 的屏幕截图。

提示

默认情况下，当方向更改或键盘处于隐藏状态时，Android 会重新加载活动。这会导致映射状态重置（重新加载映射，从而重置视图并将数据重新加载到初始状态）。若要防止这种情况发生，请将以下内容添加到清单：android:configChanges="orientation|keyboardHidden"。这将停止重新加载活动，但会在方向更改或键盘隐藏时调用 onConfigurationChanged()。

清理资源

警告

后续步骤部分中列出的教程详细介绍了如何通过帐户使用和配置 Azure Maps。如何打算继续学习这些教程，请勿清除本快速入门中创建的资源。

如果不打算继续学习这些教程，请通过以下步骤来清理资源：

关闭 Android Studio 并删除你创建的应用程序。
如果在外部设备上测试了应用程序，请从该设备上卸载它。

如果不打算继续使用 Azure Maps Android SDK 进行开发，请执行以下操作：

导航到 Azure 门户页面。选择门户主页中的“所有资源”。
选择你的 Azure Maps 帐户。在页面顶部，选择“删除”。
如果不打算继续开发 Android 应用，请卸载 Android Studio。

有关更多代码示例，请参阅以下指南：

后续步骤

在本快速入门中，你创建了 Azure Maps 帐户和演示版应用程序。请查看以下教程，详细了解 Azure Maps：

教程：将 GeoJSON 数据加载到 Azure Maps Android SDK 中