> 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, então os limites permanecem os mesmos que você já usa para alertas e relatórios. ## Qual função você precisa | Se você quiser | Use | | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | | Atuar em uma geocerca específica, quando um dispositivo está dentro dela, entra nela ou sai dela | `inGeofence()`, `enterGeofence()`, `leaveGeofence()`. Veja [Reagindo a uma geocerca](#reacting-to-one-geofence) | | Descobrir em qual geocerca um dispositivo está, sem nomear uma com antecedência | `geofenceName()`. Veja [Registrando 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.** Ele vem desativado para todas as contas por padrão, e seu provedor de serviços o ativa por conta, mediante solicitação. As outras três funções não são afetadas e não precisam de opção adicional. Entre em contato com seu provedor de serviços para ativá-lo. Veja [Antes de começar](#before-you-start). {% endhint %} ## Reagindo a uma geocerca Use estas três funções quando você já souber qual geocerca é relevante. Cada uma responde sim ou não para a maioria dos pacotes de dados que o dispositivo envia, então um fluxo pode enviar esses dados por um ramo ou outro. Em alguns pacotes, uma função não consegue responder e, em vez disso, retorna um valor vazio. Veja [Quando uma função de geocerca não retorna 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 retorna resposta `inGeofence()`, `enterGeofence()`, e `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 contém coordenadas. Uma posição de baixa qualidade ainda é verificada, então uma correção GPS fraca gera um sim ou não verdadeiro. * 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 no momento de salvar, em vez disso. 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 geralmente é 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 valores. 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 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, então pode 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 indica de qual pacote de dados tomar a posição, contando para trás a partir do atual. O terceiro indica se os pacotes que não contêm posição devem ser contados. Ambos são opcionais e seguem a mesma convenção da `value()` função. `enterGeofence()` e `leaveGeofence()` aceitam o ID da geocerca e nada mais. Ambos comparam a posição atual com a anterior, então não há índice para escolher. Um fluxo que passe um segundo parâmetro para qualquer uma das funções não pode ser salvo, e o erro nomeia a função. Mantenha o índice no intervalo de 0 a 11. `inGeofence()` aceita um índice maior, é salvo sem erro e depois 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 de geocerca dedicado , separado do padrão [autocompletar 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 %} #### Abra a configuração do nó Abra o **Lógica** nó clicando nele na área de trabalho. {% endstep %} {% step %} #### Abra o seletor de geocerca No **campo Expressão de condição (JEXL)** clique no ícone do seletor de geocerca para abrir a lista de geocercas.
Geofence picker list example, with all three options (in, enter, leave geofence)
{% endstep %} {% step %} #### Encontre e selecione 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 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. Consulte [Exemplos de condições](#condition-examples). {% endstep %} {% step %} #### Salve a configuração Clique em **Aplicar alterações** para confirmar a configuração do nó. {% endstep %} {% endstepper %} {% hint style="info" %} O seletor de geocerca lista apenas as geocercas que existem 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-a no campo você mesmo. ### Exemplos de condições
Condição de geocerca única 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**: Os dados dos dispositivos dentro da zona fluem para cá. Use esta ramificação para acionar o processamento específico da zona, como ajustar limites de velocidade ou iniciar um atributo de temporizador de permanência. * **Caminho ELSE**: Os dados dos dispositivos fora da zona fluem para cá para processamento padrão.
Detectar 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 **Webhook** Nó para notificar a Segurança do local, ou a um **Ação** Nó para registrar o evento de entrada. * **Caminho ELSE**: Continue o processamento normal para dispositivos que não entram no local.
Detectar 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 **Webhook** Nó para um sistema de despacho. * **Caminho ELSE**: Continue o processamento padrão.
Combinar 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 retorna resposta](#when-a-geofence-function-gives-no-answer). * **Caminho THEN**: Aplique regras ou notificações específicas da zona. * **Caminho ELSE**: Processe os dados de dispositivos fora de todas as zonas listadas.
Combinar Geocerca com um parâmetro do dispositivo Detecte excesso de velocidade em uma zona urbana específica: ```jexl inGeofence(84762 /* destination1 */) == true && value('speed', 0, 'valid') > 50 ``` * **Caminho THEN**: Registre um Excesso de velocidade específico para essa zona, ou envie um alerta direcionado. * **Caminho ELSE**: Continue o processamento padrão para dados em conformidade ou fora da zona.
Comparar 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` apenas no primeiro pacote após um dispositivo entrar na Geocerca. `enterGeofence()` faz a mesma coisa em uma única chamada, portanto use este formato apenas quando você precisar de um índice diferente do pacote anterior. A segunda chamada é comparada com `== false`, portanto, a expressão é acionada apenas 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(...)`, o que não produz nenhum resultado quando não há posição anterior para testar.
## Registrando a geocerca atual `geofenceName()` Informa em qual Geocerca um dispositivo está, em vez de testar uma Geocerca que você escolheu antecipadamente. 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 envia dados ao longo do dia: | Pacote de dados | `zona_atual` | | --------------- | -------------------- | | 08:14 | `Garagem principal` | | 09:02 | (vazio) | | 09:47 | `Local 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 seu provedor de serviços e peça que ele habilite a função de nome da Geocerca em sua conta. Isso ajuda a citar o nome interno do recurso, `pesquisa_de_geocerca_da_lógica_iot`. Até que ela seja ativada, um fluxo que usa a função não pode ser salvo. O Nó é marcado com este erro: ``` A função geofenceName() no nó "Resolve current zone" (#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ços ative a opção. **Você também precisa de geocercas para pesquisar.** * Pelo menos uma geocerca existe na sua conta. Veja [Geocercas](/docs/user/pt-br/guide/tracking/map-tools/geofences.md). * Para pesquisar apenas parte das suas geocercas, adicione etiquetas a elas. Veja [Use etiquetas](/docs/user/pt-br/guide/tracking/map-tools/geofences.md#use-tags) e [Etiquetas](/docs/user/pt-br/guide/account/tags.md). ### Adicione o atributo Crie um atributo calculado da maneira usual, conforme descrito em [Gerenciamento de 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 o nome da função manualmente. 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 abrangem a maioria dos casos. A terceira lê uma posição anterior em vez da atual. | Fórmula | O que ele 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á atualmente | | `geofenceName('', 1, 'valid')` | O nome de qualquer geocerca em que o dispositivo estava em um pacote de dados anterior | Os três parâmetros são opcionais: * **A etiqueta**, primeiro, 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 é importante quando você tem muitas geocercas e apenas algumas delas são relevantes para este atributo, por exemplo, depósitos, mas não locais de clientes. * **O número do pacote**, em segundo lugar, indica até onde voltar a procurar: `0` é o pacote que está sendo processado, `1` o anterior a ele, e assim por diante. Deixe-o de fora para a posição atual. * **O filtro de posição**, 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 os limites exatos de cada parâmetro, consulte [Função de nome da Geocerca](/docs/iot-logic-api/technical-details/geofence-name.md) na documentação da API do IoT Logic. ### O que é retornado O atributo armazena o nome da geocerca como texto, ou um valor vazio quando não há nome a informar. Ele fica vazio quando: * O dispositivo está fora de todas as geocercas pesquisadas. * O pacote de dados não contém posição. * Nenhuma geocerca na sua conta tem a etiqueta que você informou. 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 o testa. Para obter texto legível em vez de um espaço em branco, adicione um valor alternativo 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 define prioridade entre 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 `zona_atual` com esta fórmula: ```jexl geofenceName() ``` Todo 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 que você etiquetou Etiquete 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 tenha `depósitos` etiqueta.
Roteamento por área em um nó de Lógica `geofenceName()` também funciona como uma condição, o que é útil quando muitas geocercas compartilham uma única regra. Para enviar dados registrados dentro de qualquer geocerca etiquetada como `restrita` para o caminho THEN, use esta condição: ```jexl geofenceName('restricted') != null ``` * **Caminho THEN**: Dados registrados dentro de uma área restrita. Conecte isso a um **Webhook** nó para alertar um despachante. * **Caminho ELSE**: Todos os demais dados. Compare o resultado com `==` ou `!=` somente. Os `<`, `>`, `<=`, e `>=` operadores não fornecem um resultado útil quando o valor está vazio.
Detectar uma mudança de área Para acionar 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 os 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. Quando você seleciona uma geocerca no seletor, o ID é inserido automaticamente na expressão. #### Posso armazenar uma verificação de geocerca em um atributo? Sim. As quatro funções funcionam tanto em uma fórmula de atributo quanto em uma condição de roteamento. `geofenceName()` é a escolha natural, porque fornece texto legível. As outras três fornecem um valor sim ou não, ou um valor vazio quando a posição é desconhecida. Um valor sim ou não geralmente é mais útil para roteamento do que para armazenamento. O seletor de geocerca aparece somente no **Lógica** nó, então, em uma fórmula de atributo, você digita a função e o ID da geocerca por conta própria. #### 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 habilitá-la em 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 salvá-la. #### inGeocerca 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 contém posição recebe um valor vazio em vez de `true` ou `falso`. #### Qual é a diferença entre inGeocerca e enterGeocerca? `inGeofence()` retorna `true` para cada pacote que informa uma posição dentro da Geocerca. `enterGeofence()` retorna `true` apenas para o pacote que registra o momento em que o dispositivo entrou na Geocerca. Use `inGeofence` quando você precisar aplicar lógica a todos os dados de dentro da área. Use `enterGeofence` quando você precisar reagir especificamente ao evento de cruzar o limite. #### Por que meu atributo geofenceName está sempre vazio? Verifique estas causas em ordem: 1. A opção não está ativada na sua conta. Um fluxo salvo anteriormente continua em execução, e a função retorna um valor vazio para cada pacote. Veja [Antes de começar](#before-you-start). 2. A Etiqueta que você passou não está atribuída a nenhuma geocerca. Os nomes das Etiquetas devem corresponder a uma Etiqueta que exista na sua conta. 3. O dispositivo realmente está fora de toda geocerca que você pesquisou. 4. Você tem uma quantidade 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 da 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` 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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.