> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/user/ru/guide/account/iot-logic/nodes/geofence-functions.md).
# Функции зон
Используйте уже имеющиеся в Navixy геозоны в потоках IoT Logic, чтобы реагировать, когда устройство входит в область или покидает ее, либо фиксировать, в какой области оно находится.
Функции зон позволяют потоку реагировать на местоположение устройства, используя зоны, которые уже есть в Navixy. Вы ссылаетесь на зону вместо того, чтобы описывать область координатами, поэтому границы остаются теми же, что вы уже используете для контроля событий и отчетов.
## Какая функция вам нужна
| Если вы хотите | Используйте |
| --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Действовать в отношении одной конкретной зоны, когда устройство находится внутри нее, входит в нее или выходит из нее | `inGeofence()`, `enterGeofence()`, `leaveGeofence()`. См. [Реакция на одну зону](#reacting-to-one-geofence) |
| Узнать, в какой зоне находится устройство, не называя ее заранее | `geofenceName()`. См. [Запись текущей зоны](#recording-the-current-geofence) |
{% hint style="warning" %}
Перед тем как использовать их в выражениях IoT Logic, вы должны создать зоны в Navixy. Чтобы создать или управлять зонами, см. [Зоны](/docs/user/ru/guide/tracking/map-tools/geofences.md).
{% endhint %}
{% hint style="danger" %}
**`geofenceName()` — это платная опция, продаваемая отдельно.** По умолчанию она отключена для каждого аккаунта, и ваш поставщик услуг включает ее для аккаунта по запросу. Остальные три функции не затрагиваются и не требуют дополнительной опции.
Свяжитесь с вашим поставщиком услуг, чтобы он включил ее. См. [Перед началом](#before-you-start).
{% endhint %}
## Реакция на одну зону
Используйте эти три функции, когда вы уже знаете, какая зона имеет значение. Каждая из них отвечает «да» или «нет» для большинства пакетов данных, которые отправляет устройство, поэтому поток может направить эти данные по одной ветке или другой. В некоторых пакетах функция не может ответить и вместо этого возвращает пустое значение. См. [Когда функция зоны не дает ответа](#when-a-geofence-function-gives-no-answer).
| Функция | Отвечает «да», когда |
| ------------------- | --------------------------------------- |
| `inGeofence(id)` | Устройство сейчас находится внутри зоны |
| `enterGeofence(id)` | Устройство только что вошло в зону |
| `leaveGeofence(id)` | Устройство только что вышло из зоны |
Вы добавляете их в условие **IF/THEN Логика** узла. `ID` — это числовой ID зоны в вашем аккаунте Navixy, и селектор подставляет его за вас, поэтому вы редко вводите его вручную. См. [Как добавить условие зоны](#how-to-add-a-geofence-condition).
### Когда функция зоны не дает ответа
`inGeofence()`, `enterGeofence()`, и `leaveGeofence()` Они возвращают пустое значение вместо «да» или «нет», когда не могут ответить. Функция не может ответить в следующих случаях:
* Пакет данных не содержит координат. Позиция низкого качества все равно проверяется, поэтому слабый GPS-фикс дает корректный ответ «да» или «нет».
* Зона была удалена из вашего аккаунта Navixy или стала недоступной после сохранения потока. Если зона уже отсутствует в момент сохранения потока, она отклоняется при сохранении вместо этого.
Пустое значение останавливает условие, частью которого оно является. Когда функция сама составляет все условие, данные идут по ветке ELSE. Такое направление обычно и нужно. Когда функция объединена с чем-то еще, пустое значение может остановить все условие, включая части, у которых были значения. Чтобы остальная часть условия продолжала работать, сравните функцию с `== true`:
```jexl
leaveGeofence(51577 /* Склад в Остине */) == true || leaveGeofence(85269 /* Стройплощадка 1 */) == true
```
Полное правило см. в [Отсутствующие значения в выражениях](/docs/user/ru/guide/account/iot-logic/nodes/missing-values-in-expressions.md).
### Синтаксис
{% tabs %}
{% tab title="Текущая позиция" %}
Это формат, который селектор зоны вставляет автоматически. Название зоны отображается как комментарий для удобства чтения, но не влияет на вычисление.
```jexl
inGeofence(35229 /* Зона доставки #4 */)
enterGeofence(51577 /* Склад в Остине */)
leaveGeofence(85269 /* Стройплощадка 1 */)
```
{% endtab %}
{% tab title="Историческая позиция" %}
`inGeofence()` принимает ещё два параметра, поэтому может проверять более раннюю позицию вместо текущей:
```jexl
inGeofence(35229 /* Зона доставки № 4 */, 1)
inGeofence(35229 /* Зона доставки № 4 */, 1, 'valid')
inGeofence(35229 /* Зона доставки № 4 */, 'valid')
```
Второй параметр указывает, из какого пакета данных брать позицию, отсчитывая назад от текущего. Третий — учитывать ли пакеты без позиции. Оба параметра необязательны и следуют той же конвенции, что и `value()` функция.
`enterGeofence()` и `leaveGeofence()` берут ID зоны и ничего больше. Обе сравнивают текущую позицию с предыдущей, поэтому выбирать индекс не нужно. Поток, который передаёт второй параметр любой из этих функций, нельзя сохранить, а в ошибке будет указана функция.
Оставьте индекс в диапазоне от 0 до 11. `inGeofence()` принимает больший индекс, сохраняется без ошибки, а затем возвращает пустое значение для каждого пакета.
Не оборачивайте функцию зоны в `value()`. Первый параметр `value()` — это имя атрибута, а не выражение, поэтому вызов вроде `value("inGeofence(35229)", 1, 'valid')` ищет атрибут с таким буквальным именем и всегда возвращает пустое значение.
Для `value()` подробностей о функции см. [выражения и синтаксис IF/THEN Логика](/docs/user/ru/guide/account/iot-logic/nodes/logic-node/logic-node-expressions-and-syntax.md).
{% endtab %}
{% endtabs %}
### Как добавить условие зоны
Поле выражения в **IF/THEN Логика** панели настройки узла содержит отдельный селектор зоны , отдельный от стандартного [автодополнения атрибутов](/docs/user/ru/guide/account/iot-logic/nodes/initiate-attribute-node/managing-attributes.md#autofill-attribute-names). Он перечисляет все зоны, определённые в вашей учётной записи Navixy, сгруппированные по имени и ID.
Чтобы добавить функцию зоны в выражение:
{% stepper %}
{% step %}
#### Откройте настройку узла
Откройте **IF/THEN Логика** узел, щёлкнув по нему на холсте.
{% endstep %}
{% step %}
#### Откройте выбор зоны
В **Выражение условия (JEXL)** поле нажмите значок выбора зоны, чтобы открыть список зон.
{% endstep %}
{% step %}
#### Найдите и выберите зону
Введите часть названия зоны, чтобы отфильтровать список. Каждая зона отображается три раза — по одному разу для каждой доступной функции. Выберите запись, которая сочетает нужную вам зону с функцией, соответствующей вашему условию:
* `inGeofence` - используйте, когда нужно проверить, находится ли устройство сейчас внутри выбранной зоны.
* `enterGeofence` - используйте, когда нужно определить, что устройство переместилось извне выбранной зоны внутрь неё.
* `leaveGeofence` - используйте, когда нужно определить, что устройство переместилось изнутри выбранной зоны наружу.
Селектор вставляет полный вызов функции в позицию курсора в поле выражения.
{% endstep %}
{% step %}
#### При необходимости объедините с другими условиями
Используйте логические операторы, чтобы объединить функцию зоны с другими условиями. См. [примеры условий](#condition-examples).
{% endstep %}
{% step %}
#### Сохраните конфигурацию
Нажмите **Примените изменения** чтобы подтвердить настройку узла.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
Селектор зоны отображает только те зоны, которые существуют в вашей учётной записи Navixy на момент открытия узла. Если вы добавите новую зону после открытия узла, закройте его и откройте снова, чтобы обновить список.
{% endhint %}
Селектор вставляет только три функции, основанные на ID. Чтобы использовать `geofenceName()`, введите её в поле вручную.
### примеры условий
Условие для одной зоны
Данные маршрута в зависимости от того, находится ли устройство сейчас внутри зоны доставки:
```jexl
inGeofence(35229 /* Зона доставки #4 */)
```
* **ветка THEN**: Сюда поступают данные с устройств внутри зоны. Используйте эту ветку, чтобы запускать обработку, специфичную для зоны, например изменять пороги скорости или запускать атрибут таймера простоя.
* **ветка ELSE**: Сюда поступают данные с устройств вне зоны для стандартной обработки.
Обнаружение въезда
Запускайте действие, когда транспортное средство въезжает на объект с ограниченным доступом:
```jexl
enterGeofence(85269 /* Стройплощадка 1 */)
```
* **ветка THEN**: Подключите к **Вебхук** узлу, чтобы уведомить охрану объекта, или к **Действие устройства** узлу, чтобы зафиксировать событие въезда.
* **ветка ELSE**: Продолжайте стандартную обработку данных для устройств, не въезжающих на объект.
Обнаружение выезда
Определяйте, когда транспортное средство покидает разрешенную сервисную зону в рабочее время:
```jexl
leaveGeofence(51577 /* Склад в Остине */) == true && value('business_hours', 0, 'valid') == true
```
* **ветка THEN**: Отправьте предупреждение через **Вебхук** узел в диспетчерскую систему.
* **ветка ELSE**: Продолжайте стандартную обработку.
Объединение нескольких зон
Проверьте, находится ли устройство внутри какой-либо из нескольких зон с ограниченным доступом:
```jexl
inGeofence(35229 /* Зона доставки № 4 */) == true || inGeofence(85269 /* Стройплощадка 1 */) == true
```
Каждая функция сравнивается с `== true`, поэтому пакет, в котором одна из них не может определить результат, не останавливает всё условие. Без сравнения первая функция, возвращающая пустое значение, останавливает условие, а остальные зоны так и не проверяются. См. [Когда функция зоны не дает ответа](#when-a-geofence-function-gives-no-answer).
* **ветка THEN**: Применяйте правила или уведомления, специфичные для зоны.
* **ветка ELSE**: Обрабатывайте данные с устройств вне всех перечисленных зон.
Зона в сочетании с параметром устройства
Определяйте превышение скорости в конкретной городской зоне:
```jexl
inGeofence(84762 /* пункт назначения 1 */) == true && value('speed', 0, 'valid') > 50
```
* **ветка THEN**: Зарегистрируйте контроль скорости, относящийся к этой зоне, или отправьте целевое предупреждение.
* **ветка ELSE**: Продолжайте стандартную обработку для данных, соответствующих требованиям, или данных вне зоны.
Сравнение с предыдущей позицией
Определите переход снаружи внутрь, сравнив текущую позицию с предыдущей:
```jexl
inGeofence(35229 /* Зона доставки № 4 */) == true && inGeofence(35229 /* Зона доставки № 4 */, 1, 'valid') == false
```
Это выражение возвращает `true` только в первом пакете после того, как устройство входит в зону. `enterGeofence()` делает то же самое одним вызовом, поэтому используйте эту форму только тогда, когда вам нужен другой индекс, чем у предыдущего пакета.
Второй вызов сравнивается с `== false`, поэтому выражение срабатывает только тогда, когда предыдущая позиция известна и была вне зоны. Устройство без предыдущей корректной позиции не подходит. Не записывайте второй термин как `!inGeofence(...)`, поскольку в этом случае при отсутствии предыдущей позиции для проверки результата не будет вообще.
## Запись текущей зоны
`geofenceName()` показывает, в какой зоне находится устройство, вместо того чтобы проверять одну заранее выбранную зону. Оно возвращает имя в виде текста, а вы сохраняете этот текст в отдельном атрибуте.
Одна формула охватывает все ваши зоны. Вам не нужно строить цепочку проверок для каждой зоны и редактировать поток каждый раз, когда вы добавляете зону. Вот что хранит атрибут у развозного автомобиля в течение дня:
| Пакет данных | `current_zone` |
| ------------ | ------------------ |
| 08:14 | `Главный гараж` |
| 09:02 | (пусто) |
| 09:47 | `Объект клиента 3` |
Вы создаете его как вычисляемый атрибут в **Вычисление атрибута** Узел. Оттуда он ведёт себя как любой другой вычисляемый атрибут: он отображается в [Анализ данных](/docs/user/ru/guide/account/iot-logic/data-stream-analyzer.md), его можно отображать на платформе как пользовательский датчик и передавать во внешнюю систему.
### Перед началом
**Эта опция должна быть включена для вашей учетной записи.** `geofenceName()` продаётся отдельно и по умолчанию отключена для всех. Свяжитесь с вашим поставщиком услуг и попросите его включить функцию названия Зоны для вашей учётной записи. Это поможет, если вы укажете внутреннее название функции, `iot_logic_зона_поиск`.
Пока функция не включена, поток, использующий эту функцию, не может быть сохранён. Узел помечен этой ошибкой:
```
Функция geofenceName() в узле «Определение текущей зоны» (#2) недоступна для вашей учетной записи
```
Удалите функцию из Узла, чтобы сохранить поток, или подождите, пока ваш провайдер включит эту опцию.
**Для поиска вам также нужны зоны.**
* В вашей учетной записи есть как минимум одна зона. См. [Зоны](/docs/user/ru/guide/tracking/map-tools/geofences.md).
* Чтобы искать только часть ваших зон, пометьте их тегами. См. [Используйте теги](/docs/user/ru/guide/tracking/map-tools/geofences.md#use-tags) и [Теги](/docs/user/ru/guide/account/tags.md).
### Добавьте атрибут
Создайте вычисляемый атрибут обычным способом, как описано в [Управление атрибутами](/docs/user/ru/guide/account/iot-logic/nodes/initiate-attribute-node/managing-attributes.md#creating-attributes), а затем введите одну из приведённых ниже формул в **Формула** поле.
Введите имя функции самостоятельно. Атрибут автодополнения не предлагает `geofenceName`, а селектор зоны доступен только в узле. **IF/THEN Логика** Узел.
### Формулы
Первые две формы покрывают большинство случаев. Третья считывает более раннюю позицию вместо текущей.
| Формула | Что возвращает |
| ------------------------------ | --------------------------------------------------------------------- |
| `geofenceName()` | Имя любой зоны, в которой сейчас находится устройство |
| `geofenceName('depots')` | Имя зоны с тегом `депо` в которой устройство сейчас находится |
| `geofenceName('', 1, 'valid')` | Имя любой зоны, в которой устройство было на один пакет данных раньше |
Все три параметра необязательны:
* **Тег**, во-первых, ограничивает поиск зонами, помеченными этим именем. Регистр не имеет значения, а пустой тег означает все зоны. Тегирование важно, когда у вас много зон и только некоторые из них имеют смысл для этого атрибута, например депо, но не объекты клиентов.
* **Номер пакета**, во-вторых, указывает, как далеко назад смотреть: `0` является обрабатываемым пакетом, `1` предыдущий, и так далее. Не указывайте его для текущей позиции.
* **Фильтр позиций**, третий, — `'действительный'` чтобы пропускать пакеты, не содержащие позиции, или `'все'` чтобы учитывать их. Не указывайте его, и пакеты без позиции будут учитываться.
Для точных ограничений каждого параметра см. [функция названия зоны](/docs/iot-logic-api/technical-details/geofence-name.md) в документации API IoT Logic.
### Что возвращается
Атрибут содержит имя зоны в виде текста или пустое значение, когда имени нет. Оно пустое, когда:
* Устройство находится вне всех найденных зон.
* Пакет данных не содержит координат.
* Ни одна зона в вашем аккаунте не имеет указанного вами тега.
Пустое значение выглядит одинаково во всех трёх случаях. В формуле это пустое значение записывается как `null`, и именно так это проверяет пример маршрутизации ниже.
Чтобы вместо пустого значения получить читаемый текст, добавьте запасной вариант с помощью `?:` оператора:
```jexl
geofenceName() ?: 'Outside all geofences'
```
Когда позиция попадает внутрь двух перекрывающихся зон, функция возвращает одно из двух имён. Navixy не ранжирует перекрывающиеся зоны, и одно и то же имя возвращается, пока устройство находится в области перекрытия.
### Примеры формул
Текущее имя зоны как атрибут
В **Вычисление атрибута** узле создайте атрибут с именем `current_zone` с такой формулой:
```jexl
geofenceName()
```
Каждый пакет данных, записанный внутри зоны, получает имя этой зоны. Пакеты, записанные вне всех зон, получают пустое значение.
Только зоны, которые вы пометили
Пометьте зоны гаража тегом `депо`, затем создайте атрибут с такой формулой:
```jexl
geofenceName('depots') ?: 'In transit'
```
Устройство внутри гаража получает имя этого гаража. Устройство в любом другом месте получает `В пути`, в том числе устройство внутри зоны, у которой нет `депо` тега.
Маршрутизация по области в узле IF/THEN Логика
`geofenceName()` также работает как условие, что полезно, когда многие зоны используют одно правило. Чтобы отправлять данные, записанные внутри любой зоны с тегом `restricted` по ветке THEN, используйте это условие:
```jexl
geofenceName('restricted') != null
```
* **ветка THEN**: Данные, записанные внутри зоны с ограниченным доступом. Подключите их к **Вебхук** узлу, чтобы оповестить диспетчера.
* **ветка ELSE**: Все остальные данные.
Сравните результат с `==` или `!=` только. `<`, `>`, `<=`, и `>=` операторы не дают полезного результата, когда значение пусто.
Обнаружение смены зоны
Чтобы срабатывать только на пакете, в котором устройство меняет зону, сравните текущее имя с именем в предыдущей позиции:
```jexl
geofenceName() != geofenceName('', 1, 'valid')
```
Пустой первый параметр означает все зоны, а `'действительный'` заставляет сравнение пропускать пакеты, которые не содержали координат. Без `'действительный'`, пакет без координат воспринимается как пустое имя зоны, и условие сообщает об изменении, которого не было.
## Часто задаваемые вопросы
#### Где найти ID зоны?
Селектор зон отображает имя каждой зоны и её числовой ID в списке. Также ID можно найти в интерфейсе зон Navixy. Когда вы выбираете зону в селекторе, ID автоматически вставляется в выражение.
#### Могу ли я сохранить проверку зоны в атрибуте?
Да. Все четыре функции работают как в формуле атрибута, так и в условии маршрутизации. `geofenceName()` естественный выбор, потому что он дает читаемый текст. Остальные три дают значение «да» или «нет» либо пустое значение, когда позиция неизвестна. Значение «да» или «нет» обычно полезнее для маршрутизации, чем для хранения.
Выбор зоны доступен только в **IF/THEN Логика** узле, поэтому в формуле атрибута вы вводите функцию и идентификатор зоны вручную.
#### Почему я не могу сохранить поток, который использует geofenceName?
`geofenceName()` Это платная опция и по умолчанию отключена. Обратитесь к поставщику услуг, чтобы ее включили для вашей учетной записи. См. [Перед началом](#before-you-start).
#### Что произойдет, если удалена указанная зона?
Если зона, на которую ссылаются в выражении, будет удалена из вашей учетной записи Navixy, функция больше не сможет отвечать и вернет пустое значение. В **IF/THEN Логика** узле, который использует функцию сам по себе, данные проходят через соединение ELSE. Узел сохраняет свой атрибут как пустое значение, а не как `false`. В условии, которое объединяет функцию с другими терминами, пустое значение может остановить все условие. В **Вычисление атрибута** узле у атрибута нет значения для этого пакета. См. [Отсутствующие значения в выражениях](/docs/user/ru/guide/account/iot-logic/nodes/missing-values-in-expressions.md).
Поток продолжает выполняться, но вы больше не можете сохранить его, пока не исправите выражение. Повторное сохранение завершается с `Узел «<название узла>» (#<идентификатор узла>) содержит несуществующие или недоступные геозоны`. Обновите или удалите выражение, чтобы восстановить и маршрутизацию, и возможность сохранения.
#### Оценивает ли inGeofence текущее GPS-положение устройства?
Да. `inGeofence()` проверяет положение, переданное в текущем пакете данных, по границам зоны. Каждый пакет оценивается независимо, поэтому результат отражает положение устройства в момент получения этого пакета. Пакету, не содержащему координат, вместо этого присваивается пустое значение `true` или `false`.
#### В чем разница между inGeofence и enterGeofence?
`inGeofence()` возвращает `true` для каждого пакета, который сообщает о положении внутри Зоны. `enterGeofence()` возвращает `true` только для пакета, который фиксирует момент, когда устройство пересекло границу Зоны. Используйте `inGeofence` когда вам нужно применять логику ко всем данным внутри зоны. Используйте `enterGeofence` когда вам нужно реагировать именно на событие пересечения границы.
#### Почему атрибут geofenceName всегда пуст?
Проверьте эти причины по порядку:
1. Опция не включена для вашей учётной записи. Ранее сохранённый поток продолжает выполняться, и функция возвращает пустое значение для каждого пакета. См. [Перед началом](#before-you-start).
2. Переданный вами тег не назначен ни одной зоне. Имена тегов должны совпадать с тегом, который существует в вашей учётной записи.
3. Устройство действительно находится вне каждой зоны, которую вы искали.
4. У вас очень большое количество зон, и формула не передаёт тег. Передайте тег, чтобы искать по меньшему набору. Точный порог указан в [функция названия зоны](/docs/iot-logic-api/technical-details/geofence-name.md).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://navixy.com/docs/user/ru/guide/account/iot-logic/nodes/geofence-functions.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
, отдельный от стандартного [автодополнения атрибутов](/docs/user/ru/guide/account/iot-logic/nodes/initiate-attribute-node/managing-attributes.md#autofill-attribute-names). Он перечисляет все зоны, определённые в вашей учётной записи Navixy, сгруппированные по имени и ID.
Чтобы добавить функцию зоны в выражение:
{% stepper %}
{% step %}
#### Откройте настройку узла
Откройте **IF/THEN Логика** узел, щёлкнув по нему на холсте.
{% endstep %}
{% step %}
#### Откройте выбор зоны
В **Выражение условия (JEXL)** поле нажмите значок выбора зоны, чтобы открыть список зон.