快速入門：使用 Azure 地圖服務建立 Android 應用程式

發行項
08/08/2024

本文說明如何將 Azure 地圖服務新增至 Android 應用程式。文中會逐步引導您完成下列基本步驟：

設定您的開發環境。
建立您自己的 Azure 地圖服務帳戶。
取得您的主要 Azure 地圖服務金鑰以在應用程式中使用。
從專案參考 Azure 地圖服務程式庫。
將 Azure 地圖服務控制項新增至應用程式。

注意

Azure 地圖服務 Android SDK 淘汰

適用於 Android 的 Azure 地圖服務原生 SDK 現已被取代，將於 3/31/25 淘汰。若要避免服務中斷，請在 3/31/25 之前遷移至 Azure 地圖服務 Web SDK。如需詳細資訊，請參閱 Azure 地圖服務 Android SDK 移轉指南 (部分機器翻譯)。

必要條件

訂閱 Microsoft Azure。如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。
Android Studio. 如果您沒有 Android Studio，可從 Google 免費取得。

注意

本快速入門中的許多指示都是使用 Android Studio Arctic Fox (2020.3.1) 所建立。如果您使用不同版本的 Android Studio，則 Android Studio 的特定步驟可能會有所不同。

建立 Azure 地圖服務帳戶

使用下列步驟建立新的 Azure 地圖服務帳戶：

在 Azure 入口網站的左上角選取 [建立資源]。
在 [搜尋 Marketplace] 方塊中，輸入 Azure 地圖服務，然後從搜尋結果中選取 [Azure 地圖服務]。
選取建立按鈕。
在 [建立地圖服務帳戶] 頁面上輸入下列值：
- 您想要使用於此帳戶的 [訂用帳戶]。
- 此帳戶的 [資源群組] 名稱。您可以選擇 [建立新的] 或 [使用現有的] 資源群組。
- 新帳戶的 [名稱]。
- 此帳戶的 [定價層]。選取 Gen2。
- 閱讀條款，並勾選核取方塊，以確認您已閱讀並同意授權和隱私權聲明。
- 選取 [檢閱 + 建立] 按鈕。
- 一旦您確定 [檢閱 + 建立] 頁面中的所有項目都正確，請選取 [建立] 按鈕。

取得您帳戶的訂用帳戶金鑰

成功建立 Azure 地圖服務帳戶後，擷取訂用帳戶金鑰以便能查詢地圖服務 API。

在入口網站中開啟 Azure 地圖服務帳戶。
在左窗格中，選取 [驗證]。
複製 [主索引鍵] 並在本機加以儲存，以供本教學課程稍後使用。

注意

為了安全起見，建議您在主要和次要金鑰之間輪替。若要輪替金鑰，將您的應用程式更新為使用次要金鑰，部署，然後按下主要金鑰旁的循環/重新整理按鈕，以產生新的主要金鑰。舊的主要金鑰將會停用。如需金鑰輪替的詳細資訊，請參閱使用金鑰輪替和稽核來設定 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 地圖服務 Android SDK 所支援的最早版本。
選取 [完成] 以建立您的新專案。

請參閱 Android Studio 文件，以取得更多如何安裝 Android Studio 並建立新專案的說明。

設定虛擬裝置

Android Studio 可讓您在電腦上設定虛擬 Android 裝置。這麼做可以協助您在開發期間測試應用程式。

若要設定 Android 虛擬裝置 (AVD)：

在 [工具] 功能表中選取 [AVD 管理員]。
隨即出現 [Android 虛擬裝置管理員]。選取 [建立虛擬裝置]
在 [手機] 類別中選取 [Nexus 5X]，然後選取 [下一步]。

如需設定 AVD 的詳細資訊，請參閱 Android Studio 文件中的建立和管理虛擬裝置。

顯示建立新虛擬設備時，Android 虛擬裝置管理員中 [選取硬體] 畫面的螢幕快照。

安裝 Azure 地圖服務 Android SDK

建置應用程式的下一步是安裝 Azure 地圖服務 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 地圖服務 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"
    />

若要更新主要活動，請在 [專案導覽器] 中選取應用程式 > res > 配置 >activity_main.xml：

顯示 Android Studio 中 [項目導覽器] 窗格中activity_main.xml檔案的螢幕快照。

在 MainActivity.java 檔案中：

新增 Azure 地圖服務 SDK 的匯入。
設定您的 Azure 地圖服務驗證資訊。
在 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 地圖服務 SDK 的匯入
設定您的 Azure 地圖服務驗證資訊
在 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 地圖服務的螢幕快照。

提示

根據預設，Android 會在方向變更或隱藏鍵盤時重新載入活動。這會導致地圖狀態重設 (重新載入地圖，以重新載入檢視並將資料重新載入至初始狀態)。若要避免發生這種情況，請將下列內容新增至 mainfest：android:configChanges="orientation|keyboardHidden"。這會阻止活動重新載入，而是在方向變更或隱藏鍵盤時呼叫 onConfigurationChanged()。

清除資源

警告

後續步驟一節中所列出的教學課程詳述了如何利用您的帳戶來使用及設定 Azure 地圖服務。如果您打算繼續進行教學課程，請勿清除在此快速入門中建立的資源。

如果您不打算繼續教學課程，則請採取下列步驟來清除資源：

關閉 Android Studio，並刪除您建立的應用程式。
如果您已在外部裝置上測試應用程式，請將該裝置上的應用程式解除安裝。

如果您不打算繼續使用 Azure 地圖服務 SDK 來開發：

瀏覽至 Azure 入口網站頁面。從主要入口網站頁面中選取 [所有資源]。
選取您的 Azure 地圖服務帳戶。在頁面頂端，選取 [刪除]。
或者，如果您不打算繼續開發 Android 應用程式，請將 Android Studio 解除安裝。

如需更多程式碼範例，請參閱下列指南：

下一步

在本快速入門中，您已建立 Azure 地圖服務帳戶，並建立了示範應用程式。查看下列教學課程，以深入了解 Azure 地圖服務：

教學課程：將 GeoJSON 資料載入 Azure 地圖服務 Android SDK

共用方式為