Maps JavaScript API: как получить ключ API или идентификатор клиента

Примечание. Тарифный план Premium платформы Google Карт больше недоступен для регистрации и новых клиентов.

Выбор метода аутентификации

Возможные методы аутентификации запросов к Maps JavaScript API перечислены ниже.

  • Клиенты с тарифным планом Premium могут использовать ключ API или идентификатор клиента, чтобы выполнять аутентификацию запросов.
  • Клиенты с предыдущей лицензией должны использовать идентификатор клиента для аутентификации запросов.

Ниже перечислены инструменты и отчеты, доступные для каждого метода аутентификации.

  • При использовании ключа API (план Premium) вы можете:
    • управлять всеми API на странице API в Google Cloud Console;
    • просматривать данные об использовании в реальном времени и за последние 30 дней в Cloud Console;
    • добавлять в запросы параметр channel, чтобы просматривать отчеты с более подробной информацией об использовании;
    • просматривать отчеты об использовании более чем за 30 дней в Cloud Console.
  • При использовании идентификатора клиента (план Premium или предыдущая лицензия) вы можете:
    • добавлять в запросы параметр channel, чтобы просматривать отчеты с более подробной информацией об использовании;
    • просматривать отчеты об использовании более чем за 30 дней в Cloud Console;
    • использовать инструменты Maps Analytics для Maps JavaScript API.

Подробнее об отчетах, доступных для клиентов с планом Premium

Аутентификация с помощью ключа API

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

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

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

  1. Перейдите на страницу выбора проекта в Cloud Console. Выберите проект Google Cloud, для которого нужно добавить ключ API, или создайте новый.

    Перейти на страницу выбора проекта

    Примечание. Чтобы получить полный доступ ко всем функциям плана Premium, необходимо использовать проект, связанный с аккаунтом Premium. При покупке лицензии вашему ресурсу в рамках плана Premium присваивается название в следующем формате: gme-[company] > proj-[number] ([type]). Чтобы приступить к работе с нужным проектом, войдите как владелец проекта в консоль по адресу console.cloud.google.com/project/number (вместо number укажите номер проекта). Имя владельца проекта можно найти в приветственном письме.

  2. Откройте страницу Google Maps Platform > Credentials (Платформа Google Карт > Учетные данные).

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

  3. На странице Credentials (Учетные данные) нажмите Create credentials > API key (Создать учетные данные > Ключ API).
    Появится диалоговое окно с созданным ключом API.
  4. Нажмите Закрыть.
    Новый ключ API можно будет найти в разделе API keys (Ключи API) на странице Credentials (Учетные данные).
    Не забудьте настроить ограничения для ключа API, прежде чем использовать его в рабочей среде.

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

Каждый запрос к платформе Google Карт должен содержать ключ API. Укажите свой ключ API вместо YOUR_API_KEY в следующем примере:

<script async defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
type="text/javascript"></script>

Протокол HTTPS является обязательным для запросов с ключом API и рекомендуемым для запросов с идентификатором клиента. Используйте его для приложений, содержащих в запросах конфиденциальные данные пользователей, такие как их местоположение.

Настройка ограничений для ключей API

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

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

  1. Откройте страницу Google Maps Platform > Credentials (Платформа Google Карт > Учетные данные).

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

  2. Выберите нужный ключ API. Откроется страница со свойствами ключа API.
  3. В разделе Key restrictions (Ограничения для ключа) установите следующие ограничения:
    • Ограничения для приложений:
      1. Чтобы принимать запросы от сайтов из вашего списка, выберите HTTP referrers (web sites) (HTTP-источники перехода (веб-сайты)) в списке Application restrictions (Допустимый тип приложений).
      2. Укажите один или несколько сайтов – источников перехода. Например, если ввести *.google.com, то приниматься будут запросы от https://developers.google.com и всех остальных сайтов, заканчивающихся на google.com.

        Примечание. В источниках file:// необходимо использовать специальное представление, которое следует добавить к ограничению, заданному для ключа. Фрагмент file:// необходимо заменить на __file_url__, прежде чем добавить его к ограничению ключа. Например, вместо file:///path/to/ используйте формат __file_url__//path/to/*. После активации источников file:// рекомендуется постоянно следить за статистикой использования, чтобы убедиться, что показатели соответствуют вашим ожиданиям.

    • Ограничения для API:
      1. Нажмите Restrict key (Применить ограничения для ключа).
      2. В раскрывающемся списке Select APIs (Выберите API) нажмите Google Maps Platform (Платформа Google Карт). Если такого варианта нет, вам необходимо включить платформу Google Карт.
      3. Если в вашем проекте используется библиотека Places Library, выберите Places API. Также необходимо включить и выбрать API, указанные в этом списке, для всех других сервисов, которые нужны для работы JavaScript API (Directions Service, Distance Matrix Service, Elevation Service и/или Geocoding Service).
  4. Внеся все изменения, нажмите Сохранить.

Аутентификация с помощью идентификатора клиента

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

Все идентификаторы клиента начинаются с префикса gme-. Ниже показан общепринятый формат.

gme-[company] > proj-[number] ([type])

Аутентификацию запросов Maps JavaScript API можно выполнять с помощью идентификатора клиента и авторизованных URL (вместо ключа API).

Примечание. Этот идентификатор клиента не является ключом и может использоваться только вместе с авторизованными URL. Подробнее о том, как зарегистрировать авторизованные URL

Как указать идентификатор клиента при загрузке API

Ниже показан пример кода для загрузки Maps JavaScript API. Вместо YOUR_CLIENT_ID введите свой идентификатор клиента.

  <script async defer
  src="https://maps.googleapis.com/maps/api/js?client=YOUR_CLIENT_ID&v=quarterly&callback=initMap"></script>

Необходимо указать конечную версию (также называемую стабильной) или более раннюю версию. Для этого добавьте параметр v=quarterly. На приложения, которые используют экспериментальную версию, соглашение об уровне обслуживания для тарифного плана Premium платформы Google Карт не распространяется.

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

Как зарегистрировать авторизованные URL

Чтобы не допустить применение вашего идентификатора клиента третьими лицами на своих сайтах, его использование необходимо ограничить, указав список авторизованных URL.

Для этого выполните следующие действия.

  1. Войдите в Google Cloud Console.
  2. В меню слева выберите пункт Maps: Manage Client ID (Карты: управление идентификатором клиента).

За один раз можно добавить до 100 URL. Идентификатор клиента может быть связан более чем с 3000 авторизованных URL. Если на Google Картах в вашем приложении будет доступно более 3000 местоположений, мы рекомендуем использовать ключи API вместо URL.

В отношении авторизованных URL следует учитывать следующие факторы:

Доменное имя или IP-адрес не обязательно должны быть общедоступными.
Например, могут использоваться http://myintranet и http://192.168.1.1.
Все субдомены указанного домена также будут авторизованы.
Например, если вы авторизуете http://example.com, при этом будет также авторизован и домен http://www.example.com. Однако это правило не действует в обратную сторону: если адрес http://www.example.com авторизован, это не означает, что http://example.com также будет авторизован.
Все вложенные пути авторизованного пути также являются авторизованными.
Например, если вы авторизуете http://example.com, при этом также будет авторизован и путь http://example.com/foo. Кроме того, поскольку субдомены указанного домена также авторизованы, то авторизуется и http://sub.example.com/bar.
Путь вводится с учетом регистра.
Например, адрес http://www.example.com/ThisPath/ не идентичен http://www.example.com/thispath/.
Вы можете указать порты для допустимых URL.
Например, если авторизован адрес http://example.com:8080/foo, то http://example.com уже не будет авторизован.
Протоколы HTTP и HTTPS формируют разные URL.
Например, если адрес https://example.com авторизован, то это не означает, что http://example.com будет также авторизован.

Все приведенные выше правила применяются ко всем адресам, поэтому важно заранее продумать, какие URL вы будете авторизовывать. Например, если вы авторизуете все вложенные пути указанного пути и все субдомены, в результате могут быть авторизованы страницы, для которых вы не планировали это делать. Пример:

http://example.com/ также авторизует http://sub.example.com/path.

Подробная информация доступна в статье Устранение неполадок с авторизацией URL для плана Premium платформы Google Карт.