Spatial - Post Geofence

リファレンス

サービス:: Maps

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

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

Post Geofence API は、指定されたジオフェンスまたはフェンスのセットに対する座標の近接性を取得する HTTP POST 要求です。要求では POST 、フェンスデータを事前にアップロードする必要はありません。代わりに、クエリパラメーターで追跡するオブジェクトの場所と、要求後の本文でフェンスまたはフェンスデータのセットを指定します。ジオフェンスデータ形式の詳細については、「 GeoJSON データのジオフェンス」を参照してください。応答には、ジオフェンスの外側の端からの距離に関する情報が含まれます。負の値は、座標がフェンスの内側にあることを意味し、正の値はフェンスの外側にあることを意味します。

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

この API では、 Event Grid との統合がサポートされています。 isAsync パラメーターは、Event Grid との統合を有効にするために使用されます (既定では無効)。

POST https://{geography}.atlas.microsoft.com/spatial/geofence/json?api-version=2022-08-01&deviceId={deviceId}&lat={lat}&lon={lon}

省略可能なパラメーターを含む:

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 パラメーター

名前	/	必須	型	説明
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。
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。

要求ヘッダー

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

要求本文

名前	必須	型	説明
features	True	GeoJsonFeature[]	有効な `GeoJSON Feature` オブジェクトの一覧を格納します。
type	True	string: FeatureCollection	型を指定します `GeoJSON` 。 Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature、FeatureCollection の 9 つの有効な GeoJSON オブジェクトの種類のいずれかである必要があります。

応答

名前	型	説明
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 リソースの List SAS 操作から作成される共有アクセス署名トークンです。

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

公開されているアプリケーションの場合、 Map アカウントリソースで許可される配信元の特定のリストを構成して、レンダリングの不正使用を制限し、SAS トークンを定期的に更新することをお勧めします。

型: apiKey
/: header

例

PostGeofence

要求のサンプル

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

応答のサンプル

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

定義

名前	説明
ErrorAdditionalInfo	リソース管理エラーの追加情報。
ErrorDetail	エラーの詳細。
ErrorResponse	エラー応答
Geofence	このオブジェクトは、ジオフェンス近接呼び出しから返されます。
GeofenceGeometry	ジオフェンシングジオメトリ。
GeofenceMode	ジオフェンシング非同期イベントメカニズムのモード。
GeoJsonFeature	有効な `GeoJSON Feature` オブジェクト型。詳細については、 RFC 7946 を参照してください。
GeoJsonFeatureCollection	有効な `GeoJSON FeatureCollection` オブジェクト型。詳細については、 RFC 7946 を参照してください。
GeoJsonGeometry	有効な `GeoJSON` geometry オブジェクト。この型は、有効な 7 つの GeoJSON ジオメトリ型 (Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection) のいずれかである必要があります。詳細については、 RFC 7946 を参照してください。
GeoJsonGeometryCollection	有効な `GeoJSON GeometryCollection` オブジェクト型。詳細については、 RFC 7946 を参照してください。
GeoJsonLineString	有効な `GeoJSON LineString` geometry 型。詳細については、 RFC 7946 を参照してください。
GeoJsonMultiLineString	有効な `GeoJSON MultiLineString` geometry 型。詳細については、 RFC 7946 を参照してください。
GeoJsonMultiPoint	有効な `GeoJSON MultiPoint` geometry 型。詳細については、 RFC 7946 を参照してください。
GeoJsonMultiPolygon	有効な `GeoJSON MultiPolygon` オブジェクト型。詳細については、 RFC 7946 を参照してください。
GeoJsonPoint	有効な `GeoJSON Point` geometry 型。詳細については、 RFC 7946 を参照してください。
GeoJsonPolygon	有効な `GeoJSON Polygon` geometry 型。詳細については、 RFC 7946 を参照してください。
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	ユーザーの場所が交差ジオフェンシングボーダーと見なされる場合にのみ、結果を公開します。

GeoJsonFeature

有効な GeoJSON Feature オブジェクト型。詳細については、 RFC 7946 を参照してください。

名前	型	説明
featureType	string	機能の種類です。値は、現在の特徴が含まれるデータモデルによって異なります。一部のデータモデルには空の値が含まれる場合があります。
geometry	GeoJsonGeometry: GeoJsonGeometryCollection GeoJsonLineString GeoJsonMultiLineString GeoJsonMultiPoint GeoJsonMultiPolygon GeoJsonPoint GeoJsonPolygon	有効な `GeoJSON` geometry オブジェクト。この型は、有効な 7 つの GeoJSON ジオメトリ型 (Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection) のいずれかである必要があります。詳細については、 RFC 7946 を参照してください。
id	string	機能の識別子。
type	string: Feature	型を指定します `GeoJSON` 。 Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature、FeatureCollection の 9 つの有効な GeoJSON オブジェクトタイプのいずれかである必要があります。

GeoJsonFeatureCollection

有効な GeoJSON FeatureCollection オブジェクト型。詳細については、 RFC 7946 を参照してください。

名前	型	説明
features	GeoJsonFeature[]	有効な `GeoJSON Feature` オブジェクトの一覧を格納します。
type	string: FeatureCollection	型を指定します `GeoJSON` 。 Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature、FeatureCollection の 9 つの有効な GeoJSON オブジェクトタイプのいずれかである必要があります。

GeoJsonGeometry

有効な GeoJSON geometry オブジェクト。この型は、有効な 7 つの GeoJSON ジオメトリ型 (Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection) のいずれかである必要があります。詳細については、 RFC 7946 を参照してください。

名前	型	説明
type	GeoJsonObjectType	型を指定します `GeoJSON` 。 Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature、FeatureCollection の 9 つの有効な GeoJSON オブジェクトタイプのいずれかである必要があります。

GeoJsonGeometryCollection

有効な GeoJSON GeometryCollection オブジェクト型。詳細については、 RFC 7946 を参照してください。

名前	型	説明
geometries	GeoJsonGeometry[]: GeoJsonGeometryCollection[] GeoJsonLineString[] GeoJsonMultiLineString[] GeoJsonMultiPoint[] GeoJsonMultiPolygon[] GeoJsonPoint[] GeoJsonPolygon[]	有効な `GeoJSON` geometry オブジェクトの一覧が含まれます。 GeoJSON の座標は x、y の順序 (経度、緯度) であることに注意してください。
type	string: GeometryCollection	型を指定します `GeoJSON` 。 Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature、FeatureCollection の 9 つの有効な GeoJSON オブジェクトタイプのいずれかである必要があります。

GeoJsonLineString

有効な GeoJSON LineString geometry 型。詳細については、 RFC 7946 を参照してください。

名前	型	説明
coordinates	number[]	ジオメトリの `GeoJson LineString` 座標。
type	string: LineString	型を指定します `GeoJSON` 。 Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature、FeatureCollection の 9 つの有効な GeoJSON オブジェクトタイプのいずれかである必要があります。

GeoJsonMultiLineString

有効な GeoJSON MultiLineString geometry 型。詳細については、 RFC 7946 を参照してください。

名前	型	説明
coordinates	number[]	ジオメトリの `GeoJson MultiLineString` 座標。
type	string: MultiLineString	型を指定します `GeoJSON` 。 Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature、FeatureCollection の 9 つの有効な GeoJSON オブジェクトタイプのいずれかである必要があります。

GeoJsonMultiPoint

有効な GeoJSON MultiPoint geometry 型。詳細については、 RFC 7946 を参照してください。

名前	型	説明
coordinates	number[]	ジオメトリの `GeoJson MultiPoint` 座標。
type	string: MultiPoint	型を指定します `GeoJSON` 。 Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature、FeatureCollection の 9 つの有効な GeoJSON オブジェクトタイプのいずれかである必要があります。

GeoJsonMultiPolygon

有効な GeoJSON MultiPolygon オブジェクト型。詳細については、 RFC 7946 を参照してください。

名前	型	説明
coordinates	number[]	有効な `GeoJSON Polygon` オブジェクトの一覧を格納します。 GeoJSON の座標は x、y 順 (経度、緯度) であることに注意してください。
type	string: MultiPolygon	型を指定します `GeoJSON` 。 Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature、FeatureCollection の 9 つの有効な GeoJSON オブジェクトタイプのいずれかである必要があります。

GeoJsonPoint

有効な GeoJSON Point geometry 型。詳細については、 RFC 7946 を参照してください。

名前	型	説明
coordinates	number[]	は `Position` 、2 つ以上の要素を持つ数値の配列です。最初の 2 つの要素は経度と緯度であり、正確にはその順序です。高度/標高は、オプションの 3 番目の要素です。詳細については、 RFC 7946 を参照してください。
type	string: Point	型を指定します `GeoJSON` 。 Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature、FeatureCollection の 9 つの有効な GeoJSON オブジェクトタイプのいずれかである必要があります。

GeoJsonPolygon

有効な GeoJSON Polygon geometry 型。詳細については、 RFC 7946 を参照してください。

名前	型	説明
coordinates	number[]	geometry 型の `GeoJson Polygon` 座標。
type	string: Polygon	型を指定します `GeoJSON` 。 Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature、FeatureCollection の 9 つの有効な GeoJSON オブジェクトタイプのいずれかである必要があります。

JsonFormat

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

名前	型	説明
json	string	JavaScript オブジェクト表記データ交換形式

次の方法で共有

Spatial - Post Geofence

URI パラメーター

要求ヘッダー

要求本文

応答

セキュリティ

AADToken

メモ

スコープ

subscription-key

SAS Token

例

PostGeofence

要求のサンプル

応答のサンプル

定義

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

Geofence

GeofenceGeometry

GeofenceMode

GeoJsonFeature

GeoJsonFeatureCollection

GeoJsonGeometry

GeoJsonGeometryCollection

GeoJsonLineString

GeoJsonMultiLineString

GeoJsonMultiPoint

GeoJsonMultiPolygon

GeoJsonPoint

GeoJsonPolygon

JsonFormat

その他のリソース