Spatial - Get Geofence

Reference

Služba:: Maps

Verze rozhraní API:: 2022-08-01

Slouží k získání blízkosti souřadnice k geografické fence.

Rozhraní Get Geofence API je požadavek HTTP GET , který načítá blízkost souřadnic k geografické fence nahrané do registru dat. Do účtu služby Azure Storage nahrajete geografickoufenci nebo sadu plotů a pak ji zaregistrujete ve svém účtu Azure Maps pomocí registru dat. Další informace najdete v tématu Vytvoření registru dat. Další informace o formátu dat geografické zóny najdete v tématu Geofencing GeoJSON data. Pokud chcete zadat dotaz na blízkost souřadnic, zadejte umístění objektu, který sledujete, a ID plotu nebo sady plotů a odpověď bude obsahovat informace o vzdálenosti od vnějšího okraje geografické zóny. Záporná hodnota znamená, že souřadnice je uvnitř plotu, zatímco kladná hodnota znamená, že je mimo plot.

Toto rozhraní API je možné použít pro různé scénáře, mezi které patří sledování majetku, správa vozového parku nebo nastavení upozornění na přesun objektů.

Rozhraní API podporuje integraci se službou Event Grid. Parametr isAsync se používá k povolení integrace se službou Event Grid (ve výchozím nastavení je zakázaný). K otestování tohoto rozhraní API můžete pomocí služby Registru dat nahrát ukázková data z příkladů rozhraní POST Geofence API (Text požadavku) a nahradit {udid} z níže uvedené ukázkové žádosti údaji použitými udid k vytvoření registru dat. Další informace o službě registru dat najdete v tématu Vytvoření registru dat.

Kód InnerError geografické fencing

V kontraktu chyby odpovědi na geografickou fencing je objekt obsahující innererror informace o chybě specifické pro službu. code je vlastnost, ve innererror které se může mapovat na konkrétní typ chyby geografické fencing. Následující tabulka ukazuje mapování kódu mezi všemi známými typy chyb klienta na odpovídající chybu messagegeografické fencing .

innererror.code	error.message
NullDeviceId	ID zařízení nesmí být null.
NullUdid	Udid by neměl mít hodnotu null.
UdidWrongFormat	Udid by se měl získat z rozhraní API pro příjem uživatelských dat.
InvalidUserTime	Usertime je neplatný.
InvalidSearchBuffer	Searchbuffer je neplatný.
InvalidSearchRange	Rozsah hodnot searchbuffer by měl být od 0 do 500 metrů.
Neplatný název	Parametry lat a/nebo lon jsou neplatné.
InvalidIsAsyncValue	Parametr IsAsync je neplatný.
InvalidModeValue	Parametr mode je neplatný.
InvalidJson	Data monitorování geografických fencingu nejsou platným souborem JSON.
NotSupportedGeoJson	Data geografické fencingu nelze číst jako funkce nebo kolekce funkcí.
InvalidGeoJson	Data monitorování geografických fencingu jsou neplatná.
NoUserDataWithAccountOrSubscription	Nejde najít data monitorování geografických monitorů uživatelů se zadaným ID účtu nebo ID předplatného.
NoUserDataWithUdid	Nejde najít data monitorování geografické fencingu uživatelů s poskytnutým identifikátorem udid.

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

S volitelnými parametry:

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}

Parametry identifikátoru URI

Name	V	Vyžadováno	Typ	Description
format	path	True	JsonFormat	Požadovaný formát odpovědi Podporuje se pouze `json` formát.
geography	path	True	string	Umístění účtu Azure Maps Platné hodnoty jsou my (USA – východ, USA – středozápad, USA – západ 2) a eu (Severní Evropa, Západní Evropa). Tento parametr je povinný, pokud `udid` je v požadavku zadán parametr . Pokud se například účet Azure Maps nachází v oblasti USA – východ, budou přijímány pouze požadavky na geografickou oblast.
api-version	query	True	string	Číslo verze rozhraní API služby Azure Maps
deviceId	query	True	string	ID zařízení
lat	query	True	number	Zeměpisná šířka předávaného umístění. Příklad: 48,36.
lon	query	True	number	Zeměpisná délka předávaného umístění Příklad: -124,63.
udid	query	True	string	Jedinečné ID použité při vytváření registru dat k nahrání platné GeoJSON FeatureCollection objektu. Podrobnosti najdete v dokumentu RFC 7946 . Všechny vlastnosti prvku by měly obsahovat `geometryId`, který slouží k identifikaci geometrie a rozlišuje malá a velká písmena. Další informace o službě registru dat najdete v tématu Vytvoření registru dat.
isAsync	query		boolean	Pokud je true, požadavek bude používat asynchronní event mechanismus; Pokud je false, požadavek se synchronizuje a neaktivuje žádnou událost. Výchozí hodnota je False.
mode	query		GeofenceMode	Režim mechanismu geograficky fencingu asynchronních událostí.
searchBuffer	query		number	Poloměr vyrovnávací paměti kolem geofence v metrech, který definuje, jak daleko hledat uvnitř a vně ohraničení plotu proti souřadnici zadané při výpočtu výsledku. Minimální hodnota je 0 a maximum je 500. Výchozí hodnota je 50.
userTime	query		string date-time	Čas požadavku uživatele. Pokud se v požadavku nezobrazí, výchozí hodnota je DateTime.Now.
z	query		number	Hladina moře v metrech od místa prošel. Pokud je tento parametr uveden, použije se 2D extruze. Příklad: 200.

Hlavička požadavku

Name	Vyžadováno	Typ	Description
x-ms-client-id		string	Určuje, který účet je určen pro použití ve spojení s modelem zabezpečení Microsoft Entra ID. Představuje jedinečné ID účtu Azure Maps a dá se načíst z rozhraní API účtu roviny správy Služby Azure Maps. Informace o použití zabezpečení Microsoft Entra ID ve službě Azure Maps najdete v následujících článcích .

Odpovědi

Name	Typ	Description
200 OK	Geofence	OK Hodnota hlavičky X-Correlation-id se nachází v odpovědi asynchronního volání a v datech událostí Event Gridu. Pomáhá korelovat odpověď asynchronního volání s odpovídající událostí Event Gridu. Hlavičky X-Correlation-id: string
Other Status Codes	ErrorResponse	Došlo k neočekávané chybě.

Name

Typ

Description

200 OK

Geofence

OK Hodnota hlavičky X-Correlation-id se nachází v odpovědi asynchronního volání a v datech událostí Event Gridu. Pomáhá korelovat odpověď asynchronního volání s odpovídající událostí Event Gridu.

Hlavičky

X-Correlation-id: string

Other Status Codes

ErrorResponse

Došlo k neočekávané chybě.

Zabezpečení

AADToken

Toto jsou toky Microsoft Entra OAuth 2.0 . Při spárování s řízením přístupu na základě role v Azure se dá použít k řízení přístupu k rozhraním REST API služby Azure Maps. Řízení přístupu na základě role v Azure slouží k určení přístupu k jednomu nebo několika účtům prostředků nebo dílčím prostředkům Azure Maps. Každému uživateli, skupině nebo instančnímu objektu je možné udělit přístup prostřednictvím předdefinované role nebo vlastní role, která se skládá z jednoho nebo více oprávnění k rozhraním REST API služby Azure Maps.

Pokud chcete implementovat scénáře, doporučujeme zobrazit si koncepty ověřování. Souhrnně řečeno, tato definice zabezpečení poskytuje řešení pro modelování aplikací prostřednictvím objektů schopných řízení přístupu k určitým rozhraním API a oborům.

Poznámky

Tato definice zabezpečení vyžaduje použití hlavičky x-ms-client-id k označení prostředku Azure Maps, ke kterému aplikace žádá o přístup. To je možné získat z rozhraní API pro správu map.

Je Authorization URL specifický pro instanci veřejného cloudu Azure. Suverénní cloudy mají jedinečné autorizační adresy URL a konfigurace Microsoft Entra ID. * Řízení přístupu na základě role v Azure se konfiguruje z roviny správy Azure prostřednictvím webu Azure Portal, PowerShellu, rozhraní příkazového řádku, sad Azure SDK nebo rozhraní REST API. * Použití webové sady SDK služby Azure Maps umožňuje nastavení aplikace na základě konfigurace pro více případů použití.

Další informace o platformě Microsoft Identity Platform najdete v tématu Přehled platformy Microsoft Identity Platform.

Typ: oauth2
Tok: implicit
URL autorizace: https://login.microsoftonline.com/common/oauth2/authorize

Rozsahy

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

subscription-key

Toto je sdílený klíč, který se zřizuje při vytváření prostředku Azure Maps prostřednictvím roviny správy Azure prostřednictvím webu Azure Portal, PowerShellu, rozhraní příkazového řádku, sad Azure SDK nebo rozhraní REST API.

S tímto klíčem má každá aplikace oprávnění pro přístup ke všem rozhraním REST API. Jinými slovy, ty je v současné době možné považovat za hlavní klíče k účtu, pro který jsou vystaveny.

U veřejně vystavených aplikací doporučujeme používat přístup mezi servery k rozhraním REST API služby Azure Maps, kde je možné tento klíč bezpečně uložit.

Typ: apiKey
V: header

SAS Token

Jedná se o token sdíleného přístupového podpisu, který se vytvoří z operace List SAS v prostředku Azure Maps prostřednictvím roviny správy Azure portal, PowerShellu, rozhraní příkazového řádku, sad Azure SDK nebo rozhraní REST API.

S tímto tokenem má každá aplikace oprávnění k přístupu pomocí řízení přístupu na základě role v Azure a podrobného řízení k vypršení platnosti, četnosti a oblastem použití konkrétního tokenu. Jinými slovy, token SAS je možné použít k tomu, aby aplikace mohly řídit přístup bezpečnějším způsobem než sdílený klíč.

U veřejně vystavených aplikací doporučujeme nakonfigurovat konkrétní seznam povolených zdrojů v prostředku mapového účtu , aby se omezilo zneužití vykreslování a pravidelně obnovovali token SAS.

Typ: apiKey
V: header

Příklady

GetGeofence

Ukázkový požadavek

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

Ukázková odpověď

Stavový kó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
}

Definice

Name	Description
ErrorAdditionalInfo	Další informace o chybě správy prostředků
ErrorDetail	Podrobnosti o chybě.
ErrorResponse	Odpověď na chybu
Geofence	Tento objekt je vrácen z volání blízkosti geografické zóny.
GeofenceGeometry	Geometrie geofencingu.
GeofenceMode	Režim mechanismu asynchronních událostí geografické fencing.
JsonFormat	Požadovaný formát odpovědi. Podporuje se pouze `json` formát.

ErrorAdditionalInfo

Další informace o chybě správy prostředků

Name	Typ	Description
info	object	Další informace.
type	string	Další typ informací.

ErrorDetail

Podrobnosti o chybě.

Name	Typ	Description
additionalInfo	ErrorAdditionalInfo[]	Další informace o chybě
code	string	Kód chyby
details	ErrorDetail[]	Podrobnosti o chybě
message	string	Chybová zpráva
target	string	Cíl chyby.

ErrorResponse

Odpověď na chybu

Name	Typ	Description
error	ErrorDetail	Objekt chyby.

Geofence

Tento objekt je vrácen z volání blízkosti geografické zóny.

Name	Typ	Description
expiredGeofenceGeometryId	string[]	Seznamy ID geometrie geografické zóny, jehož platnost vypršela vzhledem k času uživatele v požadavku.
geometries	GeofenceGeometry[]	Zobrazí seznam geometrií plotu, které obsahují pozici souřadnic nebo překrývají funkci searchBuffer kolem pozice.
invalidPeriodGeofenceGeometryId	string[]	Seznamy ID geometrie geografické zóny, která je v neplatném období vzhledem k času uživatele v požadavku.
isEventPublished	boolean	True, pokud je alespoň jedna událost publikovaná pro předplatitele události Azure Maps, false, pokud se pro předplatitele události Azure Maps nepublikuje žádná událost. Tato odpověď se zobrazí pouze v případě, že je parametr dotazu isAsync nastavený na hodnotu true.

GeofenceGeometry

Geometrie geofencingu.

Name	Typ	Description
deviceId	string	ID zařízení.
distance	number	Vzdálenost od souřadnice k nejbližšímu ohraničení geografické zóny (v metrech s výjimkou zvláštních hodnot -999/999). Pozitivní znamená, že souřadnice je mimo geofence. Pokud je souřadnice mimo geofence, ale více než hodnota searchBuffer od nejbližšího ohraničení geografické zóny, je hodnota 999. Záporné znamená, že souřadnice je uvnitř geografické zóny. Pokud je souřadnice uvnitř mnohoúhelníku, ale více než hodnota searchBuffer od nejbližšího ohraničení geografické fencing, je hodnota -999. Hodnota 999 znamená, že existuje velká jistota, že souřadnice je mimo geofence. Hodnota -999 znamená, že existuje velká jistota, že souřadnice je dobře v rámci geografické zóny.
geometryId	string	Jedinečné ID identifikuje geometrii.
nearestLat	number	Zeměpisná šířka nejbližšího bodu geometrie.
nearestLon	number	Zeměpisná délka nejbližšího bodu geometrie.
nearestZ	number	Hladina moře v metrech od nejbližšího bodu na geometrii 2D extruze. Tato odpověď se zobrazí pouze v případě, že je v požadavku zadaná hodnota zInMeter.
udId	string	Jedinečné ID použité při vytváření registru dat k nahrání platného objektu GeoJSON FeatureCollection. Podrobnosti najdete v dokumentu RFC 7946 . Všechny vlastnosti funkce by měly obsahovat `geometryId`, který se používá k identifikaci geometrie a rozlišuje velká a malá písmena. Další informace o službě registru dat najdete v tématu Vytvoření registru dat.

GeofenceMode

Režim mechanismu asynchronních událostí geografické fencing.

Name	Typ	Description
All	string	Publikujte všechny výsledky dotazů do odběru událostí účtu Azure Maps.
EnterAndExit	string	Publikujte výsledek pouze tehdy, když je umístění uživatele považováno za hraniční desku pro přechod geofencingu.

JsonFormat

Požadovaný formát odpovědi. Podporuje se pouze json formát.

Name	Typ	Description
json	string	Formát výměny dat v zápisu objektů JavaScriptu

Sdílet prostřednictvím

Spatial - Get Geofence

Kód InnerError geografické fencing

Parametry identifikátoru URI

Hlavička požadavku

Odpovědi

Zabezpečení

AADToken

Poznámky

Rozsahy

subscription-key

SAS Token

Příklady

GetGeofence

Ukázkový požadavek

Ukázková odpověď

Definice

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

Geofence

GeofenceGeometry

GeofenceMode

JsonFormat

Další materiály