> 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/pt-br/guide/account/iot-logic/nodes/geofence-functions.md).
# Funções de geocerca
Use as cercas geográficas que você já tem no Navixy dentro dos fluxos do IoT Logic para agir quando um dispositivo entra ou sai de uma área, ou para registrar em qual área ele está.
As funções de geocerca permitem que um fluxo reaja à posição de um dispositivo, usando as geocercas que você já tem no Navixy. Você referencia uma geocerca em vez de descrever uma área com coordenadas, para que os limites permaneçam os mesmos que você já usa para alertas e relatórios.
## Qual função você precisa
| Se você quiser | Use |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Agir sobre uma geocerca específica, quando um dispositivo está dentro dela, entra nela ou sai dela | `inGeofence()`, `enterGeofence()`, `leaveGeofence()`. Veja [Reagir a uma geocerca](#reacting-to-one-geofence) |
| Descobrir em qual geocerca um dispositivo está, sem nomear uma com antecedência | `geofenceName()`. Veja [Registrar a geocerca atual](#recording-the-current-geofence) |
{% hint style="warning" %}
Você deve criar geocercas no Navixy antes de poder referenciá-las em expressões do IoT Logic. Para criar ou gerenciar geocercas, veja [Geocercas](/docs/user/pt-br/guide/tracking/map-tools/geofences.md).
{% endhint %}
{% hint style="danger" %}
**`geofenceName()` é uma opção paga, vendida separadamente.** Ela vem desativada por padrão para todas as contas, e seu provedor de serviço a habilita por conta mediante solicitação. As outras três funções não são afetadas e não precisam de nenhuma opção extra.
Entre em contato com seu provedor de serviço para ativá-la. Veja [Antes de começar](#before-you-start).
{% endhint %}
## Reagir a uma geocerca
Use estas três funções quando você já souber qual geocerca importa. Cada uma responde sim ou não para a maioria dos pacotes de dados que o dispositivo envia, para que um fluxo possa enviar esses dados por um caminho ou outro. Em alguns pacotes, uma função não consegue responder e retorna um valor vazio. Veja [Quando uma função de geocerca não fornece resposta](#when-a-geofence-function-gives-no-answer).
| Função | Responde sim quando |
| ------------------- | ------------------------------------------------ |
| `inGeofence(id)` | O dispositivo está dentro da geocerca no momento |
| `enterGeofence(id)` | O dispositivo acabou de entrar na geocerca |
| `leaveGeofence(id)` | O dispositivo acabou de sair da geocerca |
Você os adiciona à condição de um **Lógica** nó. O `id` é o ID numérico da geocerca na sua conta Navixy, e um seletor o preenche para você, então você raramente o digita manualmente. Veja [Como adicionar uma condição de geocerca](#how-to-add-a-geofence-condition).
### Quando uma função de geocerca não fornece resposta
`inGeofence()`, `enterGeofence()`{{longitude}} `leaveGeofence()` retornam um valor vazio em vez de sim ou não quando não conseguem responder. Uma função não consegue responder nestes casos:
* O pacote de dados não carrega coordenadas. Uma posição de baixa qualidade ainda é testada, então um sinal GPS fraco gera um sim ou não real.
* A geocerca foi excluída da sua conta Navixy ou ficou inacessível depois que o fluxo foi salvo. Uma geocerca que já esteja ausente quando você salvar o fluxo é rejeitada nesse momento.
Um valor vazio interrompe a condição da qual faz parte. Quando a função é a condição inteira, os dados vão para o caminho ELSE. Esse roteamento normalmente é o que você quer. Quando a função é combinada com qualquer outra coisa, o valor vazio pode interromper a condição inteira, inclusive os termos que tinham valor. Para manter o restante da condição funcionando, compare a função com `== true`:
```jexl
leaveGeofence(51577 /* Austin Warehouse */) == true || leaveGeofence(85269 /* Construction site 1 */) == true
```
Para a regra completa, veja [Valores ausentes em expressões](/docs/user/pt-br/guide/account/iot-logic/nodes/missing-values-in-expressions.md).
### Sintaxe
{% tabs %}
{% tab title="Posição atual" %}
Este é o formato que o seletor de geocerca insere automaticamente. O nome da geocerca aparece como um comentário para facilitar a leitura, mas não afeta a avaliação.
```jexl
inGeofence(35229 /* Delivery zone #4 */)
enterGeofence(51577 /* Austin Warehouse */)
leaveGeofence(85269 /* Construction site 1 */)
```
{% endtab %}
{% tab title="Posição histórica" %}
`inGeofence()` aceita dois parâmetros adicionais, para que possa testar uma posição anterior em vez da atual:
```jexl
inGeofence(35229 /* Delivery zone #4 */, 1)
inGeofence(35229 /* Delivery zone #4 */, 1, 'valid')
inGeofence(35229 /* Delivery zone #4 */, 'valid')
```
O segundo parâmetro informa de qual pacote de dados obter a posição, contando de trás para frente a partir do atual. O terceiro informa se os pacotes que não carregam posição devem ser contados. Ambos são opcionais e seguem a mesma convenção da `value()` função.
`enterGeofence()` Webhook `leaveGeofence()` Aceitam o ID da geocerca e nada mais. Ambas comparam a posição atual com a anterior, então não há índice a escolher. Um fluxo que passe um segundo parâmetro a qualquer uma das funções não pode ser salvo, e o erro nomeia a função.
Mantenha o índice na faixa de 0 a 11. `inGeofence()` aceita um índice maior, salva sem erro e, em seguida, retorna um valor vazio para cada pacote.
Não envolva uma função de geocerca dentro de `value()`. O primeiro parâmetro de `value()` é um nome de atributo, não uma expressão, então uma chamada como `value("inGeofence(35229)", 1, 'valid')` procura um atributo com esse nome literal e sempre retorna um valor vazio.
Para `value()` detalhes da função, consulte [Expressões e sintaxe da Lógica](/docs/user/pt-br/guide/account/iot-logic/nodes/logic-node/logic-node-expressions-and-syntax.md).
{% endtab %}
{% endtabs %}
### Como adicionar uma condição de geocerca
O campo de expressão no **Lógica** painel de configuração do nó inclui um seletor dedicado de geocerca , separado do autocompletar padrão de [atributos](/docs/user/pt-br/guide/account/iot-logic/nodes/initiate-attribute-node/managing-attributes.md#autofill-attribute-names). Ele lista todas as geocercas definidas na sua conta Navixy, agrupadas por nome e ID.
Para adicionar uma função de geocerca à sua expressão:
{% stepper %}
{% step %}
#### Abrir a configuração do nó
Abra o **Lógica** nó clicando nele na área de trabalho.
{% endstep %}
{% step %}
#### Abrir o seletor de geocerca
No **campo de Expressão de condição (JEXL)** , clique no ícone do seletor de geocerca para abrir a lista de geocercas.
{% endstep %}
{% step %}
#### Encontrar e selecionar uma geocerca
Digite parte do nome da geocerca para filtrar a lista. Cada geocerca aparece três vezes, uma para cada função disponível. Selecione a entrada que combina a geocerca de que você precisa com a função que corresponde à sua condição:
* `inGeofence` - use quando você precisar verificar se um dispositivo está atualmente localizado dentro da zona selecionada.
* `enterGeofence` - use quando você precisar detectar que um dispositivo se moveu de fora da zona selecionada para dentro dela.
* `leaveGeofence` - use quando você precisar detectar que um dispositivo se moveu de dentro da zona selecionada para fora dela.
O seletor insere a chamada completa da função na posição do cursor no campo de expressão.
{% endstep %}
{% step %}
#### Combine com outras condições, se necessário
Use operadores lógicos para combinar a função de geocerca com outras condições. Veja [Exemplos de condições](#condition-examples).
{% endstep %}
{% step %}
#### Salvar a configuração
Salvar **Aplicar alterações** para confirmar a configuração do nó.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
O seletor de geocerca lista apenas geocercas que existam na sua conta Navixy no momento em que você abre o nó. Se você adicionar uma nova geocerca depois de abrir o nó, feche-o e abra-o novamente para atualizar a lista.
{% endhint %}
O seletor insere apenas as três funções baseadas em ID. Para usar `geofenceName()`, digite-o você mesmo no campo.
### Exemplos de condições
Condição única de geocerca
Dados da rota com base em se um dispositivo está atualmente dentro de uma zona de entrega:
```jexl
inGeofence(35229 /* Delivery zone #4 */)
```
* **Caminho THEN**: Dados de dispositivos dentro da zona fluem por aqui. Use este ramo para acionar processamento específico da zona, como ajustar limites de velocidade ou iniciar um atributo de temporizador de permanência.
* **Caminho ELSE**: Dados de dispositivos fora da zona fluem por aqui para processamento padrão.
Detecção de entrada
Acione uma ação quando um veículo entrar em um local restrito:
```jexl
enterGeofence(85269 /* Construction site 1 */)
```
* **Caminho THEN**: Conecte a um **nos nós do IoT Logic fornecem os mesmos recursos subjacentes com automação completa de fluxo e direcionamento para vários dispositivos.** nó para notificar a segurança do local, ou a um **e** nó para registrar o evento de entrada.
* **Caminho ELSE**: Continue o processamento normal dos dados para dispositivos que não entram no local.
Detecção de saída
Detecte quando um veículo sai de uma área de serviço autorizada durante o horário comercial:
```jexl
leaveGeofence(51577 /* Austin Warehouse */) == true && value('business_hours', 0, 'valid') == true
```
* **Caminho THEN**: Envie um alerta por meio de um **nos nós do IoT Logic fornecem os mesmos recursos subjacentes com automação completa de fluxo e direcionamento para vários dispositivos.** nó para um sistema de despacho.
* **Caminho ELSE**: Continue o processamento normal.
Combinação de várias geocercas
Verifique se um dispositivo está dentro de qualquer uma de várias zonas restritas:
```jexl
inGeofence(35229 /* Delivery zone #4 */) == true || inGeofence(85269 /* Construction site 1 */) == true
```
Cada função é comparada com `== true`, então um pacote em que uma delas não consegue decidir não interrompe toda a condição. Sem a comparação, a primeira função que retorna um valor vazio interrompe a condição, e as outras zonas nunca são testadas. Veja [Quando uma função de geocerca não fornece resposta](#when-a-geofence-function-gives-no-answer).
* **Caminho THEN**: Aplique regras ou notificações específicas da zona.
* **Caminho ELSE**: Processe dados de dispositivos fora de todas as zonas listadas.
Geocerca combinada com um parâmetro do dispositivo
Detecte excesso de velocidade dentro de uma zona urbana específica:
```jexl
inGeofence(84762 /* destination1 */) == true && value('speed', 0, 'valid') > 50
```
* **Caminho THEN**: Registre um evento de Excesso de velocidade específico dessa zona, ou envie um alerta direcionado.
* **Caminho ELSE**: Continue o processamento padrão para dados conformes ou fora da zona.
Comparando com a posição anterior
Detecte uma transição de fora para dentro comparando a posição atual com a anterior:
```jexl
inGeofence(35229 /* Delivery zone #4 */) == true && inGeofence(35229 /* Delivery zone #4 */, 1, 'valid') == false
```
Esta expressão retorna `true` somente no primeiro pacote após um dispositivo entrar na geocerca. `enterGeofence()` faz a mesma coisa em uma única chamada, portanto use esta forma somente quando você precisar de um índice diferente do pacote anterior.
A segunda chamada é comparada com `== false`, então a expressão dispara somente quando a posição anterior é conhecida e estava fora da geocerca. Um dispositivo sem posição válida anterior não corresponde. Não escreva o segundo termo como `!inGeofence(...)`, que não produz nenhum resultado quando não há posição anterior a ser testada.
## Registrar a geocerca atual
`geofenceName()` indica em qual geocerca um dispositivo está, em vez de testar uma geocerca que você escolheu com antecedência. Ela retorna o nome como texto, e você armazena esse texto em um atributo próprio.
Uma única fórmula cobre todas as geocercas que você tem. Você não monta uma cadeia de verificações por geocerca e não edita o fluxo toda vez que adiciona uma geocerca. Veja o que o atributo contém para um veículo de entrega que reporta ao longo do dia:
| Pacote de dados | `current_zone` |
| --------------- | ------------------- |
| 08:14 | `Garagem principal` |
| 09:02 | (vazio) |
| 09:47 | `Site do cliente 3` |
Você o cria como um atributo calculado em um **Iniciar Atributo** nó. A partir daí, ele se comporta como qualquer outro atributo calculado: ele aparece em [Analisador de dados](/docs/user/pt-br/guide/account/iot-logic/data-stream-analyzer.md), ele pode ser exibido na plataforma como um sensor personalizado e pode ser encaminhado para um sistema externo.
### Antes de começar
**A opção deve estar ativada para a sua conta.** `geofenceName()` É vendido separadamente e vem desativado por padrão para todos. Entre em contato com o seu provedor de serviços e peça para ativar a função de nome da geocerca para a sua conta. Ajuda informar o nome interno do recurso, `iot_logic_Geocerca_search`.
Até que seja ativado, um fluxo que usa a função não pode ser salvo. O Nó é marcado com este erro:
```
A função geofenceName() no nó "Resolver zona atual" (#2) não está disponível para sua conta
```
Remova a função do Nó para salvar o fluxo, ou aguarde até que seu provedor de serviço ative a opção.
**Você também precisa de geocercas para pesquisar.**
* Existe pelo menos uma geocerca na sua conta. Veja [Geocercas](/docs/user/pt-br/guide/tracking/map-tools/geofences.md).
* Para pesquisar apenas parte das suas geocercas, marque-as com etiquetas. Veja [Usar etiquetas](/docs/user/pt-br/guide/tracking/map-tools/geofences.md#use-tags) Webhook [Etiquetas](/docs/user/pt-br/guide/account/tags.md).
### Adicione o atributo
Crie um atributo calculado da maneira usual, conforme descrito em [Gerenciar atributos](/docs/user/pt-br/guide/account/iot-logic/nodes/initiate-attribute-node/managing-attributes.md#creating-attributes), e insira uma das fórmulas abaixo no **Fórmula** campo.
Digite você mesmo o nome da função. O atributo autocomplete não oferece `geofenceName`, e o seletor de geocerca está disponível apenas no **Lógica** nó.
### Fórmulas
As duas primeiras formas cobrem a maioria dos casos. A terceira lê uma posição anterior em vez da atual.
| Fórmula | O que retorna |
| ------------------------------ | ---------------------------------------------------------------------------------- |
| `geofenceName()` | O nome de qualquer geocerca em que o dispositivo esteja no momento |
| `geofenceName('depots')` | O nome de uma geocerca etiquetada `depósitos` em que o dispositivo está no momento |
| `geofenceName('', 1, 'valid')` | O nome de qualquer geocerca em que o dispositivo estava um pacote de dados antes |
Os três parâmetros são opcionais:
* **A etiqueta**, em primeiro lugar, limita a busca às geocercas que você etiquetou com esse nome. Maiúsculas ou minúsculas não fazem diferença, e uma etiqueta vazia significa todas as geocercas. A etiquetagem importa quando você tem muitas geocercas e apenas algumas delas são relevantes para esse atributo, por exemplo, depósitos, mas não locais de clientes.
* **O número do pacote**, em segundo lugar, indica até onde voltar na busca: `0` é o pacote que está sendo processado, `1` o anterior, e assim por diante. Deixe-o de fora para a posição atual.
* **Filtro de posição**, terceiro, é `'válido'` para ignorar pacotes que não continham posição, ou `'todos'` para contá-los. Deixe-o de fora e os pacotes sem posição serão contados.
Para ver os limites exatos de cada parâmetro, consulte [Função de nome de Geocerca](/docs/iot-logic-api/technical-details/geofence-name.md) na documentação da API do IoT Logic.
### O que você recebe de volta
O atributo armazena o nome da geocerca como texto, ou um valor vazio quando não há nome a ser fornecido. Ele fica vazio quando:
* O dispositivo está fora de todas as geocercas que foram pesquisadas.
* O pacote de dados não contém posição.
* Nenhuma geocerca em sua conta tem a etiqueta que você passou.
Um valor vazio parece igual nos três casos. Em uma fórmula, esse valor vazio é escrito como `null`, que é como o exemplo de roteamento abaixo verifica isso.
Para obter texto legível em vez de um valor em branco, adicione um valor de fallback com o `?:` operador:
```jexl
geofenceName() ?: 'Outside all geofences'
```
Quando uma posição cai dentro de duas geocercas sobrepostas, a função retorna um dos dois nomes. A Navixy não classifica geocercas sobrepostas, e o mesmo nome é retornado enquanto o dispositivo permanecer na sobreposição.
### Exemplos de fórmulas
Nome atual da geocerca como um atributo
Em um **Iniciar Atributo** nó, crie um atributo chamado `current_zone` com esta fórmula:
```jexl
geofenceName()
```
Cada pacote de dados registrado dentro de uma geocerca recebe o nome dessa geocerca. Pacotes registrados fora de todas as geocercas recebem um valor vazio.
Somente as geocercas com a etiqueta que você aplicou
Aplique a etiqueta nas suas geocercas de garagem com `depósitos`, então crie um atributo com esta fórmula:
```jexl
geofenceName('depots') ?: 'In transit'
```
Um dispositivo dentro de uma garagem recebe o nome dessa garagem. Um dispositivo em qualquer outro lugar recebe `Em trânsito`, inclusive um dispositivo dentro de uma geocerca que não tem nenhuma `depósitos` etiqueta.
Roteamento por área em um nó de Lógica
`geofenceName()` também funciona como condição, o que é útil quando muitas geocercas compartilham uma única regra. Para enviar dados registrados dentro de qualquer geocerca com a etiqueta restrita para o caminho THEN, use esta condição: `restrita` para o caminho THEN, use esta condição:
```jexl
geofenceName('restricted') != null
```
* **Caminho THEN**: Dados registrados dentro de uma área restrita. Conecte-os a um **nos nós do IoT Logic fornecem os mesmos recursos subjacentes com automação completa de fluxo e direcionamento para vários dispositivos.** nó para alertar um despachante.
* **Caminho ELSE**: Todos os outros dados.
Compare o resultado com `==` ... `!=` apenas. Os `<`, `>`, `<=`{{longitude}} `>=` operadores não fornecem um resultado útil quando o valor está vazio.
Detectar uma mudança de área
Para disparar apenas no pacote em que o dispositivo muda de geocerca, compare o nome atual com o nome na posição anterior:
```jexl
geofenceName() != geofenceName('', 1, 'valid')
```
O primeiro parâmetro vazio significa todas as geocercas, e `'válido'` faz com que a comparação ignore pacotes que não continham posição. Sem `'válido'`, um pacote sem posição é lido como um nome de geocerca vazio, e a condição relata uma mudança que não aconteceu.
## Perguntas frequentes
#### Onde encontro o ID da geocerca?
O seletor de geocercas exibe o nome e o ID numérico de cada geocerca na lista. Você também pode encontrar o ID na interface de geocercas da Navixy. Ao selecionar uma geocerca no seletor, o ID é inserido automaticamente na expressão.
#### Posso armazenar uma verificação de geocerca em um atributo?
Sim. Todas as quatro funções também funcionam em uma fórmula de atributo, assim como em uma condição de roteamento. `geofenceName()` é a escolha natural, porque fornece texto legível. As outras três fornecem um valor de sim ou não, ou um valor vazio quando a posição é desconhecida. Um valor de sim ou não geralmente é mais útil para roteamento do que para armazenamento.
O seletor de geocerca aparece apenas no **Lógica** nó, então, em uma fórmula de atributo, você digita a função e o ID da geocerca manualmente.
#### Por que não consigo salvar um fluxo que usa geofenceName?
`geofenceName()` É uma opção paga e vem desativada por padrão. Entre em contato com seu provedor de serviços para ativá-la na sua conta. Veja [Antes de começar](#before-you-start).
#### O que acontece se a geocerca referenciada for excluída?
Se uma geocerca referenciada em uma expressão for excluída da sua conta Navixy, a função não poderá mais responder e retornará um valor vazio. Em um **Lógica** nó que usa a função por conta própria, os dados fluem pela conexão ELSE. O nó armazena seu próprio atributo como um valor vazio, não como `falso`. Em uma condição que combina a função com outros termos, o valor vazio pode interromper toda a condição. Em um **Iniciar Atributo** nó, o atributo não tem valor para esse pacote. Veja [Valores ausentes em expressões](/docs/user/pt-br/guide/account/iot-logic/nodes/missing-values-in-expressions.md).
O fluxo continua em execução, mas você não pode mais salvá-lo até corrigir a expressão. Salvá-lo novamente falha com `Nó "" (#) contém geozonas inexistentes ou inacessíveis`. Atualize ou remova a expressão para restaurar tanto o roteamento quanto a capacidade de salvar.
#### O inGeofence avalia a posição GPS atual do dispositivo?
Sim. `inGeofence()` verifica a posição informada no pacote de dados atual em relação aos limites da Geocerca. Cada pacote é avaliado independentemente, portanto o resultado reflete a posição do dispositivo no momento em que esse pacote foi recebido. Um pacote que não carrega posição recebe um valor vazio em vez de `true` ... `falso`.
#### Qual é a diferença entre inGeofence e enterGeofence?
`inGeofence()` retorna `true` para cada pacote que informa uma posição dentro da Geocerca. `enterGeofence()` retorna `true` somente para o pacote que registra o momento em que o dispositivo cruzou a Geocerca. Use `inGeofence` quando você precisa aplicar lógica a todos os dados de dentro da área. Use `enterGeofence` quando você precisa reagir especificamente ao evento de cruzar o limite.
#### Por que meu atributo geocercaName está sempre vazio?
Verifique estas causas nesta ordem:
1. A opção não está ativada para sua conta. Um fluxo salvo anteriormente continua em execução, e a função retorna um valor vazio para cada pacote. Consulte [Antes de começar](#before-you-start).
2. A Etiqueta que você informou não está atribuída a nenhuma Geocerca. Os nomes das Etiquetas devem corresponder a uma Etiqueta que exista em sua conta.
3. O dispositivo realmente está fora de todas as Geocercas que você pesquisou.
4. Você tem um número muito grande de Geocercas e a fórmula não passa nenhuma Etiqueta. Passe uma Etiqueta para pesquisar um conjunto menor. O limite exato está em [Função de nome de Geocerca](/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/pt-br/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.
, separado do autocompletar padrão de [atributos](/docs/user/pt-br/guide/account/iot-logic/nodes/initiate-attribute-node/managing-attributes.md#autofill-attribute-names). Ele lista todas as geocercas definidas na sua conta Navixy, agrupadas por nome e ID.
Para adicionar uma função de geocerca à sua expressão:
{% stepper %}
{% step %}
#### Abrir a configuração do nó
Abra o **Lógica** nó clicando nele na área de trabalho.
{% endstep %}
{% step %}
#### Abrir o seletor de geocerca
No **campo de Expressão de condição (JEXL)** , clique no ícone do seletor de geocerca para abrir a lista de geocercas.