Spatial - Get Geofence

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

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

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

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

地理柵欄 InnerError 程式代碼

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

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

要求標頭

回應

安全性

AADToken

這些是 Microsoft Entra OAuth 2.0 流程。 與 Azure 角色型存取控制 配對時，可用來控制 Azure 地圖服務 REST API 的存取。 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身分識別平臺概觀。

類型: oauth2
Flow: implicit
授權 URL: https://login.microsoftonline.com/common/oauth2/authorize

範圍

subscription-key

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

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

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

類型: apiKey
位於: header

SAS Token

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

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

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

類型: apiKey
位於: header

範例

GetGeofence

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

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

定義

ErrorAdditionalInfo

資源管理錯誤其他資訊。

ErrorDetail

錯誤詳細數據。

ErrorResponse

錯誤回應

Geofence

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

GeofenceGeometry

地理柵欄幾何。

GeofenceMode

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

JsonFormat

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