Configuración de una geovalla con Azure MapsSet up a geofence by using Azure Maps

Este tutorial le guía por los pasos básicos para configurar la geovalla con Azure Maps.This tutorial walks you through the basics steps to set up geofence by using Azure Maps. El escenario que tratamos en este tutorial es ayudar a los administradores de sitios de construcción a supervisar los equipos potencialmente peligrosos que se mueven más allá de las áreas de construcción designadas.The scenario we address in this tutorial is help construction site managers monitor potential hazardous equipment moving beyond the designated construction areas. Un sitio de construcción implica regulaciones y equipos costosos.A construction site involves expensive equipment and regulations. Por lo general requiere que el equipo permanezca dentro del sitio de construcción y no salga sin permiso.It typically requires that the equipment stays inside the construction site and does not leave without permission.

Vamos a usar Data Upload API de Azure Maps para almacenar una geovalla y Geofence API de Azure Maps para comprobar la ubicación del equipo en relación con la geovalla.We will use Azure Maps Data Upload API to store a geofence, and use Azure maps Geofence API to check the equipment location relative to the geofence. Usaremos Azure Event Grid para transmitir los resultados de la geovalla y establecer una notificación basada en los resultados de la geovalla.We will use Azure Event Grid to stream the geofence results and set up a notification based on the geofence results. Para más información sobre Event Grid, consulte Azure Event Grid.To learn more about Event Grid, see Azure Event Grid. En este tutorial, aprenderá a:In this tutorial you will learn, how to:

  • Cargar el área de la geovalla en el servicio de datos de Azure Maps con Data Upload API.Upload geofence area in the Azure Maps, Data service using the Data Upload API.
  • Configurar una instancia de Event Grid para controlar los eventos de la geovalla.Set up an Event Grid to handle geofence events.
  • Configurar el controlador de eventos de la geovalla.Setup geofence events handler.
  • Configurar alertas en respuesta a eventos de la geovalla con Logic Apps.Set up alerts in response to geofence events using Logic Apps.
  • Usar las API del servicio de geovalla de Azure Maps para realizar un seguimiento de si un recurso de construcción está dentro del sitio de construcción o no.Use Azure Maps geofence service APIs to track whether a construction asset is within the construction site or not.

Requisitos previosPrerequisites

Crear una cuenta de Azure MapsCreate an Azure Maps account

Para completar los pasos de este tutorial, primero necesita consultar el artículo sobre cómo administrar la cuenta y las claves para crear y administrar la suscripción de cuenta con el plan de tarifa S1.To complete the steps in this tutorial, you first need to see manage account and keys to create and manage your account subscription with S1 pricing tier.

Carga de geovallasUpload geofences

Para cargar la geovalla en el sitio de construcción mediante Data Upload API, se va a usar la aplicación Postman.To upload the geofence for the construction site using the Data Upload API, we will use the postman application. Para este tutorial, se asume que hay un área total del sitio en construcción, que es un parámetro difícil que el equipo de construcción no debe infringir.For the sake of this tutorial, we assume there is an overall construction site area, which is a hard parameter that the construction equipment should not violate. Las infracciones de esta valla son un ataque grave y se notifican a Operations Manager.Violations of this fence are a serious offense and are reported to the Operations Manager. Se puede utilizar un conjunto optimizado de vallas adicionales que realizan el seguimiento de diferentes áreas de construcción dentro del área de construcción general de acuerdo con la programación.An optimized set of additional fences can be used that track different construction areas within the overall construction area as per schedule. Se supone que la geovalla principal tiene un subsitio 1, con un tiempo de expiración establecido y expirará después de dicho período.We can assume that the main geofence has a subsite1, which has a set expiration time and will expire after that time. Se pueden crear más geovallas anidadas según sus requisitos.You can create more nested geofences as per your requirements. Por ejemplo, en el subsitio 1 se podría realizar el trabajo durante la semana 1 a 4 de la programación y en el subsitio 2 el trabajo se lleva a cabo durante la semana 5 a 7.For example, subsite1 could be where work is taking place during week 1 to 4 of the schedule and subsite 2 is where work takes place during week 5 to 7. Se pueden cargar todas estas vallas como un único conjunto de datos al principio del proyecto y se pueden utilizar para realizar un seguimiento de las reglas basadas en el tiempo y el espacio.All such fences can be loaded as a single dataset at the beginning of the project and used to track rules based on time and space. Para más información sobre el formato de datos de la geovalla, consulte Geofence GeoJSON data (Datos GeoJSON de geovalla).For more information on geofence data format, see Geofence GeoJSON data. Para más información sobre cómo cargar datos en el servicio Azure Maps, consulte la documentación de Data Upload API.For more information on uploading data to the Azure Maps service, see Data Upload API documentation .

Abra la aplicación Postman y siga estos pasos para cargar la geovalla del sitio de construcción mediante Data Upload API de Azure Maps.Open the Postman app and follow the following steps to upload the construction site geofence using the Azure Maps, Data Upload API.

  1. Abra la aplicación Postman, haga clic en New | Create new (Nuevo | Crear nuevo) y seleccione Request (Solicitud).Open the Postman app and click new | Create new, and select Request. Escriba un nombre de solicitud para la carga de datos de geovalla, seleccione una colección o carpeta donde guardarlo y haga clic en Save (Guardar).Enter a Request name for Upload geofence data, select a collection or folder to save it to, and click Save.

    Carga de geovallas con Postman

  2. Seleccione el método POST HTTP en la pestaña del generador e introduzca la siguiente URL para realizar una solicitud POST.Select POST HTTP method on the builder tab and enter the following URL to make a POST request.

    https://atlas.microsoft.com/mapData/upload?subscription-key={subscription-key}&api-version=1.0&dataFormat=geojson
    

    El parámetro GEOJSON en la ruta de acceso de la dirección URL representa el formato de datos de los datos que se cargan.The GEOJSON parameter in the URL path represents the data format of the data being uploaded.

  3. Haga clic en Params (Parámetros) y escriba los siguientes pares de clave-valor que se usarán para la dirección URL de la solicitud POST.Click Params, and enter the following Key/Value pairs to be used for the POST request URL. Reemplace el valor de subscription-key por la clave de suscripción de Azure Maps.Replace subscription-key value with your Azure Maps subscription key.

    Parámetros de clave-valor de Postman

  4. Haga clic en Body (Cuerpo), seleccione el formato de entrada sin procesar y elija JSON como formato de entrada en la lista desplegable.Click Body then select raw input format and choose JSON as the input format from the dropdown list. Proporcione el siguiente código JSON como datos que se van a cargar:Provide the following JSON as data to be uploaded:

    {
       "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": "2019-01-15T00:00:00",
               "validityPeriod": [
                 {
                   "startTime": "2019-01-08T01:00:00",
                   "endTime": "2019-01-08T17:00:00",
                   "recurrenceType": "Daily",
                   "recurrenceFrequency": 1,
                   "businessDayOnly": true
                 }
               ]
             }
           }
         }
       ]
    }
    
  5. Haga clic en Send (Enviar) y revise el encabezado de la respuesta.Click send and review the response header. El encabezado de ubicación contiene el identificador URI para acceder o descargar los datos para su uso futuro.The location header contains the URI to access or download the data for future use. También contiene un udId único para los datos cargados.It also contains a unique udId for the uploaded data.

    https://atlas.microsoft.com/mapData/{udId}/status?api-version=1.0&subscription-key={Subscription-key}
    

Configuración de un controlador de eventosSet up an event handler

Para notificar a Operations Manager sobre los eventos de entrada y salida, hay que crear un controlador de eventos que reciba las notificaciones.To notify the Operations Manager regarding enter and exit events, we should create an event handler that receives the notifications.

Se crearán dos servicios Logic Apps para controlar, introducir y generar eventos.We will create two Logic Apps services to handle, enter, and exit events. También se crearán desencadenadores de eventos en las instancias de Logic Apps que se desencadenarán con estos eventos.We will also create event triggers within the Logic Apps that get triggered by these events. La idea consiste en enviar alertas, en este caso correos electrónicos a Operations Manager cada vez que el equipo entra o sale del sitio.The idea is to send alerts, in this case emails to the Operations Manager whenever equipment enters or exits the construction site. La siguiente ilustración muestra la creación de una aplicación lógica para el evento de entrada de la geovalla.The following figure illustrates creation of a Logic App for geofence enter event. De forma similar, puede crear otro para el evento de salida.Similarly, you can create another one for exit event. Para más información, puede ver todos los controladores de eventos admitidos.You can see all supported event handlers for more info.

  1. Creación de una aplicación lógica en Azure PortalCreate a Logic App in Azure portal

    Creación de instancias de Logic Apps

  2. Seleccione un desencadenador de la solicitud HTTP y después seleccione "Send an email" (Enviar un correo electrónico) como acción en el conector de OutlookSelect an HTTP request trigger and then select "send an email" as an action in the outlook connector

    Esquema de Logic Apps

  3. Guarde la aplicación lógica para generar el punto de conexión de la dirección URL HTTP y copie dicha dirección.Save the logic app to generate the HTTP URL endpoint and copy the HTTP URL.

    Punto de conexión de Logic Apps

Creación de una suscripción a eventos de Azure MapsCreate an Azure Maps Events subscription

Azure Maps admite tres tipos de eventos.Azure Maps supports three event types. Puede echar un vistazo a los tipos de eventos de Azure Maps admitidos aquí.You can have a look at the Azure Maps supported event types here. Se van a crear dos suscripciones diferentes, una para los eventos de entrada y otra para los de salida.We will create two different subscriptions, one for enter and the other for exit events.

Siga estos pasos para crear una suscripción de eventos para los eventos de entrada de la geovalla.Follow the steps below to create an event subscription for the geofence enter events. Puede suscribirse a eventos de salida de la geovalla de forma similar.You can subscribe to geofence exit events in a similar manner.

  1. Vaya a la cuenta de Azure Maps mediante este vínculo del portal y seleccione la pestaña Events (Eventos).Navigate to your Azure Maps account via this portal link and select the events Tab.

    Eventos de Azure Maps

  2. Para crear una suscripción de eventos, seleccione la suscripción de eventos desde la página correspondiente.To create an event subscription, select Event Subscription from the events page.

    Suscripción a eventos de Azure Maps

  3. Asigne un nombre a la suscripción de eventos y suscríbase al tipo de evento de entrada.Name the events subscription, and subscribe to the Enter event type. Ahora, seleccione webhook como Tipo de punto de conexión y copie el punto de conexión de la dirección URL HTTP de la aplicación lógica en Endpoint (Punto de conexión).Now, select Web Hook as "Endpoint Type" and copy your Logic App HTTP URL endpoint into "Endpoint"

    Suscripción de eventos

Uso de Geofence APIUse Geofence API

Puede usar Geofence API para comprobar si un dispositivo (el equipo forma parte del estado) está dentro o fuera de una geovalla.You can use the Geofence API to check whether a device (equipment is part of status) is inside or outside a geofence. Para comprender mejor Get Geofence API,To better understand the geofence GET API. se realiza la consulta en diferentes ubicaciones donde un equipo determinado se ha movido con el tiempo.We query it against different locations where a particular equipment has moved over time. La siguiente ilustración muestra cinco ubicaciones de un equipo de construcción en particular con un id. de dispositivo único como se observa en orden cronológico.The following figure illustrates five locations of a particular construction equipment with a unique device id as observed in chronological order. Cada una de estas cinco ubicaciones se utiliza para evaluar el cambio de estado de entrada y salida de la geovalla frente a la misma.Each of these five locations is used to assess the geofence enter and exit status change against the fence. Si se produce un cambio de estado, el servicio de geovalla desencadena un evento, que envía Event Grid a la aplicación lógica.If a state change occurs, the geofence service triggers an event, which is sent to the Logic App by the Event Grid. Como resultado, el administrador de la operación recibirá la correspondiente notificación de entrada o salida por correo electrónico.As a result the operation's manager will receive the corresponding enter or exit notification via an email.

Nota

El escenario y el comportamiento anteriores se basan en el mismo id. de dispositivo, de modo que refleja las cinco ubicaciones diferentes como en la siguiente ilustración.The above scenario and behavior is based on the same device id so that it reflects the five different locations as in the figure below.

Mapa de geovalla

En la aplicación Postman, abra una nueva pestaña en la misma colección que ha creado anteriormente.In the Postman app, open a new tab in the same collection you created above. Seleccione el método GET HTTP en la pestaña del generador:Select GET HTTP method on the builder tab:

A continuación se presentan cinco solicitudes HTTP GET de Geofence API, con diferentes coordenadas de ubicación correspondientes del equipo según se observan en orden cronológico.Following are five HTTP GET Geofencing API requests, with different corresponding location coordinates of the equipment as observed in chronological order. Cada solicitud va seguida por el cuerpo de la respuesta.Each request is followed by the response body.

  1. Ubicación 1:Location 1:

    https://atlas.microsoft.com/spatial/geofence/json?subscription-key={subscription-key}&api-version=1.0&deviceId=device_01&udId={udId}&lat=47.638237&lon=-122.1324831&searchBuffer=5&isAsync=True&mode=EnterAndExit
    

    Consulta de la geovalla 1

    Si se observa la respuesta anterior, la distancia negativa desde la geovalla principal significa que el equipo está dentro de la geovalla y la distancia positiva desde la geovalla del subsitio significa que está fuera de la geovalla del subsitio.If you look at the response above, the negative distance from the main geofence means that the equipment is inside the geofence and the positive from the subsite geofence means that it is outside the subsite geofence.

  2. Ubicación 2:Location 2:

    https://atlas.microsoft.com/spatial/geofence/json?subscription-key={subscription-key}&api-version=1.0&deviceId=device_01&udId={udId}&lat=47.63800&lon=-122.132531&searchBuffer=5&isAsync=True&mode=EnterAndExit
    

    Consulta de la geovalla 2

    Si se observa cuidadosamente la respuesta anterior de JSON, el equipo está fuera del subsitio, pero dentro de la valla principal.If you look at the preceding JSON response carefully the equipment is outside the subsite, but is inside the main fence. No desencadena ningún evento y no se envía ningún correo electrónico.It does not trigger an event and no email is sent.

  3. Ubicación 3:Location 3:

    https://atlas.microsoft.com/spatial/geofence/json?subscription-key={subscription-key}&api-version=1.0&deviceId=device_01&udId={udId}&lat=47.63810783315048&lon=-122.13336020708084&searchBuffer=5&isAsync=True&mode=EnterAndExit
    

    Consulta de la geovalla 3

    Se ha producido un cambio de estado y ahora el equipo se encuentra dentro de las geovallas principal y secundaria.A state change has occurred and now the equipment is within both the main and subsite geofences. Este proceso publica un evento y se enviará un correo electrónico de notificación a Operations Manager.This publishes an event and a notification email will be sent to the Operations Manager.

  4. Ubicación 4:Location 4:

    https://atlas.microsoft.com/spatial/geofence/json?subscription-key={subscription-key}&api-version=1.0&deviceId=device_01&udId={udId}&lat=47.637988&lon=-122.1338344&searchBuffer=5&isAsync=True&mode=EnterAndExit
    

    Consulta de la geovalla 4

    Al observar atentamente la respuesta correspondiente, se puede observar que aquí no se publica ningún evento a pesar de que el equipo haya salido de la geovalla del subsitio.By observing the corresponding response carefully, you can note that no event gets published here even though the equipment has exited the subsite geofence. Si se observa la hora especificada por el usuario en la solicitud GET, se puede ver que la geovalla del subsitio ha expirado en relación a esta hora y que el equipo sigue en la geovalla principal.If you look at the user's specified time in the GET request, you can see that the subsite geofence has expired relative to this time and the equipment is still in the main geofence. También puede ver el identificador de geometría de la geovalla del subsitio en expiredGeofenceGeometryId en el cuerpo de respuesta.You can also see the geometry ID of the subsite geofence under expiredGeofenceGeometryId in the response body.

  5. Ubicación 5:Location 5:

    https://atlas.microsoft.com/spatial/geofence/json?subscription-key={subscription-key}&api-version=1.0&deviceId=device_01&udId={udId}&lat=47.63799&lon=-122.134505&userTime=2019-01-16&searchBuffer=5&isAsync=True&mode=EnterAndExit
    

    Consulta de la geovalla 5

    Puede ver que el equipo ha salido de la geovalla del sitio de construcción principal.You can see that the equipment has left the main construction site geofence. Publica un evento, pero es una infracción grave y se envía un correo electrónico de alerta crítica a Operations Manager.It publishes an event, it is a serious violation, and a critical alert email is sent to the Operations Manager.

Pasos siguientesNext steps

En este tutorial ha aprendido cómo configurar una geovalla al cargarla en Azure Maps y un servicio de datos mediante Data Upload API.In this tutorial you learned, how to set up geofence by uploading it in the Azure Maps, Data service using the Data Upload API. También ha aprendido a usar Event Grid de Azure Maps para suscribirse y controlar los eventos de la geovalla.You also learned how to use Azure Maps Events Grid to subscribe to and handle geofence events.