Udostępnij za pośrednictwem


Spatial - Post Geofence

Służy do zbliżenia współrzędnych do geofencingu.

Interfejs Post Geofence API to żądanie HTTP POST , które pobiera bliskość współrzędnych do dostarczonego ogrodzenia lub zestawu ogrodzeń. W przypadku POST żądań nie trzeba wcześniej przekazywać danych ogrodzenia, zamiast tego podać lokalizację obiektu, który śledzisz w parametrach zapytania, a także ogrodzenie lub zestaw danych ogrodzenia w treści żądania. Aby uzyskać więcej informacji na temat formatu danych geofencing, zobacz Geofencing GeoJSON data (Geofencing GeoJSON). Odpowiedź będzie zawierać informacje o odległości od zewnętrznej krawędzi geofencingu. Wartość ujemna oznacza, że współrzędna znajduje się wewnątrz ogrodzenia, a wartość dodatnia oznacza, że znajduje się poza ogrodzeniem.

Ten interfejs API może być używany w różnych scenariuszach, takich jak śledzenie zasobów, zarządzanie flotą lub konfigurowanie alertów dotyczących przenoszenia obiektów.

Interfejs API obsługuje integrację z usługą Event Grid. Parametr isAsync służy do włączania integracji z usługą Event Grid (domyślnie wyłączone).

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}

Parametry identyfikatora URI

Nazwa W Wymagane Typ Opis
format
path True

JsonFormat

Żądany format odpowiedzi. Obsługiwany jest tylko json format.

geography
path True

string

Lokalizacja konta usługi Azure Maps. Prawidłowe wartości to nas (Wschodnie stany USA, Zachodnio-środkowe stany USA, Zachodnie stany USA 2) i eu (Europa Północna, Europa Zachodnia). Ten parametr jest wymagany, gdy udid element jest dostarczany w żądaniu. Jeśli na przykład konto usługi Azure Maps znajduje się w regionie Wschodnie stany USA, zostaną zaakceptowane tylko żądania dotyczące lokalizacji geograficznej.

api-version
query True

string

Numer wersji interfejsu API usługi Azure Maps.

deviceId
query True

string

Identyfikator urządzenia

lat
query True

number

Szerokość geograficzna przekazywanej lokalizacji. Przykład: 48.36.

lon
query True

number

Długość geograficzna przekazywanej lokalizacji. Przykład: -124.63.

isAsync
query

boolean

Jeśli wartość true, żądanie będzie używać mechanizmu zdarzeń asynchronicznych; Jeśli wartość false, żądanie zostanie zsynchronizowane i nie wyzwoli żadnego zdarzenia. Wartość domyślna to false.

mode
query

GeofenceMode

Tryb geofencingu mechanizmu zdarzeń asynchronicznych.

searchBuffer
query

number

Promień buforu wokół geofencingu w metrach, który określa, jak daleko szukać wewnątrz i poza granicą ogrodzenia względem współrzędnych podanych podczas obliczania wyniku. Wartość minimalna to 0, a wartość maksymalna to 500. Wartość domyślna to 50.

userTime
query

string

date-time

Czas żądania użytkownika. Jeśli nie zostanie wyświetlona w żądaniu, wartość domyślna to DateTime.UtcNow.

z
query

number

Poziom morza w mierniku lokalizacji, która jest przekazywana. Jeśli ten parametr zostanie przedstawiony, stosowane jest ekstruzji geofencingu 2D. Przykład: 200.

Nagłówek żądania

Nazwa Wymagane Typ Opis
x-ms-client-id

string

Określa, które konto jest przeznaczone do użycia w połączeniu z modelem zabezpieczeń Microsoft Entra ID. Reprezentuje unikatowy identyfikator konta usługi Azure Maps i można go pobrać z interfejsu API konta płaszczyzny zarządzania usługi Azure Maps. Aby użyć zabezpieczeń identyfikatora Entra firmy Microsoft w usłudze Azure Maps, zobacz następujące artykuły , aby uzyskać wskazówki.

Treść żądania

Nazwa Wymagane Typ Opis
features True

GeoJsonFeature[]

Zawiera listę prawidłowych GeoJSON Feature obiektów.

type True string:

FeatureCollection

Określa GeoJSON typ. Musi być jednym z dziewięciu prawidłowych typów obiektów GeoJSON — Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature i FeatureCollection.

Odpowiedzi

Nazwa Typ Opis
200 OK

Geofence

OK Wartość nagłówka X-Correlation-id znajduje się w odpowiedzi wywołania asynchronicznego i danych zdarzenia usługi Event Grid. Pomaga skorelować odpowiedź wywołania asynchronicznego z odpowiednim zdarzeniem usługi Event Grid.

Nagłówki

X-Correlation-id: string

Other Status Codes

ErrorResponse

Wystąpił nieoczekiwany błąd.

Zabezpieczenia

AADToken

Są to przepływy protokołu Microsoft Entra OAuth 2.0 . Po połączeniu z kontrolą dostępu opartą na rolach platformy Azure można użyć jej do kontrolowania dostępu do interfejsów API REST usługi Azure Maps. Mechanizmy kontroli dostępu opartej na rolach platformy Azure służą do wyznaczania dostępu do co najmniej jednego konta zasobu usługi Azure Maps lub zasobów podrzędnych. Każdy użytkownik, grupa lub jednostka usługi może mieć dostęp za pośrednictwem wbudowanej roli lub roli niestandardowej składającej się z co najmniej jednego uprawnienia do interfejsów API REST usługi Azure Maps.

Aby zaimplementować scenariusze, zalecamy wyświetlenie pojęć związanych z uwierzytelnianiem. Podsumowując, ta definicja zabezpieczeń stanowi rozwiązanie do modelowania aplikacji za pośrednictwem obiektów, które mogą kontrolować dostęp do określonych interfejsów API i zakresów.

Uwagi

  • Ta definicja zabezpieczeń wymaga użycia nagłówka x-ms-client-id w celu wskazania, do którego zasobu usługi Azure Maps aplikacja żąda dostępu. Można to uzyskać z poziomu interfejsu API zarządzania usługami Maps.

Element Authorization URL jest specyficzny dla wystąpienia chmury publicznej platformy Azure. Suwerenne chmury mają unikatowe adresy URL autoryzacji i konfiguracje identyfikatorów Entra firmy Microsoft. * Kontrola dostępu oparta na rolach platformy Azure jest konfigurowana z poziomu płaszczyzny zarządzania platformy Azure za pośrednictwem witryny Azure Portal, programu PowerShell, interfejsu wiersza polecenia, zestawów Azure SDK lub interfejsów API REST. * Użycie zestawu SDK sieci Web usługi Azure Maps umożliwia skonfigurowanie aplikacji na podstawie konfiguracji dla wielu przypadków użycia.

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

Scopes

Nazwa Opis
https://atlas.microsoft.com/.default https://atlas.microsoft.com/.default

subscription-key

Jest to klucz współużytkowany podczas tworzenia zasobu usługi Azure Maps za pośrednictwem płaszczyzny zarządzania platformy Azure za pośrednictwem witryny Azure Portal, programu PowerShell, interfejsu wiersza polecenia, zestawów AZURE SDK lub interfejsów API REST.

Za pomocą tego klucza każda aplikacja jest autoryzowana do uzyskiwania dostępu do wszystkich interfejsów API REST. Innymi słowy, mogą one być obecnie traktowane jako klucze główne dla konta, dla którego są wystawiane.

W przypadku publicznie uwidocznionych aplikacji zalecamy użycie dostępu serwer-serwer do interfejsów API REST usługi Azure Maps, w których ten klucz może być bezpiecznie przechowywany.

Typ: apiKey
W: header

SAS Token

Jest to token sygnatury dostępu współdzielonego tworzony na podstawie operacji list SYGNATUR dostępu współdzielonego w zasobie usługi Azure Maps za pośrednictwem płaszczyzny zarządzania platformy Azure za pośrednictwem witryny Azure Portal, programu PowerShell, interfejsu wiersza polecenia, zestawów AZURE SDK lub interfejsów API REST.

Dzięki temu tokenowi każda aplikacja jest autoryzowana do uzyskiwania dostępu za pomocą kontroli dostępu opartej na rolach platformy Azure oraz szczegółowej kontroli wygaśnięcia, szybkości i regionów użycia dla określonego tokenu. Innymi słowy, token SAS może służyć do umożliwienia aplikacjom kontrolowania dostępu w sposób bardziej bezpieczny niż klucz wspólny.

W przypadku publicznie uwidocznionych aplikacji zalecamy skonfigurowanie określonej listy dozwolonych źródeł w zasobie konta mapy w celu ograniczenia nadużyć renderowania i regularnego odnawiania tokenu SAS.

Typ: apiKey
W: header

Przykłady

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
}

Definicje

Nazwa Opis
ErrorAdditionalInfo

Dodatkowe informacje o błędzie zarządzania zasobami.

ErrorDetail

Szczegóły błędu.

ErrorResponse

Odpowiedź na błąd

Geofence

Ten obiekt jest zwracany z wywołania zbliżeniowego geofencingu.

GeofenceGeometry

Geometria geofencingu.

GeofenceMode

Tryb geofencingu mechanizmu zdarzeń asynchronicznych.

GeoJsonFeature

Prawidłowy GeoJSON Feature typ obiektu. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

GeoJsonFeatureCollection

Prawidłowy GeoJSON FeatureCollection typ obiektu. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

GeoJsonGeometry

Prawidłowy GeoJSON obiekt geometryczny. Typ musi być jednym z siedmiu prawidłowych typów geometrii GeoJSON — Punkt, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon i GeometryCollection. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

GeoJsonGeometryCollection

Prawidłowy GeoJSON GeometryCollection typ obiektu. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

GeoJsonLineString

Prawidłowy GeoJSON LineString typ geometrii. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

GeoJsonMultiLineString

Prawidłowy GeoJSON MultiLineString typ geometrii. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

GeoJsonMultiPoint

Prawidłowy GeoJSON MultiPoint typ geometrii. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

GeoJsonMultiPolygon

Prawidłowy GeoJSON MultiPolygon typ obiektu. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

GeoJsonPoint

Prawidłowy GeoJSON Point typ geometrii. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

GeoJsonPolygon

Prawidłowy GeoJSON Polygon typ geometrii. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

JsonFormat

Żądany format odpowiedzi. Obsługiwany jest tylko json format.

ErrorAdditionalInfo

Dodatkowe informacje o błędzie zarządzania zasobami.

Nazwa Typ Opis
info

object

Dodatkowe informacje.

type

string

Dodatkowy typ informacji.

ErrorDetail

Szczegóły błędu.

Nazwa Typ Opis
additionalInfo

ErrorAdditionalInfo[]

Dodatkowe informacje o błędzie.

code

string

Kod błędu.

details

ErrorDetail[]

Szczegóły błędu.

message

string

Komunikat o błędzie.

target

string

Element docelowy błędu.

ErrorResponse

Odpowiedź na błąd

Nazwa Typ Opis
error

ErrorDetail

Obiekt error.

Geofence

Ten obiekt jest zwracany z wywołania zbliżeniowego geofencingu.

Nazwa Typ Opis
expiredGeofenceGeometryId

string[]

Lista identyfikatora geometrii geofencingu, który wygasł względem czasu użytkownika w żądaniu.

geometries

GeofenceGeometry[]

Wyświetla listę geometrii ogrodzenia, które zawierają położenie współrzędnych lub nakładają się na wartość searchBuffer wokół pozycji.

invalidPeriodGeofenceGeometryId

string[]

Lista identyfikatora geometrii geofencingu, który jest nieprawidłowy w stosunku do czasu użytkownika w żądaniu.

isEventPublished

boolean

Prawda, jeśli co najmniej jedno zdarzenie zostało opublikowane dla subskrybenta zdarzeń usługi Azure Maps, wartość false, jeśli żadne zdarzenie nie zostało opublikowane dla subskrybenta zdarzenia usługi Azure Maps. Zostanie on przedstawiony tylko w odpowiedzi, gdy parametr zapytania "isAsync" jest ustawiony na wartość true.

GeofenceGeometry

Geometria geofencingu.

Nazwa Typ Opis
deviceId

string

Identyfikator urządzenia.

distance

number

Odległość od współrzędnych do najbliższego obramowania geofencingu (w metrach z wyjątkiem sytuacji, gdy są używane wartości specjalne -999/999). Dodatnie oznacza, że współrzędna znajduje się poza ogrodzeniem geograficznym. Jeśli współrzędna znajduje się poza ogrodnicą geograficzną, ale więcej niż wartość parametru searchBuffer od najbliższego obramowania geofencingu, wartość wynosi 999. Ujemna oznacza, że współrzędna znajduje się wewnątrz geofencingu. Jeśli współrzędna znajduje się wewnątrz wielokąta, ale więcej niż wartość searchBuffer od najbliższego obramowania geofencingu, wartość to -999. Wartość 999 oznacza, że istnieje duża pewność, że współrzędna znajduje się daleko poza geofencingiem. Wartość -999 oznacza, że istnieje duża pewność, że współrzędna jest dobrze w obrębie geofencingu.

geometryId

string

Unikatowy identyfikator identyfikuje geometrię.

nearestLat

number

Szerokość geograficzna najbliższego punktu geometrii.

nearestLon

number

Długość geograficzna najbliższego punktu geometrii.

nearestZ

number

Poziom morza w mierniku najbliższego punktu na geometrii ekstruzji 2D. Ta wartość będzie wyświetlana tylko w odpowiedzi, gdy w żądaniu zostanie podana wartość "zInMeter".

udId

string

Unikatowy identyfikator używany podczas tworzenia rejestru danych w celu przekazania prawidłowego obiektu FeatureCollection w formacie GeoJSON. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 . Wszystkie właściwości funkcji powinny zawierać geometryIdelement , który służy do identyfikowania geometrii i uwzględnia wielkość liter. Aby uzyskać więcej informacji na temat usługi rejestru danych, zobacz Jak utworzyć rejestr danych.

GeofenceMode

Tryb geofencingu mechanizmu zdarzeń asynchronicznych.

Nazwa Typ Opis
All

string

Opublikuj wszystkie wyniki zapytania w subskrypcji zdarzeń konta usługi Azure Maps.

EnterAndExit

string

Publikuj wynik tylko wtedy, gdy lokalizacja użytkownika jest uznawana za przekroczenie tablicy geofencingu.

GeoJsonFeature

Prawidłowy GeoJSON Feature typ obiektu. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

Nazwa Typ Opis
featureType

string

Typ funkcji. Wartość zależy od modelu danych, do której należy bieżąca funkcja. Niektóre modele danych mogą mieć pustą wartość.

geometry GeoJsonGeometry:

Prawidłowy GeoJSON obiekt geometryczny. Typ musi być jednym z siedmiu prawidłowych typów geometrii GeoJSON — Punkt, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon i GeometryCollection. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

id

string

Identyfikator funkcji.

type string:

Feature

Określa GeoJSON typ. Musi być jednym z dziewięciu prawidłowych typów obiektów GeoJSON — Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature i FeatureCollection.

GeoJsonFeatureCollection

Prawidłowy GeoJSON FeatureCollection typ obiektu. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

Nazwa Typ Opis
features

GeoJsonFeature[]

Zawiera listę prawidłowych GeoJSON Feature obiektów.

type string:

FeatureCollection

Określa GeoJSON typ. Musi być jednym z dziewięciu prawidłowych typów obiektów GeoJSON — Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature i FeatureCollection.

GeoJsonGeometry

Prawidłowy GeoJSON obiekt geometryczny. Typ musi być jednym z siedmiu prawidłowych typów geometrii GeoJSON — Punkt, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon i GeometryCollection. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

Nazwa Typ Opis
type

GeoJsonObjectType

Określa GeoJSON typ. Musi być jednym z dziewięciu prawidłowych typów obiektów GeoJSON — Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature i FeatureCollection.

GeoJsonGeometryCollection

Prawidłowy GeoJSON GeometryCollection typ obiektu. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

Nazwa Typ Opis
geometries GeoJsonGeometry[]:

Zawiera listę prawidłowych GeoJSON obiektów geometrycznych. Należy pamiętać , że współrzędne w formacie GeoJSON są w kolejności x, y (długość geograficzna, szerokość geograficzna).

type string:

GeometryCollection

Określa GeoJSON typ. Musi być jednym z dziewięciu prawidłowych typów obiektów GeoJSON — Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature i FeatureCollection.

GeoJsonLineString

Prawidłowy GeoJSON LineString typ geometrii. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

Nazwa Typ Opis
coordinates

number[]

Współrzędne geometrii GeoJson LineString .

type string:

LineString

Określa GeoJSON typ. Musi być jednym z dziewięciu prawidłowych typów obiektów GeoJSON — Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature i FeatureCollection.

GeoJsonMultiLineString

Prawidłowy GeoJSON MultiLineString typ geometrii. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

Nazwa Typ Opis
coordinates

number[]

Współrzędne geometrii GeoJson MultiLineString .

type string:

MultiLineString

Określa GeoJSON typ. Musi być jednym z dziewięciu prawidłowych typów obiektów GeoJSON — Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature i FeatureCollection.

GeoJsonMultiPoint

Prawidłowy GeoJSON MultiPoint typ geometrii. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

Nazwa Typ Opis
coordinates

number[]

Współrzędne geometrii GeoJson MultiPoint .

type string:

MultiPoint

Określa GeoJSON typ. Musi być jednym z dziewięciu prawidłowych typów obiektów GeoJSON — Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature i FeatureCollection.

GeoJsonMultiPolygon

Prawidłowy GeoJSON MultiPolygon typ obiektu. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

Nazwa Typ Opis
coordinates

number[]

Zawiera listę prawidłowych GeoJSON Polygon obiektów. Należy pamiętać , że współrzędne w formacie GeoJSON są w kolejności x, y (długość geograficzna, szerokość geograficzna).

type string:

MultiPolygon

Określa GeoJSON typ. Musi być jednym z dziewięciu prawidłowych typów obiektów GeoJSON — Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature i FeatureCollection.

GeoJsonPoint

Prawidłowy GeoJSON Point typ geometrii. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

Nazwa Typ Opis
coordinates

number[]

A Position to tablica liczb z co najmniej dwoma elementami. Pierwsze dwa elementy to długość geograficzna i szerokość geograficzna, dokładnie w tej kolejności. Wysokość/wysokość jest opcjonalnym trzecim elementem. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

type string:

Point

Określa GeoJSON typ. Musi być jednym z dziewięciu prawidłowych typów obiektów GeoJSON — Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature i FeatureCollection.

GeoJsonPolygon

Prawidłowy GeoJSON Polygon typ geometrii. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .

Nazwa Typ Opis
coordinates

number[]

Współrzędne dla GeoJson Polygon typu geometrii.

type string:

Polygon

Określa GeoJSON typ. Musi być jednym z dziewięciu prawidłowych typów obiektów GeoJSON — Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature i FeatureCollection.

JsonFormat

Żądany format odpowiedzi. Obsługiwany jest tylko json format.

Nazwa Typ Opis
json

string

Format wymiany danych notacji obiektów JavaScript