Руководство по Настройка геозоны с использованием Azure Maps

  • Статья
  • Чтение занимает 11 мин

В этом руководстве показано, как создавать и использовать службы геозон в Azure Maps.

Рассмотрим следующий сценарий.

Руководителю строительного объекта нужно отслеживать оборудование, которое пересекает периметр строительной зоны в любую сторону. Всякий раз, когда оборудование прибывает в зону или покидает ее, руководителю отправляется уведомление по электронной почте.

Azure Maps предоставляет несколько служб, которые помогут отслеживать оборудование, прибывающее в зону строительства и покидающее ее. В этом руководстве рассмотрены следующие задачи:

  • Создайте учетную запись Azure Maps с глобальным регионом.
  • Отправка данных о геозонах в формате GeoJSON, которые определяют отслеживаемый строительный объект. Вы примените API отправки данных для передачи геозон в виде координат многоугольника в учетную запись Azure Maps.
  • Настройка двух активируемых приложений логики, которые отправляют по электронной почте уведомления руководителю строительного объекта при пересечении оборудованием границ геозоны.
  • Применение Сетки событий Azure для подписки на события входа в геозону Azure Maps и выхода из нее. Вы настроите две подписки для событий веб-перехватчиков, которые вызывают конечные точки HTTP, определенные в этих двух приложениях логики. После этого Logic Apps будет отправлять уведомления по электронной почте о входе оборудования в геозону и выходе из нее.
  • Применение API поиска по геозоне для получения уведомлений о пересечении оборудованием границ геозоны.

Предварительные требования

  • В этом руководстве используется приложение Postman, но вы можете выбрать другую среду разработки API.

Создайте учетную запись Azure Maps с глобальным регионом

Для асинхронного события API геозоны требуется, чтобы свойство «Регион» учетной записи Azure Maps было установлено со значением Глобальный. Это не является вариантом при создании учетной записи Azure Maps в портале Azure, однако у вас есть несколько других вариантов создания новой учетной записи Azure Maps с параметром глобального региона. В этом разделе перечислены три метода, которые можно использовать для создания учетной записи Azure Maps с регионом, для которого задано значение global.

Примечание

Свойство location в шаблоне ARM и команде PowerShell New-AzMapsAccount ссылается на то же свойство, что и поле Region в портал Azure.

Использование шаблона ARM для создания учетной записи Azure Maps с глобальным регионом

Вам потребуется Создать учетную запись Azure Maps с помощью шаблона ARM, установив для location значение global в разделе resources шаблона ARM.

Использование PowerShell для создания учетной записи Azure Maps с глобальным регионом

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

Использование Azure CLI для создания учетной записи Azure Maps с глобальным регионом

Команда Azure CLI az maps account create не имеет свойства расположения, но по умолчанию имеет значение "global", что позволяет создать учетную запись Azure Maps с параметром глобального региона для использования с асинхронным событием API геозоны.

Отправка данных о геозоне в формате GeoJSON

В этом руководстве показано, как отправить данные о геозоне в формате JSON с коллекцией FeatureCollection. FeatureCollection определяет две геозоны в виде многоугольников на строительном объекте. Для первой геозоны какие-либо ограничения, включая временные, отсутствуют. Вторую можно запрашивать только в рабочее время (с 9:00 до 17:00 по тихоокеанскому времени), и с 1 января 2022 года она будет недействительна. См. сведения о формате данных GeoJSON.

Совет

Вы можете в любое время изменить сведения о геозонах. Дополнительные сведения см. в статье об API отправки данных.

Чтобы передать данные о геозонах в формате GeoJSON, сделайте следующее.

  1. В приложении Postman выберите New (Создать).

  2. В окне Create New (Создание) выберите HTTP Request (HTTP-запрос).

  3. Введите имя запроса, например POST GeoJSON Data Upload.

  4. Выберите метод HTTP POST.

  5. Введите следующий URL-адрес: Запрос должен выглядеть аналогично следующему URL-адресу (замените {Azure-Maps-Primary-Subscription-key} ключом своей основной подписки):

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

    Параметр geojson в URL-адресе определяет формат отправляемых данных.

  6. Откройте вкладку Тело.

  7. В раскрывающихся списках выберите raw и JSON.

  8. Скопируйте приведенные ниже данные GeoJSON и вставьте их в окно Body (Основной текст).

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

  9. Нажмите кнопку Отправить.

  10. В окне ответа откройте вкладку Headers (Заголовки).

  11. Скопируйте значение ключа Operation-Location: status URL. Для проверки состояния передачи данных GeoJSON мы используем status URL.

    https://us.atlas.microsoft.com/mapData/operations/{operationId}?api-version=2.0

Проверка состояния передачи данных GeoJSON

Чтобы проверить состояние данных GeoJSON и получить их уникальный идентификатор (udid), выполните следующие действия.

  1. Нажмите кнопку Создать.

  2. В окне Create New (Создание) выберите HTTP Request (HTTP-запрос).

  3. Введите имя запроса, например GET, состояние отправки данных.

  4. Выберите метод HTTP GET.

  5. Введите значение status URL, скопированное на шаге Отправка данных о геозоне в формате GeoJSON. Запрос должен выглядеть аналогично следующему URL-адресу (замените {Azure-Maps-Primary-Subscription-key} ключом своей основной подписки):

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

  6. Нажмите кнопку Отправить.

  7. В окне ответа откройте вкладку Headers (Заголовки).

  8. Скопируйте значение ключа Resource-Location: resource location URL. resource location URL содержит уникальный идентификатор (udid) отправленных данных. Сохраните это значение udid, чтобы вы могли отправлять запросы к API получения геозоны, как показано в последнем разделе этого руководства.

    Скопируйте URL-адрес расположения ресурса.

(Необязательно.) Извлечение метаданных данных GeoJSON

Из переданных данных можно извлечь метаданные. Метаданные содержат такие сведения, как URL-адрес расположения ресурса, дата создания, дата обновления, размер и состояние отправки.

Для получения метаданных содержимого выполните следующие действия:

  1. Нажмите кнопку Создать.

  2. В окне Create New (Создание) выберите HTTP Request (HTTP-запрос).

  3. Введите имя запроса, например GET, метаданные отправки данных.

  4. Выберите метод HTTP GET.

  5. Введите значение resource Location URL, скопированное на шаге Проверка состояния передачи данных GeoJSON. Запрос должен выглядеть аналогично следующему URL-адресу (замените {Azure-Maps-Primary-Subscription-key} ключом своей основной подписки):

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

  6. В окне ответа выберите вкладку Body (Текст). Метаданные будут похожи на следующий фрагмент кода JSON:

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

Создание рабочих процессов в Azure Logic Apps

Далее мы создадим две конечные точки приложения логики, которые будут отправлять уведомления по электронной почте.

Чтобы создать приложения логики, сделайте следующее.

  1. Войдите на портал Azure.

  2. В верхнем левом углу окна портала Azure щелкните Создать ресурс.

  3. В поле Поиск по Marketplace введите Приложение логики.

  4. Из списка результатов выберите Приложение логики. Затем выберите Создать.

  5. На странице Приложение логики укажите следующее:

    • Подписка для этого приложения логики.
    • Группа ресурсов для этого приложения логики. Вы можете создать новую или использовать существующую группу ресурсов.
    • Имя приложения логики. В этом примере используется имя Equipment-Enter.

    Для работы с этим руководством оставьте значения по умолчанию для всех остальных параметров.

    Снимок экрана страницы создания приложения логики.

  6. Выберите Review + Create (Просмотреть и создать). Проверьте свои настройки параметров и щелкните Создать.

  7. Когда развертывание успешно завершится, щелкните Перейти к ресурсу.

  8. В конструкторе приложений логики прокрутите страницу вниз до раздела Start with a common trigger (Начинаем с часто используемого триггера). Выберите При получении HTTP-запроса.

    Снимок экрана страницы создания триггера HTTP в приложении логики.

  9. В правом верхнем углу конструктора приложений логики выберите Сохранить. Будет автоматически создан URL-адрес HTTP-запроса POST. Сохраните URL-адрес — Он понадобится для создания конечной точки события в следующем разделе.

    Снимок экрана, на котором показан URL-адрес и содержимое в формате JSON для HTTP-запроса приложения логики.

  10. Выберите + Новый шаг.

  11. В поле поиска введите outlook.com email. Прокрутите список Действия вниз и щелкните Отправка электронной почты (V2) .

    Снимок экрана конструктора создания приложения логики.

  12. Войдите в учетную запись Outlook. Выберите Да, чтобы разрешить приложению логики доступ к этой учетной записи. Заполните поля для отправки сообщения электронной почты.

    Снимок экрана страницы создание приложения логики (шаг отправки электронного письма).

    Совет

    В уведомлениях по электронной почте можно получить данные ответов GeoJSON, например geometryId или deviceId. В Logic Apps можно настроить чтение данных, отправляемых службой "Сетка событий". Сведения о том, как настроить в приложении логики получение данных о событиях и их передачу в уведомлениях по электронной почте, см. в этом учебнике: Отправка уведомлений электронной почты о событиях в Центре Интернета вещей Azure с помощью Сетки событий и Logic Apps.

  13. В левом верхнем углу конструктора приложений логики выберите Сохранить.

  14. Чтобы создать второе приложение логики для информирования руководителя о выходе оборудования из строительной зоны, повторите приведенную выше процедуру. Присвойте этому приложению логики имя Equipment-Exit.

Создание подписок на события Azure Maps

Azure Maps поддерживает три типа событий. В этом руководстве мы создадим подписки на следующие два события:

  • события входа в геозону;
  • события выхода из геозоны.

Чтобы создать подписки на события входа в геозону и выхода из геозоны, выполните следующие действия.

  1. В учетной записи Azure Maps выберите Подписки.

  2. Выберите имя своей подписки.

  3. В меню "Параметры" выберите События.

    Снимок экрана с изображением пункта меню для перехода к событиям учетной записи Azure Maps.

  4. На странице "События" щелкните +Подписка на события.

    Снимок экрана страницы создания подписки на события Azure Maps.

  5. На странице Создание подписки на события укажите следующее:

    • Имя для этой подписки на события.
    • В поле Схема события выберите Схема Сетки событий.
    • Имя системного раздела для этой подписки на события (в данном случае это Contoso-Construction).
    • В фильтре по типам событий выберите тип события Geofence Entered.
    • В поле Тип конечной точки выберите Web Hook.
    • В поле Конечная точка вставьте URL-адрес созданной на предыдущем шаге конечной точки HTTP-запроса POST из приложения логики для событий входа, который вы получили ранее. Если вы забыли сохранить это значение, просто переключитесь в окно конструктора приложений логики и скопируйте адрес из шага создания триггера HTTP.

    Снимок экрана со сведениями о подписке на события Azure Maps

  6. Нажмите кнопку создания.

  7. Повторите эту процедуру для события выхода из геозоны. На шаге 3 обязательно выберите тип события Geofence Exited.

Использование API определения пространственной геозоны

Далее мы применим API определения пространственной геозоны для отправки уведомлений по электронной почте руководителю строительного объекта о том, что элемент оборудования входит в границы геозоны или покидает ее.

Каждый элемент оборудования имеет deviceId. В этом примере будет отслеживаться только один элемент оборудования с уникальным идентификатором device_1.

На следующей схеме представлены пять расположений этого элемента оборудования с течением времени, начиная с позиции Начало, которая не входит в пределы наших геозон. Для работы с этим руководством мы не отправляем запрос к устройству в расположении Начало, поэтому это расположение не определено.

При отправке запроса API определения пространственной геозоны с новым расположением оборудования, которое соответствует первому входу оборудования в зону или выходу из нее, Сетка событий вызовет соответствующую конечную точку приложения логики, чтобы отправить руководителю уведомление строительного объекта по электронной почте.

Каждая из следующих секций выполняет запрос к API с разными координатами расположения оборудования.

Схема карты геозоны в Azure Maps

Расположение оборудования 1 (47,638237,-122,132483)

  1. В приложении Postman выберите New (Создать).

  2. В окне Create New (Создание) выберите HTTP Request (HTTP-запрос).

  3. Введите имя запроса, например Location 1.

  4. Выберите метод HTTP GET.

  5. Введите следующий URL-адрес: Запрос будет выглядеть как приведенный ниже URL-адрес (замените {Azure-Maps-Primary-Subscription-key} значением первичного ключа подписки, а {udid} — значением udid, которое вы сохранили на шаге Отправка данных о геозоне в формате GeoJSON).

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

  6. Нажмите кнопку Отправить.

  7. Ответ должен выглядеть как приведенный ниже фрагмент 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. Руководитель строительного объекта получает уведомление по электронной почте о том, что оборудование вошло в геозону.

Расположение 2 (47,63800,-122,132531)

  1. В приложении Postman выберите New (Создать).

  2. В окне Create New (Создание) выберите HTTP Request (HTTP-запрос).

  3. Введите имя запроса, например Location 2.

  4. Выберите метод HTTP GET.

  5. Введите следующий URL-адрес: Запрос будет выглядеть как приведенный ниже URL-адрес (замените {Azure-Maps-Primary-Subscription-key} значением первичного ключа подписки, а {udid} — значением udid, которое вы сохранили на шаге Отправка данных о геозоне в формате GeoJSON).

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

  6. Нажмите кнопку Отправить.

  7. Ответ должен выглядеть как приведенный ниже фрагмент 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, и уведомление руководителю строительного объекта не будет отправлено по электронной почте.

Расположение 3 (47,63810783315048,-122,13336020708084)

  1. В приложении Postman выберите New (Создать).

  2. В окне Create New (Создание) выберите HTTP Request (HTTP-запрос).

  3. Введите имя запроса, например Location 3.

  4. Выберите метод HTTP GET.

  5. Введите следующий URL-адрес: Запрос будет выглядеть как приведенный ниже URL-адрес (замените {Azure-Maps-Primary-Subscription-key} значением первичного ключа подписки, а {udid} — значением udid, которое вы сохранили на шаге Отправка данных о геозоне в формате GeoJSON).

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

  6. Нажмите кнопку Отправить.

  7. Ответ должен выглядеть как приведенный ниже фрагмент 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. Руководитель строительного объекта получает уведомление по электронной почте о том, что оборудование вошло в геозону.

Примечание

Если оборудование переходит в дополнительную геозону в нерабочее время, событие не публикуется и руководитель не получает уведомлений.

Расположение 4 (47,637988,-122,1338344)

  1. В приложении Postman выберите New (Создать).

  2. В окне Create New (Создание) выберите HTTP Request (HTTP-запрос).

  3. Введите имя запроса, например Location 4.

  4. Выберите метод HTTP GET.

  5. Введите следующий URL-адрес: Запрос будет выглядеть как приведенный ниже URL-адрес (замените {Azure-Maps-Primary-Subscription-key} значением первичного ключа подписки, а {udid} — значением udid, которое вы сохранили на шаге Отправка данных о геозоне в формате GeoJSON).

    https://atlas.microsoft.com/spatial/geofence/json?subscription-key={Your-Azure-Maps-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

  6. Нажмите кнопку Отправить.

  7. Ответ должен выглядеть как приведенный ниже фрагмент 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, и уведомление по электронной почте руководителю не отправляется.

Расположение 5(47,63799,-122,134505)

  1. В приложении Postman выберите New (Создать).

  2. В окне Create New (Создание) выберите HTTP Request (HTTP-запрос).

  3. Введите имя запроса, например Location 5.

  4. Выберите метод HTTP GET.

  5. Введите следующий URL-адрес: Запрос будет выглядеть как приведенный ниже URL-адрес (замените {Azure-Maps-Primary-Subscription-key} значением первичного ключа подписки, а {udid} — значением udid, которое вы сохранили на шаге Отправка данных о геозоне в формате GeoJSON).

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

  6. Нажмите кнопку Отправить.

  7. Ответ должен выглядеть как приведенный ниже фрагмент 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, и руководителю строительного объекта будет отправлено по электронной почте уведомление о том, что оборудование вышло из геозоны.

Вы также можете отправлять уведомления по электронной почте с помощью Сетки событий и Logic Apps и проверять поддерживаемые обработчики событий в Сетке событий с помощью Azure Maps.

Очистка ресурсов

Нет ресурсов, требующих очистки.

Дальнейшие действия

Обработка типов содержимого в Azure Logic Apps