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 Google Maps Platform > 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 affiché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 racine et ajoutez le code suivant à l'élément dependencies sous buildscript.
    buildscript {
        dependencies {
            // ...
            classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0"
        }
    }
        
  2. Ensuite, ouvrez le fichier build.gradle au niveau de l'application et ajoutez le code suivant à l'élément plugins.
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
        
  3. Enregistrez le fichier et synchronisez votre projet avec Gradle.
  4. 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
        
  5. Enregistrez le fichier et synchronisez votre projet avec Gradle.
  6. 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.

Lorsque vous restreignez votre clé API, vous devez fournir l'empreinte du certificat SHA-1 de la clé de signature utilisée pour signer l'application. Il existe deux types de certificats :

  • Certificat de débogage : n'utilisez ce type de certificat qu'avec des applications que vous testez et d'autres codes hors production. N'essayez pas de publier une application signée avec un certificat de débogage. Les outils Android SDK génèrent ce certificat automatiquement lorsque vous exécutez une version de débogage.
  • Certificat de version : utilisez ce certificat lorsque vous êtes prêt à publier votre application sur une plate-forme de téléchargement d'applications. Les SDK Tools pour Android génèrent ce certificat lorsque vous exécutez une version de production.

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

Pour restreindre une clé API :

  1. Accédez à la page Google Maps Platform > 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 savoir comment obtenir votre empreinte de certificat, consultez Authentifier votre client. Si vous utilisez plutôt la signature d'application Play, vous devez accéder à la page de signature d'application sur la Play Console pour obtenir votre empreinte de certificat.
    • 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.