Tutorial: Menyiapkan geofence menggunakan Azure Maps

Artikel
07/27/2022
11 menit untuk membaca

Tutorial ini memandu Anda melalui dasar-dasar pembuatan dan penggunaan layanan geofence Azure Maps.

Pertimbangkan skenario berikut:

Manajer situs konstruksi harus melacak peralatan saat memasuki dan meninggalkan perimeter area konstruksi. Setiap kali sebuah peralatan keluar atau memasuki perimeter ini, pemberitahuan email dikirim ke manajer operasi.

Azure Maps menyediakan sejumlah layanan untuk mendukung pelacakan peralatan yang masuk dan keluar dari area konstruksi. Dalam tutorial ini, Anda akan:

Membuat akun Azure Maps dengan wilayah global.
Mengunggah data GeoJSON Geofencing yang menentukan area lokasi konstruksi yang ingin Anda pantau. Anda akan menggunakan Data Upload API untuk mengunggah geofence sebagai koordinat poligon ke akun Azure Maps Anda.
Siapkan dua aplikasi logika yang, ketika dipicu, mengirim pemberitahuan surel ke manajer operasi lokasi konstruksi saat peralatan masuk dan keluar dari area geofence.
Gunakan Azure Event Grid untuk berlangganan kejadian masuk dan keluar untuk geofence Azure Maps Anda. Anda menyiapkan dua langganan kejadian webhook yang memanggil titik akhir HTTP yang ditentukan di dua aplikasi logika Anda. Aplikasi logika selanjutnya mengirim pemberitahuan surel yang sesuai tentang peralatan yang bergerak menjauhi atau memasuki geofence.
Gunakan Search Geofence Get API untuk menerima pemberitahuan saat satu bagian peralatan keluar dan masuk area geofence.

Prasyarat

Tutorial ini menggunakan aplikasi Postman, tetapi Anda dapat menggunakan lingkungan pengembangan API berbeda.

Membuat akun Azure Maps dengan wilayah global

Peristiwa sinkronisasi Geofence API mengharuskan properti wilayah akun Azure Maps Anda diatur ke Global. Ini tidak diberikan sebagai opsi saat membuat akun Azure Maps di portal Azure, namun Anda memiliki beberapa opsi lain untuk membuat akun Azure Maps baru dengan pengaturan wilayah global. Bagian ini mencantumkan tiga metode yang dapat digunakan untuk membuat akun Azure Maps dengan wilayah yang diatur ke global.

Catatan

location Properti di pola dasar ARM dan PowerShell New-AzMapsAccount perintah mengacu ke properti yang sama dengan Region bidang di portal Azure.

Menggunakan pola dasar ARM untuk membuat akun Azure Maps dengan wilayah global

Anda perlu Membuat akun Azure Maps Anda menggunakan pola dasar ARM, pastikan untuk diatur location ke global bagian resources pola dasar ARM.

Gunakan PowerShell untuk membuat akun Azure Maps dengan wilayah global

New-AzMapsAccount -ResourceGroupName your-Resource-Group -Name name-of-maps-account -SkuName g2 -Location global

Gunakan Azure CLI untuk membuat akun Azure Maps dengan wilayah global

Perintah Azure CLI membuat akun azure maps tidak memiliki properti lokasi, tetapi default ke "global", sehingga berguna untuk membuat akun Azure Maps dengan pengaturan wilayah global untuk digunakan dengan peristiwa asinkron Geofence API.

Mengunggah data GeoJSON geofencing

Dalam tutorial ini, Anda akan mengunggah data GeoJSON geofencing yang berisi FeatureCollection. FeatureCollection berisi dua geofence yang menentukan area poligonal di dalam lokasi konstruksi. Geofence pertama tidak memiliki waktu kedaluwarsa atau pembatasan. Geofence kedua hanya dapat dikuerikan terhadap jam kerja (09:00-17:00 di Zona Waktu Pasifik) dan tidak akan berlaku lagi setelah 1 Januari 2022. Untuk informasi selengkapnya tentang format GeoJSON, lihat Data GeoJSON Geofencing.

Tip

Anda dapat memperbarui data geofencing kapan saja. Untuk informasi selengkapnya, lihat Data Upload API.

Untuk mengunggah data GeoJSON geofencing:

Di aplikasi Postman, pilih Baru.
Di jendela Buat Baru, pilih Permintaan HTTP.
Masukkan Nama permintaan untuk permintaan tersebut, seperti Unggah Data GeoJSON POST.
Pilih metode HTTP POST.
Masukkan URL berikut. Permintaan tersebut akan terlihat seperti URL berikut (ganti {Azure-Maps-Primary-Subscription-key} dengan kunci langganan primer):
```
https://us.atlas.microsoft.com/mapData?subscription-key={Your-Azure-Maps-Primary-Subscription-key}&api-version=2.0&dataFormat=geojson
```
Parameter geojson dalam jalur URL menunjukkan format data dari data yang diunggah.
Pilih tab Isi.
Di daftar tarik-turun, pilih mentah dan JSON.

Salin data GeoJSON berikut dan tempel di jendela Isi:

{
   "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
             }
           ]
         }
       }
     }
   ]
}

Pilih Kirim.
Dalam jendela tanggapan, pilih tab Header.
Salin nilai kunci Operasi-Lokasi, yang merupakan status URL. Kami akan menggunakan status URL untuk memeriksa status unggahan data GeoJSON.
```
https://us.atlas.microsoft.com/mapData/operations/{operationId}?api-version=2.0
```

Memeriksa status unggahan data GeoJSON

Untuk memeriksa status data GeoJSON dan mengambil ID uniknya (udid):

Pilih Baru.
Di jendela Buat Baru, pilih Permintaan HTTP.
Masukkan Nama permintaan untuk permintaan tersebut, seperti Status Unggahan Data GET.
Pilih metode HTTP GET.
Masukkan status URL yang Anda salin ke Unggah data Geofencing GeoJSON. Permintaan tersebut akan terlihat seperti URL berikut (ganti {Azure-Maps-Primary-Subscription-key} dengan kunci langganan primer):
```
https://us.atlas.microsoft.com/mapData/{operationId}?api-version=2.0&subscription-key={Your-Azure-Maps-Primary-Subscription-key}
```
Pilih Kirim.
Dalam jendela tanggapan, pilih tab Header.
Salin nilai kunci Sumber Daya-Lokasi, yang merupakan resource location URL. resource location URL berisi pengidentifikasi unik (udid) dari data yang diunggah. Simpan udid ini untuk mengkueri API Get Geofence di bagian akhir tutorial ini.

(Opsional) Mengambil metadata data GeoJSON

Anda dapat mengambil metadata dari data yang diunggah. Metadata tersebut berisi informasi seperti URL lokasi sumber daya, tanggal pembuatan, tanggal, ukuran, dan status unggahan yang diperbarui.

Untuk dapat mengambil metadata konten:

Pilih Baru.
Di jendela Buat Baru, pilih Permintaan HTTP.
Masukkan Nama permintaan untuk permintaan tersebut, seperti Metadata Unggahan Data GET.
Pilih metode HTTP GET.
Masukkan resource Location URL yang Anda salin ke Periksa status unggahan data GeoJSON. Permintaan tersebut akan terlihat seperti URL berikut (ganti {Azure-Maps-Primary-Subscription-key} dengan kunci langganan primer):
```
https://us.atlas.microsoft.com/mapData/metadata/{udid}?api-version=2.0&subscription-key={Your-Azure-Maps-Primary-Subscription-key}
```

Dalam jendela respons, pilih tab Isi. Metadata harus seperti fragmen JSON berikut:

{
    "udid": "{udid}",
    "location": "https://us.atlas.microsoft.com/mapData/6ebf1ae1-2a66-760b-e28c-b9381fcff335?api-version=2.0",
    "created": "5/18/2021 8:10:32 PM +00:00",
    "updated": "5/18/2021 8:10:37 PM +00:00",
    "sizeInBytes": 946901,
    "uploadStatus": "Completed"
}

Membuat alur kerja di Azure Logic Apps

Berikutnya, kita akan membuat dua titik akhir aplikasi logika yang memicu pemberitahuan surel.

Untuk membuat aplikasi logika:

Masuk ke portal Microsoft Azure.
Di pojok kiri atas portal Microsoft Azure, pilih Buat sumber daya.
Di kotak Cari Marketplace, ketik Logic App.
Pilih Aplikasi Logika dari hasil. Kemudian, pilih Buat.
Di halaman Logic App, masukkan nilai berikut:
- Langganan yang ingin Anda gunakan untuk aplikasi logika ini.
- Nama grup sumber daya untuk aplikasi logika ini. Anda dapat memilih untuk Buat baru atau Gunakan grup sumber daya yang ada.
- Nama Logic App dari aplikasi logika Anda. Dalam hal ini, gunakan Equipment-Enter sebagai nama.
Untuk tujuan tutorial ini, simpan semua nilai lain pada pengaturan defaultnya.
Pilih Tinjau + Buat. Tinjau pengaturan Anda dan pilih Buat.
Setelah penyebaran berhasil diselesaikan, pilih Buka sumber daya.
Di Logic App Designer, gulir ke bawah ke bagian Mulai dengan pemicu umum. Pilih Saat permintaan HTTP diterima.
Di pojok kanan atas Logic App Designer, pilih Simpan. URL POST HTTP dibuat secara otomatis. Simpan URL-nya. Anda memerlukannya di bagian berikutnya untuk membuat titik akhir kejadian.
Pilih + Langkah Baru.
Pada kotak pencarian, ketik outlook.com email. Dalam daftar Tindakan, gulir ke bawah dan pilih Kirim surel (V2) .
Masuk ke akun Outlook Anda. Pastikan memilih Ya untuk mengizinkan aplikasi logika mengakses akun. Isi bidang untuk mengirim surel.

Tip

Anda dapat mengambil data respons GeoJSON, seperti geometryId atau deviceId, di pemberitahuan surel. Anda dapat mengonfigurasi Logic Apps untuk membaca data yang dikirim oleh Event Grid. Untuk informasi tentang cara mengonfigurasi Logic Apps untuk menggunakan dan meneruskan data kejadian ke pemberitahuan surel, lihat Tutorial: Mengirim pemberitahuan surel tentang kejadian Azure IoT Hub menggunakan Event Grid dan Logic Apps.
Di bagian kiri atas Logic App Designer, pilih Simpan.
Untuk membuat aplikasi logika kedua untuk memberi tahu manajer saat peralatan keluar dari lokasi konstruksi, ulangi proses yang sama. Beri nama Equipment-Exit aplikasi logika.

Membuat langganan kejadian Azure Maps

Azure Maps mendukung tiga jenis kejadian. Dalam tutorial ini, Anda akan membuat langganan untuk dua kejadian berikut:

Kejadian geofence masuk
Kejadian geofence keluar

Untuk membuat langganan kejadian geofence masuk dan keluar:

Dalam akun Azure Maps Anda, pilih Langganan.
Pilih nama langganan Anda.
Dalam menu pengaturan, pilih kejadian.
Dalam halaman kejadian, Pilih + Langganan Kejadian.
Di halaman Buat Langganan Kejadian, masukkan nilai berikut:
- Nama langganan kejadian.
- Skema Kejadian harus berupa Skema Event Grid.
- Nama Topik Sistem untuk langganan kejadian ini, yang dalam hal ini adalah Contoso-Construction.
- Untuk Filter ke Jenis Kejadian, pilih Geofence Entered sebagai jenis kejadian.
- Untuk Jenis Titik Akhir, pilih Web Hook.
- Untuk Titik Akhir, salin URL POST HTTP untuk titik akhir aplikasi logika yang Anda buat di bagian sebelumnya. Jika lupa menyimpannya, Anda bisa kembali ke Logic App Designer dan menyalinnya dari langkah pemicu HTTP.
Pilih Buat.
Ulangi proses yang sama untuk kejadian geofence keluar. Pastikan memilih Geofence Exited sebagai jenis kejadian.

Menggunakan Spatial Geofence Get API

Berikutnya, kita akan menggunakan Spatial Geofence Get API untuk mengirim pemberitahuan surel ke manajer operasi ketika seperangkat peralatan masuk ke atau keluar dari geofence.

Setiap peralatan memiliki deviceId. Dalam tutorial ini, Anda melacak satu bagian peralatan, dengan ID yang unik device_1.

Diagram berikut memperlihatkan lima lokasi peralatan dari waktu ke waktu, dimulai di lokasi Mulai, yang berada di suatu tempat di luar geofence. Untuk tujuan tutorial ini, lokasi Mulai tidak ditentukan, karena Anda tidak akan mengkueri perangkat di lokasi tersebut.

Saat Anda mengkueri Spatial Geofence Get API dengan lokasi peralatan yang menunjukkan masuk atau keluar geofence awal, Event Grid memanggil titik akhir aplikasi logika yang sesuai untuk mengirim pemberitahuan surel ke manajer operasi.

Masing-masing bagian berikut membuat permintaan API menggunakan lima koordinat lokasi peralatan yang berbeda.

Diagram of geofence map in Azure Maps

Lokasi peralatan 1 (47.638237,-122.132483)

Di aplikasi Postman, pilih Baru.
Di jendela Buat Baru, pilih Permintaan HTTP.
Masukkan Nama permintaan untuk permintaan tersebut, seperti Lokasi 1.
Pilih metode HTTP GET.

Masukkan URL berikut. Permintaan tersebut akan terlihat seperti URL berikut, (ganti {Azure-Maps-Primary-Subscription-key} dengan kunci langganan utama Anda, dan {udid} dengan udid yang Anda simpan di bagian Unggah data GeoJSON Geofencing ).

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

Pilih Kirim.

Respons tersebut harus seperti fragmen GeoJSON berikut:

{
  "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
}

Dalam respons GeoJSON sebelumnya, jarak negatif dari geofence lokasi utama berarti peralatan berada di dalam geofence. Jarak positif dari geofensi sublokasi berarti peralatan berada di luar geofence sublokasi. Karena ini adalah pertama kalinya perangkat ini diletakkan di dalam geofence lokasi utama, parameter isEventPublished diatur ke true. Manajer operasi menerima pemberitahuan surel bahwa peralatan sudah memasuki geofence.

Lokasi 2 (47.63800,-122.132531)

Di aplikasi Postman, pilih Baru.
Di jendela Buat Baru, pilih Permintaan HTTP.
Masukkan Nama permintaan untuk permintaan tersebut, seperti Lokasi 2.
Pilih metode HTTP GET.

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

Pilih Kirim.

Respons tersebut harus seperti fragmen GeoJSON berikut:

{
  "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
}

Dalam respons GeoJSON sebelumnya, peralatan tetap berada di geofence lokasi utama dan belum memasuki geofence sublokasi. Akibatnya, parameter isEventPublished diatur ke false, dan manajer operasi tidak menerima pemberitahuan surel apa pun.

Lokasi 3 (47.63810783315048,-122.13336020708084)

Di aplikasi Postman, pilih Baru.
Di jendela Buat Baru, pilih Permintaan HTTP.
Masukkan Nama permintaan untuk permintaan tersebut, seperti Lokasi 3.
Pilih metode HTTP GET.

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

Pilih Kirim.

Respons tersebut harus seperti fragmen GeoJSON berikut:

{
  "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
}

Dalam respons GeoJSON sebelumnya, peralatan tetap berada di geofence lokasi utama, tetapi memasuki geofence sublokasi. Akibatnya, parameter isEventPublished diatur ke true. Manajer operasi menerima pemberitahuan surel yang menunjukkan peralatan sudah memasuki geofence.

Catatan

Jika peralatan sudah pindah ke sublokasi setelah jam kerja, tidak ada kejadian yang akan dipublikasikan dan manajer operasi tidak akan menerima pemberitahuan apa pun.

Lokasi 4 (47.637988,-122.1338344)

Di aplikasi Postman, pilih Baru.
Di jendela Buat Baru, pilih Permintaan HTTP.
Masukkan Nama permintaan untuk permintaan tersebut, seperti Lokasi 4.
Pilih metode HTTP GET.

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

Pilih Kirim.

Respons tersebut harus seperti fragmen GeoJSON berikut:

{
  "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
}

Dalam respons GeoJSON sebelumnya, peralatan tetap berada di geofence lokasi utama, tetapi keluar dari geofence sublokasi. Namun, perhatikan bahwa nilai userTime adalah setelah expiredTime seperti yang didefinisikan dalam data geofence. Akibatnya, parameter isEventPublished diatur ke false, dan manajer operasi tidak menerima pemberitahuan surel.

Lokasi 5 (47.63799, -122.134505)

Di aplikasi Postman, pilih Baru.
Di jendela Buat Baru, pilih Permintaan HTTP.
Masukkan Nama permintaan untuk permintaan tersebut, seperti Lokasi 5.
Pilih metode HTTP GET.

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

Pilih Kirim.

Respons tersebut harus seperti fragmen GeoJSON berikut:

{
  "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
}

Dalam respons GeoJSON sebelumnya, peralatan sudah keluar dari geofence lokasi utama. Akibatnya, parameter isEventPublished diatur ke true, dan manajer operasi menerima pemberitahuan surel yang menunjukkan peralatan sudah keluar dari geofence.

Anda juga dapat Kirim pemberitahuan surel menggunakan Event Grid dan Logic Apps dan memeriksa Penanganan Aktivitas yang Didukung di Event Grid menggunakan Azure Maps.

Membersihkan sumber daya

Tidak ada sumber daya yang memerlukan pembersihan.

Langkah berikutnya

Menangani jenis konten di Azure Logic Apps