Spatial - Get Geofence

參考

Service:: Maps

API Version:: 2022-08-01

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

Get Geofence API 是 HTTP GET 要求，可擷取已上傳至數據登錄之地理柵欄的座標鄰近性。您將地理柵欄或一組柵欄上傳至 Azure 記憶體帳戶，然後使用數據登錄向您的 Azure 地圖服務帳戶註冊，以取得詳細資訊，請參閱如何建立數據登錄。如需地理柵欄數據格式的詳細資訊，請參閱地理柵欄 GeoJSON 數據。若要查詢座標的鄰近性，您可以提供您要追蹤的物件位置，以及柵欄或一組柵欄的標識碼，而回應會包含地理柵欄外緣距離的相關信息。負值表示座標位於柵欄內部，而正值表示它位於柵欄之外。

此 API 可用於各種案例，包括資產追蹤、車隊管理，或設定行動物件的警示。

API 支援與事件方格整合。 isAsync 參數可用來啟用預設停用與事件方格的整合 () 。若要測試此 API，您可以從 Post Geofence API 範例上傳範例數據， (使用資料登入服務) 要求本文，並使用用來建立資料登錄的取代 {udid} 來自下列 udid 範例要求的。如需數據登錄服務的詳細資訊，請參閱如何建立數據登錄。

地理柵欄 InnerError 程式代碼

在地理柵欄回應錯誤合約中， innererror 是包含有關錯誤之服務特定信息的物件。 code 是屬性 innererror ，可以對應至特定的地理柵欄錯誤類型。下表顯示所有已知用戶端錯誤類型與對應地理柵欄錯誤 message之間的程式碼對應。

innererror.code	error.message
NullDeviceId	裝置標識碼不應為 Null。
NullUdid	Udid 不應該為 null。
UdidWrongFormat	應該從用戶數據擷取 API 取得 Udid。
InvalidUserTime	Usertime 無效。
InvalidSearchBuffer	Searchbuffer 無效。
InvalidSearchRange	搜尋緩衝區的值範圍應從 0 到 500 公尺。
InvalidLatLon	Lat 和/或 lon 參數無效。
InvalidIsAsyncValue	IsAsync 參數無效。
InvalidModeValue	mode 參數無效。
InvalidJson	地理柵欄數據不是有效的 json 檔案。
NotSupportedGeoJson	地理柵欄數據無法讀取為功能或FeatureCollections。
InvalidGeoJson	地理柵欄數據無效。
NoUserDataWithAccountOrSubscription	找不到具有所提供帳戶標識碼和/或 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}

With optional parameters:

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

名稱	位於	必要	類型	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。
udid	query	True	string	建立數據登錄以上傳有效 GeoJSON FeatureCollection 物件時所使用的唯一標識符。如需詳細資訊，請參閱 RFC 7946 。所有特徵的屬性都應該包含 `geometryId`，用於識別幾何且區分大小寫。如需數據登錄服務的詳細資訊，請參閱如何建立數據登錄。
isAsync	query		boolean	如果為 true，則要求會使用異步事件機制;如果為 false，則會同步處理要求，且不會觸發任何事件。預設值為 false。
mode	query		GeofenceMode	地理柵欄異步事件機制的模式。
searchBuffer	query		number	以公尺為單位的地理柵欄周圍緩衝區半徑，定義要根據計算結果時所提供的座標，在柵欄的框線內和外部搜尋距離。最小值為 0，最大值為 500。預設值為 50。
userTime	query		string date-time	使用者要求時間。如果要求中未顯示，預設值為 DateTime.Now。
z	query		number	所傳遞位置的計量中的海道。如果呈現此參數，則會使用 2D 立體化。範例：200。

要求標頭

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

回應

名稱	類型	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 入口網站、PowerShell、CLI、Azure SDK 或 REST API，從 Azure 地圖服務資源上的列出 SAS 作業建立共用存取簽章令牌。

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

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

Type: apiKey
In: header

範例

GetGeofence

Sample Request

HTTP

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

Status code:: 200

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

定義

名稱	Description
ErrorAdditionalInfo	資源管理錯誤其他資訊。
ErrorDetail	錯誤詳細數據。
ErrorResponse	錯誤回應
Geofence	此物件會從地理柵欄鄰近呼叫傳回。
GeofenceGeometry	地理柵欄幾何。
GeofenceMode	地理柵欄異步事件機制的模式。
JsonFormat	所需的回應格式。僅支援 `json` 格式。

ErrorAdditionalInfo

資源管理錯誤其他資訊。

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

ErrorDetail

錯誤詳細數據。

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

ErrorResponse

錯誤回應

名稱	類型	Description
error	ErrorDetail	error 物件。

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 以外的特殊值 -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	只有在將使用者位置視為跨地理柵欄面板器時，才會發佈結果。

JsonFormat

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

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

Spatial - Get Geofence

地理柵欄 InnerError 程式代碼

URI 參數

要求標頭

回應

安全性

AADToken

備註

Scopes

subscription-key

SAS Token

範例

GetGeofence

Sample Request

Sample Response

定義

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

Geofence

GeofenceGeometry

GeofenceMode

JsonFormat

其他資源