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

發行項
04/07/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 金鑰保存庫。

在 Android Studio 中建立專案

完成下列步驟，以在Android Studio中建立具有空白活動的新專案：

啟動 Android Studio，然後從 [檔案] 功能選取 [新增]，然後選取 [新增專案...]。
在 [新增專案] 畫面中，從畫面左側的 [範本] 清單中選取 [電話] 和 [平板計算機]。
從範本清單中選取 [空白活動 ]，然後 選取 [下一步]。
在 [ 空白活動] 畫面中，輸入下列欄位的值：
- 名稱. 輸入 Azure 地圖 App。
- 套件名稱。使用預設 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. 請確定您在 compileOptions 區 Android 段中的動作如下：
```
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"
    />

若要更新主要活動，請在 [項目導覽器] 中選取應用程式>重新>>設定activity_main.xml：

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

在 MainActivity.java 檔案中：

新增 Azure 地圖服務 SDK 的匯入。
設定您的 Azure 地圖服務驗證資訊。
在 onCreate 方法中取得對應控件實例。

提示

藉由使用 setSubscriptionKey 或 setAadProperties 方法在 AzureMaps 類別中全域設定驗證資訊，您就不需要在每個檢視中新增驗證資訊。

地圖控制項包含其本身用來管理 Android OpenGL 生命週期的生命週期方法。這些生命週期方法必須直接從包含的活動呼叫。若要正確呼叫地圖控件的生命週期方法，請在包含地圖控件的 Activity 中覆寫下列生命週期方法，然後呼叫個別的地圖控件方法。

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 生命週期的生命週期方法。這些生命週期方法必須直接從包含的活動呼叫。若要正確呼叫地圖控件的生命週期方法，請在包含地圖控件的 Activity 中覆寫下列生命週期方法。而且，您必須呼叫個別的地圖控件方法。

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 裝置中測試您的應用程式。您應該會看到類似下面的地圖：

顯示Android應用程式中 Azure 地圖服務的螢幕快照。

提示

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

清除資源

警告

後續步驟一節所列的教學課程詳細說明如何使用和設定帳戶 Azure 地圖服務。如果您打算繼續進行教學課程，請勿清除本快速入門中建立的資源。

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

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

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

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

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

下一步

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

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

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