Utiliser des clés API

Avant de commencer

Pour utiliser le SDK Maps pour Android, vous devez disposer d'un projet associé à un compte de facturation et vous devez activer le SDK Maps pour Android. Pour en savoir plus, consultez Configurer vos projets dans Cloud Console.

Créer des clés API

Une clé API est un identifiant unique qui permet d'authentifier les requêtes associées à votre projet à des fins d'utilisation et de facturation. Vous devez associer au moins une clé API à votre projet.

Pour créer une clé API :

  1. Accédez à la page API et services > Identifiants.

    Accéder à la page "Identifiants"

  2. Sur la page Identifiants, cliquez sur Créer des identifiants > Clé API.
    La boîte de dialogue Clé API créée affiche la clé API que vous venez de créer.
  3. Cliquez sur Fermer.
    La nouvelle clé API est répertoriée sur la page Identifiants sous Clés API.
    (N'oubliez pas de restreindre la clé API avant de l'utiliser en production.)

Ajouter la clé API à votre application

Cette section explique comment stocker votre clé API pour qu'elle puisse être référencée de manière plus sécurisée par votre application. Vous ne devez pas vérifier votre clé API dans votre système de contrôle des versions. Nous vous recommandons donc de la stocker dans le fichier local.properties, qui se trouve dans le répertoire racine de votre projet. Pour en savoir plus sur le fichier local.properties, consultez Fichiers de propriétés Gradle.

Pour vous faciliter la tâche, vous pouvez utiliser le plug-in Secrets Gradle pour Android.

Pour installer le plug-in et stocker votre clé API :

  1. Dans Android Studio, ouvrez votre fichier build.gradle au niveau de l'application et ajoutez le code suivant à l'élément plugins.
    id 'com.google.secrets_gradle_plugin' version '0.5'
        
  2. Enregistrez le fichier et synchronisez votre projet avec Gradle.
  3. Ouvrez local.properties dans votre répertoire au niveau du projet, puis ajoutez le code suivant. Remplacez YOUR_API_KEY par votre clé API.
    MAPS_API_KEY=YOUR_API_KEY
        
  4. Enregistrez le fichier et synchronisez votre projet avec Gradle.
  5. Dans votre fichier AndroidManifest.xml, accédez à com.google.android.geo.API_KEY et mettez à jour le android:value attribute comme suit :
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="${MAPS_API_KEY}" />
        

Remarque : Comme indiqué ci-dessus, com.google.android.geo.API_KEY est le nom de métadonnées recommandé pour la clé API. Une clé portant ce nom peut être utilisée pour l'authentification auprès de diverses API Google Maps basées sur Google Maps et s'exécutant sur la plate-forme Android, y compris le SDK Maps pour Android. Pour assurer la rétrocompatibilité, l'API accepte également le nom com.google.android.maps.v2.API_KEY. Cet ancien nom autorise l'authentification auprès de l'API Google Maps Android v2 uniquement. Une application ne peut spécifier qu'un seul des noms de métadonnées de clé API. Si les deux noms sont spécifiés, l'API renvoie une exception.

Restreindre les clés API

Restreindre les clés API permet de renforcer la sécurité de votre application, car vous vous assurez que seules les requêtes autorisées sont effectuées avec votre clé API. Nous vous recommandons vivement de suivre les instructions pour définir des restrictions au niveau de vos clés API. Pour en savoir plus, consultez les bonnes pratiques concernant les clés API.

Pour restreindre une clé API :

  1. Accédez à la page API et services > Identifiants.

    Accéder à la page "Identifiants"

  2. Sélectionnez la clé API pour laquelle vous souhaitez définir une restriction. La page des propriétés de la clé API s'affiche.
  3. Sous Restrictions relatives aux clés, définissez les restrictions suivantes :
    • Restrictions relatives aux applications :
      1. Sélectionnez Applications Android.
      2. Cliquez sur + Ajouter le nom du package et l'empreinte.
      3. Saisissez le nom du package et l'empreinte du certificat SHA-1. Exemple :
        com.example.android.mapexample
        BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75
        (Pour plus d'informations, consultez Obtenir l'empreinte SHA-1 de votre application.)
    • Restrictions relatives aux API :
      1. Cliquez sur Restreindre la clé.
      2. Sélectionnez SDK Maps pour Android dans le menu déroulant Select APIs.
        (Si le SDK Maps pour Android n'est pas répertorié, vous devez l'activer.)
  4. Pour finaliser vos modifications, cliquez sur Enregistrer.

Obtenir l'empreinte SHA-1 de votre application

La restriction de la clé API Android est basée sur une version abrégée du certificat numérique de l'application, appelée empreinte SHA-1.

Obtenir les informations de certification d'Android Studio

Si vous suivez le Guide de démarrage du SDK Maps pour Android, Android Studio crée un fichier google_maps_api.xml pratique avec les identifiants de votre application.

Choisissez l'une des méthodes suivantes pour obtenir votre clé API à partir d'Android Studio :

  • Méthode la plus simple et la plus rapide : utilisez le lien fourni dans le fichier google_maps_api.xml qu'Android Studio a créé pour vous.
    1. Copiez le lien fourni dans le fichier google_maps_api.xml et collez-le dans votre navigateur. Ce lien vous dirige vers la Google Cloud Console et lui fournit les informations requises via des paramètres d'URL, ce qui réduit le nombre d'éléments à saisir manuellement.
    2. Suivez les instructions pour créer un projet dans la Cloud Console ou sélectionnez un projet existant.
    3. Créez une clé API restreinte à Android pour votre projet.
    4. Copiez la clé API obtenue, revenez dans Android Studio, puis collez la clé API dans l'élément <string> du fichier google_maps_api.xml.
  • Méthode un peu moins rapide : Utilisez les identifiants fournis dans le fichier google_maps_api.xml créé par Android Studio.
    1. Copiez les identifiants fournis dans le fichier google_maps_api.xml.
    2. Accédez à la console Google Cloud Platform.
    3. Utilisez les identifiants copiés pour ajouter votre application à une clé API existante ou en créer une.

Obtenir vous-même les informations sur le certificat

Si vous n'avez pas suivi le guide de démarrage lors de la création de votre application, vous devez obtenir vous-même l'empreinte SHA-1 de votre certificat. Assurez-vous d'abord d'utiliser le bon certificat. Il en existe deux types :

  • Un certificat de débogage : les outils Android SDK génèrent automatiquement ce certificat lorsque vous exécutez une version de débogage. Utilisez ce certificat uniquement avec les applications que vous testez. N'essayez pas de publier une application signée avec un certificat de débogage. Le certificat de débogage est décrit plus en détail dans la section Connexion en mode débogage de la documentation pour les développeurs Android.
  • Un certificat de version : le SDK Tools pour Android génère ce certificat lorsque vous créez une build. Vous pouvez également générer ce certificat à l'aide du programme keytool. Utilisez ce certificat lorsque vous êtes prêt à proposer une version publique de l'application.

Procédez comme suit pour afficher l'empreinte numérique SHA-1 d'un certificat à l'aide du programme keytool avec le paramètre -v. Pour plus d'informations sur Keytool, consultez la documentation Oracle.

Certificat de débogage

Afficher l'empreinte du certificat de débogage

  1. Recherchez le fichier keystore de débogage. Le fichier est nommé debug.keystore. Il est créé lorsque vous compilez votre projet pour la première fois. Par défaut, il est stocké dans le même répertoire que vos fichiers AVD (Android Virtual Device) :

    • macOS et Linux : ~/.android/
    • Windows Vista et Windows 7 : C:\Users\your_user_name\.android\
  2. Affichez l'empreinte SHA-1 :

    • Pour Linux ou macOS, ouvrez une fenêtre sur le terminal et procédez comme suit :

      keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
    • Pour Windows Vista et Windows 7, exécutez la commande suivante :

      keytool -list -v -keystore "%USERPROFILE%\.android\debug.keystore" -alias androiddebugkey -storepass android -keypass android

Le résultat doit ressembler à ce qui suit :

Alias name: androiddebugkey
Creation date: Jan 01, 2013
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Android Debug, O=Android, C=US
Issuer: CN=Android Debug, O=Android, C=US
Serial number: 4aa9b300
Valid from: Mon Jan 01 08:04:04 UTC 2013 until: Mon Jan 01 18:04:04 PST 2033
Certificate fingerprints:
     MD5:  AE:9F:95:D0:A6:86:89:BC:A8:70:BA:34:FF:6A:AC:F9
     SHA1: BB:0D:AC:74:D3:21:E1:43:07:71:9B:62:90:AF:A1:66:6E:44:5D:75
     Signature algorithm name: SHA1withRSA
     Version: 3
Certificat de version

Afficher l'empreinte du certificat de version

  1. Recherchez le fichier keystore du certificat de version. Il n'existe pas d'emplacement ou de nom par défaut pour le keystore de version. Si vous n'en spécifiez aucun lorsque vous compilez une version de votre application, le fichier .apk ne sera pas signé et vous devrez le signer avant la publication. Pour le certificat de version, vous avez également besoin de l'alias du certificat et des mots de passe du keystore et du certificat. Vous pouvez afficher les alias de toutes les clés d'un keystore en saisissant :

    keytool -list -keystore your_keystore_name

    Remplacez your_keystore_name par le chemin d'accès complet et le nom du keystore, y compris l'extension .keystore. Vous êtes alors invité à saisir le mot de passe du keystore. L'outil keytool affiche alors tous les alias du keystore.

  2. Saisissez la commande suivante sur un terminal ou dans une invite de commande :

    keytool -list -v -keystore your_keystore_name -alias your_alias_name

    Remplacez your_keystore_name par le chemin d'accès complet et le nom du keystore, y compris l'extension .keystore. Remplacez your_alias_name par l'alias que vous avez attribué au certificat lorsque vous l'avez créé.

Le résultat doit ressembler à ce qui suit :

Alias name: <alias_name>
Creation date: Feb 02, 2013
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Android Debug, O=Android, C=US
Issuer: CN=Android Debug, O=Android, C=US
Serial number: 4cc9b300
Valid from: Mon Feb 02 08:01:04 UTC 2013 until: Mon Feb 02 18:05:04 PST 2033
Certificate fingerprints:
    MD5:  AE:9F:95:D0:A6:86:89:BC:A8:70:BA:34:FF:6B:AC:F9
    SHA1: BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:90:AF:A1:66:6E:44:5D:75
    Signature algorithm name: SHA1withRSA
    Version: 3

La ligne commençant par SHA1 contient l'empreinte SHA-1 du certificat. L'empreinte correspond à la séquence de 20 nombres hexadécimaux à deux chiffres séparés par un deux-points.

Pour plus d'informations sur les certificats numériques, reportez-vous au guide Android Sign your app.