Udostępnij za pośrednictwem


Spatial - Get Geofence

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

Interfejs Get Geofence API to żądanie HTTP GET , które pobiera bliskość współrzędnej do geofencencji przekazanej do rejestru danych. Możesz przekazać geofencing lub zestaw ogrodzeń do konta usługi Azure Storage, a następnie zarejestrować go przy użyciu konta usługi Azure Maps przy użyciu rejestru danych, aby uzyskać więcej informacji, zobacz Jak utworzyć rejestr danych. Aby uzyskać więcej informacji na temat formatu danych geofencingu, zobacz Geofencing GeoJSON data (Dane geofencingu GeoJSON). Aby wykonać zapytanie o bliskość współrzędnej, należy podać lokalizację śledzonego obiektu, a także identyfikator ogrodzenia lub zestawu ogrodzeń, a 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). Aby przetestować ten interfejs API, możesz przekazać przykładowe dane z przykładów interfejsu API geofence post (treść żądania) przy użyciu usługi rejestru danych i zastąpić je z przykładowego żądania poniżej udid za pomocą {udid} polecenia użytego do utworzenia rejestru danych. Aby uzyskać więcej informacji na temat usługi rejestru danych, zobacz Jak utworzyć rejestr danych.

Geofencing InnerError code

W kontrakcie innererror błędu odpowiedzi geofencing jest obiektem zawierającym informacje specyficzne dla usługi dotyczące błędu. code to właściwość, w innererror której można zamapować na określony typ błędu geofencingu. W poniższej tabeli przedstawiono mapowanie kodu między wszystkimi znanym typem błędu klienta odpowiadającym błędowi geofencingu message.

innererror.code error.message
NullDeviceId Identyfikator urządzenia nie powinien mieć wartości null.
NullUdid Identyfikator Udid nie powinien mieć wartości null.
UdidWrongFormat Identyfikator Udid powinien zostać uzyskany z interfejsu API pozyskiwania danych użytkownika.
InvalidUserTime Czas użytkownika jest nieprawidłowy.
InvalidSearchBuffer Usługa Searchbuffer jest nieprawidłowa.
InvalidSearchRange Zakres wartości searchbuffer powinien wynosić od 0 do 500 metrów.
InvalidLatLon Parametry lat i/lub lon są nieprawidłowe.
InvalidIsAsyncValue Parametr IsAsync jest nieprawidłowy.
InvalidModeValue Parametr trybu jest nieprawidłowy.
InvalidJson Dane geofencingu nie są prawidłowym plikiem json.
NotSupportedGeoJson Dane geofencingu nie mogą być odczytywane jako funkcja lub featureCollections.
InvalidGeoJson Dane geofencingu są nieprawidłowe.
NoUserDataWithAccountOrSubscription Nie można odnaleźć danych geofencing użytkownika z podanym identyfikatorem konta i/lub identyfikatorem subskrypcji.
NoUserDataWithUdid Nie można odnaleźć danych geofencing użytkownika z podanym identyfikatorem udid.
GET https://{geography}.atlas.microsoft.com/spatial/geofence/json?api-version=2022-08-01&deviceId={deviceId}&udid={udid}&lat={lat}&lon={lon}
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}

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, Zachodnie 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, akceptowane będą 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.

udid
query True

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 jest używany do identyfikowania geometrii i uwzględnia wielkość liter. Aby uzyskać więcej informacji na temat usługi rejestru danych, zobacz Jak utworzyć rejestr danych.

isAsync
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

GeofenceMode

Tryb mechanizmu zdarzeń asynchronicznych geofencingu.

searchBuffer
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.

userTime
query

string

date-time

Czas żądania użytkownika. Jeśli żądanie nie zostanie przedstawione, wartość domyślna to DateTime.Now.

z
query

number

Poziom morza w mierniku przekazywanej lokalizacji. Jeśli ten parametr zostanie przedstawiony, jest używana ekstruzja 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ń microsoft Entra ID w usłudze Azure Maps, zobacz następujące artykuły , aby uzyskać wskazówki.

Odpowiedzi

Nazwa Typ Opis
200 OK

Geofence

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.

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 . 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 usługi Azure Maps. Mechanizmy kontroli dostępu oparte na rolach platformy Azure służą do wyznaczania dostępu do co najmniej jednego konta zasobów 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ęć 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 usługi 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 identyfikatorów entra firmy Microsoft. * Kontrola dostępu oparta na rolach platformy Azure jest konfigurowana z 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 konfigurację opartą na konfiguracji aplikacji w wielu przypadkach użycia.

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

Zakresy

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

subscription-key

Jest to klucz wspólny aprowizowany 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 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 serwera do serwera 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 listy 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 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.

Typ: apiKey
W: header

Przykłady

GetGeofence

Przykładowe żądanie

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

Przykładowa odpowiedź

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

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 mechanizmu zdarzeń asynchronicznych geofencingu.

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 błędu.

Geofence

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

Nazwa Typ Opis
expiredGeofenceGeometryId

string[]

Lista identyfikatora geometrii geofencencji, która wygasła 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 funkcję searchBuffer wokół pozycji.

invalidPeriodGeofenceGeometryId

string[]

Lista identyfikatora 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ń usługi Azure Maps, wartość false, jeśli żadne zdarzenie nie zostało opublikowane dla subskrybenta zdarzeń usługi 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ć geometryIdelement , który jest używany 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 mechanizmu zdarzeń asynchronicznych geofencingu.

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.

JsonFormat

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

Nazwa Typ Opis
json

string

Format wymiany danych notacji obiektów JavaScript