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 zbliżenie współrzędnych do podanego geofencingu lub zestawu ogrodzeń. W przypadku POST
żądań nie trzeba wcześniej przekazywać danych ogrodzenia, zamiast tego należy 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 geofencingu, zobacz Geofencing GeoJSON data (Dane geofencingu GeoJSON). Odpowiedź będzie zawierać informacje o odległości od zewnętrznej krawędzi geofencencji. Wartość ujemna oznacza, że współrzędna znajduje się wewnątrz ogrodzenia, podczas gdy wartość dodatnia oznacza, że znajduje się poza ogrodzeniem.
Ten interfejs API może służyć do różnych scenariuszy, takich jak śledzenie zasobów, zarządzanie flotą lub konfigurowanie alertów dotyczących ruchomych 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 |
Żądany format odpowiedzi. Obsługiwany jest tylko |
|
geography
|
path | True |
string |
Lokalizacja konta Azure Maps. Prawidłowe wartości to nas (Wschodnie stany USA, Zachodnie stany USA, Zachodnie stany USA 2) i eu (Europa Północna, Europa Zachodnia). Ten parametr jest wymagany, gdy |
api-version
|
query | True |
string |
Numer wersji interfejsu API Azure Maps. |
device
|
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. |
is
|
query |
boolean |
Jeśli to prawda, żą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 |
Tryb mechanizmu zdarzeń asynchronicznych geofencingu. |
||
search
|
query |
number |
Promień buforu wokół geofencencji w metrach, który definiuje, 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. |
|
user
|
query |
string date-time |
Czas żądania użytkownika. Jeśli żądanie nie zostanie przedstawione, wartość domyślna to DateTime.UtcNow. |
|
z
|
query |
number |
Poziom morza w mierniku przekazywanej lokalizacji. Jeśli ten parametr zostanie przedstawiony, zastosowano geofencing 2D 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ń Tożsamość Microsoft Entra. Reprezentuje unikatowy identyfikator konta Azure Maps i można go pobrać z interfejsu API konta płaszczyzny zarządzania Azure Maps. Aby użyć zabezpieczeń Tożsamość Microsoft Entra w usłudze Azure Maps, zobacz następujące artykuły, aby uzyskać wskazówki. |
Treść żądania
Nazwa | Wymagane | Typ | Opis |
---|---|---|---|
features | True |
Zawiera listę prawidłowych |
|
type | True |
string:
Feature |
Określa |
Odpowiedzi
Nazwa | Typ | Opis |
---|---|---|
200 OK |
OK Wartość nagłówka X-Correlation-id jest obecna w odpowiedzi wywołania asynchronicznego i danych zdarzeń usługi Event Grid. Pomaga skorelować odpowiedź wywołania asynchronicznego z odpowiednim zdarzeniem usługi Event Grid. Headers X-Correlation-id: string |
|
Other Status Codes |
Wystąpił nieoczekiwany błąd. |
Zabezpieczenia
AADToken
Są to przepływy protokołu OAuth 2.0 Microsoft Entra. W połączeniu z kontrolą dostępu opartą na rolach platformy Azure może służyć do kontrolowania dostępu do interfejsów API REST Azure Maps. Mechanizmy kontroli dostępu opartej na rolach platformy Azure służą do wyznaczania dostępu do co najmniej jednego konta zasobów 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 Azure Maps interfejsów API REST.
Aby zaimplementować scenariusze, zalecamy wyświetlenie pojęć dotyczących uwierzytelniania. Podsumowując, ta definicja zabezpieczeń udostępnia 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
, aby wskazać, do którego zasobu Azure Maps aplikacja żąda dostępu. Można to uzyskać za pomocą interfejsu API zarządzania mapami.
Element Authorization URL
jest specyficzny dla wystąpienia chmury publicznej platformy Azure. Suwerenne chmury mają unikatowe adresy URL autoryzacji i konfiguracje Tożsamość Microsoft Entra.
* Kontrola dostępu oparta na rolach platformy Azure jest konfigurowana z płaszczyzny zarządzania platformy Azure za pośrednictwem Azure Portal, programu PowerShell, interfejsu wiersza polecenia, zestawów SDK platformy Azure lub interfejsów API REST.
* Użycie zestawu AZURE MAPS Web SDK umożliwia konfigurację opartą na konfiguracji aplikacji w wielu przypadkach użycia.
- Aby uzyskać więcej informacji na temat Platforma tożsamości Microsoft, zobacz omówienie Platforma tożsamości Microsoft.
Type:
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ólny aprowizowany podczas tworzenia zasobu Azure Maps za pośrednictwem płaszczyzny zarządzania platformy Azure za pośrednictwem Azure Portal, programu PowerShell, interfejsu wiersza polecenia, zestawów SDK platformy Azure lub interfejsów API REST.
Przy użyciu 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 do konta, dla którego są wystawiane.
W przypadku publicznie uwidocznionych aplikacji naszym zaleceniem jest użycie dostępu do serwera Azure Maps interfejsów API REST, w których ten klucz może być bezpiecznie przechowywany.
Type:
apiKey
In:
header
SAS Token
Jest to token sygnatury dostępu współdzielonego tworzony na podstawie operacji listy sygnatur dostępu współdzielonego w zasobie Azure Maps za pośrednictwem płaszczyzny zarządzania platformy Azure za pośrednictwem Azure Portal, programu PowerShell, interfejsu wiersza polecenia, zestawów SDK platformy Azure lub interfejsów API REST.
Przy użyciu tego tokenu każda aplikacja jest autoryzowana do uzyskiwania dostępu za pomocą kontroli dostępu opartej na rolach platformy Azure i szczegółowej kontroli wygaśnięcia, szybkości i regionów użycia dla określonego tokenu. Innymi słowy, token sygnatury dostępu współdzielonego może służyć do umożliwienia aplikacjom kontrolowania dostępu w bardziej bezpieczny sposób 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 SYGNATURy dostępu współdzielonego.
Type:
apiKey
In:
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 |
---|---|
Error |
Dodatkowe informacje o błędzie zarządzania zasobami. |
Error |
Szczegóły błędu. |
Error |
Odpowiedź na błąd |
Geofence |
Ten obiekt jest zwracany z wywołania zbliżeniowego geofencingu. |
Geofence |
Geometria geofencingu. |
Geofence |
Tryb mechanizmu zdarzeń asynchronicznych geofencingu. |
Geo |
Prawidłowy |
Geo |
Prawidłowy |
Geo |
Prawidłowy |
Geo |
Prawidłowy |
Geo |
Prawidłowy |
Geo |
Prawidłowy |
Geo |
Prawidłowy |
Geo |
Prawidłowy |
Geo |
Prawidłowy |
Geo |
Prawidłowy |
Json |
Żądany format odpowiedzi. Obsługiwany jest tylko |
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 |
Dodatkowe informacje o błędzie. |
|
code |
string |
Kod błędu. |
details |
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 |
Obiekt błędu. |
Geofence
Ten obiekt jest zwracany z wywołania zbliżeniowego geofencingu.
Nazwa | Typ | Opis |
---|---|---|
expiredGeofenceGeometryId |
string[] |
Listy identyfikator geometrii geofencencji, która wygasła względem czasu użytkownika w żądaniu. |
geometries |
Listy geometrie ogrodzenia, które zawierają położenie współrzędnych lub nakładają się na wartość searchBuffer wokół pozycji. |
|
invalidPeriodGeofenceGeometryId |
string[] |
Listy identyfikator geometrii geofencencji, która jest w nieprawidłowym okresie względem czasu użytkownika w żądaniu. |
isEventPublished |
boolean |
Prawda, jeśli co najmniej jedno zdarzenie zostało opublikowane dla subskrybenta zdarzeń Azure Maps, wartość false, jeśli żadne zdarzenie nie zostanie opublikowane dla subskrybenta zdarzeń Azure Maps. Zostanie to przedstawione 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ższej granicy geofencencji (w metrach, z wyjątkiem sytuacji, gdy są używane wartości specjalne -999/999). Dodatnie oznacza, że współrzędna znajduje się poza geofencją. Jeśli współrzędna znajduje się poza geofencją, ale więcej niż wartość searchBuffer z dala od najbliższego obramowania geofencingu, wartość wynosi 999. Ujemna oznacza, że współrzędna znajduje się wewnątrz geofencencji. Jeśli współrzędna znajduje się wewnątrz wielokąta, ale więcej niż wartość searchBuffer z dala od najbliższego obramowania geofencingu, wartość to -999. Wartość 999 oznacza, że istnieje duża pewność, że współrzędna znajduje się daleko poza geofencją. Wartość -999 oznacza, że istnieje duża pewność, że współrzędna znajduje się dobrze w geofencencji. |
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. Zostanie to przedstawione tylko w odpowiedzi, gdy wartość zostanie podana dla parametru "zInMeter" w żądaniu. |
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ć |
GeofenceMode
Tryb mechanizmu zdarzeń asynchronicznych geofencingu.
Nazwa | Typ | Opis |
---|---|---|
All |
string |
Opublikuj wszystkie wyniki zapytania w celu Azure Maps subskrypcji zdarzeń konta. |
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 |
id |
string |
Identyfikator funkcji. |
type |
string:
Feature |
Określa |
GeoJsonFeatureCollection
Prawidłowy GeoJSON FeatureCollection
typ obiektu. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .
Nazwa | Typ | Opis |
---|---|---|
features |
Zawiera listę prawidłowych |
|
type |
string:
Feature |
Określa |
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 |
Geo |
Określa |
GeoJsonGeometryCollection
Prawidłowy GeoJSON GeometryCollection
typ obiektu. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .
Nazwa | Typ | Opis |
---|---|---|
geometries | GeoJsonGeometry[]: |
Zawiera listę prawidłowych |
type |
string:
Geometry |
Określa |
GeoJsonLineString
Prawidłowy GeoJSON LineString
typ geometrii. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .
Nazwa | Typ | Opis |
---|---|---|
coordinates |
number[] |
Współrzędne geometrii |
type |
string:
Line |
Określa |
GeoJsonMultiLineString
Prawidłowy GeoJSON MultiLineString
typ geometrii. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .
Nazwa | Typ | Opis |
---|---|---|
coordinates |
number[] |
Współrzędne geometrii |
type |
string:
Multi |
Określa |
GeoJsonMultiPoint
Prawidłowy GeoJSON MultiPoint
typ geometrii. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .
Nazwa | Typ | Opis |
---|---|---|
coordinates |
number[] |
Współrzędne geometrii |
type |
string:
Multi |
Określa |
GeoJsonMultiPolygon
Prawidłowy GeoJSON MultiPolygon
typ obiektu. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .
Nazwa | Typ | Opis |
---|---|---|
coordinates |
number[] |
Zawiera listę prawidłowych |
type |
string:
Multi |
Określa |
GeoJsonPoint
Prawidłowy GeoJSON Point
typ geometrii. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .
Nazwa | Typ | Opis |
---|---|---|
coordinates |
number[] |
A |
type |
string:
Point |
Określa |
GeoJsonPolygon
Prawidłowy GeoJSON Polygon
typ geometrii. Aby uzyskać szczegółowe informacje, zobacz RFC 7946 .
Nazwa | Typ | Opis |
---|---|---|
coordinates |
number[] |
Współrzędne dla |
type |
string:
Polygon |
Określa |
JsonFormat
Żądany format odpowiedzi. Obsługiwany jest tylko json
format.
Nazwa | Typ | Opis |
---|---|---|
json |
string |