Управление API-ключами | On‑Premise | 2GIS Documentation
On‑Premise
Личный кабинет

Управление API-ключами партнёров

Данная инструкция описывает регистрацию партнёров (конечных пользователей) установленного комплекса On-Premise и создание API-ключей для них. Вы узнаете:

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

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

Перед началом работы убедитесь, что выполнены следующие шаги:

  1. Сервис API-ключей установлен и работает корректно.
  2. В сервис добавлен пользователь с правами администратора с помощью утилиты keysctl.

После этого:

  1. Перейдите по ссылке вида https://keys.example.com/ (вы получили ее в результате установки сервиса).
  2. Войдите в веб-интерфейс, используя учетные данные пользователя с правами администратора.

В интерфейсе администратора вы можете работать с двумя вкладками:

  • Партнёры

    Партнёры

    Здесь вы можете:

    • Добавлять новых партнёров.

    • Просматривать список существующих партнёров и фильтровать его по нужным параметрам: название партнёра, ключ, данные контактного лица, логин менеджера (администратора, добавившего партнёра) и другие.

    • Выгружать список всех партнёров в формате .xlsx: нажмите Скачать partners.xlsx в правом верхнем углу экрана.

      В выгрузку попадают все существующие партнёры, применённые фильтры не учитываются.

  • API-ключи

    Ключи

    Здесь вы можете:

    • Просматривать список существующих ключей всех партнёров и фильтровать его по нужным параметрам: номер ключа, email контактного лица, логин менеджера (администратора, добавившего партнёра) и другие.

    • Выгружать список всех ключей в формате .xlsx: нажмите Скачать keys.xlsx в правом верхнем углу экрана.

      В выгрузку попадают все существующие ключи, применённые фильтры не учитываются.

  1. Перейдите на вкладку Партнёры и нажмите Добавить партнёра.

  2. Заполните информацию о партнёре:

    Добавление партнёра
    • Название: имя учетной записи, которое будет отображаться в интерфейсе администратора.
    • Страна: страна проживания партнёра.
    • Город: город проживания партнёра.
    • Язык: язык коммуникации с партнёром.
    • Контактное лицо: данные о контактном лице партнёра: ФИО и email. По умолчанию используются для всех ключей партнёра, если в отдельных ключах не заданы другие данные.
  3. Нажмите Добавить.

  1. Перейдите на вкладку Партнёры и выберите карточку нужного партнёра.
  2. Нажмите на иконку Редактировать рядом с названием партнёра.
  3. Измените необходимые данные и нажмите Сохранить.
  1. Перейдите на вкладку Партнёры и выберите карточку нужного партнёра.

  2. Нажмите Добавить ключ.

  3. Заполните информацию о ключе:

    Создать ключ
    • Партнёр: ID партнёра, для которого создаётся ключ (по умолчанию выбран текущий партнёр).

    • Режим:

      • Demo: ознакомительный режим с ограничениями, которые накладываются сервисами:

        • Поиск: не более 5 страниц с результатами, не более 20 результатов на странице;
        • Навигация: длина маршрута не более 50 км;
      • Prod: режим для полной эксплуатации.

    • Назначение: описание назначения ключа.

    • Контактное лицо (необязательно): данные о контактном лице для данного ключа. Если оставить поля пустыми, используются данные о контактном лице партнёра.

  4. Нажмите Создать.

Примечание

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

Пример ключа

Вы можете изменить описание и контактное лицо ключа, а также переназначить ключ другому партнёру следующим образом:

  1. Выберите нужный ключ в карточке партнёра или на вкладке API-ключи.
  2. Нажмите на иконку Редактировать рядом с номером ключа.
  3. Измените необходимые данные и нажмите Сохранить.

Чтобы изменить режим работы ключа (Demo/Prod), используйте переключатель на основной странице ключа.

Вы можете изменить список сервисов, к которым партнёр сможет получить доступ по данному ключу:

  1. Выберите нужный ключ в карточке партнёра или на вкладке API-ключи.
  2. Прокрутите страницу вниз до списка доступных сервисов.
  3. Чтобы добавить или убрать доступ к сервису, используйте переключатель слева от имени сервиса.
Выбор сервисов

Чтобы заблокировать ключ:

  1. Выберите нужный ключ в карточке партнёра или на вкладке API-ключи.
  2. Нажмите Заблокировать.

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

Чтобы настроить ограничения ключа:

  1. Выберите нужный ключ в карточке партнёра или на вкладке API-ключи.

  2. Нажмите иконку Шестеренка в разделе Ограничения ключа.

  3. Настройте ограничения:

    Ограничения ключа
    • Deactivation time: дата будущей блокировки (по умолчанию отсутствует).

    • По территории:

      • Группы сегментов: список сегментов (территорий), которые будут доступны. По умолчанию доступны все сегменты из списка, но вы можете ограничить набор.
      • Вкл. сегменты: дополнительный список сегментов вне выбранных выше групп, которые будут доступны. Например, вы можете выбрать всю территорию одной страны и один город в другой стране.
      • Искл. сегменты: список сегментов из выбранных выше групп, доступ к которым будет закрыт. Например, вы можете выбрать всю территорию страны и ограничить доступ к определённому городу внутри неё.
    • По IP или подсетям: список IP-адресов, по которым использование ключа будет недоступно.

    • По HTTP-заголовкам: настройки ограничения доступа для запросов по имени сервера, URL страницы и другим параметрам.

  4. Нажмите Сохранить.

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