Spatial - Get Geofence

Referenz

Service:: 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 Reihe von Zäunen in ein Azure Storage-Konto hoch und registrieren ihn dann bei Ihrem Azure Maps Konto mithilfe der Datenregistrierung. Weitere Informationen finden Sie unter Erstellen einer Datenregistrierung. Weitere Informationen zum Geofencedatenformat finden Sie unter Geofencing GeoJSON-Daten. Um die Nähe einer Koordinate abzufragen, geben Sie den Speicherort des zu verfolgenden Objekts sowie die ID für den Zaun oder satz von Zäunen an, und die Antwort enthält Informationen über die Entfernung vom äußeren Rand des Geofences. Ein negativer Wert bedeutet, dass sich die Koordinate innerhalb des Zauns befindet, während ein positiver Wert bedeutet, dass sie sich außerhalb des Zauns befindet.

Diese API kann für eine Vielzahl von Szenarien verwendet werden, die z. B. Ressourcennachverfolgung, Flottenverwaltung oder Das Einrichten von Warnungen zum Verschieben von Objekten umfassen.

Die API unterstützt die Integration in Event Grid. Der parameter isAsync wird verwendet, um die Integration mit Event Grid zu aktivieren (standardmäßig deaktiviert). Um diese API zu testen, können Sie die Beispieldaten aus post Geofence-API-Beispielen (Anforderungstext) mithilfe des Datenregistrierungsdiensts hochladen und die {udid} aus der folgenden Beispielanforderung durch die ersetzen, die udid zum Erstellen der Datenregistrierung verwendet wird. Weitere Informationen zum Datenregistrierungsdienst finden Sie unter Erstellen der 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 von der API für die Benutzerdatenerfassung abgerufen werden.
InvalidUserTime	Usertime ist ungültig.
InvalidSearchBuffer	Searchbuffer 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}

With optional parameters:

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. Es stellt eine eindeutige ID für das Azure Maps-Konto dar und kann von der konto-API auf Azure Maps Verwaltungsebene abgerufen werden. Anleitungen zur Verwendung 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 enthalten. Es hilft dabei, die Antwort des asynchronen Aufrufs mit dem entsprechenden Event Grid-Ereignis zu korrelieren. Headers 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 enthalten. Es hilft dabei, die Antwort des asynchronen Aufrufs mit dem entsprechenden Event Grid-Ereignis zu korrelieren.

Headers

X-Correlation-id: string

Other Status Codes

ErrorResponse

Ein unerwarteter Fehler ist aufgetreten.

Sicherheit

AADToken

Dies sind die Microsoft Entra OAuth 2.0 Flows. Wenn sie mit der rollenbasierten Zugriffssteuerung in Azure gekoppelt ist, 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 Ressourcenkonto oder Unterressourcen festzulegen. Jedem Benutzer, jeder Gruppe oder jedem 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.

Zum Implementieren von Szenarien empfiehlt es sich, Authentifizierungskonzepte anzuzeigen. Zusammenfassend bietet diese Sicherheitsdefinition eine Lösung zum Modellieren von Anwendungen über Objekte, die auf bestimmte APIs und Bereiche zugreifen können.

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.

Der Authorization URL ist spezifisch für die öffentliche Azure-Cloud-instance. Sovereign Clouds verfügen über eindeutige Autorisierungs-URLs und Microsoft Entra ID Konfigurationen. * Die rollenbasierte Zugriffssteuerung in Azure wird über die Azure-Verwaltungsebene über Azure-Portal, PowerShell, 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 Microsoft Identity Platform Übersicht.

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

Scopes

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

subscription-key

Dies ist ein gemeinsam genutzter Schlüssel, der beim Erstellen einer Azure Maps Ressource über die Azure-Verwaltungsebene über Azure-Portal, PowerShell, 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 master Schlü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.

Type: apiKey
In: header

SAS Token

Hierbei handelt es sich um ein Shared Access Signature Token, das aus dem Sas-Listenvorgang auf der Azure Maps-Ressource über die Azure-Verwaltungsebene über Azure-Portal, PowerShell, CLI, Azure SDKs oder REST-APIs erstellt wird.

Mit diesem Token ist jede Anwendung autorisiert, mit rollenbasierten Zugriffssteuerungen in Azure auf den Ablauf, die Rate und die Region(en) der Verwendung für das jeweilige Token zuzugreifen. Mit anderen Worten, das SAS-Token kann verwendet werden, um Anwendungen zu ermöglichen, den Zugriff auf eine sicherere Weise als der freigegebene Schlüssel zu steuern.

Für öffentlich zugängliche Anwendungen empfiehlt es sich, eine bestimmte Liste der zulässigen Ursprünge für die Zuordnungskontoressource zu konfigurieren, um den Renderingmissbrauch zu begrenzen und das SAS-Token regelmäßig zu erneuern.

Type: apiKey
In: header

Beispiele

GetGeofence

Sample Request

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

Sample Response

Status code:: 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	Gewünschtes 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[]	Listen der Geometrie-ID des Geofences, 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[]	Listen der Geometrie-ID des Geofences, der sich in einem ungültigen Zeitraum relativ zur Benutzerzeit in der Anforderung 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 Rand 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	Meeresspiegel 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 der Datenregistrierung.

GeofenceMode

Modus des Geofencing-asynchronen Ereignismechanismus.

Name	Typ	Beschreibung
All	string	Veröffentlichen Sie alle Abfrageergebnisse in Azure Maps Kontoereignisabonnement.
EnterAndExit	string	Veröffentlichen Sie das Ergebnis nur, wenn der Benutzerspeicherort als Kreuzung der Geofencing-Begrenzung betrachtet wird.

JsonFormat

Gewünschtes Format der Antwort. Nur das json-Format wird unterstützt.

Name	Typ	Beschreibung
json	string	Das Datenaustauschformat der JavaScript-Objektnotation

Share via

Spatial - Get Geofence

Geofencing InnerError-Code

URI-Parameter

Anforderungsheader

Antworten

Sicherheit

AADToken

Hinweise

Scopes

subscription-key

SAS Token

Beispiele

GetGeofence

Sample Request

Sample Response

Definitionen

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

Geofence

GeofenceGeometry

GeofenceMode

JsonFormat

Zusätzliche Ressourcen