История страницы

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

1. Подготовьте справочник.
2. Подготовьте конфигурацию.
3. Скопируйте справочник и конфигурацию на сервер подсказок.
4. Перезагрузите подсказки.
5. Используйте через API или jQuery-плагин.

Ниже каждый из шагов рассмотрен более подробно.

Готовые внешние справочники

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

...

• кем выдан паспорт,;
• почтовые отделения;
• налоговые инспекции,;
• почтовые отделения,
• мировые суды,;
• марки автомобилей;
• страны;
• валюты;
• ОКВЭД;
• ОКПД,;
• ОКВЭДи другие.

Если хотите подключить собственный справочник — читайте дальше, как это сделать.

Справочник

Справочник — это обычный CSV-файл:

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

Если надо, чтобы подсказки возвращали вычисляемые поля (например, «ФИО», составленное из фамилии, имени, и отчества) — эти поля тоже должны быть в справочнике. Сами подсказки их делать не умеют.

Если одни записи справочника более «весомые», чем другие (например, головные организации против филиалов), то веса должны быть предрассчитаны для всех записей и вынесены в отдельный столбец — сами подсказки этого делать не будут.

По умолчанию значения полей подсказки трактуют как строки, даже если по факту это числа или даты.

Пример справочника

...

Барчук Валерий Николаевич

...

Конфигурация

Конфигурация — это YAML-файл в кодировке UTF-8, который описывает, как подсказки работают со справочниками. Проще всего объяснить его на примере:

# название справочника
# наш пример — справочник сотрудников
name: employees
# настройки чтения CSV файла
# необязательно, значения по умолчанию описаны ниже
csv:
  quote: '"'
  delimiter: ','
  endOfLine: '\n'
  encoding: UTF-8
# какие есть поля и как их использовать
fields:
  # Исправлять латинскую раскладку, по умолчанию true
  switch_layout: false
  # какие поля участвуют в поиске по идентификаторам
  # необязательно, по умолчанию не задано
  ids:
    hid: ~
    inn: ~
  # какие поля участвуют в полнотекстовом поиске (обязательно хотя бы одно)
  # для полей можно указать параметр boost — вес для ранжирования
  #   чем больше вес, тем «весомее» считается совпадение по этому полю
  #   например, если вес по fullname = 10, а по email = 1,
  #   то совпадение по ФИО считается весомее, чем по адресу эл. почты
  #   по умолчанию вес = 1
  search:
    fullname:
      boost: 10
    email: ~
    phone: ~
  # по каким полям фильтровать
  # необязательно, по умолчанию не задано
  filter:
    department: ~
  # по какому полю ранжировать
  # необязательно, по умолчанию не задано
  # чем больше значение, тем выше ранжируется соответствующая запись справочника
  # если указано несколько полей, то значения умножаются
  # по умолчанию вес = 1
  boost:
    salary: ~
  # по какому полю сортировать
  # необязательно, по умолчанию равно настройке fields.value + ALPHA_NUMERIC
  # принцип сортировки:
  #   ALPHA_NUMERIC - по алфавиту (с честной сортировкой чисел)
  #   TOKEN_COUNT - по количеству слов (чем меньше слов, тем выше позиция)
  sort:
    fullname:   TOKEN_COUNT
    department: ALPHA_NUMERIC
  # какое поле показывать в списке (suggestion.value, обязательно)
  value: fullname
  # какое поле содержит полное значение одной строкой
  # необязательно, по умолчанию равно настройке fields.value
  unrestricted_value: fullname_with_position
  # какие поля возвращать в объекте подсказки (suggestion.data)
  # необязательно, по умолчанию не задано (suggestion.data == null)
  data:
    name: ~
    surname: ~
    patronymic: ~
    email: ~
    phone: ~
    position: ~
    department: ~

Начиная с версии 19.11 поддерживается поиск ближайшего объекта в справочнике по географическим координатами. Чтобы он заработал, в справочнике должны быть поля с широтой и долготой. Их необходимо указать в конфигурации: 

fields:
    ...
    geolocate:
        latitude: {название поля с широтой}
        longitude: {название поля с долготой}
    ...

Начиная с версии 19.11 можно явно указать тип полей справочника. Поддерживаются типы: int, float, bool, str.

fields:
  ...
  data:
    postal_code: str
    is_closed: bool
    address_qc: int
    geo_lat: float
    ...

По умолчанию для boost и geolocate полей устанавливается тип float, для всех остальных полей – string. Для boost-полей тип может быть только float или int, а для geolocate-полей тип может быть только float.

Скопировать на сервер

Конфигурацию:

1. Сохранить конфигурацию в файл {name}.yaml, где {name} — название справочника, как указано в самом первом параметре конфигурации.
   Для нашего примера это employees.yaml
2. Создать на сервере каталог /SGT_ROOT/configuration/outward/ и скопировать в него файл конфигурации.
   Для нашего примера итоговый путь к файлу будет /data/configuration/outward/employees.yaml

Справочник:

1. Сохранить справочник в файл {name}.csv, где {name} — название справочника, как указано в конфигурации.
   Для нашего примера это employees.csv
2. Создать на сервере каталог /SGT_ROOT/dictionaries/{name}/ и скопировать в него файл справочника.
   Для нашего примера итоговый путь к файлу будет /data/dictionaries/employees/employees.csv

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

Проверить на демо-странице

Работу подсказок можно проверить на демо-странице по адресу http://СЕРВЕР:ПОРТ/suggestions/outward

В поле «Тип» укажите название справочника, после этого подсказки заработают:

Image Removed

API

Аналогично «родным» справочникам:

POST /suggestions/api/4_1/rs/suggest/employees HTTP/1.1
Host: suggestions.evercorp.ru
Content-Type: application/json

{
  "query": "Василий"
}

Поддерживается стандартный параметр count и фильтрация (если настроена фильтрация, параметр filter в конфигурации справочника):

POST /suggestions/api/4_1/rs/suggest/employees HTTP/1.1
Host: suggestions.evercorp.ru
Content-Type: application/json

{
  "query": "Василий",
  "filters": [{"department": "Маркетинг"}, {"department": "ИТ"}]
  "count": 5
}

Поиск по идентификаторам (если настроены идентификаторы, параметр ids в конфигурации справочника):

POST /suggestions/api/4_1/rs/findById/employees HTTP/1.1
Host: suggestions.evercorp.ru
Content-Type: application/json

{
  "query": "1024"
}

Геолокация (с версии 19.11 если заданы координаты, параметр geolocate в конфигурации справочника). Работает аналогично геолокации для адресов – возвращает ближайшие объекты по заданным координатам.

POST /suggestions/api/4_1/rs/geolocate/postal_unit HTTP/1.1
Host: suggestions.evercorp.ru
Content-Type: application/json

{
"lat": 55.763938, "lon": 37.637281, "radius_meters": 10000, "count": 15
}

GET /suggestions/api/4_1/rs/geolocate/postal_unit?lat=55.763938&lon=37.637281 HTTP/1.1
Host: suggestions.evercorp.ru

...

lon

...

count

...

radius_meters

...

jQuery-плагин

В плагине всё как обычно, только в поле type указывается название справочника:

$("#manager").suggestions({
  type: "employees",
  ...
});

Если конфигурация справочника допускает, можно использовать фильтрацию:

...

Подготовить справочник

Настроить конфигурацию

Подключить конфигурацию и справочник

Проверить на демо-странице

Использовать через API

Использовать через jQuery-плагин