Spatial - Post Geofence

參考

Service:: Maps

API Version:: 2022-08-01

使用來取得地理柵欄座標的鄰近性。

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}

With optional parameters:

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 參數

名稱	位於	必要	類型	Description
format	path	True	JsonFormat	所需的回應格式。僅支援 `json` 格式。
geography	path	True	string	Azure 地圖服務帳戶的位置。有效值為 (美國東部、美國中西部、美國西部 2) 和歐盟 (北歐、西歐) 。在要求中提供時 `udid` ，需要此參數。例如，如果 Azure 地圖服務帳戶位於美國東部，則只會接受我們地理位置的要求。
api-version	query	True	string	Azure 地圖服務 API 的版本號碼。
deviceId	query	True	string	裝置的識別碼
lat	query	True	number	所傳遞位置的緯度。範例：48.36。
lon	query	True	number	所傳遞位置的經度。範例：-124.63。
isAsync	query		boolean	如果為 true，則要求會使用異步事件機制;如果為 false，則會同步處理要求，且不會觸發任何事件。預設值為 false。
mode	query		GeofenceMode	地理柵欄異步事件機制的模式。
searchBuffer	query		number	地理柵欄周圍地理柵欄的半徑，定義在計算結果時所提供座標的柵欄內外搜尋距離。最小值為 0，最大值為 500。預設值為 50。
userTime	query		string date-time	使用者要求時間。如果要求中未顯示，預設值為 DateTime.UtcNow。
z	query		number	所傳遞位置計量的海平面。如果呈現此參數，則會套用 2D 立體化地理柵欄。範例：200。

要求標頭

名稱	必要	類型	Description
x-ms-client-id		string	指定哪一個帳戶是搭配 Microsoft Entra ID 安全性模型使用。它代表 Azure 地圖服務帳戶的唯一標識符，可以從 Azure 地圖服務管理平面帳戶 API 擷取。若要在 Azure 地圖服務中使用 Microsoft Entra ID 安全性，請參閱下列文章以取得指引。

要求本文

名稱	必要	類型	Description
features	True	GeoJsonFeature[]	包含有效 `GeoJSON Feature` 對象的清單。
type	True	string: FeatureCollection	指定 `GeoJSON` 類型。必須是九個有效的 GeoJSON 物件類型之一 - Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature 和 FeatureCollection。

回應

名稱	類型	Description
200 OK	Geofence	確定異步呼叫的回應和 Event Grid 事件數據中存在 X-Correlation-id 標頭值。這有助於將異步呼叫的回應與對應的 Event Grid 事件相互關聯。 Headers X-Correlation-id: string
Other Status Codes	ErrorResponse	發生意外錯誤。

名稱

類型

Description

200 OK

Geofence

確定異步呼叫的回應和 Event Grid 事件數據中存在 X-Correlation-id 標頭值。這有助於將異步呼叫的回應與對應的 Event Grid 事件相互關聯。

Headers

X-Correlation-id: string

Other Status Codes

ErrorResponse

發生意外錯誤。

安全性

AADToken

這些是 Microsoft Entra OAuth 2.0 流程。與 Azure 角色型存取控制配對時，可用來控制對 REST API 的存取 Azure 地圖服務。 Azure 角色型訪問控制可用來指定一或多個 Azure 地圖服務資源帳戶或子資源的存取權。任何使用者、群組或服務主體都可以透過內建角色或由一或多個許可權組成的自定義角色來授與存取權，以 Azure 地圖服務 REST API。

若要實作案例，建議您檢視驗證概念。總而言之，此安全性定義提供一個解決方案，可透過能夠針對特定 API 和範圍進行存取控制的物件，將應用程式模型化 () 。

備註

此安全性定義需要使用x-ms-client-id 標頭來指出應用程式要求存取權 Azure 地圖服務資源。這可以從地圖服務管理 API 取得。

Authorization URL專屬於 Azure 公用雲端實例。主權雲端具有唯一的授權 URL 和 Microsoft Entra ID 組態。 * 透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API，從 Azure 管理平面設定 Azure 角色型存取控制。 * Azure 地圖服務 Web SDK 的使用方式允許針對多個使用案例設定應用程式的組態型設定。

如需 Microsoft 身分識別平台的詳細資訊，請參閱 Microsoft 身分識別平台概觀。

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

名稱	Description
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

這是透過 Azure 管理平面透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API 建立 Azure 地圖服務資源時所佈建的共用密鑰。

使用此金鑰時，任何應用程式都會獲得存取所有 REST API 的授權。換句話說，這些目前可視為發行帳戶的主要密鑰。

對於公開的應用程式，我們建議使用可安全地儲存此密鑰之 Azure 地圖服務 REST API 的伺服器對伺服器存取。

Type: apiKey
In: header

SAS Token

這是透過 Azure 管理平面透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API，從 Azure 地圖服務資源上的清單 SAS 作業建立共用存取簽章令牌。

使用此令牌時，任何應用程式都有權使用 Azure 角色型訪問控制進行存取，並精細控制到期、速率和區域 (特定令牌的使用) 。換句話說，SAS 令牌可用來允許應用程式以比共用密鑰更安全的方式控制存取。

對於公開的應用程式，我們建議在地圖帳戶資源上設定允許的來源特定清單，以限制轉譯濫用，並定期更新 SAS 令牌。

Type: apiKey
In: header

範例

PostGeofence

Sample Request

HTTP

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

Sample Response

Status code:: 200

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

定義

名稱	Description
ErrorAdditionalInfo	資源管理錯誤其他資訊。
ErrorDetail	錯誤詳細數據。
ErrorResponse	錯誤回應
Geofence	此物件會從地理柵欄鄰近呼叫傳回。
GeofenceGeometry	地理柵欄幾何。
GeofenceMode	地理柵欄異步事件機制的模式。
GeoJsonFeature	有效的 `GeoJSON Feature` 物件類型。如需詳細資訊，請參閱 RFC 7946 。
GeoJsonFeatureCollection	有效的 `GeoJSON FeatureCollection` 物件類型。如需詳細資訊，請參閱 RFC 7946 。
GeoJsonGeometry	有效的 `GeoJSON` geometry 物件。此類型必須是七個有效 GeoJSON 幾何類型的其中一個 -Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon 和 GeometryCollection。如需詳細資訊，請參閱 RFC 7946 。
GeoJsonGeometryCollection	有效的 `GeoJSON GeometryCollection` 物件類型。如需詳細資訊，請參閱 RFC 7946 。
GeoJsonLineString	有效的 `GeoJSON LineString` 幾何類型。如需詳細資訊，請參閱 RFC 7946 。
GeoJsonMultiLineString	有效的 `GeoJSON MultiLineString` 幾何類型。如需詳細資訊，請參閱 RFC 7946 。
GeoJsonMultiPoint	有效的 `GeoJSON MultiPoint` 幾何類型。如需詳細資訊，請參閱 RFC 7946 。
GeoJsonMultiPolygon	有效的 `GeoJSON MultiPolygon` 物件類型。如需詳細資訊，請參閱 RFC 7946 。
GeoJsonPoint	有效的 `GeoJSON Point` 幾何類型。如需詳細資訊，請參閱 RFC 7946 。
GeoJsonPolygon	有效的 `GeoJSON Polygon` 幾何類型。如需詳細資訊，請參閱 RFC 7946 。
JsonFormat	所需的回應格式。僅支援 `json` 格式。

ErrorAdditionalInfo

資源管理錯誤其他資訊。

名稱	類型	Description
info	object	其他資訊。
type	string	其他信息類型。

ErrorDetail

錯誤詳細數據。

名稱	類型	Description
additionalInfo	ErrorAdditionalInfo[]	錯誤其他資訊。
code	string	錯誤碼。
details	ErrorDetail[]	錯誤詳細資料。
message	string	錯誤訊息。
target	string	錯誤目標。

ErrorResponse

錯誤回應

名稱	類型	Description
error	ErrorDetail	錯誤物件。

Geofence

此物件會從地理柵欄鄰近呼叫傳回。

名稱	類型	Description
expiredGeofenceGeometryId	string[]	清單地理柵欄的幾何標識符，該地理柵欄相對於要求中的用戶時間到期。
geometries	GeofenceGeometry[]	列出包含該座標位置或在該位置與 searchBuffer 周圍重疊的柵欄幾何。
invalidPeriodGeofenceGeometryId	string[]	清單地理柵欄的幾何標識碼，此標識碼在與要求中的用戶時間相對無效的期間內。
isEventPublished	boolean	如果至少有一個事件發佈到 Azure 地圖服務事件訂閱者，則為 True。如果沒有事件發佈到 Azure 地圖服務事件訂閱者，則為 False。只有在 'isAsync' 查詢參數設定為 true 時，才會在響應中顯示。

GeofenceGeometry

地理柵欄幾何。

名稱	類型	Description
deviceId	string	裝置的識別碼。
distance	number	除了) 使用特殊值 -999/999 以外，從座標到地理柵欄最接近的邊界 (距離。正值表示座標在地理柵欄外。如果座標位在地理柵欄外，但與地理柵欄邊界的最短距離超過 searchBuffer 的值，則該值為 999。負數表示座標在地理柵欄內。如果座標位在多邊形內，但與地理柵欄邊界的最短距離超過 searchBuffer 的值，則該值為 -999。值為 999 表示座標在地理柵欄外是極可信的。值為 -999 表示座標在地理柵欄內是極可信的。
geometryId	string	唯一標識碼會識別幾何。
nearestLat	number	幾何之最接近點的緯度。
nearestLon	number	幾何之最接近點的經度。
nearestZ	number	2D 立體化幾何上最接近點的海層。只有在要求中為『zInMeter』提供值時，才會顯示此項目回應。
udId	string	建立數據登錄以上傳有效 GeoJSON FeatureCollection 物件時所使用的唯一標識符。如需詳細資訊，請參閱 RFC 7946 。所有特徵的屬性都應該包含 `geometryId`，用於識別幾何且區分大小寫。如需數據登錄服務的詳細資訊，請參閱如何建立數據登錄。

GeofenceMode

地理柵欄異步事件機制的模式。

名稱	類型	Description
All	string	將所有查詢結果發佈至 Azure 地圖服務帳戶事件訂用帳戶。
EnterAndExit	string	只有在使用者位置被視為跨越地理柵欄面板時發佈結果。

GeoJsonFeature

有效的 GeoJSON Feature 物件類型。如需詳細資訊，請參閱 RFC 7946 。

名稱	類型	Description
featureType	string	功能的類型。值取決於目前功能所屬的數據模型。某些數據模型可能會有空的值。
geometry	GeoJsonGeometry: GeoJsonGeometryCollection GeoJsonLineString GeoJsonMultiLineString GeoJsonMultiPoint GeoJsonMultiPolygon GeoJsonPoint GeoJsonPolygon	有效的 `GeoJSON` geometry 物件。此類型必須是七個有效 GeoJSON 幾何類型的其中一個 -Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon 和 GeometryCollection。如需詳細資訊，請參閱 RFC 7946 。
id	string	功能的標識碼。
type	string: Feature	指定 `GeoJSON` 類型。必須是九個有效 GeoJSON 物件類型的其中一種： Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature 和 FeatureCollection。

GeoJsonFeatureCollection

有效的 GeoJSON FeatureCollection 物件類型。如需詳細資訊，請參閱 RFC 7946 。

名稱	類型	Description
features	GeoJsonFeature[]	包含有效 `GeoJSON Feature` 對象的清單。
type	string: FeatureCollection	指定 `GeoJSON` 類型。必須是九個有效 GeoJSON 物件類型的其中一種： Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature 和 FeatureCollection。

GeoJsonGeometry

有效的 GeoJSON geometry 物件。此類型必須是七個有效 GeoJSON 幾何類型的其中一個 -Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon 和 GeometryCollection。如需詳細資訊，請參閱 RFC 7946 。

名稱	類型	Description
type	GeoJsonObjectType	指定 `GeoJSON` 類型。必須是九個有效 GeoJSON 物件類型的其中一種： Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature 和 FeatureCollection。

GeoJsonGeometryCollection

有效的 GeoJSON GeometryCollection 物件類型。如需詳細資訊，請參閱 RFC 7946 。

名稱	類型	Description
geometries	GeoJsonGeometry[]: GeoJsonGeometryCollection[] GeoJsonLineString[] GeoJsonMultiLineString[] GeoJsonMultiPoint[] GeoJsonMultiPolygon[] GeoJsonPoint[] GeoJsonPolygon[]	包含有效 `GeoJSON` geometry 物件的清單。請注意，GeoJSON 中的座標以 x、y 順序 (經度、緯度) 。
type	string: GeometryCollection	指定 `GeoJSON` 類型。必須是九個有效 GeoJSON 物件類型的其中一種： Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature 和 FeatureCollection。

GeoJsonLineString

有效的 GeoJSON LineString 幾何類型。如需詳細資訊，請參閱 RFC 7946 。

名稱	類型	Description
coordinates	number[]	幾何的 `GeoJson LineString` 座標。
type	string: LineString	指定 `GeoJSON` 類型。必須是九個有效 GeoJSON 物件類型的其中一種： Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature 和 FeatureCollection。

GeoJsonMultiLineString

有效的 GeoJSON MultiLineString 幾何類型。如需詳細資訊，請參閱 RFC 7946 。

名稱	類型	Description
coordinates	number[]	幾何的 `GeoJson MultiLineString` 座標。
type	string: MultiLineString	指定 `GeoJSON` 類型。必須是九個有效 GeoJSON 物件類型的其中一種： Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature 和 FeatureCollection。

GeoJsonMultiPoint

有效的 GeoJSON MultiPoint 幾何類型。如需詳細資訊，請參閱 RFC 7946 。

名稱	類型	Description
coordinates	number[]	幾何的 `GeoJson MultiPoint` 座標。
type	string: MultiPoint	指定 `GeoJSON` 類型。必須是九個有效 GeoJSON 物件類型的其中一種： Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature 和 FeatureCollection。

GeoJsonMultiPolygon

有效的 GeoJSON MultiPolygon 物件類型。如需詳細資訊，請參閱 RFC 7946 。

名稱	類型	Description
coordinates	number[]	包含有效 `GeoJSON Polygon` 對象的清單。請注意，GeoJSON 中的座標以 x、y 順序 (經度、緯度) 。
type	string: MultiPolygon	指定 `GeoJSON` 類型。必須是九個有效 GeoJSON 物件類型的其中一種： Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature 和 FeatureCollection。

GeoJsonPoint

有效的 GeoJSON Point 幾何類型。如需詳細資訊，請參閱 RFC 7946 。

名稱	類型	Description
coordinates	number[]	`Position`是具有兩個或多個元素的數位數位數位數位。前兩個元素是經度和緯度，精確地以該順序排列。高度/提高許可權是選擇性的第三個元素。如需詳細資訊，請參閱 RFC 7946 。
type	string: Point	指定 `GeoJSON` 類型。必須是九個有效 GeoJSON 物件類型的其中一種： Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature 和 FeatureCollection。

GeoJsonPolygon

有效的 GeoJSON Polygon 幾何類型。如需詳細資訊，請參閱 RFC 7946 。

名稱	類型	Description
coordinates	number[]	`GeoJson Polygon`幾何類型的座標。
type	string: Polygon	指定 `GeoJSON` 類型。必須是九個有效 GeoJSON 物件類型的其中一種： Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature 和 FeatureCollection。

JsonFormat

所需的回應格式。僅支援 json 格式。

名稱	類型	Description
json	string	JavaScript 物件表示法數據交換格式

Spatial - Post Geofence

URI 參數

要求標頭

要求本文

回應

安全性

AADToken

備註

Scopes

subscription-key

SAS Token

範例

PostGeofence

Sample Request

Sample Response

定義

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

Geofence

GeofenceGeometry

GeofenceMode

GeoJsonFeature

GeoJsonFeatureCollection

GeoJsonGeometry

GeoJsonGeometryCollection

GeoJsonLineString

GeoJsonMultiLineString

GeoJsonMultiPoint

GeoJsonMultiPolygon

GeoJsonPoint

GeoJsonPolygon

JsonFormat

其他資源