Получение API ключа

Google Maps JavaScript API предоставляет доступ к картографическим сервисам Google непосредственно из веб-приложений. Для идентификации проекта, контроля использования сервисов, ведения статистики и применения ограничений безопасности используется специальный API-ключ.

API-ключ представляет собой уникальную строку символов, которая передается при загрузке библиотеки Google Maps JavaScript API. Без действительного ключа большинство функций API недоступно.

Пример структуры API-ключа:

AIzaSyAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Каждый ключ привязан к определенному проекту в Google Cloud и позволяет Google определять источник запросов.

Требования перед получением ключа

Перед созданием API-ключа необходимо подготовить следующие компоненты:

учетную запись Google;
доступ к Google Cloud Console;
созданный проект Google Cloud;
подключенный платежный аккаунт Billing.

Даже если приложение использует бесплатные лимиты, подключение биллинга является обязательным требованием большинства картографических сервисов Google.

Создание проекта в Google Cloud

Работа с Google Maps Platform начинается с создания отдельного проекта.

Открытие консоли Google Cloud

После входа в Google Cloud Console в верхней части интерфейса отображается селектор проектов.

Для создания нового проекта необходимо:

Открыть список проектов.
Нажать кнопку создания проекта.
Указать название проекта.
При необходимости выбрать организацию.
Подтвердить создание.

Пример имени проекта:

MapsDemoProject

После завершения процесса система создаст изолированную среду, в рамках которой будут храниться:

API-ключи;
настройки безопасности;
статистика запросов;
платежные данные;
журналы использования.

Подключение платежного аккаунта

Большинство сервисов Google Maps Platform требует активного платежного аккаунта.

Для подключения биллинга необходимо:

Перейти в раздел Billing.
Создать новый платежный аккаунт либо выбрать существующий.
Связать его с созданным проектом.

После привязки биллинга проект получает возможность использовать сервисы Google Maps Platform.

При отсутствии платежного аккаунта запросы к API могут завершаться ошибками авторизации.

Включение Google Maps JavaScript API

Создание ключа само по себе недостаточно. Сначала необходимо активировать конкретный API.

Переход в библиотеку API

В меню Google Cloud Console открывается раздел:

APIs & Services → Library

В каталоге сервисов необходимо найти:

Maps JavaScript API

После открытия страницы сервиса нажимается кнопка включения.

Что происходит после активации

После включения API проект получает право выполнять запросы к JavaScript-библиотеке карт.

Становятся доступны:

отображение карт;
работа с маркерами;
маршруты;
геокодирование через дополнительные API;
стилизация карт;
события взаимодействия пользователя.

Создание API-ключа

После активации Maps JavaScript API можно перейти к генерации ключа.

Раздел Credentials

В консоли необходимо открыть:

APIs & Services → Credentials

Затем выбрать:

Create Credentials → API Key

Система автоматически создаст новый ключ.

Пример отображения результата:

API key created

AIzaSyBxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Сразу после генерации ключ становится активным.

Использование созданного ключа

Полученный ключ передается в URL подключения библиотеки Google Maps JavaScript API.

Пример:

<script
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY">
</script>

Значение YOUR_API_KEY заменяется реальным ключом.

Пример:

<script
    src="https://maps.googleapis.com/maps/api/js?key=AIzaSyBxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx">
</script>

При загрузке страницы браузер отправляет запрос к серверам Google и проверяет действительность ключа.

Ограничение доступа к API-ключу

Созданный ключ нельзя оставлять без ограничений.

Ключ без настроек безопасности может быть использован посторонними лицами, что приведет к:

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

Поэтому сразу после создания рекомендуется настроить ограничения.

Ограничение по HTTP-реферерам

Для веб-приложений наиболее распространенным способом защиты является ограничение по домену.

Настройка ограничений

В параметрах ключа необходимо выбрать:

Application restrictions

Затем активировать вариант:

HTTP referrers (web sites)

После этого указываются разрешенные адреса.

Примеры:

https://example.com/*

https://www.example.com/*

https://app.example.com/*

Только страницы указанных сайтов смогут использовать данный ключ.

Ограничение по API

Помимо ограничения по доменам рекомендуется ограничить список доступных сервисов.

Для этого используется раздел:

API restrictions

В списке выбирается:

Restrict key

После чего указываются разрешенные API.

Например:

Maps JavaScript API

Если ключ предназначен только для отображения карт, дополнительные сервисы подключать не следует.

Такой подход существенно повышает безопасность.

Проверка работы ключа

После создания и настройки ключа желательно убедиться в его корректной работе.

Минимальный пример страницы:

<!DOCTYPE html>
<html>
<head>
    <title>Google Map</title>

    <script
        src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY">
    </script>

    <script>
        function initMap() {
            const map = new google.maps.Map(
                document.getElementById("map"),
                {
                    center: {
                        lat: 55.7558,
                        lng: 37.6176
                    },
                    zoom: 10
                }
            );
        }

        window.onl oad = initMap;
    </script>
</head>
<body>
    <div id="map"
         style="width:800px;height:500px;">
    </div>
</body>
</html>

Если карта отображается корректно, ключ работает успешно.

Проверка через консоль браузера

При возникновении проблем полезно открыть инструменты разработчика браузера.

Наиболее распространенные ошибки отображаются в консоли JavaScript.

Примеры сообщений:

Google Maps JavaScript API error:
InvalidKeyMapError

Означает использование неверного ключа.

RefererNotAllowedMapError

Указывает на отсутствие текущего домена в списке разрешенных рефереров.

BillingNotEnabledMapError

Говорит о том, что для проекта не подключен биллинг.

ApiNotActivatedMapError

Появляется при попытке использовать API, который не был активирован в проекте.

Управление несколькими ключами

В рамках одного проекта допускается создание нескольких API-ключей.

Распространенная схема:

Назначение	Ключ
Production	Отдельный
Development	Отдельный
Тестовая среда	Отдельный
Внутренние инструменты	Отдельный

Такой подход позволяет:

разделять статистику использования;
применять разные ограничения безопасности;
быстро отключать скомпрометированные ключи;
контролировать расход квот.

Ротация API-ключей

Для крупных проектов рекомендуется периодически обновлять ключи.

Типичный процесс выглядит следующим образом:

Создается новый ключ.
Настраиваются ограничения.
Приложение переводится на новый ключ.
Проверяется работоспособность.
Старый ключ удаляется.

Подобная процедура снижает риски утечки учетных данных.

Мониторинг использования ключа

Google Cloud предоставляет инструменты контроля использования API.

Основные показатели:

количество запросов;
ошибки авторизации;
потребление квот;
распределение запросов по времени;
активность различных сервисов.

Мониторинг доступен через разделы:

Google Maps Platform

APIs & Services

Регулярный анализ статистики помогает выявлять:

подозрительную активность;
ошибки конфигурации;
превышение лимитов;
неиспользуемые API-ключи.

Удаление API-ключа

Если ключ больше не используется, его рекомендуется удалить.

Для этого необходимо:

Открыть раздел Credentials.
Выбрать нужный ключ.
Нажать Delete.
Подтвердить удаление.

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

Удаление особенно важно при обнаружении утечки ключа или завершении жизненного цикла проекта.

Практические рекомендации по безопасности

Никогда не публиковать ключ без ограничений.

Всегда ограничивать ключ по HTTP-реферерам для веб-приложений.

Разрешать только необходимые API.

Использовать отдельные ключи для разработки и продакшена.

Периодически анализировать статистику использования.

Удалять неиспользуемые ключи.

Своевременно выполнять ротацию ключей.

Не хранить серверные ключи в клиентском JavaScript-коде.

Регулярно проверять сообщения об ошибках в Google Cloud Console и инструментах разработчика браузера.