Share via


Spatial - Post Geofence

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

Die Post Geofence API ist eine HTTP-Anforderung POST , die die Nähe einer Koordinate zu einem bereitgestellten Geofence oder einer Gruppe von Zäunen abruft. Bei POST Anforderungen müssen Sie die Zaundaten nicht im Voraus hochladen, sondern geben den Speicherort des Objekts an, das Sie in Abfrageparametern nachverfolgen, sowie die Zaun- oder Zäunedaten im Post-Anforderungstext. Weitere Informationen zum Geofencedatenformat finden Sie unter Geofencing GeoJSON-Daten. 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).

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

Name In Erforderlich Typ Beschreibung
format
path True

JsonFormat

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

geography
path True

string

Standort des Azure Maps-Kontos. Gültige Werte sind us (USA, Osten, USA, Westen, Mitte, Usa, Westen 2) und eu (Europa, Norden, Europa, Westen). Dieser Parameter ist erforderlich, wenn ein udid in der Anforderung angegeben wird. Wenn sich das Azure Maps-Konto beispielsweise in den USA, Osten befindet, werden nur Anfragen 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.

isAsync
query

boolean

Wenn true, verwendet die Anforderung den 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 der Grenze des Zauns mit der Koordinate gesucht werden soll, die bei der Berechnung des Ergebnisses angegeben wurde. Der Mindestwert ist 0, und das Maximum ist 500. Der Standardwert lautet "50".

userTime
query

string

date-time

Die Benutzeranforderungszeit. Wenn in der Anforderung nicht angezeigt wird, lautet der Standardwert DateTime.UtcNow.

z
query

number

Der Meeresspiegel in Meter des zu übergebenden Standorts. Wenn dieser Parameter angezeigt wird, wird das 2D-Extrusionsgeofencing angewendet. 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.

Anforderungstext

Name Erforderlich Typ Beschreibung
features True

GeoJsonFeature[]

Enthält eine Liste gültiger GeoJSON Feature Objekte.

type True string:

FeatureCollection

Gibt den GeoJSON-Typ an. Muss einer der neun gültigen GeoJSON-Objekttypen sein: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature und FeatureCollection.

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.

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.

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

PostGeofence

Sample Request

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"
      }
    }
  ]
}

Sample Response

{
  "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
}

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.

GeoJsonFeature

Ein gültiger GeoJSON Feature Objekttyp. Weitere Informationen finden Sie unter RFC 7946 .

GeoJsonFeatureCollection

Ein gültiger GeoJSON FeatureCollection Objekttyp. Weitere Informationen finden Sie unter RFC 7946 .

GeoJsonGeometry

Ein gültiges GeoJSON geometry-Objekt. Der Typ muss einer der sieben gültigen GeoJSON-Geometrietypen sein: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon und GeometryCollection. Weitere Informationen finden Sie unter RFC 7946 .

GeoJsonGeometryCollection

Ein gültiger GeoJSON GeometryCollection Objekttyp. Weitere Informationen finden Sie unter RFC 7946 .

GeoJsonLineString

Ein gültiger GeoJSON LineString Geometrietyp. Weitere Informationen finden Sie unter RFC 7946 .

GeoJsonMultiLineString

Ein gültiger GeoJSON MultiLineString Geometrietyp. Weitere Informationen finden Sie unter RFC 7946 .

GeoJsonMultiPoint

Ein gültiger GeoJSON MultiPoint Geometrietyp. Weitere Informationen finden Sie unter RFC 7946 .

GeoJsonMultiPolygon

Ein gültiger GeoJSON MultiPolygon Objekttyp. Weitere Informationen finden Sie unter RFC 7946 .

GeoJsonPoint

Ein gültiger GeoJSON Point Geometrietyp. Weitere Informationen finden Sie unter RFC 7946 .

GeoJsonPolygon

Ein gültiger GeoJSON Polygon Geometrietyp. Weitere Informationen finden Sie unter RFC 7946 .

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[]

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 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 in Azure Maps Kontoereignisabonnement.

EnterAndExit

string

Veröffentlichen Sie das Ergebnis nur, wenn der Benutzerstandort als geofencing-Grenze überschritten betrachtet wird.

GeoJsonFeature

Ein gültiger GeoJSON Feature Objekttyp. Weitere Informationen finden Sie unter RFC 7946 .

Name Typ Beschreibung
featureType

string

Der Funktionstyp Der Wert hängt vom Datenmodell ab, zu dem das aktuelle Feature gehört. Einige Datenmodelle verfügen möglicherweise über einen leeren Wert.

geometry GeoJsonGeometry:

Ein gültiges GeoJSON geometry-Objekt. Der Typ muss einer der sieben gültigen GeoJSON-Geometrietypen sein: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon und GeometryCollection. Weitere Informationen finden Sie unter RFC 7946 .

id

string

Bezeichner für das Feature.

type string:

Feature

Gibt den GeoJSON-Typ an. Muss einer der neun gültigen GeoJSON-Objekttypen sein: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature und FeatureCollection.

GeoJsonFeatureCollection

Ein gültiger GeoJSON FeatureCollection Objekttyp. Weitere Informationen finden Sie unter RFC 7946 .

Name Typ Beschreibung
features

GeoJsonFeature[]

Enthält eine Liste gültiger GeoJSON Feature Objekte.

type string:

FeatureCollection

Gibt den GeoJSON-Typ an. Muss einer der neun gültigen GeoJSON-Objekttypen sein: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature und FeatureCollection.

GeoJsonGeometry

Ein gültiges GeoJSON geometry-Objekt. Der Typ muss einer der sieben gültigen GeoJSON-Geometrietypen sein: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon und GeometryCollection. Weitere Informationen finden Sie unter RFC 7946 .

Name Typ Beschreibung
type

GeoJsonObjectType

Gibt den GeoJSON-Typ an. Muss einer der neun gültigen GeoJSON-Objekttypen sein: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature und FeatureCollection.

GeoJsonGeometryCollection

Ein gültiger GeoJSON GeometryCollection Objekttyp. Weitere Informationen finden Sie unter RFC 7946 .

Name Typ Beschreibung
geometries GeoJsonGeometry[]:

Enthält eine Liste gültiger GeoJSON Geometrieobjekte. Beachten Sie , dass die Koordinaten in GeoJSON in x,y-Reihenfolge (Längengrad, Breitengrad) liegen.

type string:

GeometryCollection

Gibt den GeoJSON-Typ an. Muss einer der neun gültigen GeoJSON-Objekttypen sein: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature und FeatureCollection.

GeoJsonLineString

Ein gültiger GeoJSON LineString Geometrietyp. Weitere Informationen finden Sie unter RFC 7946 .

Name Typ Beschreibung
coordinates

number[]

Koordinaten für die GeoJson LineString Geometrie.

type string:

LineString

Gibt den GeoJSON-Typ an. Muss einer der neun gültigen GeoJSON-Objekttypen sein: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature und FeatureCollection.

GeoJsonMultiLineString

Ein gültiger GeoJSON MultiLineString Geometrietyp. Weitere Informationen finden Sie unter RFC 7946 .

Name Typ Beschreibung
coordinates

number[]

Koordinaten für die GeoJson MultiLineString Geometrie.

type string:

MultiLineString

Gibt den GeoJSON-Typ an. Muss einer der neun gültigen GeoJSON-Objekttypen sein: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature und FeatureCollection.

GeoJsonMultiPoint

Ein gültiger GeoJSON MultiPoint Geometrietyp. Weitere Informationen finden Sie unter RFC 7946 .

Name Typ Beschreibung
coordinates

number[]

Koordinaten für die GeoJson MultiPoint Geometrie.

type string:

MultiPoint

Gibt den GeoJSON-Typ an. Muss einer der neun gültigen GeoJSON-Objekttypen sein: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature und FeatureCollection.

GeoJsonMultiPolygon

Ein gültiger GeoJSON MultiPolygon Objekttyp. Weitere Informationen finden Sie unter RFC 7946 .

Name Typ Beschreibung
coordinates

number[]

Enthält eine Liste gültiger GeoJSON Polygon Objekte. Beachten Sie , dass die Koordinaten in GeoJSON in der Reihenfolge x, y (Längengrad, Breitengrad) liegen.

type string:

MultiPolygon

Gibt den GeoJSON-Typ an. Muss einer der neun gültigen GeoJSON-Objekttypen sein: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature und FeatureCollection.

GeoJsonPoint

Ein gültiger GeoJSON Point Geometrietyp. Weitere Informationen finden Sie unter RFC 7946 .

Name Typ Beschreibung
coordinates

number[]

Ein Position ist ein Array von Zahlen mit zwei oder mehr Elementen. Die ersten beiden Elemente sind Längen- und Breitengrad, genau in dieser Reihenfolge. Höhe/Höhe ist ein optionales drittes Element. Weitere Informationen finden Sie unter RFC 7946 .

type string:

Point

Gibt den GeoJSON-Typ an. Muss einer der neun gültigen GeoJSON-Objekttypen sein: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature und FeatureCollection.

GeoJsonPolygon

Ein gültiger GeoJSON Polygon Geometrietyp. Weitere Informationen finden Sie unter RFC 7946 .

Name Typ Beschreibung
coordinates

number[]

Koordinaten für den GeoJson Polygon geometry-Typ.

type string:

Polygon

Gibt den GeoJSON-Typ an. Muss einer der neun gültigen GeoJSON-Objekttypen sein: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature und FeatureCollection.

JsonFormat

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

Name Typ Beschreibung
json

string

Das Datenaustauschformat der JavaScript-Objektnotation