Spatial - Post Geofence

Referensi

Service:: Maps

API Version:: 2022-08-01

Gunakan untuk mendapatkan kedekatan koordinat ke geofence.

Post Geofence API adalah permintaan HTTP POST yang mengambil kedekatan koordinat ke geofence atau set pagar yang disediakan. Dengan POST permintaan, Anda tidak perlu mengunggah data pagar terlebih dahulu, sebagai gantinya Anda menyediakan lokasi objek yang Anda lacak dalam parameter kueri serta data pagar atau set pagar dalam isi permintaan pos. Untuk informasi selengkapnya tentang format data geofence, lihat Data GeoJSON Geofencing. Respons akan berisi informasi tentang jarak dari tepi luar geofence. Nilai negatif menandakan bahwa koordinat berada di dalam pagar sementara nilai positif berarti bahwa itu 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).

POST https://{geography}.atlas.microsoft.com/spatial/geofence/json?api-version=2022-08-01&deviceId={deviceId}&lat={lat}&lon={lon}

With optional parameters:

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}

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.
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.UtcNow.
z	query		number	Permukaan laut dalam meter lokasi yang dilewati. Jika parameter ini disajikan, geofencing ekstrusi 2D diterapkan. 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.

Isi Permintaan

Nama	Diperlukan	Jenis	Deskripsi
features	True	GeoJsonFeature[]	Berisi daftar objek yang valid `GeoJSON Feature` .
type	True	string: FeatureCollection	Menentukan jenisnya `GeoJSON` . Harus salah satu dari sembilan jenis objek GeoJSON yang valid - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature dan FeatureCollection.

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 akun sumber daya atau sub-sumber daya Azure Maps. 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 pemodelan 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 meminta 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, ini saat ini dapat diperlakukan sebagai kunci master ke akun tempat mereka 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 fine-grain ke kedaluwarsa, tarif, 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 spesifik asal yang diizinkan pada sumber daya akun Peta untuk membatasi penyalahgunaan penyalahgunaan dan memperbarui Token SAS secara teratur.

Type: apiKey
In: header

Contoh

PostGeofence

Sample Request

HTTP

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

Status code:: 200

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

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.
GeoJsonFeature	Jenis objek yang valid `GeoJSON Feature` . Silakan merujuk ke RFC 7946 untuk detailnya.
GeoJsonFeatureCollection	Jenis objek yang valid `GeoJSON FeatureCollection` . Silakan merujuk ke RFC 7946 untuk detailnya.
GeoJsonGeometry	Objek geometri yang valid `GeoJSON` . Jenisnya harus salah satu dari tujuh jenis geometri GeoJSON yang valid - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon dan GeometryCollection. Silakan merujuk ke RFC 7946 untuk detailnya.
GeoJsonGeometryCollection	Jenis objek yang valid `GeoJSON GeometryCollection` . Silakan merujuk ke RFC 7946 untuk detailnya.
GeoJsonLineString	Jenis geometri yang valid `GeoJSON LineString` . Silakan merujuk ke RFC 7946 untuk detailnya.
GeoJsonMultiLineString	Jenis geometri yang valid `GeoJSON MultiLineString` . Silakan merujuk ke RFC 7946 untuk detailnya.
GeoJsonMultiPoint	Jenis geometri yang valid `GeoJSON MultiPoint` . Silakan merujuk ke RFC 7946 untuk detailnya.
GeoJsonMultiPolygon	Jenis objek yang valid `GeoJSON MultiPolygon` . Silakan merujuk ke RFC 7946 untuk detailnya.
GeoJsonPoint	Jenis geometri yang valid `GeoJSON Point` . Silakan merujuk ke RFC 7946 untuk detailnya.
GeoJsonPolygon	Jenis geometri yang valid `GeoJSON Polygon` . Silakan merujuk ke RFC 7946 untuk detailnya.
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.

GeoJsonFeature

Jenis objek yang valid GeoJSON Feature . Silakan merujuk ke RFC 7946 untuk detailnya.

Nama	Jenis	Deskripsi
featureType	string	Jenis fitur. Nilai tergantung pada model data, fitur saat ini adalah bagian dari. Beberapa model data mungkin memiliki nilai kosong.
geometry	GeoJsonGeometry: GeoJsonGeometryCollection GeoJsonLineString GeoJsonMultiLineString GeoJsonMultiPoint GeoJsonMultiPolygon GeoJsonPoint GeoJsonPolygon	Objek geometri yang valid `GeoJSON` . Jenisnya harus salah satu dari tujuh jenis geometri GeoJSON yang valid - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon dan GeometryCollection. Silakan merujuk ke RFC 7946 untuk detailnya.
id	string	Pengidentifikasi untuk fitur tersebut.
type	string: Feature	Menentukan jenis.`GeoJSON` Harus salah satu dari sembilan jenis objek GeoJSON yang valid - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature dan FeatureCollection.

GeoJsonFeatureCollection

Jenis objek yang valid GeoJSON FeatureCollection . Silakan merujuk ke RFC 7946 untuk detailnya.

Nama	Jenis	Deskripsi
features	GeoJsonFeature[]	Berisi daftar objek yang valid `GeoJSON Feature` .
type	string: FeatureCollection	Menentukan jenis.`GeoJSON` Harus salah satu dari sembilan jenis objek GeoJSON yang valid - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature dan FeatureCollection.

GeoJsonGeometry

Objek geometri yang valid GeoJSON . Jenisnya harus salah satu dari tujuh jenis geometri GeoJSON yang valid - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon dan GeometryCollection. Silakan merujuk ke RFC 7946 untuk detailnya.

Nama	Jenis	Deskripsi
type	GeoJsonObjectType	Menentukan jenis.`GeoJSON` Harus salah satu dari sembilan jenis objek GeoJSON yang valid - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature dan FeatureCollection.

GeoJsonGeometryCollection

Jenis objek yang valid GeoJSON GeometryCollection . Silakan merujuk ke RFC 7946 untuk detailnya.

Nama	Jenis	Deskripsi
geometries	GeoJsonGeometry[]: GeoJsonGeometryCollection[] GeoJsonLineString[] GeoJsonMultiLineString[] GeoJsonMultiPoint[] GeoJsonMultiPolygon[] GeoJsonPoint[] GeoJsonPolygon[]	Berisi daftar objek geometri yang valid `GeoJSON` . Perhatikan bahwa koordinat di GeoJSON dalam urutan x, y (bujur, lintang).
type	string: GeometryCollection	Menentukan jenis.`GeoJSON` Harus salah satu dari sembilan jenis objek GeoJSON yang valid - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature dan FeatureCollection.

GeoJsonLineString

Jenis geometri yang valid GeoJSON LineString . Silakan merujuk ke RFC 7946 untuk detailnya.

Nama	Jenis	Deskripsi
coordinates	number[]	Koordinat `GeoJson LineString` untuk geometri.
type	string: LineString	Menentukan jenis.`GeoJSON` Harus salah satu dari sembilan jenis objek GeoJSON yang valid - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature dan FeatureCollection.

GeoJsonMultiLineString

Jenis geometri yang valid GeoJSON MultiLineString . Silakan merujuk ke RFC 7946 untuk detailnya.

Nama	Jenis	Deskripsi
coordinates	number[]	Koordinat `GeoJson MultiLineString` untuk geometri.
type	string: MultiLineString	Menentukan jenis.`GeoJSON` Harus salah satu dari sembilan jenis objek GeoJSON yang valid - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature dan FeatureCollection.

GeoJsonMultiPoint

Jenis geometri yang valid GeoJSON MultiPoint . Silakan merujuk ke RFC 7946 untuk detailnya.

Nama	Jenis	Deskripsi
coordinates	number[]	Koordinat `GeoJson MultiPoint` untuk geometri.
type	string: MultiPoint	Menentukan jenis.`GeoJSON` Harus salah satu dari sembilan jenis objek GeoJSON yang valid - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature dan FeatureCollection.

GeoJsonMultiPolygon

Jenis objek yang valid GeoJSON MultiPolygon . Silakan merujuk ke RFC 7946 untuk detailnya.

Nama	Jenis	Deskripsi
coordinates	number[]	Berisi daftar objek yang valid `GeoJSON Polygon` . Perhatikan bahwa koordinat di GeoJSON dalam urutan x, y (bujur, lintang).
type	string: MultiPolygon	Menentukan jenis.`GeoJSON` Harus salah satu dari sembilan jenis objek GeoJSON yang valid - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature dan FeatureCollection.

GeoJsonPoint

Jenis geometri yang valid GeoJSON Point . Silakan merujuk ke RFC 7946 untuk detailnya.

Nama	Jenis	Deskripsi
coordinates	number[]	`Position` adalah array angka dengan dua elemen atau lebih. Dua elemen pertama adalah bujur dan lintang, tepatnya dalam urutan tersebut. Ketinggian/Elevasi adalah elemen ketiga opsional. Silakan merujuk ke RFC 7946 untuk detailnya.
type	string: Point	Menentukan jenis.`GeoJSON` Harus salah satu dari sembilan jenis objek GeoJSON yang valid - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature dan FeatureCollection.

GeoJsonPolygon

Jenis geometri yang valid GeoJSON Polygon . Silakan merujuk ke RFC 7946 untuk detailnya.

Nama	Jenis	Deskripsi
coordinates	number[]	Koordinat `GeoJson Polygon` untuk jenis geometri.
type	string: Polygon	Menentukan jenis.`GeoJSON` Harus salah satu dari sembilan jenis objek GeoJSON yang valid - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature dan FeatureCollection.

JsonFormat

Format respons yang diinginkan. Hanya json format yang didukung.

Nama	Jenis	Deskripsi
json	string	Format Pertukaran Data Notasi Objek JavaScript

Spatial - Post Geofence

Parameter URI

Header Permintaan

Isi Permintaan

Respons

Keamanan

AADToken

Catatan

Scopes

subscription-key

SAS Token

Contoh

PostGeofence

Sample Request

Sample Response

Definisi

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

Geofence

GeofenceGeometry

GeofenceMode

GeoJsonFeature

GeoJsonFeatureCollection

GeoJsonGeometry

GeoJsonGeometryCollection

GeoJsonLineString

GeoJsonMultiLineString

GeoJsonMultiPoint

GeoJsonMultiPolygon

GeoJsonPoint

GeoJsonPolygon

JsonFormat

Sumber Daya Tambahan: