チュートリアル:Azure Maps を使用してジオフェンスを設定する

[アーティクル]
01/11/2024

このチュートリアルでは、Azure Maps ジオフェンスサービスの作成と使用の基礎を確認します。

以下のシナリオについて考えてみます。

建設現場の管理者が、建設区域の境界を出入りする機材を追跡する必要があります。それらの境界を機材が出入りするたびに、メール通知が Operations Manager に送信されます。

建設区域を出入りする機材の追跡をサポートするサービスが Azure Maps には用意されています。このチュートリアルでは、次のことについて説明します。

監視対象の建設現場区域を定義するジオフェンシング GeoJSON データをアップロードする。ジオフェンスをポリゴン座標として Azure ストレージアカウントにアップロードし、データレジストリサービスを使用してそのデータを Azure Maps アカウントに登録します。
機材がジオフェンス領域を出入りしたときにトリガーされ、メール通知を建設現場の作業管理者に送信する 2 つのロジックアプリを設定する。
Azure Event Grid を使用して Azure Maps ジオフェンスの enter イベントと exit イベントをサブスクライブする。ここでは、2 つのロジックアプリに定義された HTTP エンドポイントを呼び出す Webhook イベントのサブスクリプションを 2 つ設定します。これらのロジックアプリから、ジオフェンスを出入りする機材に関する適切なメール通知が送信されます。
機材がジオフェンス領域を出入りしたときに、Search Geofence Get API を使用して通知を受信する。

前提条件

このチュートリアルでは、Postman アプリケーションを使用しますが、別の API 開発環境を使用することもできます。

重要

URL の例で、{Your-Azure-Maps-Subscription-key} を、実際の Azure Maps サブスクリプションキーに置き換えてください。

ジオフェンシング GeoJSON データをアップロードする

このチュートリアルでは、FeatureCollection を含むジオフェンシング GeoJSON データをアップロードする方法について説明します。 FeatureCollection には、建設現場内の多角形領域を定義する 2 つのジオフェンスが含まれています。 1 つ目のジオフェンスには、時間の有効期限や制限はありません。 2 つ目は、照会できる期間が作業時間 (太平洋標準時の午前 9 時から午後 5 時) に限られ、2022 年 1 月 1 日を過ぎると無効となります。 GeoJSON 形式の詳細については、「ジオフェンシング GeoJSON データ」を参照してください。

次のジオフェンスデータを使用して、ジオフェンス JSON ファイルを作成します。次に、このファイルを 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
             }
           ]
         }
       }
     }
   ]
}

データレジストリの作成方法に関する記事で説明されている手順に従って、ジオフェンス JSON ファイルを Azure ストレージアカウントにアップロードし、Azure マップアカウントに登録します。

重要

一意識別子 (udid) の値を必ず書き留めてください。必要になります。 udid は、ソースコードと HTTP 要求から Azure ストレージアカウントにアップロードしたジオフェンスを参照する方法です。

Azure Logic Apps でワークフローを作成する

次に、メール通知をトリガーする 2 つのロジックアプリエンドポイントを作成します。

ロジックアプリを作成するには、次の手順を実行します。

Azure portal にサインインします。
Azure portal の左上隅にある [リソースの作成] を選択します。
[Search services and marketplace]\(検索サービスとマーケットプレース\) ボックスに「Logic App」と入力します。
結果から [ロジックアプリ] を選択します。そのうえで [Create](作成) を選択します。
[Logic App] ページで、次の値を入力します。
- このロジックアプリに使用する "サブスクリプション"。
- このロジックアプリの "リソースグループ" の名前。 [新規作成] を選んで新しく作成することも、 [既存のものを使用] を選んで既存のリソースグループを使うこともできます。
- "ロジックアプリ名"。この場合は、名前として Equipment-Enter を使用します。
- プランの種類として [従量課金] を選択します。詳細については、ロジックアプリのドキュメントの課金モデルと価格モデルを参照してください。
このチュートリアルの目的上、他の値はすべて、既定の設定のままにしてください。
完了したら、[確認と作成] を選択します。 Azure によってロジックアプリリソースに関する情報が検証されたら、[作成] を選択します。
デプロイが正常に完了したら、 [リソースに移動] を選択します。
左側のメニューの [開発ツール] セクションで [ロジックアプリデザイナー] を選択し、[共通のトリガーで開始] セクションまで下にスクロールします。 [HTTP 要求の受信時] を選択します。
ロジックアプリデザイナーの右上隅にある [保存] を選択します。 HTTP POST の URL が自動的に生成されます。 URL を保存します。次のセクションでイベントのエンドポイントを作成する際に必要となります。
[+ 新しいステップ] を選択します。
検索ボックスに「outlook.com email」と入力します。 [アクション] の一覧を下へスクロールし、 [メールの送信 (V2)] を選択します。
Outlook アカウントにサインインします。アカウントへのアクセスをロジックアプリに許可するために、必ず [はい] を選択してください。メール送信に関するフィールドに値を入力します。

ヒント

geometryId や deviceId などの GeoJSON 応答データは、メール通知で取得できます。 Event Grid によって送信されたデータを読み取るように Logic Apps を構成できます。イベントデータを使用したり、イベントデータをメール通知に渡したりするように Logic Apps を構成する方法については、「チュートリアル: Event Grid および Logic Apps を使用して Azure IoT Hub イベントに関する電子メール通知を送信する」を参照してください。
[ロジックアプリデザイナー] の左上隅にある [保存] を選択します。
建設現場から機材が出されたときに管理者に通知する 2 つ目のロジックアプリを作成するには、同じ手順を繰り返します。このロジックアプリには Equipment-Exit という名前を付けます。

Azure Maps イベントのサブスクリプションを作成する

Azure Maps では、3 種類のイベントをサポートしています。このチュートリアルでは、次の 2 つのイベントに対するサブスクリプションを作成する方法について説明します。

ジオフェンス開始イベント
ジオフェンス終了イベント

ジオフェンス出口を作成し、イベントサブスクリプションに入ります。

Azure Maps アカウントで、 [サブスクリプション] を選択します。
サブスクリプション名を選択します。
設定メニューから、 [イベント] を選択します。
イベントページで [+ イベントサブスクリプション] を選択します。
[イベントサブスクリプションの作成] ページで、次の値を入力します。
- イベントサブスクリプションの "名前"。
- [イベントスキーマ] は [イベントグリッドスキーマ] にする必要があります。
- このイベントサブスクリプションの "システムトピック名"。この場合は、Contoso-Construction となります。
- [イベントの種類のフィルター] では、イベントの種類として Geofence Entered を選択します。
- [エンドポイントのタイプ] では、Web Hook を選択します。
- [エンドポイント] には、前のセクションで作成したロジックアプリの enter エンドポイントの HTTP POST の URL をコピーします。保存し忘れていた場合は、ロジックアプリデザイナーに戻って HTTP トリガーの手順からコピーしてください。
［作成］ を選択します
ジオフェンス終了イベントに対して同じ手順を繰り返します。イベントの種類として必ず Geofence Exited を選択してください。

Spatial Geofence Get API を使用する

次に、Spatial Geofence Get API を使用して、機材がジオフェンスを出入りしたときにメール通知を Operations Manager に送信します。

各機材には deviceId が指定されます。このチュートリアルでは、一意の ID が device_1 である 1 つの機材を追跡します。

次の図は、時間の経過に伴う機材の 5 つの位置を示したものです。ジオフェンス外部のどこかにある Start 位置が起点となります。このチュートリアルの目的上、"開始" 位置は定義されていません。その位置のデバイスに対してクエリを実行することはないからです。

ジオフェンスの最初の出入りを示す機材位置を指定して Spatial Geofence Get API に対するクエリを実行すると、Event Grid によって適切なロジックアプリエンドポイントが呼び出されて、メール通知が Operations Manager に送信されます。

以降の各セクションでは、5 つの異なる機材位置座標を使用して API 要求を実行します。

Diagram of geofence map in Azure Maps

機材位置 1 (47.638237,-122.132483)

Postman アプリ内で [新規] を選択します。
[新規作成] ウィンドウで [HTTP 要求] を選択します。
要求の [要求名] を入力します (Location 1 など)。
GET HTTP メソッドを選択します。
次の URL を入力します。要求は、次の URL のようになるはずです ({udid} は「ジオフェンシング GeoJSON データをアップロードする」セクションで保存した 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
```
Note

{geography} を実際の地域スコープに置き換えます。詳細については、「Azure Maps サービスの地域スコープ」および Spatial Geofence Get API に関するページを参照してください。
[Send] を選択します。

応答は次のような 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 アプリ内で [新規] を選択します。
[新規作成] ウィンドウで [HTTP 要求] を選択します。
要求の [要求名] を入力します (Location 2 など)。
GET HTTP メソッドを選択します。

次の URL を入力します。要求は、次の URL のようになるはずです ({udid} は「ジオフェンシング GeoJSON データをアップロードする」セクションで保存した 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

[Send] を選択します。

応答は次のような 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 アプリ内で [新規] を選択します。
[新規作成] ウィンドウで [HTTP 要求] を選択します。
要求の [要求名] を入力します (Location 3 など)。
GET HTTP メソッドを選択します。

  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

[Send] を選択します。

応答は次のような 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 には、機材がジオフェンスに入ったことを示すメール通知が送信されます。

Note

作業時間を過ぎてから機材がサブサイトに移動した場合は、イベントが発行されず、作業管理者に通知は送信されません。

場所 4 (47.637988,-122.1338344)

Postman アプリ内で [新規] を選択します。
[新規作成] ウィンドウで [HTTP 要求] を選択します。
要求の [要求名] を入力します (Location 4 など)。
GET HTTP メソッドを選択します。

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

[Send] を選択します。

応答は次のような 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 アプリ内で [新規] を選択します。
[新規作成] ウィンドウで [HTTP 要求] を選択します。
要求の [要求名] を入力します (Location 5 など)。
GET HTTP メソッドを選択します。

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

[Send] を選択します。

応答は次のような 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 には、機材がジオフェンスから出たことを示すメール通知が送信されます。

Event Grid と Logic Apps を使用して電子メール通知を送信することもできます。詳細については、「Azure Event Grid のイベントハンドラー」を参照してください。

リソースをクリーンアップする

クリーンアップが必要なリソースはありません。

次のステップ

Azure Logic Apps における各種コンテンツの扱い

チュートリアル:Azure Maps を使用してジオフェンスを設定する

前提条件

ジオフェンシング GeoJSON データをアップロードする

Azure Logic Apps でワークフローを作成する

Azure Maps イベントのサブスクリプションを作成する

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)

リソースをクリーンアップする

次のステップ

その他のリソース