你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
教程:使用 Azure Maps 设置地域隔离区
本教程将引导你完成创建和使用 Azure Maps 地理围栏服务的基本步骤。
假设出现了下面这种情景:
负责构造的站点管理员需要在设备进入和退出构造区域周界范围时对其进行跟踪。 每当有设备离开或进入这些范围时,运营管理员都会收到电子邮件通知。
Azure Maps 提供了服务来支持对进入和离开构造区域的设备进行跟踪。 在本教程中,将:
- 上传用于定义要监视的构造站点区域的地理围栏 GeoJSON 数据。 可以将地理围栏作为多边形坐标上传到 Azure 存储帐户,然后使用数据注册表服务将该数据注册到 Azure Maps 帐户。
- 设置两个逻辑应用,当设备进入或退出地理围栏区域,将触发应用并向构造站点的运营管理员发送邮件通知。
- 使用 Azure 事件网格订阅 Azure Maps 地理围栏进入和退出事件。 你将设置两个 Webhook 事件订阅,用于调用两个逻辑应用中定义的 HTTP 终结点。 然后,逻辑应用将发送有关设备移出或移入地理围栏的相应邮件通知。
- 使用搜索地理围栏 GET API 在有设备退出和进入地理围栏区域时接收通知。
先决条件
本教程使用 Postman 应用程序,但你也可以选择其他 API 开发环境。
重要
在 URL 示例中,将 {Your-Azure-Maps-Subscription-key}
替换为 Azure Maps 订阅密钥。
上传地理围栏 GeoJSON 数据
本教程演示如何上传包含 FeatureCollection
的地理围栏 GeoJSON 数据。 FeatureCollection
包含用于定义站点内多边形区域的两个地理围栏。 第一个地理围栏不设过期时间或时间限制。 第二个地理围栏只能在营业时间(太平洋时区上午 9:00 到下午 5:00)接受查询,且在 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 逻辑应用中创建工作流
接下来,创建两个用于触发电子邮件通知的逻辑应用终结点。
若要创建逻辑应用:
登录 Azure 门户。
在 Azure 门户的左上角,选择“创建资源”。
在搜索服务和市场框中,键入逻辑应用。
从结果中选择“逻辑应用”。 然后选择“创建”。
在“逻辑应用”页上,输入以下值:
- 要用于此逻辑应用的“订阅”。
- 此逻辑应用的“资源组”名称。 可以选择新建或使用现有的资源组 。
- 你的逻辑应用的“逻辑应用名称”。 本例使用
Equipment-Enter
作为名称。 - 选择“消耗”作为计划类型。 有关详细信息,请参阅 逻辑应用文档中的计费和定价模型 。
考虑到本教程的目的,请将其余值保留为其默认设置。
完成后,选择“ 查看 + 创建”。 在 Azure 验证你的逻辑应用资源的相关信息后,请选择“创建”。
部署成功完成后,选择“转到资源”。
在左侧菜单中的“开发工具”部分选择“逻辑应用设计器”,向下滚动到“开始使用常用触发器”部分。 选择“收到 HTTP 请求时”。
在逻辑应用设计器的右上角,选择“保存”。 随即自动生成“HTTP POST URL”。 保存 URL。 下一部分中需要用它来创建事件终结点。
选择“+ 新步骤”。
在搜索框中,键入“
outlook.com email
”。 在“操作”列表中,向下滚动并选择“发送电子邮件 (V2)” 。登录到 Outlook 帐户。 确保选择“是”以允许逻辑应用访问该帐户。 填充用于发送电子邮件的字段。
提示
在电子邮件通知中检索 GeoJSON 响应数据(如
geometryId
或deviceId
)。 可以将逻辑应用配置为读取事件网格发送的数据。 有关如何配置逻辑应用以使用事件数据并将其传递到电子邮件通知的详细信息,请参阅教程:使用事件网格和逻辑应用发送有关 Azure IoT 中心事件的电子邮件通知。在“逻辑应用设计器”的左上角,选择“保存” 。
重复相同的过程以创建第二个逻辑应用,以便在设备退出构造站点时通知管理员。 将逻辑应用命名为
Equipment-Exit
。
创建 Azure Maps 事件订阅
Azure Maps 支持三种事件类型。 本教程将演示如何创建对下面两个事件的订阅:
- 地理围栏进入事件
- 地理围栏退出事件
创建地理围栏离开和进入事件订阅:
在 Azure Maps 帐户中,选择“订阅”。
选择你的订阅名称。
在设置菜单中,选择“事件”。
在事件页面中,选择“+ 事件订阅”。
在“创建事件订阅”页中输入以下值:
- 事件订阅的“名称”。
- “事件架构”应为“事件网格架构” 。
- 此事件订阅的“系统主题名称”,在本例中为
Contoso-Construction
。 - 对于“事件类型筛选器”,请选择
Geofence Entered
作为事件类型。 - 对于“终结点类型”,选择
Web Hook
。 - 对于“终结点”,复制在上一个部分创建的“逻辑应用进入”终结点的 HTTP POST URL。 如果忘记保存,可以直接返回到逻辑应用设计器并从 HTTP 触发器步骤复制它。
选择创建。
对地理围栏退出事件重复相同的过程。 请确保选择
Geofence Exited
作为事件类型。
使用空间地理围栏获取 API
接下来,我们使用空间地理围栏获取 API 在有设备进入或离开地理围栏时向运营管理员发送电子邮件通知。
每个设备都有一个 deviceId
。 在本教程中,你将跟踪单个设备,其唯一 ID 为 device_1
。
下图显示了一段时间内设备的五个位置,并从位于地理围栏外的“启动”位置开始。 考虑到本教程的目的,不定义“开始”位置,因为不会在该位置查询设备。
当使用指示最初地理围栏进入或离开的设备位置查询空间地理围栏获取 API 时,事件网格会调用相应的逻辑应用终结点,来向运营管理员发送电子邮件通知。
以下每个部分都使用设备的 5 个不同位置坐标发出 API 请求。
设备位置 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
注意
请将 {geography} 替换为你的地理范围。 有关详细信息,请参阅《Azure Maps 服务地理范围》和《空间地理围栏获取 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
。 运营管理员会收到电子邮件通知,指示设备已进入地理围栏。
位置 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
,这样运营管理员不会收到任何电子邮件通知。
位置 3 (47.63810783315048,-122.13336020708084)
在 Postman 应用中,选择“新建”。
在“新建”窗口中,选择“HTTP 请求” 。
在“请求名称”中输入请求名称,比如 Location 3。
选择“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.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
。 运营管理员会收到电子邮件通知,指示设备已进入地理围栏。
注意
如果设备在营业时间后移入子站点,则不会发布任何事件,运营管理员不会收到任何通知。
位置 4 (47.637988,-122.1338344)
在 Postman 应用中,选择“新建”。
在“新建”窗口中,选择“HTTP 请求” 。
在“请求名称”中输入请求名称,比如 Location 4。
选择“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.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
,这样运营管理员不会收到电子邮件通知。
位置 5 (47.63799, -122.134505)
在 Postman 应用中,选择“新建”。
在“新建”窗口中,选择“HTTP 请求” 。
在“请求名称”中输入请求名称,比如 Location 5。
选择“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.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
,这样运营管理员将收到指示设备已离开地理围栏的电子邮件通知。
还可以使用事件网格和逻辑应用发送电子邮件通知。 有关详细信息,请参阅Azure 事件网格中的事件处理程序。
清理资源
没有需要清理的资源。