Spatial - Get Geofence

Referensi

Service:: Maps

API Version:: 2022-08-01

Gunakan untuk mendapatkan kedekatan koordinat ke geofence.

Get Geofence API adalah permintaan HTTP GET yang mengambil kedekatan koordinat ke geofence yang telah diunggah ke registri Data. Anda mengunggah geofence atau sekumpulan pagar ke Akun Azure Storage, lalu mendaftarkannya ke Akun Azure Maps Anda menggunakan registri Data, untuk informasi selengkapnya lihat Cara membuat registri data. Untuk informasi selengkapnya tentang format data geofence, lihat Data GeoJSON geofencing. Untuk mengkueri kedekatan koordinat, Anda menyediakan lokasi objek yang Anda lacak serta ID untuk pagar atau set pagar, dan respons akan berisi informasi tentang jarak dari tepi luar geofence. Nilai negatif menandakan bahwa koordinat berada di dalam pagar sementara nilai positif berarti berada di luar pagar.

API ini dapat digunakan untuk berbagai skenario yang mencakup hal-hal seperti pelacakan aset, manajemen armada, atau menyiapkan pemberitahuan untuk memindahkan objek.

API mendukung integrasi dengan Event Grid. Parameter isAsync digunakan untuk mengaktifkan integrasi dengan Event Grid (dinonaktifkan secara default). Untuk menguji API ini, Anda dapat mengunggah data sampel dari contoh POST Geofence API (Isi Permintaan) menggunakan layanan Registri data dan mengganti {udid} dari permintaan sampel di bawah ini dengan udid yang digunakan untuk membuat registri Data. Untuk informasi selengkapnya tentang layanan registri data, lihat Cara membuat registri data.

Kode Geofencing InnerError

Dalam kontrak kesalahan respons geofencing, innererror adalah objek yang berisi informasi spesifik layanan tentang kesalahan. code adalah properti di innererror mana dapat memetakan ke jenis kesalahan geofencing tertentu. Tabel di bawah ini menunjukkan pemetaan kode antara semua jenis kesalahan klien yang diketahui ke kesalahan messagegeofencing yang sesuai .

innererror.code	error.message
NullDeviceId	Id Perangkat tidak boleh null.
NullUdid	Udid tidak boleh null.
UdidWrongFormat	Udid harus diperoleh dari API penyerapan data pengguna.
InvalidUserTime	Waktu pengguna tidak valid.
InvalidSearchBuffer	Searchbuffer tidak valid.
InvalidSearchRange	Rentang nilai searchbuffer harus dari 0 hingga 500 meter.
InvalidLatLon	Parameter lat dan/atau lon tidak valid.
InvalidIsAsyncValue	Parameter IsAsync tidak valid.
InvalidModeValue	Parameter mode tidak valid.
InvalidJson	Data geofencing bukan file json yang valid.
NotSupportedGeoJson	Data geofencing tidak dapat dibaca sebagai Fitur atau FeatureCollections.
InvalidGeoJson	Data geofencing tidak valid.
NoUserDataWithAccountOrSubscription	Tidak dapat menemukan data geofencing pengguna dengan id akun dan/atau id langganan yang disediakan.
NoUserDataWithUdid	Tidak dapat menemukan data geofencing pengguna dengan udid yang disediakan.

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}

Parameter URI

Nama	Dalam	Diperlukan	Jenis	Deskripsi
format	path	True	JsonFormat	Format respons yang diinginkan. Hanya `json` format yang didukung.
geography	path	True	string	Lokasi Akun Azure Maps. Nilai yang valid adalah kita (US Timur, US Tengah Barat, AS Barat 2) dan Eropa (Eropa Utara, Eropa Barat). Parameter ini diperlukan ketika `udid` disediakan dalam permintaan. Misalnya, jika Akun Azure Maps terletak di US Timur, hanya permintaan kepada kami geografi yang akan diterima.
api-version	query	True	string	Nomor versi API Azure Maps.
deviceId	query	True	string	ID perangkat
lat	query	True	number	Garis lintang lokasi yang dilewati. Contoh: 48.36.
lon	query	True	number	Garis bujur lokasi yang dilewati. Contoh: -124.63.
udid	query	True	string	Id unik yang digunakan saat membuat registri Data untuk mengunggah objek GeoJSON FeatureCollection yang valid. Silakan merujuk ke RFC 7946 untuk detailnya. Semua properti fitur harus berisi `geometryId`, yang digunakan untuk mengidentifikasi geometri dan peka huruf besar/kecil. Untuk informasi selengkapnya tentang layanan registri data, lihat Cara membuat registri data.
isAsync	query		boolean	Jika true, permintaan akan menggunakan mekanisme peristiwa asinkron; jika false, permintaan akan disinkronkan dan tidak memicu peristiwa apa pun. Nilai defaultnya adalah false.
mode	query		GeofenceMode	Mode mekanisme peristiwa asinkron geofencing.
searchBuffer	query		number	Radius buffer di sekitar geofence dalam meter yang mendefinisikan seberapa jauh untuk mencari di dalam dan di luar batas pagar terhadap koordinat yang disediakan saat menghitung hasilnya. Nilai minimum adalah 0, dan maksimum adalah 500. Nilai defaultnya adalah 50.
userTime	query		string date-time	Waktu permintaan pengguna. Jika tidak disajikan dalam permintaan, nilai defaultnya adalah DateTime.Now.
z	query		number	Permukaan laut dalam meter lokasi yang dilewati. Jika parameter ini disajikan, ekstrusi 2D digunakan. Contoh: 200.

Header Permintaan

Nama	Diperlukan	Jenis	Deskripsi
x-ms-client-id		string	Menentukan akun mana yang ditujukan untuk penggunaan bersama dengan model keamanan Microsoft Entra ID. Ini mewakili ID unik untuk akun Azure Maps dan dapat diambil dari API Akun bidang manajemen Azure Maps. Untuk menggunakan keamanan Microsoft Entra ID di Azure Maps lihat artikel berikut untuk panduan.

Respons

Nama	Jenis	Deskripsi
200 OK	Geofence	OK Nilai header X-Correlation-id ada dalam respons panggilan asinkron dan data peristiwa Event Grid. Ini membantu menghubungkan respons panggilan asinkron dengan peristiwa Event Grid yang sesuai. Headers X-Correlation-id: string
Other Status Codes	ErrorResponse	Terjadi kesalahan tak terduga.

Nama

Jenis

Deskripsi

200 OK

Geofence

OK Nilai header X-Correlation-id ada dalam respons panggilan asinkron dan data peristiwa Event Grid. Ini membantu menghubungkan respons panggilan asinkron dengan peristiwa Event Grid yang sesuai.

Headers

X-Correlation-id: string

Other Status Codes

ErrorResponse

Terjadi kesalahan tak terduga.

Keamanan

AADToken

Ini adalah Alur OAuth 2.0 Microsoft Entra. Saat dipasangkan dengan kontrol akses berbasis peran Azure, kontrol akses tersebut dapat digunakan untuk mengontrol akses ke Azure Maps REST API. Kontrol akses berbasis peran Azure digunakan untuk menunjuk akses ke satu atau beberapa Azure Maps akun sumber daya atau sub-sumber daya. Setiap pengguna, grup, atau perwakilan layanan dapat diberikan akses melalui peran bawaan atau peran kustom yang terdiri dari satu atau beberapa izin untuk Azure Maps REST API.

Untuk menerapkan skenario, sebaiknya lihat konsep autentikasi. Singkatnya, definisi keamanan ini menyediakan solusi untuk memodelkan aplikasi melalui objek yang mampu mengontrol akses pada API dan cakupan tertentu.

Catatan

Definisi keamanan ini memerlukan penggunaan x-ms-client-id header untuk menunjukkan sumber daya Azure Maps mana yang diminta akses aplikasi. Ini dapat diperoleh dari API manajemen Maps.

Authorization URL khusus untuk instans cloud publik Azure. Sovereign cloud memiliki URL Otorisasi yang unik dan konfigurasi Microsoft Entra ID. * Kontrol akses berbasis peran Azure dikonfigurasi dari bidang manajemen Azure melalui portal Azure, PowerShell, CLI, Azure SDK, atau REST API. * Penggunaan Azure Maps Web SDK memungkinkan penyiapan berbasis konfigurasi aplikasi untuk beberapa kasus penggunaan.

Untuk informasi selengkapnya tentang platform identitas Microsoft, lihat gambaran umum platform identitas Microsoft.

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

Scopes

Nama	Deskripsi
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

Ini adalah kunci bersama yang disediakan saat membuat sumber daya Azure Maps melalui bidang manajemen Azure melalui portal Azure, PowerShell, CLI, Azure SDK, atau REST API.

Dengan kunci ini, aplikasi apa pun berwenang untuk mengakses semua REST API. Dengan kata lain, saat ini dapat diperlakukan sebagai kunci master ke akun tempat kunci tersebut dikeluarkan.

Untuk aplikasi yang diekspos secara publik, rekomendasi kami adalah menggunakan akses server-ke-server Azure Maps REST API tempat kunci ini dapat disimpan dengan aman.

Type: apiKey
In: header

SAS Token

Ini adalah token tanda tangan akses bersama dibuat dari operasi Daftar SAS pada sumber daya Azure Maps melalui bidang manajemen Azure melalui portal Azure, PowerShell, CLI, Azure SDK, atau REST API.

Dengan token ini, aplikasi apa pun berwenang untuk mengakses dengan kontrol akses berbasis peran Azure dan kontrol halus ke kedaluwarsa, laju, dan wilayah penggunaan untuk token tertentu. Dengan kata lain, Token SAS dapat digunakan untuk memungkinkan aplikasi mengontrol akses dengan cara yang lebih aman daripada kunci bersama.

Untuk aplikasi yang diekspos secara publik, rekomendasi kami adalah mengonfigurasi daftar asal tertentu yang diizinkan di sumber daya akun Peta untuk membatasi penyalahgunaan penyalahgunaan dan memperbarui Token SAS secara teratur.

Type: apiKey
In: header

Contoh

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
}

Definisi

Nama	Deskripsi
ErrorAdditionalInfo	Info tambahan kesalahan manajemen sumber daya.
ErrorDetail	Detail kesalahan.
ErrorResponse	Respons kesalahan
Geofence	Objek ini dikembalikan dari panggilan kedekatan geofence.
GeofenceGeometry	Geometri geofencing.
GeofenceMode	Mode mekanisme peristiwa asinkron geofencing.
JsonFormat	Format respons yang diinginkan. Hanya `json` format yang didukung.

ErrorAdditionalInfo

Info tambahan kesalahan manajemen sumber daya.

Nama	Jenis	Deskripsi
info	object	Info tambahan.
type	string	Jenis info tambahan.

ErrorDetail

Detail kesalahan.

Nama	Jenis	Deskripsi
additionalInfo	ErrorAdditionalInfo[]	Info tambahan kesalahan.
code	string	Kode kesalahan.
details	ErrorDetail[]	Detail kesalahan.
message	string	Pesan kesalahan.
target	string	Target kesalahan.

ErrorResponse

Respons kesalahan

Nama	Jenis	Deskripsi
error	ErrorDetail	Objek kesalahan.

Geofence

Objek ini dikembalikan dari panggilan kedekatan geofence.

Nama	Jenis	Deskripsi
expiredGeofenceGeometryId	string[]	Lists ID geometri geofence yang kedaluwarsa relatif terhadap waktu pengguna dalam permintaan.
geometries	GeofenceGeometry[]	Mencantumkan geometri fence yang berisi posisi koordinat atau menimpa searchBuffer di sekitar posisi.
invalidPeriodGeofenceGeometryId	string[]	Lists ID geometri geofence yang dalam periode tidak valid relatif terhadap waktu pengguna dalam permintaan.
isEventPublished	boolean	True jika setidaknya satu peristiwa dipublikasikan ke pelanggan peristiwa Azure Maps, false jika tidak ada peristiwa yang dipublikasikan kepada pelanggan peristiwa Azure Maps. Ini hanya akan disajikan sebagai respons ketika parameter kueri 'isAsync' diatur ke true.

GeofenceGeometry

Geometri geofencing.

Nama	Jenis	Deskripsi
deviceId	string	ID perangkat.
distance	number	Jarak dari koordinat ke batas terdekat geofence (dalam meter kecuali ketika nilai khusus -999/999 digunakan). Positif berarti koordinat berada di luar geofence. Jika koordinat berada di luar geofence, tetapi lebih dari nilai searchBuffer yang jauh dari perbatasan geofence terdekat, nilainya adalah 999. Negatif berarti koordinat berada di dalam geofence. Jika koordinat berada di dalam poligon, tetapi lebih dari nilai searchBuffer yang jauh dari batas geofencing terdekat, nilainya adalah -999. Nilai 999 berarti bahwa ada kepercayaan besar koordinat baik di luar geofence. Nilai -999 berarti bahwa ada kepercayaan besar koordinat baik dalam geofence.
geometryId	string	Id unik mengidentifikasi geometri.
nearestLat	number	Garis lintang titik terdekat dari geometri.
nearestLon	number	Garis bujur titik terdekat dari geometri.
nearestZ	number	Permukaan laut dalam meter titik terdekat pada geometri ekstrusi 2D. Ini hanya akan disajikan sebagai respons ketika nilai disediakan untuk 'zInMeter' dalam permintaan.
udId	string	Id unik yang digunakan saat membuat registri Data untuk mengunggah objek GeoJSON FeatureCollection yang valid. Silakan merujuk ke RFC 7946 untuk detailnya. Semua properti fitur harus berisi `geometryId`, yang digunakan untuk mengidentifikasi geometri dan peka huruf besar/kecil. Untuk informasi selengkapnya tentang layanan registri data, lihat Cara membuat registri data.

GeofenceMode

Mode mekanisme peristiwa asinkron geofencing.

Nama	Jenis	Deskripsi
All	string	Terbitkan semua hasil kueri ke langganan peristiwa akun Azure Maps.
EnterAndExit	string	Hanya terbitkan hasil ketika lokasi pengguna dianggap sebagai penyeberangan geofencing boarder.

JsonFormat

Format respons yang diinginkan. Hanya json format yang didukung.

Nama	Jenis	Deskripsi
json	string	Format Pertukaran Data Notasi Objek JavaScript

Spatial - Get Geofence

Kode Geofencing InnerError

Parameter URI

Header Permintaan

Respons

Keamanan

AADToken

Catatan

Scopes

subscription-key

SAS Token

Contoh

GetGeofence

Sample Request

Sample Response

Definisi

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

Geofence

GeofenceGeometry

GeofenceMode

JsonFormat

Sumber Daya Tambahan: