你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
Spatial - Post Geofence
使用 获取坐标与地理围栏的邻近度。
Post Geofence
API 是一个 HTTP POST
请求,用于检索坐标与提供的地理围栏或围栏集的邻近度。 使用 POST
请求时,无需提前上传围栏数据,而是在查询参数中提供要跟踪的对象的位置,并在发布请求正文中提供围栏或围栏数据集。 有关地理围栏数据格式的详细信息,请参阅 地理围栏 GeoJSON 数据。 响应将包含有关与地理围栏外边缘的距离的信息。 负值表示坐标在围栏内,而正值表示坐标在围栏之外。
此 API 可用于各种方案,包括资产跟踪、车队管理或设置移动对象的警报。
API 支持 与事件网格集成。 isAsync 参数用于启用与事件网格的集成, (默认) 禁用。
POST https://{geography}.atlas.microsoft.com/spatial/geofence/json?api-version=2022-08-01&deviceId={deviceId}&lat={lat}&lon={lon}
POST https://{geography}.atlas.microsoft.com/spatial/geofence/json?api-version=2022-08-01&deviceId={deviceId}&lat={lat}&lon={lon}&z={z}&userTime={userTime}&searchBuffer={searchBuffer}&isAsync={isAsync}&mode={mode}
URI 参数
名称 | 在 | 必需 | 类型 | 说明 |
---|---|---|---|---|
format
|
path | True |
响应的所需格式。 仅支持 |
|
geography
|
path | True |
string |
Azure Maps 帐户的位置。 有效值为 us (美国东部、美国中西部、美国西部 2) 和 eu (North Europe、West Europe) 。 在请求中提供 时 |
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。 |
is
|
query |
boolean |
如果为 true,则请求将使用异步事件机制;如果为 false,则请求将同步,并且不会触发任何事件。 默认值为 false。 |
|
mode
|
query |
地理围栏异步事件机制的模式。 |
||
search
|
query |
number |
地理围栏周围缓冲区的半径(以米为单位,用于定义根据计算结果时提供的坐标在围栏边界内外搜索的距离)。 最小值为 0,最大值为 500。 默认值为 50。 |
|
user
|
query |
string date-time |
用户请求时间。 如果请求中未显示,则默认值为 DateTime.UtcNow。 |
|
z
|
query |
number |
所经过位置的海平面(以米为单位)。 如果显示此参数,则应用 2D 延伸地理围栏。 示例:200。 |
请求头
名称 | 必需 | 类型 | 说明 |
---|---|---|---|
x-ms-client-id |
string |
指定用于与 Microsoft Entra ID 安全模型结合使用的帐户。 它表示 Azure Maps 帐户的唯一 ID,可从 Azure Maps 管理平面帐户 API 检索。 若要在 Azure Maps 中使用 Microsoft Entra ID 安全性,请参阅以下 文章 以获取指导。 |
请求正文
名称 | 必需 | 类型 | 说明 |
---|---|---|---|
features | True |
包含有效 |
|
type | True |
string:
Feature |
指定 |
响应
名称 | 类型 | 说明 |
---|---|---|
200 OK |
OK:X-Correlation-id 标头值存在于异步调用的响应和事件网格事件数据中。 它有助于将异步调用的响应与相应的事件网格事件相关联。 标头 X-Correlation-id: string |
|
Other Status Codes |
发生了意外错误。 |
安全性
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标识平台概述。
类型:
oauth2
流向:
implicit
授权 URL:
https://login.microsoftonline.com/common/oauth2/authorize
作用域
名称 | 说明 |
---|---|
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 的服务器到服务器访问,以便安全地存储此密钥。
类型:
apiKey
在:
header
SAS Token
这是通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API 通过 Azure 管理平面通过 Azure Maps 资源 上的列出 SAS 操作创建的共享访问签名令牌。
使用此令牌,任何应用程序都有权使用 Azure 基于角色的访问控制进行访问,并精细控制特定令牌的过期、速率和区域 () 。 换句话说,SAS 令牌可用于允许应用程序以比共享密钥更安全的方式控制访问。
对于公开的应用程序,我们建议在 Map 帐户资源 上配置允许的来源的特定列表,以限制呈现滥用,并定期续订 SAS 令牌。
类型:
apiKey
在:
header
示例
PostGeofence
示例请求
POST https://us.atlas.microsoft.com/spatial/geofence/json?api-version=2022-08-01&deviceId=unique_device_name_under_account&lat=48.36&lon=-124.63&userTime={userTime}&searchBuffer=50&isAsync=True&mode=EnterAndExit
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-122.13241226662022,
47.61701140091722
],
[
-122.12810106940353,
47.6169969269402
],
[
-122.12824948956276,
47.61907683751349
],
[
-122.12833297981392,
47.621929787055336
],
[
-122.12971398040168,
47.62184100705295
],
[
-122.1318413862121,
47.62195364373008
],
[
-122.13231034769727,
47.61716332618121
],
[
-122.13241226662022,
47.61701140091722
]
]
]
},
"properties": {
"geometryId": "2",
"name": "Crossroad Mall"
}
},
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-122.1534220563239,
47.60981818546625
],
[
-122.153451623509,
47.60628733146004
],
[
-122.14971782206638,
47.606250040787046
],
[
-122.14817354810637,
47.606391046012305
],
[
-122.1482735128807,
47.60983316796356
],
[
-122.15225500989803,
47.60982613678752
],
[
-122.1534220563239,
47.60981818546625
]
]
]
},
"properties": {
"geometryId": "1",
"name": "Sammamish High school"
}
}
]
}
示例响应
{
"geometries": [
{
"deviceId": "unique_device_name_under_account",
"geometryId": "2",
"distance": -999,
"nearestLat": 47.621954,
"nearestLon": -122.131841
},
{
"deviceId": "unique_device_name_under_account",
"geometryId": "1",
"distance": 999,
"nearestLat": 47.609833,
"nearestLon": -122.148274
}
],
"expiredGeofenceGeometryId": [],
"invalidPeriodGeofenceGeometryId": [],
"isEventPublished": true
}
定义
名称 | 说明 |
---|---|
Error |
资源管理错误附加信息。 |
Error |
错误详细信息。 |
Error |
错误响应 |
Geofence |
此对象是从地理围栏邻近调用返回的。 |
Geofence |
地理围栏几何图形。 |
Geofence |
地理围栏异步事件机制的模式。 |
Geo |
有效的 |
Geo |
有效的 |
Geo |
有效的 |
Geo |
有效的 |
Geo |
有效的 |
Geo |
有效的 |
Geo |
有效的 |
Geo |
有效的 |
Geo |
有效的 |
Geo |
有效的 |
Json |
响应的所需格式。 仅支持 |
ErrorAdditionalInfo
资源管理错误附加信息。
名称 | 类型 | 说明 |
---|---|---|
info |
object |
其他信息。 |
type |
string |
其他信息类型。 |
ErrorDetail
错误详细信息。
名称 | 类型 | 说明 |
---|---|---|
additionalInfo |
错误附加信息。 |
|
code |
string |
错误代码。 |
details |
错误详细信息。 |
|
message |
string |
错误消息。 |
target |
string |
错误目标。 |
ErrorResponse
错误响应
名称 | 类型 | 说明 |
---|---|---|
error |
错误对象。 |
Geofence
此对象是从地理围栏邻近调用返回的。
名称 | 类型 | 说明 |
---|---|---|
expiredGeofenceGeometryId |
string[] |
相对于请求中的用户时间过期的地理围栏几何图形 ID 的列表。 |
geometries |
列出围栏几何图形,这些几何图形包含坐标位置,或者覆盖该位置周围的 searchBuffer。 |
|
invalidPeriodGeofenceGeometryId |
string[] |
地理围栏的几何图形 ID 列表,该地理围栏相对于请求中的用户时间处于无效时间段。 |
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 |
仅当用户位置被视为交叉地理围栏板时发布结果。 |
GeoJsonFeature
有效的 GeoJSON Feature
对象类型。 有关详细信息,请参阅 RFC 7946 。
名称 | 类型 | 说明 |
---|---|---|
featureType |
string |
功能的类型。 该值取决于当前特征所属的数据模型。 某些数据模型可能具有空值。 |
geometry | GeoJsonGeometry: |
有效的 |
id |
string |
功能的标识符。 |
type |
string:
Feature |
指定 |
GeoJsonFeatureCollection
有效的 GeoJSON FeatureCollection
对象类型。 有关详细信息,请参阅 RFC 7946 。
名称 | 类型 | 说明 |
---|---|---|
features |
包含有效 |
|
type |
string:
Feature |
指定 |
GeoJsonGeometry
有效的 GeoJSON
geometry 对象。 类型必须是七种有效的 GeoJSON 几何类型之一 - Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon 和 GeometryCollection。 有关详细信息,请参阅 RFC 7946 。
名称 | 类型 | 说明 |
---|---|---|
type |
Geo |
指定 |
GeoJsonGeometryCollection
有效的 GeoJSON GeometryCollection
对象类型。 有关详细信息,请参阅 RFC 7946 。
名称 | 类型 | 说明 |
---|---|---|
geometries | GeoJsonGeometry[]: |
包含有效 |
type |
string:
Geometry |
指定 |
GeoJsonLineString
有效的 GeoJSON LineString
几何类型。 有关详细信息,请参阅 RFC 7946 。
名称 | 类型 | 说明 |
---|---|---|
coordinates |
number[] |
几何图形的 |
type |
string:
Line |
指定 |
GeoJsonMultiLineString
有效的 GeoJSON MultiLineString
几何类型。 有关详细信息,请参阅 RFC 7946 。
名称 | 类型 | 说明 |
---|---|---|
coordinates |
number[] |
几何图形的 |
type |
string:
Multi |
指定 |
GeoJsonMultiPoint
有效的 GeoJSON MultiPoint
几何类型。 有关详细信息,请参阅 RFC 7946 。
名称 | 类型 | 说明 |
---|---|---|
coordinates |
number[] |
几何图形的 |
type |
string:
Multi |
指定 |
GeoJsonMultiPolygon
有效的 GeoJSON MultiPolygon
对象类型。 有关详细信息,请参阅 RFC 7946 。
名称 | 类型 | 说明 |
---|---|---|
coordinates |
number[] |
包含有效 |
type |
string:
Multi |
指定 |
GeoJsonPoint
有效的 GeoJSON Point
几何类型。 有关详细信息,请参阅 RFC 7946 。
名称 | 类型 | 说明 |
---|---|---|
coordinates |
number[] |
是 |
type |
string:
Point |
指定 |
GeoJsonPolygon
有效的 GeoJSON Polygon
几何类型。 有关详细信息,请参阅 RFC 7946 。
名称 | 类型 | 说明 |
---|---|---|
coordinates |
number[] |
|
type |
string:
Polygon |
指定 |
JsonFormat
响应的所需格式。 仅支持 json
格式。
名称 | 类型 | 说明 |
---|---|---|
json |
string |