API-ключи
Создайте ключ, который связывает ваш сайт или программу с Measure Map Online, выберите, что ему разрешено, разделите рабочую и тестовую среду и безопасно заменяйте или ограничивайте ключ.
API-ключ позволяет вашему сайту или программе работать с вашим аккаунтом Measure Map Online: показывать карту проекта на вашем сайте, создавать проекты для посетителей, а также читать и изменять проекты через REST API. Ключи создаются и настраиваются на странице Разработчик.
Откройте страницу «Разработчик»#
В меню панели мониторинга, в группе Дополнительно, нажмите Разработчик. Страница открывается на разделе API-ключи, а остальные её разделы перечислены под ним в меню (на телефоне — вкладками вверху страницы):
- Гостевая ссылка (Open Guest): ссылка для вашего сайта, не требующая программирования. См. Open Guest.
- Попробовать API, Вебхуки и REST API: см. справочник по API.
- Встроить карту (Enterprise): см. iFrame API.
Значок вверху карточки ключа показывает состояние ключа: Активный, Не активировано (ключа ещё нет), Отключено (доступ к API приостановлен: ни один ключ не работает, и создать новый нельзя, пока поддержка не снимет приостановку) или Просрочено (подписка не активна).
Рабочая среда и песочница#
Вверху карточки ключа переключайтесь между Рабочая и Песочница. У каждой среды свой ключ, и страница показывает ключ выбранной. Выбор действует также в разделе Попробовать API и сохраняется, пока вы переходите между разделами. Встроить карту и Гостевая ссылка всегда используют рабочий ключ, потому что посетители вашего сайта могут открывать только рабочие проекты: при открытии любого из этих разделов страница возвращается к среде Рабочая.
- Рабочая — это ваш настоящий аккаунт; страница открывается на нём. На сайте используйте рабочий ключ.
- Песочница — для создания и проверки интеграции. Проекты, папки и продукты, созданные ключом песочницы, хранятся отдельно от настоящих: рабочий ключ их не видит, а ключ песочницы не видит ваши рабочие данные. Запросы с ключом песочницы не учитываются в вашей статистике использования, а гостевые проекты, созданные таким ключом, никогда не оплачиваются.
Создание нового ключа песочницы никак не влияет на рабочий ключ, и наоборот.
Выберите, что может ключ#
В разделе Доступ нового ключа каждая строка — одна область API. Выберите, насколько широкий доступ к ней получит следующий создаваемый ключ:
| Область | Варианты | Что это разрешает |
|---|---|---|
| Встроенные карты | Нет доступа, Разрешено | Вход зрителя во встроенную карту. Большинству интеграций нужно только это. |
| Проекты | Нет доступа, Чтение, Чтение и изменение | Проекты и папки с их измерениями, комментариями и экспортами. |
| Пользователи (Enterprise) | Нет доступа, Чтение, Чтение и изменение | Люди в вашем аккаунте и их места. |
| Продукты | Нет доступа, Чтение, Чтение и изменение | Ваш каталог продуктов и цены. |
Наведите указатель на вариант, чтобы увидеть, что именно он даёт. Ваш первый ключ изначально получает только Встроенные карты — этого достаточно для встроенной карты; ключ, который заменяет другой, изначально получает доступ того ключа. Выберите хотя бы одну область. Для входа от имени участника вашей организации через API нужен доступ Пользователи: Чтение и изменение, а не Встроенные карты.
Разрешения ключа фиксируются при его создании. Чтобы дать ключу больше или меньше доступа, создайте новый.
Создайте ключ#
- Выберите Рабочая или Песочница.
- Задайте доступ в разделе Доступ нового ключа.
- При желании введите название в поле Название нового ключа (необязательно), чтобы различать свои ключи.
- Нажмите Создать новый ключ.
Ключ появится в разделе Ваш API-ключ скрытым, кроме первых и последних символов, со строкой, где указано, что он может делать (Разрешения). Нажмите , чтобы показать его целиком, или , чтобы скопировать весь ключ. Каждый раз, когда в вашем аккаунте создаётся ключ, вы получаете письмо.
Ключ, созданный до появления областей доступа, может всё, кроме работы с продуктами и входа от имени участника; карточка предупреждает об этом. Если вы используете его только для встраивания, замените его более ограниченным.
Замените ключ#
Если ключ у вас уже есть, снова нажмите Создать новый ключ. Сначала приложение предупредит: Будет создан новый ключ, а текущий продолжит работать 24 часа, чтобы вы успели обновить сайты, которые его используют. Вы можете отозвать его раньше, когда закончите.
Старый ключ переходит в раздел Прежние ключи с указанием оставшегося времени и того, когда он использовался в последний раз. Всё ещё принимаются, пока вы разворачиваете новый ключ. Отзовите, как только он больше не используется. Чтобы сразу остановить его, нажмите Отозвать и подтвердите; все сайты, которые ещё его используют, немедленно перестанут работать. Когда ключ отзывается, вы получаете письмо.
Ограничения по сайтам копируются в новый ключ. Новый ключ можно создавать примерно раз в минуту.
Ограничьте ключ своими сайтами#
Использовать ключ в браузере могут только сайты из этого списка: встроенные карты и запросы со страниц любых других сайтов отклоняются. На вызовы с сервера это не влияет.
- В разделе Ограничения сайта введите свой сайт в поле
Введите веб-сайт или домен: домен, например
example.com, IP-адрес илиlocalhost. Можно вставить полный адрес: сохраняется только имя сайта, безhttps://, пути и порта. - Нажмите Добавить.
Домен охватывает и свои поддомены: example.com разрешает
shop.example.com. Нажмите , чтобы удалить сайт, и
подтвердите; после удаления последнего ключ работает с любого сайта. Каждый
раз, когда сайт удаляется из списка ключа, вы получаете письмо.
Список действует для браузеров. Встроенная карта открывается только на странице сайта из списка; если браузер не сообщает, на какой странице она находится, карта отклоняется. Запрос к REST API, отправленный с веб-страницы, должен приходить с сайта из списка. Запрос с вашего собственного сервера не указывает сайт и не проверяется. Сам Measure Map Online разрешён всегда, поэтому предпросмотры на этой странице продолжают работать.
Как используется ключ#
Раздел Использование суммирует все ваши рабочие ключи, поэтому при замене ключа статистика продолжается. Он показывает запросы за последние 30 дней — и от встроенных карт, и к REST API — со столбцом на каждый день; итог За всё время; Последний доступ; дату создания текущего ключа (Ключ создан); и Основные домены — сайты, которые чаще всего используют ваши ключи. Незнакомый сайт в этом списке — повод ограничить или заменить ключ.
Запросы песочницы не учитываются, поэтому статистика видна только в среде Рабочая. Не учитываются и запросы, которые делает сама эта страница, в разделе Попробовать API и в предпросмотрах.
Храните ключ в безопасности#
- Давайте каждому ключу только тот доступ, который ему нужен. У ключа на веб-странице (например, в адресе встроенной карты) должен быть только Встроенные карты.
- Этот ключ может изменять ваши данные. Храните его на своём сервере, а не на веб-странице или в приложении.
- Ограничьте ключ, используемый на веб-страницах, своими сайтами.
- Оставляйте ключ на странице скрытым, когда показываете свой экран; чтобы скопировать его, показывать его не нужно.
- Если ключ мог утечь, сразу создайте новый и отзовите старый в разделе Прежние ключи.
- Создавайте и проверяйте интеграцию с ключом Песочница, чтобы эксперименты никогда не попадали в ваши настоящие проекты.
Всё ещё нужна помощь?
Напишите в нашу службу поддержки и расскажите, что вы пытались сделать. Скриншоты помогут.