Spatial - Get Geofence

Odwołanie

Service:: Maps

API Version:: 2022-08-01

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 geofencingu przekazanego do rejestru danych. Przekazywanie geofencingu lub zestawu ogrodzeń do konta usługi Azure Storage, a następnie zarejestrowanie go przy użyciu konta 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 geofencing, zobacz Geofencing GeoJSON data (Geofencing GeoJSON). Aby zbadać bliskość współrzędnej, należy podać lokalizację obiektu, który śledzisz, a także identyfikator ogrodzenia lub zestaw ogrodzeń, a 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). Aby przetestować ten interfejs API, możesz przekazać przykładowe dane z przykładów interfejsu API post geofencingu (Treść żądania) przy użyciu usługi rejestru danych i zastąpić przykładowe {udid} żądanie poniższe przy udid użyciu polecenia użytego do utworzenia rejestru danych. Aby uzyskać więcej informacji na temat usługi rejestru danych, zobacz Jak utworzyć rejestr danych.

Geofencing Kod błędu wewnętrznego

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

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	Wartość Usertime jest nieprawidłowa.
InvalidSearchBuffer	Wartość 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}

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}

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 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 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 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ć `geometryId`element , 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ń 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.

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. Headers X-Correlation-id: string
Other Status Codes	ErrorResponse	Wystąpił nieoczekiwany błąd.

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.

Headers

X-Correlation-id: string

Other Status Codes

ErrorResponse

Wystąpił nieoczekiwany błąd.

Zabezpieczenia

AADToken

Są to przepływy Microsoft Entra OAuth 2.0. Po 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 Azure Maps konta zasobu 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ęć 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 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 Tożsamość Microsoft Entra. * Kontrola dostępu oparta na rolach platformy Azure jest konfigurowana z poziomu płaszczyzny zarządzania platformy Azure za pośrednictwem Azure Portal, programu PowerShell, interfejsu wiersza polecenia, zestawów AZURE SDK lub interfejsów API REST. * Użycie zestawu AZURE MAPS Web SDK umożliwia skonfigurowanie aplikacji na podstawie konfiguracji dla wielu przypadków 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ółużytkowany 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 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 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 list sygnatur dostępu współdzielonego na zasobie Azure Maps za pośrednictwem płaszczyzny zarządzania platformy Azure za pośrednictwem 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.

Type: apiKey
In: header

Przykłady

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
}

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.
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[]	Listy identyfikator geometrii geofencingu, który wygasł względem czasu użytkownika w żądaniu.
geometries	GeofenceGeometry[]	Listy geometrie ogrodzenia zawierające położenie współrzędnych lub nakładają się na wartość searchBuffer wokół pozycji.
invalidPeriodGeofenceGeometryId	string[]	Listy identyfikator geometrii geofencingu, który jest nieprawidłowy w stosunku do czasu użytkownika w żądaniu.
isEventPublished	boolean	Wartość True, jeśli co najmniej jedno zdarzenie zostało opublikowane dla subskrybenta zdarzenia Azure Maps, wartość false, jeśli żadne zdarzenie nie zostało opublikowane dla subskrybenta zdarzenia 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ć `geometryId`element , 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 Azure Maps subskrypcji zdarzeń konta.
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

Spatial - Get Geofence

Geofencing Kod błędu wewnętrznego

Parametry identyfikatora URI

Nagłówek żądania

Odpowiedzi

Zabezpieczenia

AADToken

Uwagi

Scopes

subscription-key

SAS Token

Przykłady

GetGeofence

Sample Request

Sample Response

Definicje

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

Geofence

GeofenceGeometry

GeofenceMode

JsonFormat

Dodatkowe zasoby