Spatial - Get Geofence

座標とジオフェンスの近接度を取得するには、 を使用します。

Get Geofence API は、データ レジストリにアップロードされたジオフェンスへの座標の近接性を取得する HTTP GET 要求です。 ジオフェンスまたはフェンスのセットを Azure ストレージ アカウントにアップロードし、 データ レジストリを使用して Azure Maps アカウントに登録します。詳細については、「 データ レジストリを作成する方法」を参照してください。 ジオフェンス データ形式の詳細については、「 GeoJSON データのジオフェンシング」を参照してください。 座標の近接性を照会するには、追跡するオブジェクトの位置と、フェンスまたはフェンスのセットの ID を指定します。応答にはジオフェンスの外側の端からの距離に関する情報が含まれます。 負の値は、座標がフェンスの内側にあることを示し、正の値はフェンスの外側にあることを意味します。

この API は、資産の追跡、フリート管理、オブジェクトの移動に関するアラートの設定など、さまざまなシナリオに使用できます。

この API では、 Event Grid との統合がサポートされています。 isAsync パラメーターは、Event Grid との統合を有効にするために使用されます (既定では無効)。 この API をテストするには、Data レジストリ サービスを使用して Post Geofence API の例 (要求本文) からサンプル データをアップロードし、以下udidのサンプル要求の を{udid}データ レジストリの作成に使用した に置き換えます。 データ レジストリ サービスの詳細については、「データ レジストリ を作成する方法」を参照してください。

ジオフェンシングの InnerError コード

ジオフェンシング応答エラー コントラクトでは、 は、 innererror エラーに関するサービス固有の情報を含むオブジェクトです。 code は、特定の innererror ジオフェンシング エラーの種類にマップできるプロパティです。 次の表は、既知のすべてのクライアント エラーの種類と対応するジオフェンシング エラー messageとの間のコード マッピングを示しています。

innererror.code error.message
NullDeviceId デバイス ID を null にすることはできません。
NullUdid Udid を null にすることはできません。
UdidWrongFormat Udid は、ユーザー データ インジェスト API から取得する必要があります。
InvalidUserTime Usertime が無効です。
InvalidSearchBuffer Searchbuffer が無効です。
InvalidSearchRange searchbuffer の値の範囲は 0 ~ 500 m である必要があります。
InvalidLatLon Lat パラメーターまたは lon パラメーターが無効です。
InvalidIsAsyncValue IsAsync パラメーターが無効です。
InvalidModeValue mode パラメーターが無効です。
InvalidJson ジオフェンス データは有効な json ファイルではありません。
NotSupportedGeoJson ジオフェンス データは、Feature または FeatureCollections として読み取ることはできません。
InvalidGeoJson ジオフェンス データが無効です。
NoUserDataWithAccountOrSubscription 指定されたアカウント ID またはサブスクリプション 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

JsonFormat

応答の目的の形式。 サポートされているのは json 形式のみです。

geography
path True

string

Azure Maps アカウントの場所。 有効な値は、us (米国東部、米国中西部、米国西部 2) と eu (北ヨーロッパ、西ヨーロッパ) です。 このパラメーターは、 が要求で指定されている場合 udid に必要です。 たとえば、Azure Maps アカウントが米国東部にある場合、地理に対する要求のみが受け付けられます。

api-version
query True

string

Azure Maps API のバージョン番号。

deviceId
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 を参照してください。 フィーチャのすべてのプロパティに を含める 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。

要求ヘッダー

名前 必須 説明
x-ms-client-id

string

Microsoft Entra ID セキュリティ モデルと組み合わせて使用するアカウントを指定します。 これは Azure Maps アカウントの一意の ID を表し、Azure Maps 管理プレーン アカウント API から取得できます。 Azure Maps で Microsoft Entra ID セキュリティを使用するには、ガイダンスについては、次 の記事を 参照してください。

応答

名前 説明
200 OK

Geofence

OK X-Correlation-id ヘッダー値は、非同期呼び出しの応答と Event Grid イベント データに存在します。 非同期呼び出しの応答を対応する Event Grid イベントと関連付けるのに役立ちます。

ヘッダー

X-Correlation-id: string

Other Status Codes

ErrorResponse

予期しないエラーが発生しました。

セキュリティ

AADToken

これらは Microsoft Entra OAuth 2.0 フローです。 Azure ロールベースのアクセス制御と組み合わせて使用すると、Azure Maps REST API へのアクセスを制御できます。 Azure ロールベースのアクセス制御は、1 つ以上の Azure Maps リソース アカウントまたはサブリソースへのアクセスを指定するために使用されます。 Azure Maps REST API に対する 1 つ以上のアクセス許可で構成される組み込みロールまたはカスタム ロールを使用して、任意のユーザー、グループ、またはサービス プリンシパルにアクセス権を付与できます。

シナリオを実装するには、 認証の概念を表示することをお勧めします。 要約すると、このセキュリティ定義は、特定の API とスコープに対するアクセス制御が可能なオブジェクトを使用してアプリケーションをモデル化するためのソリューションを提供します。

メモ

  • このセキュリティ定義 では 、 ヘッダーを x-ms-client-id 使用して、アプリケーションがアクセスを要求している Azure Maps リソースを示す必要があります。 これは、 Maps 管理 API から取得できます。

Authorization URLは、Azure パブリック クラウド インスタンスに固有です。 ソブリン クラウドには、一意の承認 URL と Microsoft Entra ID 構成があります。 * Azure ロールベースのアクセス制御は、Azure portal、PowerShell、CLI、Azure SDK、または REST API を介して Azure 管理プレーン から構成されます。 * Azure Maps Web SDK を使用すると、複数のユース ケースに対するアプリケーションの構成ベースのセットアップが可能になります。

型: oauth2
フロー: implicit
Authorization URL (承認 URL): https://login.microsoftonline.com/common/oauth2/authorize

スコープ

名前 説明
https://atlas.microsoft.com/.default https://atlas.microsoft.com/.default

subscription-key

これは、Azure portal、PowerShell、CLI、Azure SDK、または REST API を使用して Azure 管理プレーンを介して Azure Maps リソース を作成するときにプロビジョニングされる共有キーです。

このキーを使用すると、すべてのアプリケーションがすべての REST API にアクセスする権限が与えられている。 つまり、これらは現在、発行先のアカウントのマスター キーとして扱うことができます。

公開されているアプリケーションの場合、このキーを安全に格納できる Azure Maps REST API のサーバー間アクセスを使用することをお勧めします。

型: apiKey
/: header

SAS Token

これは、Azure portal、PowerShell、CLI、Azure SDK、または REST API を使用して、Azure 管理プレーンを介して Azure Maps リソース の SAS の一覧表示操作から作成される共有アクセス署名トークンです。

このトークンを使用すると、すべてのアプリケーションが Azure ロールベースのアクセス制御を使用してアクセスし、特定のトークンに使用される有効期限、レート、およびリージョンをきめ細かく制御できます。 つまり、SAS トークンを使用して、アプリケーションが共有キーよりもセキュリティで保護された方法でアクセスを制御できるようにします。

公開されているアプリケーションの場合、 Map アカウント リソース で許可される配信元の特定の一覧を構成して、レンダリングの不正使用を制限し、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 形式のみです。

ErrorAdditionalInfo

リソース管理エラーの追加情報。

名前 説明
info

object

追加情報。

type

string

追加情報の種類。

ErrorDetail

エラーの詳細。

名前 説明
additionalInfo

ErrorAdditionalInfo[]

エラーの追加情報。

code

string

エラー コード。

details

ErrorDetail[]

エラーの詳細です。

message

string

エラー メッセージ。

target

string

エラーのターゲット。

ErrorResponse

エラー応答

名前 説明
error

ErrorDetail

error オブジェクト。

Geofence

このオブジェクトは、ジオフェンス近接呼び出しから返されます。

名前 説明
expiredGeofenceGeometryId

string[]

要求のユーザー時間を基準にして有効期限が切れたジオフェンスのジオメトリ ID の一覧。

geometries

GeofenceGeometry[]

座標が含まれるフェンス ジオメトリ、または位置の周りに searchBuffer が重なっているフェンス ジオメトリの一覧を示します。

invalidPeriodGeofenceGeometryId

string[]

要求のユーザー時間に対して無効な期間にあるジオフェンスのジオメトリ ID の一覧。

isEventPublished

boolean

Azure Maps イベント サブスクライバーに対して少なくとも 1 つのイベントが発行されている場合は 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 を参照してください。 フィーチャのすべてのプロパティには、 が含まれている geometryId必要があります。これはジオメトリを識別するために使用され、大文字と小文字が区別されます。 データ レジストリ サービスの詳細については、「データ レジストリ を作成する方法」を参照してください。

GeofenceMode

ジオフェンシング非同期イベント メカニズムのモード。

名前 説明
All

string

すべてのクエリ結果を Azure Maps アカウント イベント サブスクリプションに発行します。

EnterAndExit

string

ユーザーの場所が交差ジオフェンシング ボーダーと見なされる場合にのみ、結果を公開します。

JsonFormat

応答の目的の形式。 サポートされているのは json 形式のみです。

名前 説明
json

string

JavaScript オブジェクト表記データ交換形式