> 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" %}
Сначала нужно создать зоны в Navixy, чтобы затем ссылаться на них в выражениях IoT Logic. Чтобы создавать зоны или управлять ими, см. [Зоны](/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 Логика** узла. The `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()` берут идентификатор зоны и больше ничего. Оба сравнивают текущую позицию с предыдущей, поэтому выбирать индекс не нужно. Поток, который передаёт второй параметр любой из этих функций, нельзя сохранить, а в сообщении об ошибке указывается функция.
Указывайте индекс в диапазоне от 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 /* Construction site 1 */)
```
* **Ветвь THEN**: Подключите к **узлу Вебхук** , чтобы уведомить охрану объекта, или к узлу **Действие устройства** , чтобы записать событие въезда.
* **Ветвь ELSE**: Продолжайте обычную обработку данных для устройств, не въезжающих на объект.
Обнаружение выезда
Определите момент, когда транспортное средство покидает разрешённую зону обслуживания в рабочее время:
```jexl
leaveGeofence(51577 /* Austin Warehouse */) == true && value('business_hours', 0, 'valid') == true
```
* **Ветвь THEN**: Отправьте предупреждение через **узлу Вебхук** узел в систему диспетчеризации.
* **Ветвь ELSE**: Продолжайте стандартную обработку.
Объединение нескольких зон
Проверьте, находится ли устройство внутри любой из нескольких ограниченных зон:
```jexl
inGeofence(35229 /* Delivery zone #4 */) == true || inGeofence(85269 /* Construction site 1 */) == true
```
Каждая функция сравнивается с `== true`, так что пакет, в котором одна из них не может принять решение, не останавливает всё условие. Без этого сравнения первая функция, которая возвращает пустое значение, останавливает условие, и остальные зоны вообще не проверяются. См. [Когда функция зоны не дает ответа](#when-a-geofence-function-gives-no-answer).
* **Ветвь THEN**: Применяйте правила или уведомления, специфичные для зоны.
* **Ветвь ELSE**: Обрабатывайте данные от устройств вне всех перечисленных зон.
Зона в сочетании с параметром устройства
Определите превышение скорости в пределах определённой городской зоны:
```jexl
inGeofence(84762 /* destination1 */) == true && value('speed', 0, 'valid') > 50
```
* **Ветвь THEN**: Запишите контроль скорости для этой зоны или отправьте целевое предупреждение.
* **Ветвь ELSE**: Продолжайте стандартную обработку для данных, соответствующих правилам или находящихся вне зоны.
Сравнение с предыдущим положением
Определите переход извне внутрь, сравнив текущее положение с предыдущим:
```jexl
inGeofence(35229 /* Delivery zone #4 */) == true && inGeofence(35229 /* Delivery zone #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_Зона_search`.
Пока она не будет включена, поток, использующий эту функцию, нельзя сохранить. Узел помечен этой ошибкой:
```
Функция geofenceName() в узле «Resolve current zone» (#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), и введите одну из формул ниже в **Formula** поле.
Введите имя функции самостоятельно. Автодополнение атрибутов не предлагает `geofenceName`, а селектор Зоны доступен только в **IF/THEN Логика** Узле.
### Формулы
Первые две формы покрывают большинство случаев. Третья читает предыдущую позицию вместо текущей.
| Formula | Что возвращает |
| ------------------------------ | ------------------------------------------------------------------------- |
| `geofenceName()` | Название любой зоны, в которой устройство сейчас находится |
| `geofenceName('depots')` | Название зоны с тегом `депо` в которой устройство сейчас находится |
| `geofenceName('', 1, 'valid')` | Название любой зоны, в которой устройство было в предыдущем пакете данных |
Все три параметра необязательны:
* **Тег**, во-первых, ограничивает поиск по геозонам, которым вы присвоили этот тег. Регистр не важен, а пустой тег означает все геозоны. Присвоение тегов важно, когда у вас много геозон и лишь некоторые из них имеют значение для этого атрибута, например склады, но не объекты клиентов.
* **Номер пакета**, во-вторых, указывает, насколько далеко назад смотреть: `0` обрабатываемый пакет, `1` предыдущий и так далее. Опустите его для текущего положения.
* **Фильтр позиции**, в-третьих, — это `«valid»` чтобы пропустить пакеты, не содержащие координат, или `'all'` чтобы учитывать их. Уберите этот параметр, и пакеты без координат будут учитываться.
Точные ограничения каждого параметра см. [Функция имени зоны](/docs/iot-logic-api/technical-details/geofence-name.md) в документации API IoT Logic.
### Что возвращается
Атрибут содержит имя зоны в виде текста или пустое значение, если указать нечего. Он пуст, когда:
* Устройство находится вне всех найденных зон.
* Пакет данных не содержит координат.
* Ни одна зона в вашем аккаунте не имеет переданный вами тег.
Пустое значение выглядит одинаково во всех трех случаях. В формуле это пустое значение записывается как `null`, именно так его проверяет пример маршрутизации ниже.
Чтобы вместо пустого значения получить читаемый текст, добавьте запасной вариант с `?:` оператором:
```jexl
geofenceName() ?: 'Вне всех зон'
```
Когда координаты попадают в две перекрывающиеся зоны, функция возвращает одно из двух имен. Navixy не задает приоритет для перекрывающихся зон, и одно и то же имя будет возвращаться, пока устройство остается в области перекрытия.
### Примеры формул
Текущее имя зоны как атрибут
В **Вычисление атрибута** узле, создайте атрибут с именем `current_zone` с такой формулой:
```jexl
geofenceName()
```
Каждый пакет данных, записанный внутри зоны, получает имя этой зоны. Пакеты, записанные вне всех зон, получают пустое значение.
Только зоны, которые вы пометили тегом
Пометьте зоны гаража тегом `депо`, затем создайте атрибут с такой формулой:
```jexl
geofenceName('depots') ?: 'В пути'
```
Устройство внутри гаража получает имя этого гаража. Устройство где угодно еще получает `В пути`, включая устройство внутри зоны, у которой нет `депо` тега.
Маршрутизация по зоне в узле IF/THEN Логика
`geofenceName()` также работает как условие, что полезно, когда многие зоны подчиняются одному правилу. Чтобы отправлять данные, записанные внутри любой зоны с тегом `restricted` по ветке THEN, используйте это условие:
```jexl
geofenceName('restricted') != null
```
* **Ветвь THEN**: Данные, записанные внутри зоны с ограниченным доступом. Подключите его к **узлу Вебхук** узлу, чтобы оповещать диспетчера.
* **Ветвь ELSE**: Все остальные данные.
Сравните результат с `==` или `!=` только. С `<`, `>`, `<=`, и `>=` операторы не дают пригодного результата, когда значение пустое.
Обнаружение смены зоны
Чтобы срабатывать только на том пакете, в котором устройство меняет зону, сравните текущее имя с именем в предыдущей точке:
```jexl
geofenceName() != geofenceName('', 1, 'valid')
```
Пустой первый параметр означает все зоны, а `«valid»` заставляет сравнение пропускать пакеты, не содержащие координат. Без `«valid»`, пакет без координат воспринимается как пустое имя зоны, и условие сообщает об изменении, которого не было.
## Часто задаваемые вопросы
#### Где я могу найти ID зоны?
В списке в окне выбора зон отображаются название каждой зоны и числовой ID. Вы также можете найти ID в интерфейсе зон Navixy. Когда вы выбираете зону в окне выбора, ID автоматически вставляется в выражение.
#### Могу ли я сохранить проверку зоны в атрибуте?
Да. Все четыре функции работают как в формуле атрибута, так и в условии маршрутизации. `geofenceName()` Это естественный выбор, потому что он возвращает читаемый текст. Остальные три возвращают значение «да» или «нет», либо пустое значение, когда местоположение неизвестно. Значение «да» или «нет» обычно полезнее для маршрутизации, чем для хранения.
Выбор зоны доступен только в **IF/THEN Логика** узле, поэтому в формуле атрибута вы вводите функцию и ID зоны вручную.
#### Почему я не могу сохранить поток, который использует geofenceName?
`geofenceName()` Это платная опция и по умолчанию отключена. Обратитесь к поставщику услуг, чтобы ее включили для вашей учетной записи. См. [Перед началом работы](#before-you-start).
#### Что произойдет, если указанная Зона будет удалена?
Если зона, на которую ссылается выражение, удалена из вашей учетной записи Navixy, функция больше не сможет возвращать ответ и вернет пустое значение. В **IF/THEN Логика** Узел, который сам использует функцию, пропускает данные через соединение ELSE. Узел хранит свой атрибут как пустое значение, а не как `ложь`. В условии, которое объединяет функцию с другими терминами, пустое значение может остановить всё условие. В **Вычисление атрибута** на узле у этого атрибута нет значения для этого пакета. См. [Отсутствующие значения в выражениях](/docs/user/ru/guide/account/iot-logic/nodes/missing-values-in-expressions.md).
Поток продолжает работать, но вы больше не можете сохранить его, пока не исправите выражение. Повторное сохранение завершается с `Узел "" (#) содержит несуществующие или недоступные геозоны`. Обновите или удалите выражение, чтобы восстановить и маршрутизацию, и возможность сохранения.
#### Оценивает ли inGeofence текущее GPS-положение устройства?
Да. `inGeofence()` Проверяет положение, указанное в текущем пакете данных, относительно границ зоны. Каждый пакет оценивается независимо, поэтому результат отражает положение устройства в момент получения этого пакета. Пакет без координат получает пустое значение вместо `true` или `ложь`.
#### В чем разница между 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)** нажмите значок выбора зоны, чтобы открыть список зон.