你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
Spatial - Get Geofence
使用 获取坐标与地理围栏的邻近度。
API Get Geofence
是一个 HTTP GET
请求,用于检索坐标与已上传到数据注册表的地理围栏的邻近度。 将地理围栏或围栏集上传到 Azure 存储帐户,然后使用数据注册表将其注册到 Azure Maps 帐户。有关详细信息,请参阅如何创建数据注册表。 有关地理围栏数据格式的详细信息,请参阅 地理围栏 GeoJSON 数据。 若要查询坐标的邻近度,请提供要跟踪的对象的位置以及围栏或围栏集的 ID,响应将包含有关与地理围栏外部边缘的距离的信息。 负值表示坐标在围栏内,而正值表示坐标在围栏之外。
此 API 可用于各种方案,包括资产跟踪、车队管理或设置移动对象的警报。
API 支持 与事件网格集成。 isAsync 参数用于启用与事件网格的集成, (默认) 禁用。 若要测试此 API,可以使用数据注册表服务上传 Post Geofence API 示例中的示例数据 (请求正文) ,并将以下示例udid
请求中的 替换为{udid}
用于创建数据注册表的 。 有关数据注册表服务的详细信息,请参阅 如何创建数据注册表。
地理围栏 InnerError 代码
在地理围栏响应错误协定中, innererror
是包含有关错误的服务特定信息的对象。 code
是一个属性,其中 innererror
可以映射到特定的地理围栏错误类型。 下表显示了所有已知客户端错误类型与相应地理围栏错误 message
之间的代码映射。
innererror.code | error.message |
---|---|
NullDeviceId | 设备 ID 不应为 null。 |
NullUdid | Udid 不应为 null。 |
UdidWrongFormat | 应从用户数据引入 API 获取 Udid。 |
InvalidUserTime | Usertime 无效。 |
InvalidSearchBuffer | Searchbuffer 无效。 |
InvalidSearchRange | searchbuffer 的值范围应为 0 到 500 米。 |
InvalidLatLon | Lat 和/或 lon 参数无效。 |
InvalidIsAsyncValue | IsAsync 参数无效。 |
InvalidModeValue | mode 参数无效。 |
InvalidJson | 地理围栏数据不是有效的 json 文件。 |
NotSupportedGeoJson | 地理围栏数据不能作为功能或 FeatureCollection 读取。 |
InvalidGeoJson | 地理围栏数据无效。 |
NoUserDataWithAccountOrSubscription | 找不到具有提供的 account-id 和/或 subscription-id 的用户地理围栏数据。 |
NoUserDataWithUdid | 无法使用提供的 udid 找到用户地理围栏数据。 |
GET https://{geography}.atlas.microsoft.com/spatial/geofence/json?api-version=2022-08-01&deviceId={deviceId}&udid={udid}&lat={lat}&lon={lon}
GET https://{geography}.atlas.microsoft.com/spatial/geofence/json?api-version=2022-08-01&deviceId={deviceId}&udid={udid}&lat={lat}&lon={lon}&z={z}&userTime={userTime}&searchBuffer={searchBuffer}&isAsync={isAsync}&mode={mode}
URI 参数
名称 | 在 | 必需 | 类型 | 说明 |
---|---|---|---|---|
format
|
path | True |
Json |
响应的所需格式。 仅支持 |
geography
|
path | True |
string |
Azure Maps帐户的位置。 有效值为 us (美国东部、美国中西部、美国西部 2) 和欧盟 (北欧、西欧) 。 在请求中提供 时 |
api-version
|
query | True |
string |
Azure Maps API 的版本号。 |
device
|
query | True |
string |
设备 ID |
lat
|
query | True |
number |
所传递位置的纬度。 示例:48.36。 |
lon
|
query | True |
number |
所传递位置的经度。 示例:-124.63。 |
udid
|
query | True |
string |
创建 数据注册表 以上传有效的 GeoJSON FeatureCollection 对象时使用的唯一 ID。 有关详细信息,请参阅 RFC 7946 。 特征的所有属性都应包含 |
is
|
query |
boolean |
如果为 true,则请求将使用异步事件机制;如果为 false,则请求将同步且不会触发任何事件。 默认值为 false。 |
|
mode
|
query |
Geofence |
地理围栏异步事件机制的模式。 |
|
search
|
query |
number |
地理围栏周围的缓冲区半径,以米为单位,用于定义在计算结果时根据提供的坐标在围栏边界内外搜索的距离。 最小值为 0,最大值为 500。 默认值为 50。 |
|
user
|
query |
string date-time |
用户请求时间。 如果请求中未显示,则默认值为 DateTime.Now。 |
|
z
|
query |
number |
所经过位置的海平面(以米为单位)。 如果提供此参数,则使用 2D 延伸。 示例:200。 |
请求头
名称 | 必需 | 类型 | 说明 |
---|---|---|---|
x-ms-client-id |
string |
指定要与Microsoft Entra ID安全模型结合使用的帐户。 它表示Azure Maps帐户的唯一 ID,可从Azure Maps管理平面帐户 API 检索。 若要在 Azure Maps 中使用Microsoft Entra ID安全性,请参阅以下文章以获取指导。 |
响应
名称 | 类型 | 说明 |
---|---|---|
200 OK |
OK:X-Correlation-id 标头值存在于异步调用的响应和事件网格事件数据中。 它有助于将异步调用的响应与相应的事件网格事件相关联。 Headers X-Correlation-id: string |
|
Other Status Codes |
Error |
发生了意外错误。 |
安全性
AADToken
这些是Microsoft Entra OAuth 2.0 流。 与 Azure 基于角色的访问控制配对时,它可用于控制对Azure Maps REST API 的访问。 Azure 基于角色的访问控制用于指定对一个或多个Azure Maps资源帐户或子资源的访问权限。 可以通过内置角色或由一个或多个权限组成的自定义角色授予任何用户、组或服务主体的访问权限,以Azure Maps REST API。
若要实现方案,建议查看 身份验证概念。 总之,此安全定义提供了一种解决方案,用于通过能够对特定 API 和作用域进行访问控制的对象对应用程序 () 建模。
备注
- 此安全定义需要使用
x-ms-client-id
标头来指示应用程序请求访问的Azure Maps资源。 这可以从 地图管理 API 获取。
Authorization URL
特定于 Azure 公有云实例。 主权云具有唯一的授权 URL 和Microsoft Entra ID配置。
* Azure 基于角色的访问控制是通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API 从 Azure 管理平面配置的。
* 使用 Azure Maps Web SDK 允许针对多个用例对应用程序进行基于配置的设置。
- 有关Microsoft 标识平台的详细信息,请参阅Microsoft 标识平台概述。
Type:
oauth2
Flow:
implicit
Authorization URL:
https://login.microsoftonline.com/common/oauth2/authorize
Scopes
名称 | 说明 |
---|---|
https://atlas.microsoft.com/.default | https://atlas.microsoft.com/.default |
subscription-key
这是在通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API 通过 Azure 管理平面创建Azure Maps资源时预配的共享密钥。
使用此密钥,任何应用程序都有权访问所有 REST API。 换而言之,这些密钥当前可被视为为其颁发帐户的主密钥。
对于公开的应用程序,我们建议使用服务器到服务器访问Azure Maps REST API,可在其中安全存储此密钥。
Type:
apiKey
In:
header
SAS Token
这是一个共享访问签名令牌,通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API,通过 Azure 管理平面在Azure Maps资源上列出 SAS 操作创建。
使用此令牌,任何应用程序都有权使用 Azure 基于角色的访问控制进行访问,并精细控制特定令牌的过期、速率和区域 () 。 换句话说,SAS 令牌可用于允许应用程序以比共享密钥更安全的方式控制访问。
对于公开的应用程序,我们建议在 Map 帐户资源 上配置允许的来源的特定列表,以限制呈现滥用,并定期续订 SAS 令牌。
Type:
apiKey
In:
header
示例
GetGeofence
Sample Request
GET https://us.atlas.microsoft.com/spatial/geofence/json?api-version=2022-08-01&deviceId=unique_device_name_under_account&udid=f6495f62-94f8-0ec2-c252-45626f82fcb2&lat=48.36&lon=-124.63&userTime=2022-08-21T17:32:28Z&searchBuffer=50&isAsync=True&mode=EnterAndExit
Sample Response
{
"geometries": [
{
"deviceId": "unique_device_name_under_account",
"udId": "f6495f62-94f8-0ec2-c252-45626f82fcb2",
"geometryId": "2",
"distance": 999,
"nearestLat": 47.621954,
"nearestLon": -122.131841
},
{
"deviceId": "unique_device_name_under_account",
"udId": "f6495f62-94f8-0ec2-c252-45626f82fcb2",
"geometryId": "1",
"distance": -999,
"nearestLat": 47.609833,
"nearestLon": -122.148274
}
],
"expiredGeofenceGeometryId": [
"5"
],
"invalidPeriodGeofenceGeometryId": [
"3",
"4"
],
"isEventPublished": true
}
定义
名称 | 说明 |
---|---|
Error |
资源管理错误附加信息。 |
Error |
错误详细信息。 |
Error |
错误响应 |
Geofence |
此对象是从地理围栏邻近调用返回的。 |
Geofence |
地理围栏几何图形。 |
Geofence |
地理围栏异步事件机制的模式。 |
Json |
响应的所需格式。 仅支持 |
ErrorAdditionalInfo
资源管理错误附加信息。
名称 | 类型 | 说明 |
---|---|---|
info |
object |
其他信息。 |
type |
string |
其他信息类型。 |
ErrorDetail
错误详细信息。
名称 | 类型 | 说明 |
---|---|---|
additionalInfo |
Error |
错误附加信息。 |
code |
string |
错误代码。 |
details |
Error |
错误详细信息。 |
message |
string |
错误消息。 |
target |
string |
错误目标。 |
ErrorResponse
错误响应
名称 | 类型 | 说明 |
---|---|---|
error |
Error |
错误对象。 |
Geofence
此对象是从地理围栏邻近调用返回的。
名称 | 类型 | 说明 |
---|---|---|
expiredGeofenceGeometryId |
string[] |
地理围栏的几何图形 ID 的Lists,该 ID 相对于请求中的用户时间过期。 |
geometries |
Geofence |
列出围栏几何图形,这些几何图形包含坐标位置,或者覆盖该位置周围的 searchBuffer。 |
invalidPeriodGeofenceGeometryId |
string[] |
地理围栏的几何图形 ID 的Lists,该地理围栏相对于请求中的用户时间处于无效时间段内。 |
isEventPublished |
boolean |
如果至少已将一个事件发布到 Azure Maps 事件订阅服务器,则为 true;如果未将任何事件发布到 Azure Maps 事件订阅服务器,则为 false。 仅当“isAsync”查询参数设置为 true 时,才会在响应中显示这一点。 |
GeofenceGeometry
地理围栏几何图形。
名称 | 类型 | 说明 |
---|---|---|
deviceId |
string |
设备的 ID。 |
distance |
number |
从坐标到地理围栏最近边框的距离 (米,除非) 使用特殊值 -999/999。 正值表示坐标在地理围栏的外部。 如果坐标在地理围栏外部,但大于 searchBuffer 与最近地理围栏边界之间的距离值,则该值为 999。 负值表示坐标在地理围栏的内部。 如果坐标在多边形的内部,但大于 searchBuffer 与最近地理围栏边界之间的距离值,则该值为 -999。 值 999 表示坐标位于地理围栏外部的置信度很高。 值 -999 表示坐标位于地理围栏内部的置信度很高。 |
geometryId |
string |
唯一 ID 标识几何图形。 |
nearestLat |
number |
最近几何图形点的纬度。 |
nearestLon |
number |
最近几何图形点的经度。 |
nearestZ |
number |
2D 延伸几何图形上最接近点的海平面(以米为单位)。 仅当请求中为“zInMeter”提供值时,才会在响应中显示此值。 |
udId |
string |
创建 数据注册表 以上传有效的 GeoJSON FeatureCollection 对象时使用的唯一 ID。 有关详细信息,请参阅 RFC 7946 。 特征的所有属性都应包含 |
GeofenceMode
地理围栏异步事件机制的模式。
名称 | 类型 | 说明 |
---|---|---|
All |
string |
将所有查询结果发布到Azure Maps帐户事件订阅。 |
EnterAndExit |
string |
仅当用户位置被视为交叉地理围栏板时发布结果。 |
JsonFormat
响应的所需格式。 仅支持 json
格式。
名称 | 类型 | 说明 |
---|---|---|
json |
string |