教學課程：使用 Azure 地圖服務設定地理柵欄

發行項
03/27/2024

本教學課程將逐步引導您了解建立和使用 Azure 地圖服務地理柵欄服務的基本概念。

試想以下情況：

工地管理員必須在設備進入和離開建築區域的周邊時追蹤設備。每當設備離開或進入這些周邊區域時，都會傳送電子郵件通知給 Operations Manager。

Azure 地圖服務提供服務，以支援在設備進入和離開建築區域時加以追蹤。在此教學課程中，您需要：

上傳 Geofencing GeoJSON 資料，以定義您想要監視的工地區域。您會使用資料上傳 API，將地理柵欄當作多邊形座標上傳至您的 Azure 地圖服務帳戶。
設定兩個邏輯應用程式；當觸發時，會在設備進入並離開地理柵欄區域時，傳送電子郵件通知給網站建構的 Operations Manager。
使用 Azure 事件方格來訂閱 Azure 地圖服務地理柵欄進入和退出事件。您會設定兩個 Webhook 事件訂用帳戶，以呼叫您在兩個邏輯應用程式中定義的 HTTP 端點。然後，邏輯應用程式會在設備移動或進入地理柵欄時，傳送適當的電子郵件通知。
使用 Spatial Geofence Get API，在設備離開並進入地理柵欄區域時接收通知。

必要條件

本教學課程使用 Postman 應用程式，但您可以使用不同的 API 開發環境。

重要

在 URL 範例中，以您的 Azure 地圖服務訂用帳戶金鑰取代 {Your-Azure-Maps-Subscription-key}。

建立具有全域區域的 Azure 地圖服務帳戶

Geofence API 非同步事件需要 Azure 地圖服務帳戶的區域屬性設定為 [全域]。在 Azure 入口網站中建立 Azure 地圖服務帳戶時，不會提供此設定，不過您有數個其他選項可用來建立具有「全域」區域設定的新 Azure 地圖服務帳戶。本節列出三種方法，可用來建立 Azure 地圖服務帳戶，並將區域設定為「全域」。

注意

ARM 範本和 PowerShell New-AzMapsAccount 命令中的 location 屬性都會參考與 Azure 入口網站中的 Region 欄位相同的屬性。

上傳地理柵欄 GeoJSON 資料

本教學課程會示範如何上傳包含 FeatureCollection 的地理柵欄 GeoJSON 資料。 FeatureCollection 包含在工地內定義多邊形區域的兩個地理柵欄。第一個地理柵欄沒有到期時間或限制。第二個地理柵欄只能根據上班時間 (太平洋時區上午 9:00 - 下午 5:00) 進行查詢，在 2022 年 1 月 1 日之後即失效。如需關於GeoJSON 格式的詳細資訊，請參閱 Geofencing GeoJSON 資料。

提示

您可以隨時更新您的地理柵欄資料。如需詳細資訊，請參閱資料上傳 API。若要上傳地理柵欄 GeoJSON 資料：

在 Postman 應用程式中，選取 [New] \(新增\)。
在 [Create New] \(新建\) 視窗中，選取 [HTTP Request] \(HTTP 要求\)。
輸入要求的要求名稱，例如 POST GeoJSON Data Upload。
選取 [POST] HTTP 方法。
輸入下列 URL。要求應會類似於下列 URL：
```
https://{geography}.atlas.microsoft.com/mapData?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=2.0&dataFormat=geojson
```
URL 路徑中的 geojson 參數代表上傳資料的資料格式。

注意

將 {geography} 取代為您的地理範圍。如需詳細資訊，請參閱 Azure 地圖服務地理範圍，以及 Spatial Geofence Get API。
選取 [本文] 索引標籤。
在下拉式清單中，選取 [raw] \(原始\) 和 [JSON]。
複製下列 GeoJSON 資料，然後將其貼到 [本文] 視窗：

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

請選取傳送。
在回應視窗中，選取 [Headers] \(標頭\) 索引標籤。
複製 Operation-Location 金鑰的值，即 status URL。 status URL 用來檢查 GeoJSON 資料上傳的狀態。
```
https://{geography}.atlas.microsoft.com/mapData/operations/{operationId}?api-version=2.0
```

檢查 GeoJSON 資料上傳狀態

若要檢查 GeoJSON 資料的狀態並擷取其唯一識別碼 (udid)：

選取新增。
在 [Create New] \(新建\) 視窗中，選取 [HTTP Request] \(HTTP 要求\)。
輸入要求的 [Request name] \(要求名稱\)，例如 GET Data Upload Status。
選取 [GET] HTTP 方法。

輸入您在上傳地理柵欄 GeoJSON 資料中複製的 status URL。要求應會類似於下列 URL：

https://{geography}.atlas.microsoft.com/mapData/{operationId}?api-version=2.0&subscription-key={Your-Azure-Maps-Subscription-key}

請選取傳送。
在回應視窗中，選取 [Headers] \(標頭\) 索引標籤。
複製 Resource-Location 金鑰的值，即 resource location URL。 resource location URL 包含上傳資料的唯一識別碼 (udid)。在本教學課程的最後一節中，儲存 udid 以查詢 Get Geofence API。

(選擇性) 擷取 GeoJSON 資料中繼資料

您可以從上傳的資料擷取中繼資料。中繼資料包含資源位置 URL、建立日期、更新日期、大小和上傳狀態等資訊。

若要擷取內容中繼資料：

選取新增。
在 [Create New] \(新建\) 視窗中，選取 [HTTP Request] \(HTTP 要求\)。
輸入要求的 [要求名稱]，例如 GET Data Upload Metadata。
選取 [GET] HTTP 方法。

輸入您在檢查 GeoJSON 資料上傳狀態中複製的 resource Location URL。要求應會類似於下列 URL：

https://{geography}.atlas.microsoft.com/mapData/metadata/{udid}?api-version=2.0&subscription-key={Your-Azure-Maps-Subscription-key}

在回應視窗中，選取 [本文] 索引標籤。中繼資料應該會類似下列 JSON 片段：

{
    "udid": "{udid}",
    "location": "https://{geography}.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"
}

在 Azure Logic Apps 中建立工作流程

接下來，建立兩個邏輯應用程式端點，以觸發電子郵件通知。

若要建立邏輯應用程式：

登入 Azure 入口網站。
在 Azure 入口網站的左上角，選取 [建立資源]。
在 [搜尋服務和 Marketplace] 方塊中輸入 [Logic App]。
從結果中選取 [邏輯應用程式]。然後，選取 [建立]。
在 [邏輯應用程式] 頁面上，輸入下列值：
- 您想要使用於此邏輯應用程式的「訂用帳戶」。
- 此邏輯應用程式的「資源群組」名稱。您可以選擇 [建立新的] 或 [使用現有的] 資源群組。
- 邏輯應用程式的「邏輯應用程式名稱」。在此情況下，使用 Equipment-Enter 作為名稱。
- 選取 [使用量] 作為 [方案類型]。如需詳細資訊，請參閱 Logic App 文件中計費和定價模型。
基於本教學課程的目的，請將其餘所有值保留為預設設定。
當您完成時，選取 [檢閱 + 建立]。在 Azure 驗證邏輯應用程式資源的相關資訊之後，請選取 [建立]。
當部署成功完成時，選取 [移至資源]。
在左側功能表中的 [開發工具] 區段中，選取 [邏輯應用程式設計工具]，向下捲動至 [以一般觸發程式開始] 區段。選取 [收到 HTTP 要求時]。
在邏輯應用程式設計工具的右上角，選取 [儲存]。系統會自動產生 HTTP POST URL。儲存 URL。您在下一節中需要使用此資訊來建立事件端點。
選取 + 新增步驟。
在搜尋方塊中，輸入 outlook.com email。在 [動作] 清單中向下捲動，然後選取 [傳送電子郵件 (V2)]。
登入 Outlook 帳戶。請務必選取 [是] 允許邏輯應用程式存取帳戶。填寫傳送電子郵件的欄位。

提示

您可以在電子郵件通知中，取出 GeoJSON 回應資料，例如 geometryId 或 deviceId。您可以設定 Logic Apps 來讀取事件方格所傳送的資料。如需如何設定 Logic Apps 以取用事件資料並將事件資料傳遞至電子郵件通知的詳細資訊，請參閱教學課程：使用事件方格和 Logic Apps 傳送有關 Azure IoT 中樞事件的電子郵件通知。
在 [邏輯應用程式設計工具] 的左上角，選取 [儲存]。
若要建立第二個邏輯應用程式，以在設備離開工地時通知管理員，請重複相同的程序。將邏輯應用程式命名為 Equipment-Exit。

建立 Azure 地圖服務事件訂用帳戶

Azure 地圖服務支援三種事件類型。本教學課程將示範如何建立下列兩個事件的訂用帳戶：

地理柵欄輸入事件
地理柵欄結束事件

建立地理柵欄結束和輸入事件訂用帳戶：

在您的 Azure 地圖服務帳戶中，選取 [訂用帳戶]。
選取您的訂用帳戶名稱。
在 [設定] 功能表中，選取 [事件]。
在事件頁面中，選取 [+ 事件訂用帳戶]。
在 [建立事件訂用帳戶] 頁面上，輸入下列值：
- 事件訂用帳戶的「名稱」。
- 「事件結構描述」應該是「事件方格結構描述」。
- 此事件訂用帳戶的「系統主題名稱」，在此案例中是 Contoso-Construction。
- 針對「事件種類篩選條件」，選擇 Geofence Entered 作為事件種類。
- 針對「端點類型」，選擇 Web Hook。
- 針對「端點」，請複製您在上一節中所建立邏輯應用程式進入端點的 HTTP POST URL。如果您忘記儲存此資訊，可以直接回到邏輯應用程式設計工具，並從 HTTP 觸發程序步驟複製。
選取建立。
針對地理柵欄結束事件重複相同的程序。務必選擇 Geofence Exited 作為事件種類。

使用 Spatial Geofence Get API

接下來，我們繪使用 Spatial Geofence Get API，在設備進入或離開地理柵欄時，傳送電子郵件通知給 Operations Manager。

每一項設備都有 deviceId。在本教學課程中，您會追蹤單一設備，其唯一識別碼為 device_1。

下圖顯示裝置在一段時間內的五個位置，從「開始」位置開始，也就是地理柵欄以外的地方。基於本教學課程的目的，「開始」位置並未定義，因為您不用在該位置查詢裝置。

當您查詢 Spatial Geofence Get API 了解指出初始地理柵欄進入或結束的設備位置時，事件方格會呼叫適當的邏輯應用程式端點，將電子郵件通知傳送至 Operations Manager。

下列各節會使用五個不同的設備位置座標，讓 API 發出要求。

Diagram of geofence map in Azure Maps

設備位置 1 (47.638237，-122.132483)

在 Postman 應用程式中，選取 [New] \(新增\)。
在 [Create New] \(新建\) 視窗中，選取 [HTTP Request] \(HTTP 要求\)。
輸入要求的 [要求名稱]，例如「位置 1」。
選取 [GET] HTTP 方法。

輸入下列 URL。邀請應該如下列 URL 所示 (使用您儲存在上傳地理柵欄 GeoJSON 資料區段中的 udid 取代 {udid})。

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

請選取傳送。

回應應該類似下列 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
}

在上述 GeoJSON 回應中，與主要位置地理柵欄的距離顯示為負數，表示設備位於地理柵欄內。與子工地地理柵欄的距離顯示為正數，表示設備位於子工地地理柵欄外。由於這是此裝置第一次位於主要位置地理柵欄內，所以 isEventPublished 參數會設定為 true。 Operations Manager 會收到電子郵件通知，表示設備已進入地理柵欄。

位置 2 (47.63800，-122.132531)

在 Postman 應用程式中，選取 [New] \(新增\)。
在 [Create New] \(新建\) 視窗中，選取 [HTTP Request] \(HTTP 要求\)。
輸入要求的 [要求名稱]，例如「位置 2」。
選取 [GET] HTTP 方法。

輸入下列 URL。邀請應該如下列 URL 所示 (使用您儲存在上傳地理柵欄 GeoJSON 資料區段中的 udid 取代 {udid})。

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

請選取傳送。

回應應該類似下列 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
}

在上述的 GeoJSON 回應中，設備仍在主要位置地理柵欄中，而且尚未進入子位置地理柵欄。因此，isEventPublished 參數會設定為 false，而 Operations Manager 不會收到任何電子郵件通知。

位置 3 (47.63810783315048，-122.13336020708084)

在 Postman 應用程式中，選取 [New] \(新增\)。
在 [Create New] \(新建\) 視窗中，選取 [HTTP Request] \(HTTP 要求\)。
輸入要求的 [要求名稱]，例如「位置 3」。
選取 [GET] HTTP 方法。

輸入下列 URL。邀請應該如下列 URL 所示 (使用您儲存在上傳地理柵欄 GeoJSON 資料區段中的 udid 取代 {udid})。

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

請選取傳送。

回應應該類似下列 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
}

在上述的 GeoJSON 回應中，設備仍在主要位置地理柵欄中，而且進入子位置地理柵欄。因此，isEventPublished 參數會設定為 true。 Operations Manager 會收到電子郵件通知，表示設備進入地理柵欄。

注意

如果設備在上班時間後已移至子位置，則不會發佈任何事件，且 Operations Manager 不會收到任何通知。

位置 4 (47.637988，-122.1338344)

在 Postman 應用程式中，選取 [New] \(新增\)。
在 [Create New] \(新建\) 視窗中，選取 [HTTP Request] \(HTTP 要求\)。
輸入要求的 [要求名稱]，例如「位置 4」。
選取 [GET] HTTP 方法。

輸入下列 URL。邀請應該如下列 URL 所示 (使用您儲存在上傳地理柵欄 GeoJSON 資料區段中的 udid 取代 {udid})。

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

請選取傳送。

回應應該類似下列 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
}

在上述的 GeoJSON 回應中，設備仍在主要位置地理柵欄中，但是離開子位置地理柵欄。不過請注意，userTime 值會在 expiredTime (如地理柵欄資料中所定義) 之後。因此，isEventPublished 參數會設定為 false，而 Operations Manager 不會收到電子郵件通知。

位置 5 (47.63799、-122.134505)

在 Postman 應用程式中，選取 [New] \(新增\)。
在 [Create New] \(新建\) 視窗中，選取 [HTTP Request] \(HTTP 要求\)。
輸入要求的 [要求名稱]，例如「位置 5」。
選取 [GET] HTTP 方法。

輸入下列 URL。邀請應該如下列 URL 所示 (使用您儲存在上傳地理柵欄 GeoJSON 資料區段中的 udid 取代 {udid})。

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

請選取傳送。

回應應該類似下列 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
}

在上述的 GeoJSON 回應中，設備離開主要位置地理柵欄。因此，isEventPublished 參數會設定為 true，而 Operations Manager 會收到電子郵件通知，指出設備離開地理柵欄。

您也可以使用事件方格和 Logic Apps 來傳送電子郵件通知。如需詳細資訊，請參閱 Azure 事件方格事件處理常式。

清除資源

沒有任何資源需要清除。

下一步

在 Azure 邏輯應用程式中處理內容類型

教學課程：使用 Azure 地圖服務設定地理柵欄

必要條件

建立具有全域區域的 Azure 地圖服務帳戶

上傳地理柵欄 GeoJSON 資料

檢查 GeoJSON 資料上傳狀態

(選擇性) 擷取 GeoJSON 資料中繼資料

在 Azure Logic Apps 中建立工作流程

建立 Azure 地圖服務事件訂用帳戶

使用 Spatial Geofence Get API

設備位置 1 (47.638237，-122.132483)

位置 2 (47.63800，-122.132531)

位置 3 (47.63810783315048，-122.13336020708084)

位置 4 (47.637988，-122.1338344)

位置 5 (47.63799、-122.134505)

清除資源

下一步

其他資源