Использование ключей API

В этой статье рассказывается, как создать ключ API для Maps SDK для Android, добавить его в приложение и защитить приложение с помощью ограничений ключа. Вы должны добавлять ключи API во все приложения, в которых используется комплект SDK.

Подготовка

Чтобы начать использовать Maps SDK для Android, вам необходимо создать проект с платежным аккаунтом и включить Maps SDK для Android. Подробнее о процессе настройки в Cloud Console

Как создать ключи API

Ключ API – это уникальный идентификатор, который используется для аутентификации запросов, связанных с вашим проектом. Он нужен для учета использования API и оплаты. С вашим проектом должен быть связан хотя бы один ключ API.

Чтобы создать ключ API, выполните следующие действия.

  1. Перейдите на страницу API и сервисы > Учетные данные.

    Перейти на страницу "Учетные данные"

  2. На странице Учетные данные нажмите Создать учетные данные > Ключ API.
    Появится диалоговое окно с созданным ключом API.
  3. Нажмите Закрыть.
    Новый ключ API можно будет найти в разделе Ключи API на странице Учетные данные.
    Не забудьте настроить ограничения для ключа API перед его использованием.

Как добавить в приложение ключ API

В этом разделе рассказывается, как настроить безопасный вызов ключа API вашим приложением. Вводить ключ API в систему управления версиями нежелательно, поэтому мы рекомендуем хранить его в файле local.properties, который находится в корневом каталоге проекта. Подробнее о файле local.properties рассказывается в описании файлов свойств Gradle.

Чтобы вам было проще работать, используйте Secrets Gradle Plugin для Android.

Чтобы установить плагин и настроить хранение ключа API, выполните следующие действия:

  1. В Android Studio откройте файл build.gradle уровня приложения и добавьте в элемент plugins приведенный ниже код.
    id 'com.google.secrets_gradle_plugin' version '0.5'
        
  2. Сохраните файл и синхронизируйте проект с Gradle.
  3. Откройте файл local.properties в каталоге уровня проекта и добавьте в этот файл приведенный ниже код. Укажите вместо YOUR_API_KEY свой ключ API.
    MAPS_API_KEY=YOUR_API_KEY
        
  4. Сохраните файл и синхронизируйте проект с Gradle.
  5. В файле AndroidManifest.xml найдите раздел com.google.android.geo.API_KEY и измените android:value attribute следующим образом:
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="${MAPS_API_KEY}" />
        

Примечание. Как показано выше, рекомендуемое имя метаданных для ключа API – com.google.android.geo.API_KEY. Ключ с таким именем может использоваться для аутентификации нескольких API созданных на основе Google Карт для платформы Android, включая Maps SDK for Android. Для обеспечения обратной совместимости API также поддерживает имя com.google.android.maps.v2.API_KEY. Это устаревшее имя обеспечивает аутентификацию только для Android Maps API версии 2. Приложение позволяет указать только одно из имен в метаданных ключа API. Если указаны оба имени, API вызывает исключение.

Как задать ограничения для ключей API

Ограничения повышают безопасность, поскольку с помощью ключа API можно будет отправлять только авторизованные запросы. Мы настоятельно рекомендуем следовать инструкциям по настройке ограничений для ключей API. Дополнительные сведения приводятся в рекомендациях по работе с ключами API.

Чтобы задать ограничение для ключа API, выполните следующие действия:

  1. Перейдите на страницу APIs & Services > Credentials (API и сервисы > Учетные данные).

    Перейти на страницу Credentials (Учетные данные)

  2. Выберите нужный ключ API. Откроется страница со свойствами ключа API.
  3. В разделе Key restrictions (Ограничения для ключа) установите следующие ограничения:
    • Ограничения для приложений:
      1. Выберите Приложения для Android.
      2. Нажмите + Название пакета и цифровой отпечаток.
      3. Укажите название пакета и цифровой отпечаток сертификата SHA-1. Пример:
        com.example.android.mapexample
        BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75
        Подробнее о цифровом отпечатке SHA-1
    • Ограничения для API:
      1. Нажмите Применить ограничения для ключа.
      2. В раскрывающемся списке Выберите API нажмите Maps SDK для Android.
        Если Maps SDK для Android там нет, его необходимо включить.
  4. Нажмите Сохранить.

Как получить цифровой отпечаток SHA-1

В процессе настройки ограничений ключа API вам потребуется указать цифровой отпечаток сертификата SHA-1 ключа, который использовался для подписи в приложении. Цифровой отпечаток представляет собой последовательность из 20 двузначных чисел в шестнадцатеричном формате, которые разделены двоеточиями. Существует два типа сертификатов.

  • Сертификат для отладки. Создается автоматически при выполнении отладочной сборки приложения с помощью Android SDK Tools. Его следует использовать исключительно при тестировании приложений. Не пытайтесь опубликовать приложение, подписанное с помощью сертификата для отладки.
  • Сертификат для выпуска. Создается с помощью инструментов Android SDK при выполнении сборки в процессе подготовки к выпуску. Этот сертификат можно также создать с помощью программы keytool. Используйте этот сертификат, когда будете готовы разместить ваше приложение в магазине.
  • Следуйте приведенным ниже инструкциям, чтобы отобразить цифровой отпечаток SHA-1 с помощью приложения командной строки Keytool.

    Сертификат для отладки

    Отображение цифрового отпечатка сертификата для отладки

    1. Найдите свой файл хранилища ключей для отладки. Этот файл, который называется debug.keystore, создается при выполнении первой сборки проекта. По умолчанию он хранится в том же каталоге, где и файлы виртуального устройства Android (AVD):

      • macOS и Linux: ~/.android/
      • Windows Vista и Windows 7: C:\Users\your_user_name\.android\
    2. Откройте цифровой отпечаток SHA-1.

      • В Linux или macOS перейдите в окно терминала и введите следующую команду:

        keytool -list -v -keystore ~/.android/debug.keystore
         -alias androiddebugkey -storepass android -keypass android
      • В Windows Vista и Windows 7 выполните следующую команду:

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

    Пример выходных данных приведен ниже. В строке, которая начинается с SHA1, содержится цифровой отпечаток SHA-1 сертификата.

    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
    
    Сертификат для выпуска

    Отображение цифрового отпечатка сертификата для выпуска

    1. Найдите свой файл хранилища ключей сертификата для выпуска. Этот файл может называться по-разному, и для него нет стандартного местоположения. Если не указать этот файл при создании сборки приложения для выпуска, ваш пакет .apk останется без подписи и его необходимо будет подписать, чтобы обеспечить возможность публикации. Чтобы отобразить сертификат выпуска, также потребуется псевдоним и пароли для файла keystore и самого сертификата. Чтобы получить список псевдонимов для всех ключей, имеющихся в хранилище, введите следующую команду:

      keytool -list -keystore your_keystore_name

      Вместо your_keystore_name укажите полный путь к файлу, включая расширение .keystore. Потребуется ввести пароль для хранилища ключей. После этого в окне программы keytool появится список всех псевдонимов, имеющихся в хранилище.

    2. В окне терминала или в командной строке введите следующую команду:

      keytool -list -v -keystore your_keystore_name -alias your_alias_name

      Вместо your_keystore_name укажите полный путь к файлу, включая расширение .keystore. Замените your_alias_name на псевдоним, присвоенный сертификату при его создании.

    Пример выходных данных приведен ниже. В строке, которая начинается с SHA1, содержится цифровой отпечаток SHA-1 сертификата.

    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
    

    Дополнительную информацию о цифровых сертификатах вы найдете в руководстве по добавлению подписи в приложения.