Spatial - Post Geofence

  • Referencia
Service:
Maps
API Version:
2022-08-01

Egy koordináták földrajzi helyhez való közelségének lekérésére használható.

Az Post Geofence API egy HTTP-kérés POST , amely lekéri egy koordinátának a megadott földrajzi helyhez vagy kerítéskészlethez való közelségét. A kérések esetében POST nem kell előre feltöltenie a kerítésadatokat, hanem meg kell adnia a követendő objektum helyét a lekérdezési paraméterekben, valamint a kerítés vagy kerítések adatait a kérelemtörzsben. A geofence adatformátumával kapcsolatos további információkért lásd: Geofencing GeoJSON-adatok. A válasz információkat fog tartalmazni a geokerítés külső szélétől való távolságról. A negatív érték azt jelzi, hogy a koordináta a kerítésen belül van, míg a pozitív érték azt jelenti, hogy kívül esik a kerítésen.

Ez az API számos forgatókönyvhöz használható, például eszközkövetéshez, flottakezeléshez vagy objektumok áthelyezésére vonatkozó riasztások beállításához.

Az API támogatja az Event Griddel való integrációt. Az isAsync paraméter az Event Griddel való integráció engedélyezésére szolgál (alapértelmezés szerint le van tiltva).

POST https://{geography}.atlas.microsoft.com/spatial/geofence/json?api-version=2022-08-01&deviceId={deviceId}&lat={lat}&lon={lon}
With optional parameters: 
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-paraméterek

Name In Kötelező Típus Description
format
 path True

JsonFormat

A válasz kívánt formátuma. Csak json a formátum támogatott.
geography
 path True

string

A Azure Maps-fiók helye. Az érvényes értékek az USA keleti régiója, az USA nyugati középső régiója, az USA 2. nyugati régiója és az EU (Észak-Európa, Nyugat-Európa). Erre a paraméterre akkor van szükség, ha udid egy meg van adva a kérelemben. Ha például a Azure Maps-fiók az USA keleti régiójában található, csak a földrajzi hely felé irányuló kéréseket fogadja el a rendszer.
api-version
 query True

string

Azure Maps API verziószáma.
deviceId
 query True

string

Az eszköz azonosítója
lat
 query True

number

Az átadott hely szélessége. Példa: 48.36.
lon
 query True

number

Az átadott hely hosszúsága. Példa: -124.63.
isAsync
 query

boolean

Ha igaz, a kérés aszinkron eseménymechanizmust fog használni; ha hamis, a rendszer szinkronizálja a kérést, és nem indít el semmilyen eseményt. Az alapértelmezett érték a hamis.
mode
 query

GeofenceMode

A geokerítési aszinkron eseménymechanizmus módja.
searchBuffer
 query

number

A geokerítés körüli puffer sugara mérőkben, amelyek meghatározzák, hogy milyen messze kell keresni a kerítés határán belül és kívül az eredmény kiszámításakor megadott koordináta alapján. A minimális érték 0, a maximum pedig 500. Az alapértelmezett érték: 50.
userTime
 query

string

date-time

A felhasználó időt kér. Ha nem jelenik meg a kérelemben, az alapértelmezett érték a DateTime.UtcNow.
z
 query

number

A tenger szintje az átadott hely méterében. Ha ez a paraméter jelenik meg, a rendszer 2D-s kihúzás geokerítést alkalmaz. Példa: 200.

Kérelem fejléce

Name Kötelező Típus Description
x-ms-client-id

string

Meghatározza, hogy melyik fiók legyen a Microsoft Entra ID biztonsági modellel együtt használva. Ez a Azure Maps fiók egyedi azonosítóját jelöli, és lekérhető a Azure Maps felügyeletisík Fiók API-jából. A Microsoft Entra ID biztonság Azure Maps az alábbi cikkekben talál útmutatást.

Kérelem törzse

Name Kötelező Típus Description
features True

GeoJsonFeature[]

Az érvényes GeoJSON Feature objektumok listáját tartalmazza.
type True string:

FeatureCollection

Megadja a típust GeoJSON . A kilenc érvényes GeoJSON-objektumtípus egyikének kell lennie : Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature és FeatureCollection.

Válaszok

Name Típus Description
200 OK

Geofence

OK Az X-Correlation-id fejléc értéke jelen van egy aszinkron hívás válaszában és az Event Grid eseményadataiban. Segít korrelálni az aszinkron hívás válaszát a megfelelő Event Grid-eseménysel.

Headers

X-Correlation-id: string
Other Status Codes

ErrorResponse

Váratlan hiba történt.

Biztonság

AADToken

Ezek a Microsoft Entra OAuth 2.0-folyamatok. Az Azure-beli szerepköralapú hozzáférés-vezérléssel párosítva Azure Maps REST API-khoz való hozzáférés vezérlésére használható. Az Azure szerepköralapú hozzáférés-vezérlése egy vagy több Azure Maps erőforrásfiókhoz vagy alerőforráshoz való hozzáférés kijelölésére szolgál. Bármely felhasználó, csoport vagy szolgáltatásnév hozzáférést kaphat egy beépített szerepkörrel vagy egy vagy több rest API-Azure Maps ra vonatkozó engedélyből álló egyéni szerepkörrel.

A forgatókönyvek implementálásához javasoljuk, hogy tekintse meg a hitelesítési fogalmakat. Összefoglalva, ez a biztonsági definíció megoldást nyújt az alkalmazás(ok) adott API-k és hatókörök hozzáférés-vezérlésére képes objektumokon keresztüli modellezésére.

Jegyzetek

  • Ez a biztonsági definíció megköveteli a fejléc használatát annak x-ms-client-id jelzéséhez, hogy melyik Azure Maps erőforráshoz kér hozzáférést az alkalmazás. Ez a Maps management API-ból szerezhető be.

A Authorization URL az Azure nyilvános felhőpéldányára vonatkozik. A szuverén felhők egyedi engedélyezési URL-címekkel és Microsoft Entra ID konfigurációkkal rendelkeznek. * Az Azure szerepköralapú hozzáférés-vezérlése az Azure felügyeleti síkjáról van konfigurálva Azure Portal, PowerShell, CLI, Azure SDK-k vagy REST API-k használatával. * A Azure Maps Web SDK használata lehetővé teszi az alkalmazások konfigurációalapú beállítását több használati esetben.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
https://atlas.microsoft.com/.default https://atlas.microsoft.com/.default

subscription-key

Ez egy megosztott kulcs, amely akkor lesz kiépítve, ha Azure Maps-erőforrást hoz létre az Azure felügyeleti síkján keresztül Azure Portal, PowerShell, CLI, Azure SDK-k vagy REST API-k használatával.

Ezzel a kulccsal bármely alkalmazás hozzáférhet az összes REST API-hoz. Más szóval ezek jelenleg főkulcsként kezelhetők ahhoz a fiókhoz, amelyhez ki vannak adva.

Nyilvánosan közzétett alkalmazások esetében azt javasoljuk, hogy olyan Azure Maps REST API-k kiszolgálóról kiszolgálóra történő hozzáférését használja, ahol ez a kulcs biztonságosan tárolható.

Type: apiKey
In: header

SAS Token

Ez egy közös hozzáférésű jogosultságkód-jogkivonat a listázási SAS műveletből jön létre az Azure Maps erőforráson keresztül az Azure felügyeleti síkján keresztül Azure Portal, PowerShell, CLI, Azure SDK-k vagy REST API-k használatával.

Ezzel a jogkivonattal minden alkalmazás jogosult hozzáférni az Azure szerepköralapú hozzáférés-vezérlőihez, valamint az adott jogkivonathoz használt lejárati időhöz, sebességhez és régióhoz. Más szóval az SAS-jogkivonattal az alkalmazások a megosztott kulcsnál biztonságosabb módon szabályozhatják a hozzáférést.

Nyilvánosan közzétett alkalmazások esetében javasoljuk, hogy konfiguráljon egy adott listát az engedélyezett forrásokról a térképfiók-erőforráson a leképezési visszaélések korlátozásához és az SAS-jogkivonat rendszeres megújításához.

Type: apiKey
In: header

Példák

PostGeofence

Sample Request

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

Sample Response

Status code:
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
}

Definíciók

Name Description
ErrorAdditionalInfo

Az erőforrás-kezelési hiba további információi.
ErrorDetail

A hiba részletei.
ErrorResponse

Hibaválasz
Geofence

Ezt az objektumot egy geofence közelségi hívás adja vissza.
GeofenceGeometry

A geofencing geometria.
GeofenceMode

A georedundáns aszinkron eseménymechanizmus módja.
GeoJsonFeature

Érvényes GeoJSON Feature objektumtípus. A részletekért tekintse meg az RFC 7946-ot .
GeoJsonFeatureCollection

Érvényes GeoJSON FeatureCollection objektumtípus. A részletekért tekintse meg az RFC 7946-ot .
GeoJsonGeometry

Érvényes GeoJSON geometriai objektum. A típusnak a hét érvényes GeoJSON-geometriatípus egyikének kell lennie : Pont, MultiPoint, Vonallánc, MultiLineString, Polygon, MultiPolygon és GeometryCollection. A részletekért tekintse meg az RFC 7946-ot .
GeoJsonGeometryCollection

Érvényes GeoJSON GeometryCollection objektumtípus. A részletekért tekintse meg az RFC 7946-ot .
GeoJsonLineString

Érvényes GeoJSON LineString geometriatípus. A részletekért tekintse meg az RFC 7946-ot .
GeoJsonMultiLineString

Érvényes GeoJSON MultiLineString geometriatípus. A részletekért tekintse meg az RFC 7946-ot .
GeoJsonMultiPoint

Érvényes GeoJSON MultiPoint geometriatípus. A részletekért tekintse meg az RFC 7946-ot .
GeoJsonMultiPolygon

Érvényes GeoJSON MultiPolygon objektumtípus. A részletekért tekintse meg az RFC 7946-ot .
GeoJsonPoint

Érvényes GeoJSON Point geometriatípus. A részletekért tekintse meg az RFC 7946-ot .
GeoJsonPolygon

Érvényes GeoJSON Polygon geometriatípus. A részletekért tekintse meg az RFC 7946-ot .
JsonFormat

A válasz kívánt formátuma. Csak json a formátum támogatott.

ErrorAdditionalInfo

Az erőforrás-kezelési hiba további információi.

Name Típus Description
info

object

A további információk.
type

string

A további adattípus.

ErrorDetail

A hiba részletei.

Name Típus Description
additionalInfo

ErrorAdditionalInfo[]

A hiba további információi.
code

string

A hibakód.
details

ErrorDetail[]

A hiba részletei.
message

string

A hibaüzenet.
target

string

A hibacél.

ErrorResponse

Hibaválasz

Name Típus Description
error

ErrorDetail

A hibaobjektum.

Geofence

Ezt az objektumot egy geofence közelségi hívás adja vissza.

Name Típus Description
expiredGeofenceGeometryId

string[]

Listák a kérelemben megadott felhasználói időhöz képest lejárt geofencia geometriai azonosítóját.
geometries

GeofenceGeometry[]

Listák a koordináta-pozíciót tartalmazó vagy a keresőbuffert átfedő kerítésgeometriákat a pozíció körül.
invalidPeriodGeofenceGeometryId

string[]

Listák a kérelemben szereplő felhasználói időhöz képest érvénytelen geofencia geometriai azonosítóját.
isEventPublished

boolean

Igaz, ha legalább egy eseményt közzétevő a Azure Maps esemény-előfizetőnek, hamis, ha a Azure Maps esemény előfizetője nem tett közzé eseményt. Ez csak akkor jelenik meg válaszként, ha az "isAsync" lekérdezési paraméter igaz értékre van állítva.

GeofenceGeometry

A geofencing geometria.

Name Típus Description
deviceId

string

Az eszköz azonosítója.
distance

number

Távolság a koordináta és a geofencia legközelebbi határa között (mérőkben, kivéve, ha speciális értékeket használnak -999/999). A pozitív azt jelenti, hogy a koordináta kívül esik a geofencen. Ha a koordináta kívül esik a geofencen, de nagyobb, mint a searchBuffer értéke a legközelebbi geofenceszegélytől, akkor az érték 999. A negatív azt jelenti, hogy a koordináta a geofence belsejében van. Ha a koordináta a sokszögben van, de a searchBuffer értéke nagyobb a legközelebbi geofencing szegélytől távol, akkor az érték -999. A 999 érték azt jelenti, hogy nagy a megbízhatóság, hogy a koordináta jól kívül esik a geofencen. A -999 érték azt jelenti, hogy nagy a megbízhatóság a koordinátán belül.
geometryId

string

Az egyedi azonosító egy geometriát azonosít.
nearestLat

number

A geometria legközelebbi pontjának szélessége.
nearestLon

number

A geometria legközelebbi pontjának hosszúsága.
nearestZ

number

A 2D kihúzási geometria legközelebbi pontjának tengerszintje. Ez csak akkor jelenik meg válaszként, ha a kérelemben a "zInMeter" érték van megadva.
udId

string

Az adatregisztrációs adatbázis létrehozásakor használt egyedi azonosító egy érvényes GeoJSON FeatureCollection-objektum feltöltéséhez. A részletekért tekintse meg az RFC 7946-ot . A funkció minden tulajdonságának tartalmaznia kell , geometryIdamely a geometria azonosítására szolgál, és megkülönbözteti a kis- és nagybetűk megkülönböztetését. További információ az adatregisztrációs adatbázis szolgáltatásról: Adatregisztrációs adatbázis létrehozása.

GeofenceMode

A georedundáns aszinkron eseménymechanizmus módja.

Name Típus Description
All

string

Tegye közzé az összes lekérdezési eredményt Azure Maps fiókesemény-előfizetésben.
EnterAndExit

string

Csak akkor tegye közzé az eredményt, ha a felhasználó tartózkodási helye átkelő geofencing beszállónak minősül.

GeoJsonFeature

Érvényes GeoJSON Feature objektumtípus. A részletekért tekintse meg az RFC 7946-ot .

Name Típus Description
featureType

string

A szolgáltatás típusa. Az érték attól függ, hogy az aktuális funkció melyik adatmodell része. Egyes adatmodellek üres értékkel rendelkezhetnek.
geometry GeoJsonGeometry:
  • GeoJsonGeometryCollection
  • GeoJsonLineString
  • GeoJsonMultiLineString
  • GeoJsonMultiPoint
  • GeoJsonMultiPolygon
  • GeoJsonPoint
  • GeoJsonPolygon

Érvényes GeoJSON geometriai objektum. A típusnak a hét érvényes GeoJSON-geometriatípus egyikének kell lennie : Pont, MultiPoint, Vonallánc, MultiLineString, Polygon, MultiPolygon és GeometryCollection. A részletekért tekintse meg az RFC 7946-ot .
id

string

A funkció azonosítója.
type string:

Feature

Megadja a típust GeoJSON . A kilenc érvényes GeoJSON-objektumtípus egyikének kell lennie : Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonFeatureCollection

Érvényes GeoJSON FeatureCollection objektumtípus. A részletekért tekintse meg az RFC 7946-ot .

Name Típus Description
features

GeoJsonFeature[]

Az érvényes GeoJSON Feature objektumok listáját tartalmazza.
type string:

FeatureCollection

Megadja a típust GeoJSON . A kilenc érvényes GeoJSON-objektumtípus egyikének kell lennie : Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonGeometry

Érvényes GeoJSON geometriai objektum. A típusnak a hét érvényes GeoJSON-geometriatípus egyikének kell lennie : Pont, MultiPoint, Vonallánc, MultiLineString, Polygon, MultiPolygon és GeometryCollection. A részletekért tekintse meg az RFC 7946-ot .

Name Típus Description
type

GeoJsonObjectType

Megadja a típust GeoJSON . A kilenc érvényes GeoJSON-objektumtípus egyikének kell lennie : Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonGeometryCollection

Érvényes GeoJSON GeometryCollection objektumtípus. A részletekért tekintse meg az RFC 7946-ot .

Name Típus Description
geometries GeoJsonGeometry[]:
  • GeoJsonGeometryCollection[]
  • GeoJsonLineString[]
  • GeoJsonMultiLineString[]
  • GeoJsonMultiPoint[]
  • GeoJsonMultiPolygon[]
  • GeoJsonPoint[]
  • GeoJsonPolygon[]

Érvényes geometriai objektumok listáját GeoJSON tartalmazza. Vegye figyelembe , hogy a GeoJSON koordinátái x, y sorrendben vannak (hosszúság, szélesség).
type string:

GeometryCollection

Megadja a típust GeoJSON . A kilenc érvényes GeoJSON-objektumtípus egyikének kell lennie : Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonLineString

Érvényes GeoJSON LineString geometriatípus. A részletekért tekintse meg az RFC 7946-ot .

Name Típus Description
coordinates

number[]

A geometria koordinátái GeoJson LineString .
type string:

LineString

Megadja a típust GeoJSON . A kilenc érvényes GeoJSON-objektumtípus egyikének kell lennie : Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonMultiLineString

Érvényes GeoJSON MultiLineString geometriatípus. A részletekért tekintse meg az RFC 7946-ot .

Name Típus Description
coordinates

number[]

A geometria koordinátái GeoJson MultiLineString .
type string:

MultiLineString

Megadja a típust GeoJSON . A kilenc érvényes GeoJSON-objektumtípus egyikének kell lennie : Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonMultiPoint

Érvényes GeoJSON MultiPoint geometriatípus. A részletekért tekintse meg az RFC 7946-ot .

Name Típus Description
coordinates

number[]

A geometria koordinátái GeoJson MultiPoint .
type string:

MultiPoint

Megadja a típust GeoJSON . A kilenc érvényes GeoJSON-objektumtípus egyikének kell lennie : Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonMultiPolygon

Érvényes GeoJSON MultiPolygon objektumtípus. A részletekért tekintse meg az RFC 7946-ot .

Name Típus Description
coordinates

number[]

Az érvényes GeoJSON Polygon objektumok listáját tartalmazza. Vegye figyelembe , hogy a GeoJSON koordinátái x, y sorrendben vannak (hosszúság, szélesség).
type string:

MultiPolygon

Megadja a típust GeoJSON . A kilenc érvényes GeoJSON-objektumtípus egyikének kell lennie : Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonPoint

Érvényes GeoJSON Point geometriatípus. A részletekért tekintse meg az RFC 7946-ot .

Name Típus Description
coordinates

number[]

Az A Position két vagy több elemet tartalmazó számok tömbje. Az első két elem a hosszúság és a szélesség, pontosan ebben a sorrendben. A magasság/magasság opcionális harmadik elem. A részletekért tekintse meg az RFC 7946-ot .
type string:

Point

Megadja a típust GeoJSON . A kilenc érvényes GeoJSON-objektumtípus egyikének kell lennie : Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonPolygon

Érvényes GeoJSON Polygon geometriatípus. A részletekért tekintse meg az RFC 7946-ot .

Name Típus Description
coordinates

number[]

A geometriatípus koordinátái GeoJson Polygon .
type string:

Polygon

Megadja a típust GeoJSON . A kilenc érvényes GeoJSON-objektumtípus egyikének kell lennie : Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

JsonFormat

A válasz kívánt formátuma. Csak json a formátum támogatott.

Name Típus Description
json

string

A JavaScript-objektum jelölési adatcseréjének formátuma