Spatial - Post Geofence
Egy koordináták földrajzi helyhez való közelségének lekéréséhez használható.
Az Post Geofence
API egy HTTP-kérés POST
, amely lekéri a koordináták közelségét egy megadott földrajzi helyhez vagy kerítéskészlethez. A kérések esetén POST
nem kell előzetesen feltöltenie a kerítésadatokat, hanem meg kell adnia a nyomon követett objektum helyét a lekérdezési paraméterekben, valamint a kerítés vagy kerítéskészlet adatait a kérelemtörzsben. A geoinformációs adatformátummal kapcsolatos további információkért lásd: Geofencing GeoJSON-adatok. A válasz információkat tartalmaz a geofence 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 a kerítésen kívül van.
Ez az API számos forgatókönyvhez 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}
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 |
A válasz kívánt formátuma. Csak |
|
geography
|
path | True |
string |
Az Azure Maps-fiók helye. Érvényes értékek: mi (USA keleti régiója, USA nyugati középső régiója, 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 a |
api-version
|
query | True |
string |
Az Azure Maps API verziószáma. |
device
|
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. |
is
|
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 |
A georedundáns aszinkron eseménymechanizmus módja. |
||
search
|
query |
number |
A puffer sugara a geofencia körül 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átán. A minimális érték 0, a maximális érték pedig 500. Az alapértelmezett érték: 50. |
|
user
|
query |
string date-time |
A felhasználó kérési ideje. Ha a kérés nem jelenik meg, az alapértelmezett érték a DateTime.UtcNow. |
|
z
|
query |
number |
A tenger szintje az átadott hely mérőjében. Ha ez a paraméter jelenik meg, a rendszer 2D extrusion geofencinget 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 használatban a Microsoft Entra ID biztonsági modellel együtt. Az Azure Maps-fiók egyedi azonosítóját jelöli, és lekérhető az Azure Maps felügyeleti síkjának Fiók API-jából. A Microsoft Entra ID-biztonság Azure Mapsben való használatához tekintse meg az alábbi cikkeket . |
Kérelem törzse
Name | Kötelező | Típus | Description |
---|---|---|---|
features | True |
Az érvényes |
|
type | True |
string:
Feature |
Megadja a típust |
Válaszok
Name | Típus | Description |
---|---|---|
200 OK |
OK Az X-Korrelációs-azonosító 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. Fejlécek X-Correlation-id: string |
|
Other Status Codes |
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 szabályozható az Azure Maps REST API-khoz való hozzáférés. Az Azure szerepköralapú hozzáférés-vezérlői egy vagy több Azure Maps-erőforrásfiókhoz vagy alerőforrásokhoz való hozzáférés kijelölésére szolgálnak. 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 Azure Maps REST API-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ások modellezésére olyan objektumokon keresztül, amelyek hozzáférés-vezérlésre képesek adott API-kon és hatókörökön.
Jegyzetek
- Ez a biztonsági definíció megköveteli a fejléc használatát
x-ms-client-id
annak jelzéséhez, hogy az alkalmazás melyik Azure Maps-erőforráshoz kér hozzáférést. Ez a Térképek felügyeleti API-ból szerezhető be.
Ez Authorization URL
az Azure nyilvános felhőpéldányára jellemző. 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és az Azure felügyeleti síkjáról van konfigurálva az Azure Portalon, a PowerShellen, a parancssori felületen, az Azure SDK-kon vagy a REST API-kon keresztül.
* Az Azure Maps Web SDK használata lehetővé teszi egy alkalmazás konfigurációalapú beállítását több használati esetben.
- A Microsoft identitásplatformról további információt a Microsoft identitásplatform áttekintése című témakörben talál.
Típus:
oauth2
Folyamat:
implicit
Engedélyezési URL:
https://login.microsoftonline.com/common/oauth2/authorize
Hatókörök
Name | Description |
---|---|
https://atlas.microsoft.com/.default | https://atlas.microsoft.com/.default |
subscription-key
Ez egy megosztott kulcs, amely akkor van kiépítve, amikor Azure Maps-erőforrást hoz létre az Azure Felügyeleti síkon keresztül az Azure Portalon, a PowerShellen, a parancssori felületen, az Azure SDK-kon vagy a REST API-kon keresztül.
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 javasoljuk, hogy az 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ó.
Típus:
apiKey
In:
header
SAS Token
Ez egy közös hozzáférésű jogosultságkód-jogkivonat az Azure Maps-erőforrás Sas listázási műveletéből jön létre az Azure Felügyeleti síkon keresztül az Azure Portalon, a PowerShellen, a parancssori felületen, az Azure SDK-kon vagy a REST API-kon keresztül.
Ezzel a jogkivonattal minden alkalmazás jogosult hozzáférni az Azure szerepköralapú hozzáférés-vezérlőihez, valamint az adott jogkivonat lejáratához, sebességéhez és régiójához. Más szóval az SAS-jogkivonattal az alkalmazások biztonságosabb módon szabályozhatják a hozzáférést, mint a megosztott kulcs.
Nyilvánosan közzétett alkalmazások esetében azt javasoljuk, hogy konfigurálja az engedélyezett források adott listáját a Térképfiók erőforráson a megjelenítési visszaélések korlátozása és az SAS-jogkivonat rendszeres megújítása érdekében.
Típus:
apiKey
In:
header
Példák
PostGeofence
Mintakérelem
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"
}
}
]
}
Mintaválasz
{
"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 |
---|---|
Error |
Az erőforrás-kezelési hiba további információi. |
Error |
A hiba részletei. |
Error |
Hibaválasz |
Geofence |
Ezt az objektumot egy geofence közelségi hívás adja vissza. |
Geofence |
A geofencing geometria. |
Geofence |
A georedundáns aszinkron eseménymechanizmus módja. |
Geo |
Érvényes |
Geo |
Érvényes |
Geo |
Érvényes |
Geo |
Érvényes |
Geo |
Érvényes |
Geo |
Érvényes |
Geo |
Érvényes |
Geo |
Érvényes |
Geo |
Érvényes |
Geo |
Érvényes |
Json |
A válasz kívánt formátuma. Csak |
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 információtípus. |
ErrorDetail
A hiba részletei.
Name | Típus | Description |
---|---|---|
additionalInfo |
A hiba további információi. |
|
code |
string |
A hibakód. |
details |
A hiba részletei. |
|
message |
string |
A hibaüzenet. |
target |
string |
A hibacél. |
ErrorResponse
Hibaválasz
Name | Típus | Description |
---|---|---|
error |
A hibaobjektum. |
Geofence
Ezt az objektumot egy geofence közelségi hívás adja vissza.
Name | Típus | Description |
---|---|---|
expiredGeofenceGeometryId |
string[] |
A kérelemben megadott felhasználói időhöz képest lejárt geofencia geometriai azonosítójának listája. |
geometries |
Felsorolja azokat a kerítésgeometriákat, amelyek a koordináta-pozíciót tartalmazzák, vagy átfedésben vannak a searchBuffer pozíció körül. |
|
invalidPeriodGeofenceGeometryId |
string[] |
A kérelemben szereplő felhasználói időhöz képest érvénytelen időtartamú geofencia geometriai azonosítójának listája. |
isEventPublished |
boolean |
Igaz, ha legalább egy esemény közzé van téve az Azure Maps esemény-előfizetője számára, hamis, ha nem jelent meg esemény az Azure Maps esemény-előfizetője számára. 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 , |
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 az Azure Maps-fiók esemény-előfizetésében. |
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: |
Érvényes |
id |
string |
A funkció azonosítója. |
type |
string:
Feature |
Megadja a típust |
GeoJsonFeatureCollection
Érvényes GeoJSON FeatureCollection
objektumtípus. A részletekért tekintse meg az RFC 7946-ot .
Name | Típus | Description |
---|---|---|
features |
Az érvényes |
|
type |
string:
Feature |
Megadja a típust |
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 |
Geo |
Megadja a típust |
GeoJsonGeometryCollection
Érvényes GeoJSON GeometryCollection
objektumtípus. A részletekért tekintse meg az RFC 7946-ot .
Name | Típus | Description |
---|---|---|
geometries | GeoJsonGeometry[]: |
Érvényes geometriai objektumok listáját |
type |
string:
Geometry |
Megadja a típust |
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 |
type |
string:
Line |
Megadja a típust |
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 |
type |
string:
Multi |
Megadja a típust |
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 |
type |
string:
Multi |
Megadja a típust |
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 |
type |
string:
Multi |
Megadja a típust |
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 |
type |
string:
Point |
Megadja a típust |
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 |
type |
string:
Polygon |
Megadja a típust |
JsonFormat
A válasz kívánt formátuma. Csak json
a formátum támogatott.
Name | Típus | Description |
---|---|---|
json |
string |