Spatial - Get Geofence

Referenz

Dienst:: Maps

API-Version:: 2022-08-01

Verwenden Sie , um die Nähe einer Koordinate zu einem Geofence abzurufen.

Die Get Geofence API ist eine HTTP-Anforderung GET , die die Nähe einer Koordinate zu einem Geofence abruft, der in die Datenregistrierung hochgeladen wurde. Sie laden einen Geofence oder eine Gruppe von Zäunen in ein Azure Storage-Konto hoch und registrieren ihn dann über die Datenregistrierung bei Ihrem Azure Maps-Konto. Weitere Informationen finden Sie unter Erstellen einer Datenregistrierung. Weitere Informationen zum Geofence-Datenformat finden Sie unter Geofencing GeoJSON-Daten. Um die Nähe einer Koordinate abzufragen, geben Sie die Position des Objekts an, das Sie verfolgen, sowie die ID für den Zaun oder satz von Zäunen, und die Antwort enthält Informationen über die Entfernung vom äußeren Rand des Geofence. Ein negativer Wert bedeutet, dass sich die Koordinate innerhalb des Zauns befindet, während ein positiver Wert bedeutet, dass er sich außerhalb des Zauns befindet.

Diese API kann für eine Vielzahl von Szenarien verwendet werden, z. B. Ressourcenverfolgung, Flottenverwaltung oder Einrichten von Warnungen für das Verschieben von Objekten.

Die API unterstützt die Integration in Event Grid. Der IsAsync-Parameter wird verwendet, um die Integration in Event Grid zu aktivieren (standardmäßig deaktiviert). Um diese API zu testen, können Sie die Beispieldaten aus Beispielen der Post Geofence-API (Anforderungstext) mithilfe des Datenregistrierungsdiensts hochladen und die {udid} aus der folgenden Beispielanforderung durch die udid zum Erstellen der Datenregistrierung verwendete ersetzen. Weitere Informationen zum Datenregistrierungsdienst finden Sie unter Erstellen einer Datenregistrierung.

Geofencing InnerError-Code

Im Geofencing-Antwortfehlervertrag ist ein Objekt, innererror das dienstspezifische Informationen zum Fehler enthält. code ist eine Eigenschaft, in innererror der einem bestimmten Geofencingfehlertyp zugeordnet werden kann. Die folgende Tabelle zeigt die Codezuordnung zwischen allen bekannten Clientfehlertypen und dem entsprechenden Geofencingfehler message.

innererror.code	error.message
NullDeviceId	Die Geräte-ID sollte nicht NULL sein.
NullUdid	Udid sollte nicht NULL sein.
UdidWrongFormat	Udid sollte über die Benutzerdatenerfassungs-API abgerufen werden.
InvalidUserTime	Usertime ist ungültig.
InvalidSearchBuffer	Der Suchbuffer ist ungültig.
InvalidSearchRange	Der Wertbereich des Suchbuffers sollte zwischen 0 und 500 Metern liegen.
InvalidLatLon	Lat- und/oder lon-Parameter sind ungültig.
InvalidIsAsyncValue	Der IsAsync-Parameter ist ungültig.
InvalidModeValue	Der Modusparameter ist ungültig.
InvalidJson	Das Geofencing von Daten ist keine gültige JSON-Datei.
NotSupportedGeoJson	Geofencing-Daten können nicht als Feature oder FeatureCollections gelesen werden.
InvalidGeoJson	Das Geofencing von Daten ist ungültig.
NoUserDataWithAccountOrSubscription	Benutzergeofencingdaten mit der angegebenen Konto-ID und/oder Abonnement-ID können nicht gefunden werden.
NoUserDataWithUdid	Benutzergeofencingdaten können mit der bereitgestellten udid nicht gefunden werden.

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

Mit optionalen Parametern:

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-Parameter

Name	In	Erforderlich	Typ	Beschreibung
format	path	True	JsonFormat	Das gewünschte Format der Antwort. Nur das `json`-Format wird unterstützt.
geography	path	True	string	Speicherort des Azure Maps-Kontos. Gültige Werte sind us (USA, Osten, USA, Westen-Mitte, USA, Westen-Mitte 2) und eu (Europa, Norden, Europa, Westen). Dieser Parameter ist erforderlich, wenn in der Anforderung angegeben `udid` wird. Wenn sich das Azure Maps-Konto beispielsweise in "USA, Osten" befindet, werden nur Anforderungen an uns geografie akzeptiert.
api-version	query	True	string	Versionsnummer der Azure Maps API.
deviceId	query	True	string	ID des Geräts
lat	query	True	number	Der Breitengrad des übergebenen Standorts. Beispiel: 48.36.
lon	query	True	number	Der Längengrad des übergebenen Standorts. Beispiel: -124.63.
udid	query	True	string	Die eindeutige ID, die beim Erstellen einer Datenregistrierung zum Hochladen eines gültigen GeoJSON FeatureCollection-Objekts verwendet wird. Weitere Informationen finden Sie unter RFC 7946 . Alle Eigenschaften des Features sollten enthalten `geometryId`, was zum Identifizieren der Geometrie verwendet wird und die Groß-/Kleinschreibung beachtet. Weitere Informationen zum Datenregistrierungsdienst finden Sie unter Erstellen einer Datenregistrierung.
isAsync	query		boolean	Wenn true, verwendet die Anforderung einen asynchronen Ereignismechanismus. wenn false, wird die Anforderung synchronisiert und löst kein Ereignis aus. Der Standardwert ist „FALSE“.
mode	query		GeofenceMode	Modus des Geofencing-asynchronen Ereignismechanismus.
searchBuffer	query		number	Der Radius des Puffers um den Geofence in Metern, der definiert, wie weit innerhalb und außerhalb des Rahmens des Zauns zu der Koordinate gesucht werden soll, die bei der Berechnung des Ergebnisses angegeben wurde. Der Mindestwert ist 0, und der Höchstwert ist 500. Der Standardwert lautet "50".
userTime	query		string date-time	Die Zeit der Benutzeranforderung. Wird in der Anforderung nicht angezeigt, lautet der Standardwert DateTime.Now.
z	query		number	Der Meeresspiegel in Meter des übergebenen Standorts. Wenn dieser Parameter angezeigt wird, wird die 2D-Extrusion verwendet. Beispiel: 200.

Anforderungsheader

Name	Erforderlich	Typ	Beschreibung
x-ms-client-id		string	Gibt an, welches Konto für die Verwendung in Verbindung mit dem Microsoft Entra ID-Sicherheitsmodell vorgesehen ist. Sie stellt eine eindeutige ID für das Azure Maps-Konto dar und kann von der Konto-API der Azure Maps-Verwaltungsebene abgerufen werden. Informationen zur Verwendung der Microsoft Entra ID-Sicherheit in Azure Maps finden Sie in den folgenden Artikeln .

Antworten

Name	Typ	Beschreibung
200 OK	Geofence	OK Der X-Correlation-id-Headerwert ist in der Antwort eines asynchronen Aufrufs und in den Event Grid-Ereignisdaten vorhanden. Sie hilft dabei, die Antwort des asynchronen Aufrufs mit dem entsprechenden Event Grid-Ereignis zu korrelieren. Header X-Correlation-id: string
Other Status Codes	ErrorResponse	Ein unerwarteter Fehler ist aufgetreten.

Name

Typ

Beschreibung

200 OK

Geofence

OK Der X-Correlation-id-Headerwert ist in der Antwort eines asynchronen Aufrufs und in den Event Grid-Ereignisdaten vorhanden. Sie hilft dabei, die Antwort des asynchronen Aufrufs mit dem entsprechenden Event Grid-Ereignis zu korrelieren.

Header

X-Correlation-id: string

Other Status Codes

ErrorResponse

Ein unerwarteter Fehler ist aufgetreten.

Sicherheit

AADToken

Dies sind die Microsoft Entra OAuth 2.0-Flows . In Kombination mit der rollenbasierten Zugriffssteuerung von Azure kann sie verwendet werden, um den Zugriff auf Azure Maps-REST-APIs zu steuern. Rollenbasierte Zugriffssteuerungen in Azure werden verwendet, um den Zugriff auf ein oder mehrere Azure Maps-Ressourcenkonten oder -Unterressourcen festzulegen. Jedem Benutzer, jeder Gruppe oder einem Dienstprinzipal kann Zugriff über eine integrierte Rolle oder eine benutzerdefinierte Rolle gewährt werden, die aus einer oder mehreren Berechtigungen für Azure Maps-REST-APIs besteht.

Zur Implementierung von Szenarien wird empfohlen, Authentifizierungskonzepte anzuzeigen. Zusammenfassend bietet diese Sicherheitsdefinition eine Lösung zum Modellieren von Anwendungen über Objekte, die die Zugriffssteuerung für bestimmte APIs und Bereiche ermöglichen.

Hinweise

Diese Sicherheitsdefinition erfordert die Verwendung des x-ms-client-id Headers, um anzugeben, auf welche Azure Maps-Ressource die Anwendung Zugriff anfordert. Dies kann über die Kartenverwaltungs-API abgerufen werden.

Ist Authorization URL spezifisch für die öffentliche Azure-Cloudinstanz. Sovereign Clouds verfügen über eindeutige Autorisierungs-URLs und Microsoft Entra ID-Konfigurationen. * Die rollenbasierte Zugriffssteuerung von Azure wird über die Azure-Verwaltungsebene über das Azure-Portal, PowerShell, die CLI, Azure SDKs oder REST-APIs konfiguriert. * Die Verwendung des Azure Maps Web SDK ermöglicht die konfigurationsbasierte Einrichtung einer Anwendung für mehrere Anwendungsfälle.

Weitere Informationen zu Microsoft Identity Platform finden Sie unter Übersicht über Microsoft Identity Platform.

Typ: oauth2
Ablauf: implicit
Autorisierungs-URL: https://login.microsoftonline.com/common/oauth2/authorize

Bereiche

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

subscription-key

Dies ist ein gemeinsam verwendeter Schlüssel, der beim Erstellen einer Azure Maps-Ressource über die Azure-Verwaltungsebene über das Azure-Portal, PowerShell, die CLI, Azure SDKs oder REST-APIs bereitgestellt wird.

Mit diesem Schlüssel ist jede Anwendung für den Zugriff auf alle REST-APIs autorisiert. Mit anderen Worten, diese können derzeit als Hauptschlüssel für das Konto behandelt werden, für das sie ausgestellt werden.

Für öffentlich zugängliche Anwendungen wird empfohlen, den Server-zu-Server-Zugriff auf Azure Maps-REST-APIs zu verwenden, in denen dieser Schlüssel sicher gespeichert werden kann.

Typ: apiKey
In: header

SAS Token

Dies ist ein Shared Access Signature-Token, das aus dem SAS-Listenvorgang für die Azure Maps-Ressource über die Azure-Verwaltungsebene über das Azure-Portal, PowerShell, die CLI, Azure SDKs oder REST-APIs erstellt wird.

Mit diesem Token ist jede Anwendung für den Zugriff mit rollenbasierten Azure-Zugriffssteuerungen und einer präzisen Steuerung des Ablaufs, der Rate und der Regionen für das jeweilige Token autorisiert. Anders ausgedrückt: Das SAS-Token kann verwendet werden, um Anwendungen die Steuerung des Zugriffs auf eine sicherere Weise zu ermöglichen als der gemeinsam genutzte Schlüssel.

Für öffentlich verfügbar gemachte Anwendungen wird empfohlen, eine bestimmte Liste der zulässigen Ursprünge in der Ressource "Konto zuordnen " zu konfigurieren, um den Renderingmissbrauch zu begrenzen und das SAS-Token regelmäßig zu erneuern.

Typ: apiKey
In: header

Beispiele

GetGeofence

Beispielanforderung

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

Beispiel für eine Antwort

Statuscode:: 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
}

Definitionen

Name	Beschreibung
ErrorAdditionalInfo	Zusätzliche Informationen zum Ressourcenverwaltungsfehler.
ErrorDetail	Die Fehlerdetails.
ErrorResponse	Fehlerantwort
Geofence	Dieses Objekt wird von einem Geofence-Näherungsaufruf zurückgegeben.
GeofenceGeometry	Die Geofencinggeometrie.
GeofenceMode	Modus des Geofencing-asynchronen Ereignismechanismus.
JsonFormat	Das gewünschte Format der Antwort. Nur das `json`-Format wird unterstützt.

ErrorAdditionalInfo

Zusätzliche Informationen zum Ressourcenverwaltungsfehler.

Name	Typ	Beschreibung
info	object	Zusätzliche Informationen.
type	string	Typ der zusätzlichen Informationen.

ErrorDetail

Die Fehlerdetails.

Name	Typ	Beschreibung
additionalInfo	ErrorAdditionalInfo[]	Die zusätzlichen Fehlerinformationen.
code	string	Der Fehlercode.
details	ErrorDetail[]	Die Fehlerdetails.
message	string	Die Fehlermeldung.
target	string	Das Fehlerziel.

ErrorResponse

Fehlerantwort

Name	Typ	Beschreibung
error	ErrorDetail	Das Fehlerobjekt.

Geofence

Dieses Objekt wird von einem Geofence-Näherungsaufruf zurückgegeben.

Name	Typ	Beschreibung
expiredGeofenceGeometryId	string[]	Listet die Geometrie-ID des Geofences auf, der relativ zur Benutzerzeit in der Anforderung abgelaufen ist.
geometries	GeofenceGeometry[]	Listet die Zaungeometrien auf, die die Koordinatenposition enthalten oder sich mit dem searchBuffer überschneiden, der die Position umgibt.
invalidPeriodGeofenceGeometryId	string[]	Listet die Geometrie-ID des Geofence auf, der sich relativ zur Benutzerzeit in der Anforderung in einem ungültigen Zeitraum befindet.
isEventPublished	boolean	"True" wird wenn mindestens ein Ereignis im Azure Maps-Ereignisabonnenten veröffentlicht wurde, "false", wenn kein Ereignis im Azure Maps-Ereignisabonnenten veröffentlicht wurde. Dies wird nur als Antwort angezeigt, wenn der Abfrageparameter "isAsync" auf "true" festgelegt ist.

GeofenceGeometry

Die Geofencinggeometrie.

Name	Typ	Beschreibung
deviceId	string	ID des Geräts.
distance	number	Abstand von der Koordinate zum nächstgelegenen Rahmen des Geofence (in Metern außer bei Verwendung von Sonderwerten -999/999). Positiv bedeutet, dass die Koordinate sich außerhalb des Geofence befindet. Wenn sich die Koordinate außerhalb des Geofence befindet, aber mehr als den Wert von searchBuffer von der nächstgelegenen Geofencegrenze entfernt ist, beträgt der Wert 999. Negativ bedeutet, dass die Koordinate sich innerhalb des Geofence befindet. Wenn sich die Koordinate innerhalb des Polygons befindet, aber mehr als den Wert von searchBuffer von der nächstgelegenen Geofencegrenze entfernt ist, beträgt der Wert -999. Der Wert 999 bedeutet, dass mit großer Zuversicht davon ausgegangen werden kann, dass die Koordinate außerhalb des Geofence liegt. Der Wert -999 bedeutet, dass mit großer Zuversicht davon ausgegangen werden kann, dass die Koordinate innerhalb des Geofence liegt.
geometryId	string	Die eindeutige ID identifiziert eine Geometrie.
nearestLat	number	Breitengrad des nächstgelegenen Punkts der Geometrie.
nearestLon	number	Längengrad des nächstgelegenen Punkts der Geometrie.
nearestZ	number	Meereshöhe in Meter des nächsten Punkts der 2D-Extrusionsgeometrie. Dies wird nur als Antwort angezeigt, wenn der Wert für "zInMeter" in der Anforderung angegeben wird.
udId	string	Die eindeutige ID, die beim Erstellen einer Datenregistrierung zum Hochladen eines gültigen GeoJSON FeatureCollection-Objekts verwendet wird. Weitere Informationen finden Sie unter RFC 7946 . Alle Eigenschaften des Features sollten enthalten `geometryId`, was zum Identifizieren der Geometrie verwendet wird und die Groß-/Kleinschreibung beachtet. Weitere Informationen zum Datenregistrierungsdienst finden Sie unter Erstellen einer Datenregistrierung.

GeofenceMode

Modus des Geofencing-asynchronen Ereignismechanismus.

Name	Typ	Beschreibung
All	string	Veröffentlichen Sie alle Abfrageergebnisse im Azure Maps-Kontoereignisabonnement.
EnterAndExit	string	Veröffentlichen Sie das Ergebnis nur, wenn der Benutzerstandort als geofencing-Grenze überschritten betrachtet wird.

JsonFormat

Das gewünschte Format der Antwort. Nur das json-Format wird unterstützt.

Name	Typ	Beschreibung
json	string	Das Datenaustauschformat der JavaScript-Objektnotation

Freigeben über

Spatial - Get Geofence

Geofencing InnerError-Code

URI-Parameter

Anforderungsheader

Antworten

Sicherheit

AADToken

Hinweise

Bereiche

subscription-key

SAS Token

Beispiele

GetGeofence

Beispielanforderung

Beispiel für eine Antwort

Definitionen

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

Geofence

GeofenceGeometry

GeofenceMode

JsonFormat

Zusätzliche Ressourcen