Schnellstart: Erstellen einer Android-App mit Azure Maps

  • Artikel

In diesem Artikel wird beschrieben, wie Sie Azure Maps einer Android-App hinzufügen. Die folgenden grundlegenden Schritte werden erläutert:

  • Einrichten Ihrer Entwicklungsumgebung.
  • Erstellen eines eigenen Azure Maps-Kontos
  • Abrufen Ihres primären Azure Maps-Schlüssels für die Verwendung in der App
  • Verweisen auf die Azure Maps-Bibliotheken aus dem Projekt
  • Hinzufügen eines Azure Maps-Steuerelements zur App

Hinweis

Einstellung des Azure Maps Android SDK

Das Azure Maps Native SDK für Android ist jetzt veraltet und wird am 3.31.25 eingestellt. Um Dienstunterbrechungen zu vermeiden, migrieren Sie bis zum 31.03.2025 zum Azure Maps Web SDK. Weitere Informationen finden Sie im Migrationshandbuch zum Azure Maps iOS SDK.

Voraussetzungen

  1. Ein Abonnement für Microsoft Azure. Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.

  2. Android Studio Wenn Sie nicht über Android Studio verfügen, können Sie die IDE kostenlos von Google herunterladen.

Hinweis

Viele der Anweisungen in dieser Schnellstartanleitung wurden mit Android Studio Arctic Fox (2020.3.1) erstellt. Wenn Sie eine andere Version von Android Studio verwenden, können die für Android Studio geltenden Arbeitsschritte variieren.

Erstellen eines Azure Maps-Kontos

Führen Sie die folgenden Schritte durch, um ein neues Azure Maps-Konto zu erstellen:

  1. Wählen Sie im Azure-Portal in der linken oberen Ecke die Option Ressource erstellen aus.

  2. Geben Sie im Suchfeld Marketplace durchsuchen den Suchbegriff Azure Maps ein und wählen Sie Azure Maps in den Ergebnissen aus.

  3. Wählen Sie die Schaltfläche Erstellen.

  4. Geben Sie auf der Seite Azure Maps-Konto erstellen die folgenden Werte ein:

    • Abonnement, das Sie für dieses Konto verwenden möchten
    • Name der Ressourcengruppe für dieses Konto. Sie können für die Ressourcengruppe die Option Neu erstellen oder die Option Vorhandene verwenden auswählen.
    • Name des neuen Kontos
    • Der Tarif für dieses Konto. Wählen Sie Gen2.
    • Lesen Sie die Bestimmungen, und aktivieren Sie das Kontrollkästchen, um zu bestätigen, dass Sie die Lizenz- und Datenschutzbestimmungen gelesen haben und diesen zustimmen.
    • Wählen Sie die Schaltfläche Überprüfen + erstellen aus.
    • Nachdem Sie sich auf der Seite Überprüfen + erstellen vergewissert haben, dass alles richtig ist, wählen Sie die Schaltfläche Erstellen aus.

    Ein Screenshot, der den Bereich

Abrufen des Abonnementschlüssels für Ihr Konto

Rufen Sie nach der Erstellung des Azure Maps-Kontos den Abonnementschlüssel ab, mit dem Sie die Maps-APIs abfragen können.

  1. Öffnen Sie Ihr Azure Maps-Konto im Portal.
  2. Wählen Sie im linken Bereich Authentifizierung aus.
  3. Kopieren Sie den Primärschlüssel und speichern Sie ihn lokal zur späteren Verwendung in diesem Tutorial ab.

Hinweis

Aus Sicherheitsgründen wird empfohlen, dass Sie zwischen Ihrem Primär- und Sekundärschlüssel wechseln. Aktualisieren Sie zur Schlüsselrotation Ihre App, um den Sekundärschlüssel zu verwenden. Stellen Sie dann die App bereit, und drücken Sie die Taste für die Aktualisierung neben dem Primärschlüssel, um einen neuen Primärschlüssel zu generieren. Der alte Primärschlüssel wird deaktiviert. Weitere Informationen zur Schlüsselrotation finden Sie unter Einrichten von Azure Key Vault mit Schlüsselrotation und Überwachung.

Screenshot: Ihr Azure Maps-Abonnementschlüssel im Azure-Portal.

Erstellen eines Projekts in Android Studio

Führen Sie die folgenden Schritte durch, um ein neues Projekt mit einer leeren Aktivität in Android Studio zu erstellen:

  1. Starten Sie Android Studio, und wählen Sie aus dem Menü Datei die Option Neu und dann Neues Projekt... aus.

  2. Wählen Sie auf dem Bildschirm Neues ProjektPhone and Tablet (Smartphone und Tablet) aus der Liste Vorlagen auf der linken Seite des Bildschirms aus.

    Ein Screenshot zeigt den Bildschirm Neues Projekt in Android Studio.

  3. Wählen Sie aus der Liste mit den Vorlagen Empty activity (Leere Aktivität) und dann Weiter aus.

    Ein Screenshot, der den Bildschirm Leere Aktivität erstellen in Android Studio zeigt.

  4. Geben Sie im Bildschirm Empty Activity die Werte für die folgenden Felder ein:

    • Name. Geben Sie AzureMapsApp ein.
    • Paketname. Verwenden Sie den Standardnamen com.example.azuremapsapp.
    • Speicherort. Verwenden Sie den Standardspeicherort, oder wählen Sie einen neuen Speicherort, an dem Ihre Projektdateien gespeichert werden. Verwenden Sie im Pfad oder Dateinamen keine Leerzeichen, da sonst Probleme mit den NDK-Tools auftreten können.
    • Sprache: Wählen Sie Kotlin oder Java aus.
    • Minimales SDK. Wählen Sie API 21: Android 5.0.0 (Lollipop) als minimales SDK aus. Dies ist die älteste Version, die vom Android SDK in Azure Maps unterstützt wird.

  5. Wählen Sie Fertig stellen aus, um ein neues Projekt zu erstellen.

Weitere Informationen zur Installation von Android Studio und zur Erstellung eines neuen Projekts finden Sie in der Dokumentation zu Android Studio.

Einrichten eines virtuellen Geräts

Mit Android Studio können Sie ein virtuelles Android-Gerät auf Ihrem Computer einrichten. Auf diese Weise können Sie Ihre Anwendung während der Entwicklung testen.

So richten Sie das virtuelle Android-Gerät (AVD) ein:

  1. Wählen Sie im Menü Tools die Option AVD Manager (AVD-Manager) aus.
  2. Der Android Virtual Device Manager wird angezeigt. Wählen Sie Virtuelles Gerät erstellen aus.
  3. Wählen Sie in der Kategorie Telefone die Option Nexus 5X aus, und klicken Sie auf Weiter.

Weitere Informationen zum Einrichten einer AVD finden Sie unter Erstellen und Verwalten virtueller Geräte in der Android Studio-Dokumentation.

Ein Screenshot, der den Bildschirm Hardware auswählen im Android Virtual Geräte-Manager beim Erstellen eines neuen virtuellen Geräts zeigt.

Installieren des Android SDK für Azure Maps

Als nächstes müssen Sie zur Erstellung Ihrer Anwendung das Android SDK für Azure Maps installieren. Führen Sie die folgenden Schritte aus, um das SDK zu installieren:

  1. Öffnen Sie die Projekteinstellungsdatei settings.gradle, und fügen Sie dem Abschnitt Repositorys den folgenden Code hinzu:

    maven {url "https://atlas.microsoft.com/sdk/android"}

  2. Ändern Sie in der gleichen Projekteinstellungsdatei (settings.gradle) „repositoriesMode“ zu PREFER_SETTINGS:

    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)

    Ihre Projekteinstellungsdatei sollte nun wie folgt angezeigt werden:

    Ein Screenshot der Datei mit den Projekteinstellungen in Android Studio.

  3. Öffnen Sie die Datei gradle.properties des Projekts, und vergewissern Sie sich, dass android.useAndroidX und android.enableJetifier beide auf true festgelegt sind.

    Wenn die Datei gradle.propertiesandroid.useAndroidX und android.enableJetifier nicht enthält, fügen Sie die nächsten beiden Zeilen am Ende der Datei hinzu:

    android.useAndroidX=true
android.enableJetifier=true

  4. Öffnen Sie die Anwendungsdatei build.gradle, und führen Sie Folgendes durch:

    1. Vergewissern Sie sich, dass die minSdk Ihres Projekt 21 oder höher beträgt.

    2. Stellen Sie sicher, dass Ihre compileOptions im Abschnitt Android wie folgt lauten:

      compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
}

    3. Aktualisieren Sie Ihren Block „dependencies“ (Abhängigkeiten), und fügen Sie eine neue Implementierungsabhängigkeit für das neueste Android SDK von Azure Maps hinzu:

      implementation 'com.azure.android:azure-maps-control:1.+'

    4. Wählen Sie im Menü Datei die Option Sync Project with Gradle Files (Projekt mit Gradle-Dateien synchronisieren) aus.

    Ein Screenshot zeigt die Build-Dot-Gradle-Datei der Anwendung in Android Studio.

  5. Fügen Sie der Hauptaktivität ein Kartenfragment hinzu:

    <com.azure.android.maps.control.MapControl
    android:id="@+id/mapcontrol"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    />

    Wählen Sie „app“ > „res“ > „layout“ >activity_main.xml im Project navigator (Projektnavigator) aus, um die Hauptaktivität zu aktualisieren:

    Ein Screenshot zeigt die Datei activity_main.xml im Projektnavigator von Android Studio.

  1. In der Datei MainActivity.java:

    • Importe für das Azure Maps SDK hinzufügen
    • Legen Sie Ihre Azure Maps-Authentifizierungsinformationen fest.
    • Die Kartensteuerungsinstanz in der onCreate-Methode abrufen

    Tipp

    Wenn Sie die Authentifizierungsinformationen global in der AzureMaps-Klasse mithilfe der setSubscriptionKey- oder setAadProperties-Methoden festlegen, müssen Sie Ihre Authentifizierungsinformationen nicht in jeder Ansicht hinzufügen.

    Das Kartensteuerelement enthält eigene Lebenszyklusmethoden zur Verwaltung des OpenGL-Lebenszyklus von Android. Diese Lebenszyklusmethoden müssen direkt über die enthaltende Aktivität aufgerufen werden. Zum ordnungsgemäßen Aufrufen der Lebenszyklusmethoden des Kartensteuerelements überschreiben Sie die folgenden Lebenszyklusmethoden in der Aktivität, die das Kartensteuerelement enthält, und rufen dann die entsprechende Kartensteuerelementmethode auf.

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

    Bearbeiten Sie die Datei MainActivity.java wie folgt:

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

  1. In der Datei MainActivity.kt:

    • Hinzufügen von Importen für das Azure Maps SDK
    • Festlegen Ihrer Azure Maps-Authentifizierungsinformationen
    • Abrufen der Kartensteuerelementinstanz in der onCreate-Methode

    Tipp

    Wenn Sie die Authentifizierungsinformationen global in der AzureMaps-Klasse mithilfe der setSubscriptionKey- oder setAadProperties-Methoden festlegen, müssen Sie Ihre Authentifizierungsinformationen nicht in jeder Ansicht hinzufügen.

    Das Kartensteuerelement enthält eigene Lebenszyklusmethoden zur Verwaltung des OpenGL-Lebenszyklus von Android. Diese Lebenszyklusmethoden müssen direkt über die enthaltende Aktivität aufgerufen werden. Zum ordnungsgemäßen Aufrufen der Lebenszyklusmethoden des Kartensteuerelements überschreiben Sie die folgenden Lebenszyklusmethoden in der Aktivität, die das Kartensteuerelement enthält. Außerdem müssen Sie die entsprechende Kartensteuerelementmethode aufrufen.

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

    Bearbeiten Sie die Datei MainActivity.kt wie folgt:

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

  1. Wählen Sie wie im folgenden Bild dargestellt auf der Symbolleiste die Schaltfläche „Ausführen“ aus (oder drücken Sie Control + R auf einem Macintosh-Computer), um Ihre Anwendung zu erstellen.

    Ein Screenshot zeigt die Schaltfläche Ausführen in Android Studio.

Es dauert einige Sekunden, bis Android Studio die Anwendung erstellt hat. Nach Abschluss des Builds können Sie Ihre Anwendung auf dem emulierten Android-Gerät testen. Es sollte eine Zuordnung wie diese angezeigt werden:

Ein Bildschirmfoto zeigt Azure Maps in einer Android-Anwendung.

Tipp

Standardmäßig lädt Android die Aktivität neu, wenn sich die Ausrichtung ändert oder die Tastatur ausgeblendet ist. Dies führt dazu, dass der Kartenzustand zurückgesetzt wird (laden Sie die Karte neu, wodurch die Ansicht zurückgesetzt und die Daten im Anfangszustand neu geladen werden). Um dies zu verhindern, fügen Sie dem Manifest Folgendes hinzu: android:configChanges="orientation|keyboardHidden". Dadurch wird verhindert, dass die Aktivität erneut geladen wird, und stattdessen wird onConfigurationChanged() aufgerufen, wenn sich die Ausrichtung geändert hat oder die Tastatur ausgeblendet ist.

Bereinigen von Ressourcen

Warnung

In den Tutorials, die im Abschnitt Nächste Schritte aufgeführt sind, wird ausführlich erläutert, wie Sie Azure Maps mit Ihrem Konto verwenden und konfigurieren. Wenn Sie mit den Tutorials fortfahren möchten, sollten Sie die in diesem Schnellstart erstellten Ressourcen nicht bereinigen.

Falls Sie nicht mit den Tutorials fortfahren möchten, führen Sie die folgenden Schritte aus, um die Ressourcen zu bereinigen:

  1. Schließen Sie Android Studio, und löschen Sie die von Ihnen erstellte Anwendung.
  2. Falls Sie die Anwendung auf einem externen Gerät getestet haben, sollten Sie sie auf diesem Gerät deinstallieren.

Gehen Sie wie folgt vor, falls Sie die Entwicklungsarbeit mit dem Android SDK für Azure Maps nicht fortsetzen möchten:

  1. Navigieren Sie zur Seite mit dem Azure-Portal. Wählen Sie auf der Hauptseite des Portals Alle Ressourcen aus.
  2. Wählen Sie Ihr Azure Maps-Konto aus. Wählen Sie oben auf der Seite Löschen aus.
  3. Sie können Android Studio deinstallieren, falls Sie die Entwicklung von Android-Apps nicht fortsetzen möchten.

Weitere Codebeispiele finden Sie in den folgenden Leitfäden:

Nächste Schritte

In dieser Schnellstartanleitung haben Sie Ihr Azure Maps-Konto und eine Demoanwendung erstellt. Sehen Sie sich das folgende Tutorial an, um mehr über Azure Maps zu erfahren:

Tutorial: Laden von GeoJSON-Daten in das Android SDK für Azure Maps