Configurare un recinto virtuale con Mappe di AzureSet up a geofence by using Azure Maps

Questa esercitazione illustra i passaggi di base per la configurazione di un recinto virtuale con Mappe di Azure.This tutorial walks you through the basics steps to set up geofence by using Azure Maps. Lo scenario esaminato in questa esercitazione consente ai direttori di cantiere di monitorare l'uscita di macchinari potenzialmente pericolosi all'esterno delle aree di cantiere designate.The scenario we address in this tutorial is help construction site managers monitor potential hazardous equipment moving beyond the designated construction areas. Un cantiere comporta macchinari costosi e il rispetto di normative specifiche.A construction site involves expensive equipment and regulations. Richiede in genere che i macchinari rimangano all'interno del cantiere e non escano senza autorizzazione.It typically requires that the equipment stays inside the construction site and does not leave without permission.

Si userà l'API Caricamento dati di Mappe di Azure per archiviare un recinto virtuale, quindi si userà l'API Recinto virtuale di Mappe di Azure per verificare la posizione dei macchinari rispetto al recinto virtuale.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. Si userà Griglia di eventi di Azure per trasmettere i risultati del recinto virtuale e configurare una notifica in base ai risultati del recinto virtuale stesso.We will use Azure Event Grid to stream the geofence results and set up a notification based on the geofence results. Per altre informazioni su Griglia di eventi, vedere Griglia di eventi di Azure.To learn more about Event Grid, see Azure Event Grid. In questa esercitazione si apprenderà come:In this tutorial you will learn, how to:

  • Caricare l'area del recinto virtuale nel servizio dati di Mappe di Azure usando l'API Caricamento dati.Upload geofence area in the Azure Maps, Data service using the Data Upload API.
  • Configurare una griglia di eventi per gestire gli eventi del recinto virtuale.Set up an Event Grid to handle geofence events.
  • Impostare il gestore di eventi del recinto virtuale.Setup geofence events handler.
  • Configurare gli avvisi in risposta agli eventi del recinto virtuale usando App per la logica.Set up alerts in response to geofence events using Logic Apps.
  • Usare le API del servizio del recinto virtuale di Mappe di Azure per verificare se un asset di costruzione si trova nel cantiere o meno.Use Azure Maps geofence service APIs to track whether a construction asset is within the construction site or not.

PrerequisitiPrerequisites

Creare un account di Mappe di AzureCreate an Azure Maps account

Per completare i passaggi di questa esercitazione, seguire le istruzioni in Gestire l'account per creare una sottoscrizione dell'account Mappe di Azure con il piano tariffario S1 ed eseguire la procedura descritta in Ottenere la chiave primaria per ottenere la chiave di sottoscrizione primaria per l'account.To complete the steps in this tutorial, follow instructions in manage account to create an Azure Maps account subscription with S1 pricing tier and follow the steps in get primary key to get the primary subscription key for your account.

Caricare i recinti virtualiUpload geofences

Per caricare il recinto virtuale per il cantiere con l'API Caricamento dati si userà l'applicazione Postman.To upload the geofence for the construction site using the Data Upload API, we will use the postman application. Ai fini di questa esercitazione si presuppone che ci sia un'area di cantiere generale che rappresenta un parametro fisso che i macchinari edili non devono violare.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. La violazione di questo recinto rappresenta un'infrazione grave che viene segnalata al direttore di cantiere.Violations of this fence are a serious offense and are reported to the Operations Manager. È possibile usare un set ottimizzato di recinti aggiuntivi per tenere traccia delle diverse aree del cantiere generale in base al piano lavori.An optimized set of additional fences can be used that track different construction areas within the overall construction area as per schedule. Si può presupporre che il recinto virtuale principale abbia una sottoarea subsite1 con una data di scadenza definita.We can assume that the main geofence has a subsite1, which has a set expiration time and will expire after that time. È possibile creare più recinti virtuali annidati a seconda delle esigenze.You can create more nested geofences as per your requirements. È ad esempio possibile che la sottoarea subsite1 sia il luogo in cui si svolgono i lavori durante le settimane 1-4 del piano lavori e la sottoarea subsite2 sia il luogo in cui si svolgono i lavori durante le settimane 5-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. Tutti questi recinti possono essere caricati come singolo set di dati all'inizio del progetto e usati per tenere traccia delle regole nel tempo e nello spazio.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. Per altre informazioni sul formato dati del recinto virtuale, vedere Dati GeoJSON del recinto virtuale.For more information on geofence data format, see Geofence GeoJSON data. Per altre informazioni sul caricamento dei dati nel servizio Mappe di Azure, vedere Documentazione dell'API Caricamento dati.For more information on uploading data to the Azure Maps service, see Data Upload API documentation .

Aprire l'app Postman e seguire questi passaggi per caricare il recinto virtuale del cantiere usando Mappe di Azure e l'API Caricamento dati.Open the Postman app and follow the following steps to upload the construction site geofence using the Azure Maps, Data Upload API.

  1. Aprire l'app Postman e fare clic su New | Create new (Nuovo | Crea nuovo) e selezionare Request (Richiesta).Open the Postman app and click new | Create new, and select Request. Immettere un nome richiesta per Upload geofence data (Carica dati recinto virtuale), selezionare una raccolta o una cartella per il salvataggio, quindi fare clic su Salva (Save).Enter a Request name for Upload geofence data, select a collection or folder to save it to, and click Save.

    Caricare i recinti virtuali usando Postman

  2. Selezionare il metodo HTTP POST nella scheda Builder (Generatore) e immettere l'URL seguente per effettuare una richiesta 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
    

    Il parametro GEOJSON nel percorso URL rappresenta il formato dei dati caricati.The GEOJSON parameter in the URL path represents the data format of the data being uploaded.

  3. Fare clic su Params (Parametri) e immettere le coppie chiave/valore seguenti da usare per l'URL della richiesta POST.Click Params, and enter the following Key/Value pairs to be used for the POST request URL. Sostituire il valore subscription-key con la chiave di sottoscrizione primaria di Mappe di Azure.Replace subscription-key value with your Azure Maps primary subscription key.

    Parametri chiave-valore di Postman

  4. Fare clic su Body (Corpo), quindi selezionare il formato di input non elaborato e scegliere JSON come formato di input nell'elenco a discesa.Click Body then select raw input format and choose JSON as the input format from the dropdown list. Specificare il codice JSON seguente come dati da caricare: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. Fare clic su Send (Invia) e quindi esaminare l'intestazione della risposta.Click send and review the response header. Una volta completata la richiesta, l'intestazione Location conterrà l'URI di stato per controllare lo stato corrente della richiesta di caricamento.Upon a successful request, the Location header will contain the status URI to check the current status of the upload request. L'URI di stato avrà il formato seguente.The status URI will be of the following format.

    https://atlas.microsoft.com/mapData/{uploadStatusId}/status?api-version=1.0
    
  6. Copiare l'URI di stato e aggiungervi un parametro subscription-key con un valore corrispondente alla chiave di sottoscrizione dell'account Mappe di Azure.Copy your status URI and append a subscription-key parameter to it with its value being your Azure Maps account subscription key. Il formato dell'URI di stato deve essere simile a quello riportato di seguito:The status URI format should be like the one below:

    https://atlas.microsoft.com/mapData/{uploadStatusId}/status?api-version=1.0&subscription-key={Subscription-key}
    
  7. Per ottenere l'udId, aprire una nuova scheda nell'app Postman e selezionare il metodo GET HTTP nella scheda Builder (Generatore) ed effettuare una richiesta GET nell'URI di stato.To get the, udId open a new tab in the Postman app and select GET HTTP method on the builder tab and make a GET request at the status URI. Se il caricamento dei dati è riuscito, si riceverà un udId nel corpo della risposta.If your data upload was successful, you will receive a udId in the response body. Copiare l'udId per un uso successivo.Copy the udId for later use.

    {
     "udid" : "{udId}"
    }
    

Configurare un gestore di eventiSet up an event handler

Per informare il direttore di cantiere in merito agli eventi di ingresso e uscita è necessario creare un gestore di eventi che riceva le notifiche.To notify the Operations Manager regarding enter and exit events, we should create an event handler that receives the notifications.

Verranno creati due servizi di App per la logica per gestire gli eventi di ingresso e uscita.We will create two Logic Apps services to handle, enter, and exit events. In App per la logica verranno anche creati trigger di evento attivati da questi eventi.We will also create event triggers within the Logic Apps that get triggered by these events. L'obiettivo è inviare avvisi, in questo caso messaggi di posta elettronica, al direttore di cantiere ogni volta che i macchinari entrano o escono dal cantiere.The idea is to send alerts, in this case emails to the Operations Manager whenever equipment enters or exits the construction site. La figura seguente illustra la creazione di un'app per la logica per l'evento di ingresso nel recinto virtuale.The following figure illustrates creation of a Logic App for geofence enter event. È possibile crearne un'altra allo stesso modo per l'evento di uscita.Similarly, you can create another one for exit event. È possibile vedere tutti i gestori di eventi supportati per altre informazioni.You can see all supported event handlers for more info.

  1. Creare un'app per la logica nel portale di AzureCreate a Logic App in Azure portal

    Creare app per la logica

  2. Selezionare un trigger di richiesta HTTP e quindi selezionare "Send and email" (Invia una e-mail) come azione nel connettore di OutlookSelect an HTTP request trigger and then select "send an email" as an action in the outlook connector

    Schema di App per la logica

  3. Salvare l'app per la logica per generare l'endpoint dell'URL HTTP e copiare l'URL HTTP.Save the logic app to generate the HTTP URL endpoint and copy the HTTP URL.

    Endpoint di App per la logica

Creare una sottoscrizione di Eventi di Mappe di AzureCreate an Azure Maps Events subscription

Mappe di Azure supporta tre tipi di eventi.Azure Maps supports three event types. I tipi di eventi supportati da Mappe di Azure sono disponibili qui.You can have a look at the Azure Maps supported event types here. Si creeranno due sottoscrizioni diverse, una per gli eventi di ingresso e l'altra per gli eventi di uscita.We will create two different subscriptions, one for enter and the other for exit events.

Seguire questi passaggi per creare una sottoscrizione per gli eventi di ingresso del recinto virtuale.Follow the steps below to create an event subscription for the geofence enter events. Allo stesso modo è possibile creare una sottoscrizione per gli eventi di uscita del recinto virtuale.You can subscribe to geofence exit events in a similar manner.

  1. Passare al proprio account di Mappe di Azure tramite questo collegamento al portale e selezionare la scheda Eventi.Navigate to your Azure Maps account via this portal link and select the events Tab.

    Eventi di Mappe di Azure

  2. Per creare una sottoscrizione per gli eventi, selezionare Sottoscrizione di eventi dalla pagina degli eventi.To create an event subscription, select Event Subscription from the events page.

    Sottoscrizione per Eventi di Mappe di Azure

  3. Assegnare un nome alla sottoscrizione e selezionare il tipo di eventi di ingresso.Name the events subscription, and subscribe to the Enter event type. Selezionare ora Web Hook come "Tipo di endpoint" e copiare l'endpoint dell'URL HTTP dell'app per la logica in "Endpoint"Now, select Web Hook as "Endpoint Type" and copy your Logic App HTTP URL endpoint into "Endpoint"

    Sottoscrizione per gli eventi

Usare l'API Recinto virtualeUse Geofence API

È possibile usare l'API Recinto virtuale per verificare se un dispositivo (i macchinari fanno parte dello stato) si trova all'interno o all'esterno di un recinto virtuale.You can use the Geofence API to check whether a device (equipment is part of status) is inside or outside a geofence. Per comprendere meglio l'API GET Recinto virtuale,To better understand the geofence GET API. verranno eseguite query per i diversi luoghi in cui è transitato un macchinario specifico.We query it against different locations where a particular equipment has moved over time. La figura seguente illustra cinque posizioni di un particolare macchinario edile con un ID dispositivo univoco in ordine cronologico.The following figure illustrates five locations of a particular construction equipment with a unique device id as observed in chronological order. Ognuna di queste cinque posizioni viene usata per valutare la variazione di stato di ingresso e uscita rispetto al recinto virtuale.Each of these five locations is used to assess the geofence enter and exit status change against the fence. Se si verifica una variazione di stato, il servizio del recinto virtuale attiva un evento che viene inviato all'app per la logica dalla griglia di eventi.If a state change occurs, the geofence service triggers an event, which is sent to the Logic App by the Event Grid. Di conseguenza, il direttore di cantiere riceverà la notifica di ingresso o uscita corrispondente tramite una e-mail.As a result the operation's manager will receive the corresponding enter or exit notification via an email.

Nota

Lo scenario e il comportamento descritti in precedenza si basano sullo stesso ID dispositivo, quindi riflettono le cinque posizioni come nella figura seguente.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.

Mappa del recinto virtuale

Nell'app Postman aprire una nuova scheda nella stessa raccolta creata in precedenza.In the Postman app, open a new tab in the same collection you created above. Selezionare il metodo HTTP GET nella scheda Builder (Generatore):Select GET HTTP method on the builder tab:

Di seguito sono riportate cinque richieste HTTP GET dell'API Geofencing, con le diverse coordinate di posizione dei macchinari in ordine cronologico.Following are five HTTP GET Geofencing API requests, with different corresponding location coordinates of the equipment as observed in chronological order. Ogni richiesta è seguita dal corpo della risposta.Each request is followed by the response body.

  1. Posizione 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
    

    Query recinto virtuale 1

    Se si osserva la risposta precedente, la distanza negativa rispetto al recinto virtuale principale indica che il macchinario si trova all'interno del recinto virtuale, mentre la differenza positiva rispetto al recinto virtuale della sottoarea indica che il macchinario si trova all'esterno del recinto virtuale della sottoarea.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. Posizione 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
    

    Query recinto virtuale 2

    Se si osserva attentamente la risposta JSON precedente, il macchinario si trova all'esterno della sottoarea, ma all'interno del recinto principale.If you look at the preceding JSON response carefully the equipment is outside the subsite, but is inside the main fence. Non vengono attivati eventi e non vengono inviate e-mail.It does not trigger an event and no email is sent.

  3. Posizione 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
    

    Query recinto virtuale 3

    Si è verificata una variazione di stato e ora il macchinario si trova all'interno del recinto virtuale principale e del recinto della sottoarea.A state change has occurred and now the equipment is within both the main and subsite geofences. Verrà pubblicato un evento e verrà inviata una e-mail di notifica al direttore di cantiere.This publishes an event and a notification email will be sent to the Operations Manager.

  4. Posizione 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
    

    Query recinto virtuale 4

    Se si osserva attentamente la risposta corrispondente, si può notare che non vengono pubblicati eventi anche se il macchinario è uscito dal recinto virtuale della sottoarea.By observing the corresponding response carefully, you can note that no event gets published here even though the equipment has exited the subsite geofence. Se si osserva il tempo specificato dall'utente nella richiesta GET, si può notare che il recinto virtuale della sottoarea è scaduto e il macchinario si trova ancora all'interno del recinto virtuale principale.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. È anche visibile l'ID geometria del recinto virtuale della sottoarea sotto expiredGeofenceGeometryId nel corpo della risposta.You can also see the geometry ID of the subsite geofence under expiredGeofenceGeometryId in the response body.

  5. Posizione 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
    

    Query recinto virtuale 5

    Si può vedere che il macchinario è uscito dal recinto virtuale principale del cantiere.You can see that the equipment has left the main construction site geofence. Verrà pubblicato un evento in quanto si tratta di una grave violazione e verrà inviata una e-mail di avviso critico al direttore del cantiere.It publishes an event, it is a serious violation, and a critical alert email is sent to the Operations Manager.

Passaggi successiviNext steps

In questa esercitazione si è appreso come configurare un recinto virtuale caricandolo nel servizio dati di Mappe di Azure con l'API Caricamento dati.In this tutorial you learned, how to set up geofence by uploading it in the Azure Maps, Data service using the Data Upload API. Si è anche appreso come usare Griglia di eventi di Mappe di Azure per la sottoscrizione e la gestione di eventi di recinto virtuale.You also learned how to use Azure Maps Events Grid to subscribe to and handle geofence events.