Spatial - Get Geofence

Referencia

Szolgáltatás:: Maps

API-verzió:: 2022-08-01

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

Az Get Geofence API egy HTTP-kérés GET , amely lekéri a koordináták közelségét az adatregisztrációs adatbázisba feltöltött geokerítéshez. Feltölt egy geokerítést vagy kerítéskészletet egy Azure Storage-fiókba, majd regisztrálja azt az Azure Maps-fiókjában az Adatregisztrációs adatbázis használatával. További információt az Adatregisztrációs adatbázis létrehozása című témakörben talál. A geofence adatformátumával kapcsolatos további információkért lásd: Geofencing GeoJSON-adatok. Egy koordináta közelségének lekérdezéséhez meg kell adnia a követendő objektum helyét, valamint a kerítés vagy kerítéskészlet azonosítóját, és a válasz információkat tartalmaz 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). Az API teszteléséhez feltöltheti a Post Geofence API-példák (kérelemtörzs) mintaadatait az Adatregisztrációs adatbázis szolgáltatással, és lecserélheti az {udid} alábbi mintakérelmet az udid Adatregisztrációs adatbázis létrehozásához használtra. Az adatregisztrációs adatbázis szolgáltatásával kapcsolatos további információkért lásd: Adatregisztrációs adatbázis létrehozása.

Geokerítés InnerError kódja

A geokerítési válasz hibaszerződésében egy objektum, innererror amely szolgáltatásspecifikus információkat tartalmaz a hibáról. code egy tulajdonság innererror , amelyben leképezést végezhet egy adott geokerítési hibatípusra. Az alábbi táblázat az összes ismert ügyfélhibatípus és a megfelelő geokerítési hiba messageközötti kódleképezést mutatja be.

innererror.code	error.message
NullDeviceId	Az eszközazonosító nem lehet null értékű.
NullUdid	Az Udid értéke nem lehet null.
UdidWrongFormat	Az Udid-t a felhasználói adatbetöltési API-ból kell beszerezni.
InvalidUserTime	A Usertime érvénytelen.
InvalidSearchBuffer	A searchbuffer érvénytelen.
InvalidSearchRange	A keresőbuffer értéktartományának 0 és 500 méter közöttinek kell lennie.
InvalidLatLon	A Lat és/vagy lon paraméterek érvénytelenek.
InvalidIsAsyncValue	Az IsAsync paraméter érvénytelen.
InvalidModeValue	A mode paraméter érvénytelen.
InvalidJson	A geokerítési adatok nem érvényes JSON-fájlok.
NotSupportedGeoJson	A geokerítési adatok nem olvashatók funkcióként vagy FeatureCollectionsként.
InvalidGeoJson	A geokerítési adatok érvénytelenek.
NoUserDataWithAccountOrSubscription	A megadott fiókazonosítóval és/vagy előfizetés-azonosítóval rendelkező felhasználói geokerítési adatok nem találhatók.
NoUserDataWithUdid	Nem található a megadott udid-val rendelkező felhasználói geokerítési adatok.

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

Opcionális paraméterekkel:

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-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	Az 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 az Azure Maps-fiók az USA keleti régiójában található, a rendszer csak a hozzánk intézett földrajzi kérelmeket fogadja el.
api-version	query	True	string	Az 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.
udid	query	True	string	Az érvényes GeoJSON FeatureCollection objektum feltöltéséhez használt egyedi azonosító, amely egy adatjegyzék létrehozásakor használatos. A részleteket az RFC 7946-os verziójában találja. A funkció minden tulajdonságának tartalmaznia kell a `geometryId`elemet, amely a geometria azonosítására szolgál, és megkülönbözteti a kis- és nagybetűk megkülönböztetését. Az adatregisztrációs adatbázis szolgáltatásával kapcsolatos további információkért lásd: Adatregisztrációs adatbázis létrehozása.
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.Now.
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ást használ. 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 az Azure Maps-fiók egyedi azonosítóját jelöli, amely az Azure Maps felügyeleti sík fiók API-jából kérhető le. A Microsoft Entra ID security Azure Mapsben való használatához az alábbi cikkek nyújtanak útmutatást.

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. Fejlécek X-Correlation-id: string
Other Status Codes	ErrorResponse	Váratlan hiba történt.

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.

Fejlécek

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 szabályozható az Azure Maps REST API-khoz való hozzáférés. 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 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á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

Ehhez a biztonsági definícióhoz a x-ms-client-id fejléc használatával kell jelezni, hogy az alkalmazás melyik Azure Maps-erőforráshoz kér hozzáférést. 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-beli 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 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.

További információ a Microsoft identitásplatformról: A Microsoft identitásplatformjának áttekintése.

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 lesz kiépítve, ha 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 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 azt javasoljuk, hogy az Azure Maps REST API-k kiszolgálóról kiszolgálóra történő elé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ása 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 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 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.

Típus: apiKey
In: header

Példák

GetGeofence

Mintakérelem

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

Mintaválasz

Állapotkód:: 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
}

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 földrajzi közelségi hívás adja vissza.
GeofenceGeometry	A geokerítés geometriája.
GeofenceMode	A geokerítési aszinkron eseménymechanizmus módja.
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 hiba célja.

ErrorResponse

Hibaválasz

Name	Típus	Description
error	ErrorDetail	A hibaobjektum.

Geofence

Ezt az objektumot egy földrajzi 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 geokerítés geometriai azonosítójának listája.
geometries	GeofenceGeometry[]	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 viszonyítva érvénytelen időtartamú geokerítés 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 nincs közzétéve 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 geokerítés geometriája.

Name	Típus	Description
deviceId	string	Az eszköz azonosítója.
distance	number	Távolság a koordináta és a geokerítés legközelebbi szegélye között (mérőkben, kivéve, ha a -999/999 különleges értékeket használják). A pozitív azt jelenti, hogy a koordináta kívül esik a geokerítésen. Ha a koordináta kívül esik a geofencen, de nagyobb, mint a searchBuffer értéke a legközelebbi geokerítési szegélytől, akkor az érték 999. A negatív azt jelenti, hogy a koordináta a geokerítésen belül van. Ha a koordináta a sokszögen belül van, de nagyobb, mint a searchBuffer értéke a legközelebbi geokerítési szegélytől távol, akkor az érték -999. A 999-es érték azt jelenti, hogy nagy a megbízhatóság, hogy a koordináták jóval kívül esnek a geokerítésen. A -999 érték azt jelenti, hogy nagy a megbízhatóság a koordináták között.
geometryId	string	Az egyedi azonosító azonosítja a geometriá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	Tengerszint a 2D kihúzás geometriája legközelebbi pontjának mérőjében. Ez csak akkor jelenik meg válaszként, ha a kérelemben a "zInMeter" érték van megadva.
udId	string	Az érvényes GeoJSON FeatureCollection objektum feltöltéséhez használt egyedi azonosító, amely egy adatjegyzék létrehozásakor használatos. A részleteket az RFC 7946-os verziójában találja. A funkció minden tulajdonságának tartalmaznia kell a `geometryId`elemet, amely a geometria azonosítására szolgál, és megkülönbözteti a kis- és nagybetűk megkülönböztetését. Az adatregisztrációs adatbázis szolgáltatásával kapcsolatos további információkért lásd: Adatregisztrációs adatbázis létrehozása.

GeofenceMode

A geokerítési 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 keresztező geokerítési beszállónak minősül.

JsonFormat

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

Name	Típus	Description
json	string	A JavaScript object Notation Data Interchange formátuma

Megosztás a következőn keresztül:

Spatial - Get Geofence

Geokerítés InnerError kódja

URI-paraméterek

Kérelem fejléce

Válaszok

Biztonság

AADToken

Jegyzetek

Hatókörök

subscription-key

SAS Token

Példák

GetGeofence

Mintakérelem

Mintaválasz

Definíciók

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

Geofence

GeofenceGeometry

GeofenceMode

JsonFormat

További források