Tutorial: Configurar uma cerca geográfica usando o Azure Maps

Este tutorial orienta você pelas noções básicas de criação e uso de serviços de cerca geográfica do Azure Maps.

Considere o seguinte cenário:

Um gerente de canteiro de obras deve rastrear o equipamento à medida que ele entra e sai do perímetro de uma área de construção. Sempre que um equipamento sai ou entra nesses perímetros, uma notificação por e-mail é enviada ao Gerente de Operações.

O Azure Maps fornece serviços para dar suporte ao rastreamento de equipamentos que entram e saem da área de construção. Neste tutorial, vai:

  • Carregue dados GeoJSON de cerca geográfica que definem as áreas do canteiro de obras que você deseja monitorar. Você carregará cercas geográficas como coordenadas de polígono em sua conta de armazenamento do Azure e, em seguida, usará o serviço de registro de dados para registrar esses dados com sua conta do Azure Maps.
  • Configure dois aplicativos lógicos que, quando acionados, enviam notificações por e-mail para o gerente de operações do canteiro de obras quando o equipamento entra e sai da área de cerca geográfica.
  • Use a Grade de Eventos do Azure para se inscrever para entrar e sair de eventos para sua cerca geográfica do Azure Maps. Você configura duas assinaturas de evento webhook que chamam os pontos de extremidade HTTP definidos em seus dois aplicativos lógicos. Em seguida, os aplicativos lógicos enviam as notificações por e-mail apropriadas de equipamentos indo além ou entrando na cerca geográfica.
  • Use a API Search Geofence Get para receber notificações quando um equipamento sair e entrar nas áreas de cerca geográfica.

Pré-requisitos

Este tutorial usa o aplicativo Postman , mas você pode usar um ambiente de desenvolvimento de API diferente.

Importante

Nos exemplos de URL, substitua {Your-Azure-Maps-Subscription-key} pela sua chave de subscrição do Azure Maps.

Carregar dados GeoJSON de cerca geográfica

Este tutorial demonstra como carregar dados GeoJSON de cerca geográfica que contêm um FeatureCollectionarquivo . O FeatureCollection contém duas geocercas que definem áreas poligonais dentro do canteiro de obras. A primeira cerca geográfica não tem limite de tempo ou restrições. O segundo só pode ser consultado durante o horário comercial (das 9h00 às 17h00 no fuso horário do Pacífico) e não será mais válido após 1º de janeiro de 2022. Para obter mais informações sobre o formato GeoJSON, consulte Geofencing GeoJSON data.

Crie o arquivo JSON de cerca geográfica usando os seguintes dados de cerca geográfica. Em seguida, você carregará esse arquivo em sua conta de armazenamento do Azure.

{
   "type": "FeatureCollection",
   "features": [
     {
       "type": "Feature",
       "geometry": {
         "type": "Polygon",
         "coordinates": [
           [
             [
               -122.13393688201903,
               47.63829579223815
             ],
             [
               -122.13389128446579,
               47.63782047131512
             ],
             [
               -122.13240802288054,
               47.63783312249837
             ],
             [
               -122.13238388299942,
               47.63829037035086
             ],
             [
               -122.13393688201903,
               47.63829579223815
             ]
           ]
         ]
       },
       "properties": {
         "geometryId": "1"
       }
     },
     {
       "type": "Feature",
       "geometry": {
         "type": "Polygon",
         "coordinates": [
           [
             [
               -122.13374376296996,
               47.63784758098976
             ],
             [
               -122.13277012109755,
               47.63784577367854
             ],
             [
               -122.13314831256866,
               47.6382813338708
             ],
             [
               -122.1334782242775,
               47.63827591198201
             ],
             [
               -122.13374376296996,
               47.63784758098976
             ]
           ]
         ]
       },
       "properties": {
         "geometryId": "2",
         "validityTime": {
         "expiredTime": "2022-01-01T00:00:00",
         "validityPeriod": [
             {
               "startTime": "2020-07-15T16:00:00",
               "endTime": "2020-07-15T24:00:00",
               "recurrenceType": "Daily",
               "recurrenceFrequency": 1,
               "businessDayOnly": true
             }
           ]
         }
       }
     }
   ]
}

Siga as etapas descritas no artigo Como criar registro de dados para carregar o arquivo JSON de cerca geográfica em sua conta de armazenamento do Azure e registrá-lo em sua conta do Azure Maps.

Importante

Certifique-se de anotar o valor do identificador exclusivo (udid), você precisará dele. É udid assim que você faz referência à cerca geográfica que carregou em sua conta de armazenamento do Azure a partir de seu código-fonte e solicitações HTTP.

Criar fluxos de trabalho em Aplicativos Lógicos do Azure

Em seguida, crie dois pontos de extremidade de aplicativo lógico que disparam uma notificação por email.

Para criar os aplicativos lógicos:

  1. Inicie sessão no portal do Azure.

  2. No canto superior esquerdo do portal do Azure, selecione Criar um recurso.

  3. Na caixa Serviços de pesquisa e marketplace, digite Aplicativo lógico.

  4. Nos resultados, selecione Aplicativo lógico. Em seguida, selecione Criar.

  5. Na página Aplicativo Lógico, insira os seguintes valores:

    • A Subscrição que pretende utilizar para esta aplicação lógica.
    • O nome do grupo de recursos para este aplicativo lógico. Você pode optar por Criar novo ou Usar grupo de recursos existente .
    • O nome do Aplicativo Lógico do seu aplicativo lógico. Neste caso, use Equipment-Enter como o nome.
    • Selecione Consumo como o tipo de plano. Para obter mais informações, consulte Modelos de faturamento e preços na documentação do Logic App.

    Para os fins deste tutorial, mantenha todos os outros valores em suas configurações padrão.

    Screenshot of create a logic app.

  6. Quando terminar, selecione Rever + Criar. Depois que o Azure validar as informações sobre seu recurso de aplicativo lógico, selecione Criar.

  7. Quando a implantação for concluída com êxito, selecione Ir para recurso.

  8. Selecione Designer de aplicativo lógico na seção Ferramentas de desenvolvimento no menu à esquerda, role para baixo até a seção Iniciar com um gatilhocomum. Selecione Quando uma solicitação HTTP é recebida.

    Screenshot of create a logic app HTTP trigger.

  9. No canto superior direito do Logic App Designer, selecione Salvar. O URL HTTP POST é gerado automaticamente. Salve o URL. Você precisa dele na próxima seção para criar um ponto de extremidade de evento.

    Screenshot of Logic App HTTP Request URL and JSON.

  10. Selecione + Novo passo.

  11. Na caixa de pesquisa, escreva outlook.com email. Na lista Ações, role para baixo e selecione Enviar um e-mail (V2).

    Screenshot of create a logic app designer.

  12. Inicie sessão na sua conta do Outlook. Certifique-se de selecionar Sim para permitir que o aplicativo lógico acesse a conta. Preencha os campos para enviar um e-mail.

    Screenshot of create a logic app send email step.

    Gorjeta

    Você pode recuperar dados de resposta GeoJSON, como geometryId ou deviceId, em suas notificações por e-mail. Você pode configurar os Aplicativos Lógicos para ler os dados enviados pela Grade de Eventos. Para obter informações sobre como configurar os Aplicativos Lógicos para consumir e passar dados de eventos para notificações por email, consulte Tutorial: Enviar notificações por email sobre eventos do Hub IoT do Azure usando a Grade de Eventos e os Aplicativos Lógicos.

  13. No canto superior esquerdo do Logic App Designer, selecione Salvar.

  14. Para criar um segundo aplicativo lógico para notificar o gerente quando o equipamento sair do canteiro de obras, repita o mesmo processo. Nomeie o aplicativo Equipment-Exitlógico .

Criar subscrições de eventos do Azure Maps

O Azure Maps dá suporte a três tipos de eventos. Este tutorial demonstra como criar assinaturas para os dois eventos a seguir:

  • Geofence entrar em eventos
  • Eventos de saída de cerca geográfica

Crie uma saída de cerca geográfica e insira assinaturas de eventos:

  1. Na sua conta do Azure Maps, selecione Subscrições.

  2. Selecione o nome da sua subscrição.

  3. No menu de configurações, selecione eventos.

    Screenshot of go to Azure Maps account events.

  4. Na página de eventos, Selecione + Subscrição de Eventos.

    Screenshot of create an Azure Maps events subscription.

  5. Na página Criar Subscrição de Eventos , introduza os seguintes valores:

    • O Nome da assinatura do evento.
    • O Esquema de Eventos deve ser Esquema de Grade de Eventos.
    • O Nome do Tópico do Sistema para esta subscrição de evento, que neste caso é Contoso-Construction.
    • Em Filtrar para Tipos de Evento, escolha Geofence Entered como o tipo de evento.
    • Em Tipo de ponto final, escolha Web Hook.
    • Para Endpoint, copie o HTTP POST URL para o ponto de extremidade de inserção do aplicativo lógico que você criou na seção anterior. Se você esqueceu de salvá-lo, basta voltar ao Logic App Designer e copiá-lo da etapa de gatilho HTTP.

    Screenshot of Azure Maps events subscription details.

  6. Selecione Criar.

  7. Repita o mesmo processo para o evento de saída de cerca geográfica. Certifique-se de escolher Geofence Exited como o tipo de evento.

Usar a API de obtenção de cerca geográfica espacial

Em seguida, usamos a API Spatial Geofence Get para enviar notificações por e-mail ao Operations Manager quando um equipamento entra ou sai das cercas geográficas.

Cada equipamento tem um deviceIdarquivo . Neste tutorial, você está rastreando um único equipamento, com uma ID exclusiva de device_1.

O diagrama a seguir mostra os cinco locais do equipamento ao longo do tempo, começando no local Start , que está em algum lugar fora das cercas geográficas. Para os fins deste tutorial, o local de início é indefinido, porque você não consulta o dispositivo nesse local.

Quando você consulta a API de obtenção de cerca geográfica espacial com um local de equipamento que indica a entrada ou saída inicial da cerca geográfica, a Grade de Eventos chama o ponto de extremidade do aplicativo lógico apropriado para enviar uma notificação por email ao Operations Manager.

Cada uma das seções a seguir faz solicitações de API usando as cinco coordenadas de local diferentes do equipamento.

Diagram of geofence map in Azure Maps

Localização do equipamento 1 (47.638237,-122.132483)

  1. No aplicativo Postman, selecione Novo.

  2. Na janela Criar novo, selecione Solicitação HTTP.

  3. Insira um Nome da solicitação para a solicitação, como Local 1.

  4. Selecione o método HTTP GET .

  5. Insira o seguinte URL. A solicitação deve se parecer com o seguinte URL (substitua {udid} pelo udid que você salvou na seção Carregar dados Geofencing GeoJSON).

    https://{geography}.atlas.microsoft.com/spatial/geofence/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=2022-08-01&deviceId=device_01&udid={udid}&lat=47.638237&lon=-122.1324831&searchBuffer=5&isAsync=True&mode=EnterAndExit
    

    Nota

    Substitua {geography} pelo seu âmbito geográfico. Para obter mais informações, consulte Escopo geográfico do serviço Azure Maps e a API Obter cerca geográfica espacial.

  6. Selecione Enviar.

  7. A resposta deve gostar do seguinte fragmento GeoJSON:

    {
      "geometries": [
        {
          "deviceId": "device_1",
          "udId": "64f71aa5-bbee-942d-e351-651a6679a7da",
          "geometryId": "1",
          "distance": -999.0,
          "nearestLat": 47.638291,
          "nearestLon": -122.132483
        },
        {
          "deviceId": "device_1",
          "udId": "64f71aa5-bbee-942d-e351-651a6679a7da",
          "geometryId": "2",
          "distance": 999.0,
          "nearestLat": 47.638053,
          "nearestLon": -122.13295
        }
      ],
      "expiredGeofenceGeometryId": [],
      "invalidPeriodGeofenceGeometryId": [],
      "isEventPublished": true
    }
    

Na resposta GeoJSON anterior, a distância negativa da cerca geográfica do local principal significa que o equipamento está dentro da cerca geográfica. A distância positiva da cerca geográfica do subsítio significa que o equipamento está fora da cerca geográfica do subsítio. Como esta é a primeira vez que este dispositivo foi localizado dentro da cerca geográfica do site principal, o isEventPublished parâmetro é definido como true. O Operations Manager recebe uma notificação por e-mail de que o equipamento entrou na cerca geográfica.

Localização 2 (47.63800,-122.132531)

  1. No aplicativo Postman, selecione Novo.

  2. Na janela Criar novo, selecione Solicitação HTTP.

  3. Insira um Nome da solicitação para a solicitação, como Localização 2.

  4. Selecione o método HTTP GET .

  5. Insira o seguinte URL. A solicitação deve se parecer com o seguinte URL (substitua {udid} pelo udid que você salvou na seção Carregar dados Geofencing GeoJSON).

    https://{geography}.atlas.microsoft.com/spatial/geofence/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=2022-08-01&deviceId=device_01&udId={udId}&lat=47.63800&lon=-122.132531&searchBuffer=5&isAsync=True&mode=EnterAndExit
    
  6. Selecione Enviar.

  7. A resposta deve gostar do seguinte fragmento GeoJSON:

    {
      "geometries": [
        {
          "deviceId": "device_01",
          "udId": "64f71aa5-bbee-942d-e351-651a6679a7da",
          "geometryId": "1",
          "distance": -999.0,
          "nearestLat": 47.637997,
          "nearestLon": -122.132399
        },
        {
          "deviceId": "device_01",
          "udId": "64f71aa5-bbee-942d-e351-651a6679a7da",
          "geometryId": "2",
          "distance": 999.0,
          "nearestLat": 47.63789,
          "nearestLon": -122.132809
        }
      ],
      "expiredGeofenceGeometryId": [],
      "invalidPeriodGeofenceGeometryId": [],
      "isEventPublished": false
    }
    

Na resposta GeoJSON anterior, o equipamento permaneceu na cerca geográfica do local principal e não entrou na cerca geográfica do subsítio. Como resultado, o parâmetro é definido como false, e o isEventPublished Operations Manager não recebe notificações por email.

Localização 3 (47.63810783315048,-122.13336020708084)

  1. No aplicativo Postman, selecione Novo.

  2. Na janela Criar novo, selecione Solicitação HTTP.

  3. Insira um Nome da solicitação para a solicitação, como Localização 3.

  4. Selecione o método HTTP GET .

  5. Insira o seguinte URL. A solicitação deve se parecer com o seguinte URL (substitua {udid} pelo udid que você salvou na seção Carregar dados Geofencing GeoJSON).

      https://{geography}.atlas.microsoft.com/spatial/geofence/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=2022-08-01&deviceId=device_01&udid={udid}&lat=47.63810783315048&lon=-122.13336020708084&searchBuffer=5&isAsync=True&mode=EnterAndExit
    
  6. Selecione Enviar.

  7. A resposta deve gostar do seguinte fragmento GeoJSON:

    {
      "geometries": [
        {
          "deviceId": "device_01",
          "udId": "64f71aa5-bbee-942d-e351-651a6679a7da",
          "geometryId": "1",
          "distance": -999.0,
          "nearestLat": 47.638294,
          "nearestLon": -122.133359
        },
        {
          "deviceId": "device_01",
          "udId": "64f71aa5-bbee-942d-e351-651a6679a7da",
          "geometryId": "2",
          "distance": -999.0,
          "nearestLat": 47.638161,
          "nearestLon": -122.133549
        }
      ],
      "expiredGeofenceGeometryId": [],
      "invalidPeriodGeofenceGeometryId": [],
      "isEventPublished": true
    }
    

Na resposta GeoJSON anterior, o equipamento permaneceu na cerca geográfica do local principal, mas entrou na cerca geográfica do subsítio. Como resultado, o isEventPublished parâmetro é definido como true. O Operations Manager recebe uma notificação por e-mail indicando que o equipamento entrou em uma cerca geográfica.

Nota

Se o equipamento tivesse sido movido para o subsite após o horário comercial, nenhum evento seria publicado e o gerente de operações não receberia nenhuma notificação.

Localização 4 (47.637988,-122.1338344)

  1. No aplicativo Postman, selecione Novo.

  2. Na janela Criar novo, selecione Solicitação HTTP.

  3. Insira um Nome da solicitação para a solicitação, como Localização 4.

  4. Selecione o método HTTP GET .

  5. Insira o seguinte URL. A solicitação deve se parecer com o seguinte URL (substitua {udid} pelo udid que você salvou na seção Carregar dados Geofencing GeoJSON).

    https://{geography}.atlas.microsoft.com/spatial/geofence/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=2022-08-01&deviceId=device_01&udid={udid}&lat=47.637988&userTime=2023-01-16&lon=-122.1338344&searchBuffer=5&isAsync=True&mode=EnterAndExit
    
  6. Selecione Enviar.

  7. A resposta deve gostar do seguinte fragmento GeoJSON:

    {
      "geometries": [
        {
          "deviceId": "device_01",
          "udId": "64f71aa5-bbee-942d-e351-651a6679a7da",
          "geometryId": "1",
          "distance": -999.0,
          "nearestLat": 47.637985,
          "nearestLon": -122.133907
        }
      ],
      "expiredGeofenceGeometryId": [
        "2"
      ],
      "invalidPeriodGeofenceGeometryId": [],
      "isEventPublished": false
    }
    

Na resposta GeoJSON anterior, o equipamento permaneceu na cerca geográfica do local principal, mas saiu da cerca geográfica do subsítio. Observe, no entanto, que o valor está após o userTimeexpiredTime definido nos dados de cerca geográfica. Como resultado, o parâmetro é definido como false, e o isEventPublished Operations Manager não recebe uma notificação por email.

Localização 5 (47.63799, -122.134505)

  1. No aplicativo Postman, selecione Novo.

  2. Na janela Criar novo, selecione Solicitação HTTP.

  3. Insira um Nome da solicitação para a solicitação, como Localização 5.

  4. Selecione o método HTTP GET .

  5. Insira o seguinte URL. A solicitação deve se parecer com o seguinte URL (substitua {udid} pelo udid que você salvou na seção Carregar dados Geofencing GeoJSON).

    https://{geography}.atlas.microsoft.com/spatial/geofence/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=2022-08-01&deviceId=device_01&udid={udid}&lat=47.63799&lon=-122.134505&searchBuffer=5&isAsync=True&mode=EnterAndExit
    
  6. Selecione Enviar.

  7. A resposta deve gostar do seguinte fragmento GeoJSON:

    {
      "geometries": [
      {
        "deviceId": "device_01",
        "udId": "64f71aa5-bbee-942d-e351-651a6679a7da",
        "geometryId": "1",
        "distance": -999.0,
        "nearestLat": 47.637985,
        "nearestLon": -122.133907
      },
      {
        "deviceId": "device_01",
        "udId": "64f71aa5-bbee-942d-e351-651a6679a7da",
        "geometryId": "2",
        "distance": 999.0,
        "nearestLat": 47.637945,
        "nearestLon": -122.133683
      }
      ],
      "expiredGeofenceGeometryId": [],
      "invalidPeriodGeofenceGeometryId": [],
      "isEventPublished": true
    }
    

Na resposta GeoJSON anterior, o equipamento saiu da cerca geográfica do local principal. Como resultado, o parâmetro é definido como true, e o Operations Manager recebe uma notificação por e-mail indicando que o isEventPublished equipamento saiu de uma cerca geográfica.

Você também pode enviar notificações por e-mail usando a Grade de Eventos e os Aplicativos Lógicos. Para obter mais informações, consulte Manipuladores de eventos na Grade de Eventos do Azure.

Clean up resources (Limpar recursos)

Não há recursos que exijam limpeza.

Próximos passos