Utiliser des clés API

Cette rubrique explique comment créer une clé API pour le SDK Maps pour Android, l'ajouter à votre application et sécuriser cette dernière en limitant la clé. Vous devez ajouter une clé API à toute application qui utilise le SDK.

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 en savoir plus, consultez Obtenir une empreinte SHA-1.
    • Restrictions d'API :
      1. Cliquez sur Restreindre la clé.
      2. Sélectionnez SDK Maps pour Android dans le menu déroulant Sélectionner des API.
        Si le SDK Maps pour Android n'est pas répertorié, vous devez l'activer.
  4. Pour valider vos modifications, cliquez sur Enregistrer.

Obtenir une empreinte SHA-1

Lorsque vous limitez votre clé API, vous devez fournir l'empreinte du certificat SHA-1 de la clé de signature utilisée pour signer l'application. L'empreinte correspond à la séquence de 20 nombres hexadécimaux à deux chiffres séparés par un deux-points. Il existe deux types de certificats :

  • Un certificat de débogage : les SDK Tools pour Android génèrent automatiquement ce certificat lorsque vous utilisez 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.
  • Certificat de version : les SDK Tools pour Android génèrent ce certificat lorsque vous exécutez une build publique. Vous pouvez également générer ce certificat à l'aide du programme keytool. Utilisez ce certificat lorsque vous êtes prêt à publier votre application sur une plate-forme de téléchargement.
  • Suivez les étapes ci-dessous pour afficher une empreinte SHA-1 avec l'application en ligne de commande Keytool.

    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

    La sortie devrait ressembler à ce qui suit. La ligne commençant par SHA1 contient l'empreinte SHA-1 du certificat.

    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éé.

    La sortie devrait ressembler à ce qui suit. La ligne commençant par SHA1 contient l'empreinte SHA-1 du certificat.

    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
    

    Pour en savoir plus sur les certificats numériques, consultez le guide Signer votre application.