Spatial - Get Geofence

リファレンス

サービス:: Maps

API バージョン:: 2022-08-01

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

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	予期しないエラーが発生しました。

名前

型

説明

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 を使用すると、複数のユースケースに対するアプリケーションの構成ベースのセットアップが可能になります。

Microsoft ID プラットフォームの詳細については、「 Microsoft ID プラットフォームの概要」を参照してください。

型: 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

要求のサンプル

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

応答のサンプル

状態コード:: 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
}

定義

名前	説明
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 オブジェクト表記データ交換形式

次の方法で共有

Spatial - Get Geofence

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

URI パラメーター

要求ヘッダー

応答

セキュリティ

AADToken

メモ

スコープ

subscription-key

SAS Token

例

GetGeofence

要求のサンプル

応答のサンプル

定義

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

Geofence

GeofenceGeometry

GeofenceMode

JsonFormat

その他のリソース