Condividi tramite

Guida introduttiva: Creare un'app Android con Mappe di Azure

  • Articolo

Questo articolo illustra come aggiungere Mappe di Azure a un'app Android. L'articolo descrive le operazioni di base seguenti:

  • Configurare l'ambiente di sviluppo.
  • Creare un proprio account di Mappe di Azure.
  • Ottenere la chiave primaria di Mappe di Azure da usare nell'app.
  • Fare riferimento alle librerie di Mappe di Azure dal progetto.
  • Aggiungere un controllo di Mappe di Azure all'app.

Nota

Ritiro di Android SDK di Mappe di Azure

Azure Maps Native SDK per Android è ora deprecato e verrà ritirato il 3/31/25. Per evitare interruzioni del servizio, eseguire la migrazione al Web SDK di Mappe di Azure entro il 31/3/25. Per altre informazioni, vedere La guida alla migrazione di Android SDK di Mappe di Azure.

Prerequisiti

  1. Un abbonamento a Microsoft Azure. Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

  2. Android Studio. Se non hai Android Studio, puoi ottenerlo gratuitamente da Google.

Nota

Molte delle istruzioni contenute in questa guida introduttiva sono state create usando Android Studio Arctic Fox (2020.3.1). Se si usa una versione diversa di Android Studio, i passaggi specifici per Android Studio possono variare.

Creare un account di Mappe di Azure

Creare un nuovo account Mappe di Azure usando la procedura seguente:

  1. Nell'angolo superiore sinistro della portale di Azure selezionare Crea una risorsa.

  2. Nella casella Cerca nel Marketplace digitare Mappe di Azure, quindi selezionare Mappe di Azure nei risultati della ricerca.

  3. Selezionare il pulsante Crea.

  4. Nella pagina Crea account di Mappe immettere i valori seguenti:

    • La sottoscrizione da usare per l'account.
    • Il nome del gruppo di risorse per l'account. Per il gruppo di risorse è possibile selezionare l'opzione Crea nuovo o Usa esistente.
    • Il nome del nuovo account.
    • Piano tariffario dell'account. Selezionare Gen2.
    • Leggere le Condizioni e selezionare la casella di controllo per confermare di aver letto e accettato l'Informativa sulla licenza e la privacy.
    • Selezionare il pulsante Rivedi e crea.
    • Dopo aver verificato che tutto sia corretto nella pagina Rivedi e crea , selezionare il pulsante Crea .

    Screenshot che mostra il riquadro Crea account mappe nel portale di Azure.

Ottenere la chiave di sottoscrizione per l'account

Dopo aver creato correttamente l'account Mappe di Azure, recuperare la chiave di sottoscrizione che consente di eseguire query sulle API di Mappe.

  1. Aprire l'account Mappe di Azure nel portale.
  2. Nel riquadro sinistro selezionare Autenticazione.
  3. Copiare la chiave primaria e salvarla in locale per usarla più avanti in questa esercitazione.

Nota

Per motivi di sicurezza, è consigliabile ruotare tra le chiavi primarie e secondarie. Per eseguire la rotazione delle chiavi, aggiornare l'app per usare la chiave secondaria, distribuire, quindi premere il pulsante di ciclo/aggiornamento accanto alla chiave primaria per generare una nuova chiave primaria. La chiave primaria precedente verrà disabilitata. Per altre informazioni sulla rotazione delle chiavi, vedere Configurare Azure Key Vault con rotazione e controllo delle chiavi.

Screenshot che mostra la chiave di sottoscrizione di Mappe di Azure nel portale di Azure.

Creare un progetto in Android Studio

Completare i passaggi seguenti per creare un nuovo progetto con un'attività vuota in Android Studio:

  1. Avviare Android Studio e selezionare Nuovo dal menu File , quindi Nuovo progetto...

  2. Nella schermata Nuovo progetto selezionare Telefono e tablet dall'elenco Modelli sul lato sinistro della schermata.

    Screenshot che mostra la schermata Nuovo progetto in Android Studio.

  3. Selezionare Attività vuota nell'elenco dei modelli e quindi Avanti.

    Screenshot che mostra la schermata Crea un'attività vuota in Android Studio.

  4. Nella schermata Attività vuota immettere i valori per i campi seguenti:

    • Nome. Immettere AzureMapsApp.
    • Nome pacchetto. Usare l'app com.example.azuremapsapp predefinita.
    • Percorso di salvataggio. Usare il valore predefinito o selezionare un nuovo percorso per salvare i file di progetto. Evitare di usare spazi nel percorso o nel nome file a causa di potenziali problemi con gli strumenti NDK.
    • Lingua. Selezionare Kotlin o Java.
    • SDK minimo. Selezionare API 21: Android 5.0.0 (Lollipop) come SDK minimo. È la versione meno recente supportata dal Mappe di Azure Android SDK.

  5. Selezionare Fine per creare il nuovo progetto.

Vedere la documentazione di Android Studio per altre informazioni sull'installazione di Android Studio e la creazione di un nuovo progetto.

Configurare un dispositivo virtuale

Android Studio consente di configurare un dispositivo Android virtuale nel computer. Questa operazione può essere utile per testare l'applicazione durante lo sviluppo.

Per configurare un dispositivo virtuale Android :To set up an Android Virtual Device (AVD):

  1. Selezionare AVD Manager nel menu Strumenti .
  2. Viene visualizzata la Gestione dispositivi virtuale Android. Selezionare Crea dispositivo virtuale.
  3. Nella categoria Phones (Telefoni) selezionare Nexus 5X e quindi Next (Avanti).

Per altre informazioni sulla configurazione di un AVD, vedere Creare e gestire dispositivi virtuali nella documentazione di Android Studio.

Screenshot che mostra la schermata Seleziona hardware in Android Virtual Gestione dispositivi durante la creazione di un nuovo dispositivo virtuale.

Installare Android SDK per Mappe di Azure

Il passaggio successivo per la creazione dell'applicazione consiste nell'installare Android SDK per Mappe di Azure. Per installare l'SDK, seguire questa procedura:

  1. Aprire il file delle impostazioni del progetto settings.gradle e aggiungere il codice seguente alla sezione repository :

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

  2. Nello stesso file di impostazioni del progetto settings.gradle modificare repositoryMode in PREFER_SETTINGS:

    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)

    Il file delle impostazioni del progetto dovrebbe ora essere visualizzato come segue:

    Screenshot del file delle impostazioni del progetto in Android Studio.

  3. Aprire il file gradle.properties del progetto, verificare che android.useAndroidX e android.enableJetifier siano entrambi impostati su true.

    Se il file gradle.properties non include android.useAndroidX e android.enableJetifier, aggiungere le due righe successive alla fine del file:

    android.useAndroidX=true
android.enableJetifier=true

  4. Aprire il file build.gradle dell'applicazione ed eseguire le operazioni seguenti:

    1. Verificare che il valore minSdk del progetto sia 21 o superiore.

    2. Assicurarsi che compileOptions nella Android sezione siano i seguenti:

      compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
}

    3. Aggiornare il blocco delle dipendenze e aggiungere una nuova dipendenza di implementazione per la versione più recente di Android SDK Mappe di Azure:

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

    4. Selezionare Sincronizza progetto con Gradle Files dal menu File .

    Screenshot che mostra il file gradle del punto di compilazione dell'applicazione in Android Studio.

  5. Aggiungere un frammento di mappa all'attività principale:

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

    Per aggiornare l'attività principale, selezionare layout> res > dell'app > activity_main.xml nello strumento di spostamento del progetto:

    Screenshot che mostra il file activity_main.xml nel riquadro Strumento di spostamento del progetto in Android Studio.

  1. Nel file MainActivity.java:

    • Aggiungere importazioni per Mappe di Azure SDK.
    • Impostare le informazioni di autenticazione Mappe di Azure.
    • Ottenere l'istanza del controllo mappa nel metodo onCreate .

    Suggerimento

    Impostando le informazioni di autenticazione a livello globale nella AzureMaps classe usando i setSubscriptionKey metodi o setAadProperties , non sarà necessario aggiungere le informazioni di autenticazione in ogni visualizzazione.

    Il controllo mappa contiene i propri metodi del ciclo di vita per la gestione del ciclo di vita OpenGL di Android. Questi metodi del ciclo di vita devono essere chiamati direttamente dall'attività che li contiene. Per chiamare correttamente i metodi del ciclo di vita del controllo mappa, eseguire l'override dei metodi del ciclo di vita seguenti nell'attività che contiene il controllo mappa, quindi chiamare il rispettivo metodo di controllo mappa.

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

    Modificare il file MainActivity.java come segue:

    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. Nel file MainActivity.kt:

    • Aggiungere le importazioni per Azure Maps SDK
    • Impostare le informazioni di autenticazione di Mappe di Azure
    • Ottenere l'istanza del controllo mappa nel metodo OnCreate

    Suggerimento

    Impostando le informazioni di autenticazione a livello globale nella AzureMaps classe usando i setSubscriptionKey metodi o setAadProperties , non sarà necessario aggiungere le informazioni di autenticazione in ogni visualizzazione.

    Il controllo mappa contiene i propri metodi del ciclo di vita per la gestione del ciclo di vita OpenGL di Android. Questi metodi del ciclo di vita devono essere chiamati direttamente dall'attività che li contiene. Per chiamare correttamente i metodi del ciclo di vita del controllo mappa, eseguire l'override dei metodi del ciclo di vita seguenti nell'attività che contiene il controllo mappa. e chiamare il rispettivo metodo del controllo mappa.

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

    Modificare il file MainActivity.kt come segue:

    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. Selezionare il pulsante Esegui sulla barra degli strumenti, come illustrato nell'immagine seguente (o premere Control + R su un Mac) per compilare l'applicazione.

    Screenshot che mostra il pulsante Esegui in Android Studio.

Android Studio richiede alcuni secondi per compilare l'applicazione. Al termine della compilazione è possibile testare l'applicazione nel dispositivo Android emulato. Verrà visualizzata una mappa simile a questa:

Screenshot che mostra Mappe di Azure in un'applicazione Android.

Suggerimento

Per impostazione predefinita, Android ricarica l'attività quando l'orientamento cambia o la tastiera è nascosta. Ciò comporta la reimpostazione dello stato della mappa (ricaricare la mappa che reimposta la visualizzazione e ricarica i dati allo stato iniziale). Per evitare che ciò accada, aggiungere quanto segue al manifesto: android:configChanges="orientation|keyboardHidden". In questo modo l'attività smetterà di ricaricare e chiamerà onConfigurationChanged() invece quando l'orientamento è cambiato o la tastiera è nascosta.

Pulire le risorse

Avviso

Le esercitazioni elencate nella sezione Passaggi successivi offrono indicazioni dettagliate su come usare e configurare Mappe di Azure con il proprio account. Non eliminare le risorse create in questa guida introduttiva se si prevede di continuare con le esercitazioni.

Se non si intende continuare con le esercitazioni, pulire le risorse eseguendo questa procedura:

  1. Chiudere Android Studio ed eliminare l'applicazione creata.
  2. Se l'applicazione è stata testata in un dispositivo esterno, disinstallarla da tale dispositivo.

Se non si prevede di continuare a sviluppare con Android SDK per Mappe di Azure:

  1. Accedere alla pagina del portale di Azure. Selezionare Tutte le risorse dalla pagina principale del portale.
  2. Selezionare il proprio account di Mappe di Azure. Nella parte superiore della pagina selezionare Elimina.
  3. Facoltativamente, se non si prevede di continuare a sviluppare app Android, disinstallare Android Studio.

Per altri esempi di codice, vedere queste guide:

Passaggi successivi

In questa guida introduttiva vengono creati l'account di Mappe di Azure e un'applicazione demo. Per altre informazioni su Mappe di Azure, vedere l'esercitazione seguente:

Esercitazione: Caricare dati GeoJSON in Mappe di Azure Android SDK