Spatial - Post Geofence
Koordinatın bölge sınırına yakınlığını elde etmek için kullanın.
Post Geofence
API, bir koordinatın sağlanan bölge sınırına veya çit kümesine yakınlığını alan bir HTTP POST
isteğidir. İsteklerle POST
, çit verilerini önceden karşıya yüklemeniz gerekmez, bunun yerine sorgu parametrelerinde izlediğiniz nesnenin konumunu ve istek sonrası gövdesindeki çit veya çitler kümesini sağlarsınız. Coğrafi veri biçimi hakkında daha fazla bilgi için bkz. GeoJSON verilerini coğrafi sınırlama. Yanıt, coğrafi konumun dış kenarından uzaklığı hakkında bilgi içerir. Negatif bir değer, koordinatın çitin içinde olduğunu, pozitif bir değer ise çitin dışında olduğu anlamına gelir.
Bu API varlık izleme, filo yönetimi veya nesneleri taşımak için uyarılar ayarlama gibi çeşitli senaryolar için kullanılabilir.
API, Event Grid ile tümleştirmeyi destekler. isAsync parametresi Event Grid ile tümleştirmeyi etkinleştirmek için kullanılır (varsayılan olarak devre dışıdır).
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}
URI Parametreleri
Name | İçinde | Gerekli | Tür | Description |
---|---|---|---|---|
format
|
path | True |
Yanıtın istenen biçimi. Yalnızca |
|
geography
|
path | True |
string |
Azure Haritalar Hesabının konumu. Geçerli değerler: ABD (Doğu ABD, Orta Batı ABD, Batı ABD 2) ve AB (Kuzey Avrupa, Batı Avrupa). İstekte bir |
api-version
|
query | True |
string |
Azure Haritalar API'sinin sürüm numarası. |
device
|
query | True |
string |
Cihazın kimliği |
lat
|
query | True |
number |
Geçirilen konumun enlemi. Örnek: 48.36. |
lon
|
query | True |
number |
Geçirilen konumun boylamı. Örnek: -124.63. |
is
|
query |
boolean |
True ise istek zaman uyumsuz olay mekanizması kullanır; false ise istek eşitlenir ve herhangi bir olay tetiklemez. Varsayılan değer false'tur. |
|
mode
|
query |
Zaman uyumsuz olay mekanizmasının coğrafi sınırlama modu. |
||
search
|
query |
number |
Metreler içindeki coğrafi bölge etrafındaki arabelleğin yarıçapı, çitin kenarlığının içinde ve dışında sonucu hesaplarken sağlanan koordinata göre ne kadar arama yapılacağını tanımlar. En düşük değer 0, maksimum değer ise 500'dür. Varsayılan değer 50’dir. |
|
user
|
query |
string date-time |
Kullanıcı istek süresi. İstekte gösterilmiyorsa, varsayılan değer DateTime.UtcNow'dır. |
|
z
|
query |
number |
Geçiş yapılan yerin metredeki deniz seviyesi. Bu parametre sunulursa 2B ekstrüzyon bölge sınırlaması uygulanır. Örnek: 200. |
İstek Başlığı
Name | Gerekli | Tür | Description |
---|---|---|---|
x-ms-client-id |
string |
Hangi hesabın Microsoft Entra ID güvenlik modeliyle birlikte kullanıma yönelik olduğunu belirtir. Azure Haritalar hesabı için benzersiz bir kimliği temsil eder ve Azure Haritalar yönetim düzlemi Hesap API'sinden alınabilir. Azure Haritalar Microsoft Entra ID güvenliğini kullanmak için kılavuz için aşağıdaki makalelere bakın. |
İstek Gövdesi
Name | Gerekli | Tür | Description |
---|---|---|---|
features | True |
Geçerli |
|
type | True |
string:
Feature |
|
Yanıtlar
Name | Tür | Description |
---|---|---|
200 OK |
Tamam Zaman uyumsuz çağrının yanıtında ve Event Grid olay verilerinde X-Correlation-id üst bilgi değeri bulunur. Zaman uyumsuz çağrının yanıtını ilgili Event Grid olayıyla ilişkilendirmeye yardımcı olur. Headers X-Correlation-id: string |
|
Other Status Codes |
Beklenmeyen bir hata oluştu. |
Güvenlik
AADToken
Bunlar Microsoft Entra OAuth 2.0 Akışlarıdır. Azure rol tabanlı erişim denetimiyle eşleştirildiğinde, Azure Haritalar REST API'lerine erişimi denetlemek için kullanılabilir. Azure rol tabanlı erişim denetimleri, bir veya daha fazla Azure Haritalar kaynak hesabına veya alt kaynağına erişimi tanımlamak için kullanılır. Herhangi bir kullanıcı, grup veya hizmet sorumlusuna yerleşik bir rol veya REST API'lerini Azure Haritalar için bir veya daha fazla izinden oluşan özel bir rol aracılığıyla erişim verilebilir.
Senaryoları uygulamak için kimlik doğrulama kavramlarını görüntülemenizi öneririz. Özetle, bu güvenlik tanımı belirli API'ler ve kapsamlar üzerinde erişim denetimi yapabilen nesneler aracılığıyla uygulamaları modellemeye yönelik bir çözüm sağlar.
Notlar
- Bu güvenlik tanımı, uygulamanın erişim isteğinde
x-ms-client-id
bulunduğu Azure Haritalar kaynağı belirtmek için üst bilginin kullanılmasını gerektirir. Bu, Haritalar yönetim API'sinden edinilebilir.
Authorization URL
, Azure genel bulut örneğine özgüdür. Bağımsız bulutların benzersiz Yetkilendirme URL'leri ve Microsoft Entra ID yapılandırmaları vardır.
* Azure rol tabanlı erişim denetimi Azure portal, PowerShell, CLI, Azure SDK'ları veya REST API'leri aracılığıyla Azure yönetim düzleminden yapılandırılır.
* Azure Haritalar Web SDK'sının kullanımı, bir uygulamanın birden çok kullanım örneği için yapılandırma tabanlı kurulumuna olanak tanır.
- Microsoft kimlik platformu hakkında daha fazla bilgi için bkz. Microsoft kimlik platformu genel bakış.
Type:
oauth2
Flow:
implicit
Authorization URL:
https://login.microsoftonline.com/common/oauth2/authorize
Scopes
Name | Description |
---|---|
https://atlas.microsoft.com/.default | https://atlas.microsoft.com/.default |
subscription-key
Bu, Azure portal, PowerShell, CLI, Azure SDK'ları veya REST API'leri aracılığıyla Azure yönetim düzlemi aracılığıyla Azure Haritalar kaynağı oluştururken sağlanan paylaşılan bir anahtardır.
Bu anahtarla, tüm uygulamalar tüm REST API'lerine erişim yetkisine sahip olur. Başka bir deyişle, bunlar şu anda verildikleri hesabın ana anahtarları olarak kabul edilebilir.
Genel kullanıma sunulan uygulamalar için önerimiz, bu anahtarın güvenli bir şekilde depolanabildiği Azure Haritalar REST API'lerinin sunucudan sunucuya erişiminin kullanılmasıdır.
Type:
apiKey
In:
header
SAS Token
Bu paylaşılan erişim imzası belirteci, Azure portal, PowerShell, CLI, Azure SDK'ları veya REST API'leri aracılığıyla Azure yönetim düzlemi aracılığıyla Azure Haritalar kaynağındaki Sas Listeleme işleminden oluşturulur.
Bu belirteçle, tüm uygulamalar Azure rol tabanlı erişim denetimleri ve belirli bir belirtecin kullanım süresi, oranı ve bölgelerine yönelik ayrıntılı denetim ile erişim yetkisine sahip olur. Başka bir deyişle SAS Belirteci, uygulamaların erişimi paylaşılan anahtardan daha güvenli bir şekilde denetlemesine izin vermek için kullanılabilir.
Herkese açık uygulamalar için önerimiz, uygunsuz işlemeyi sınırlamak ve SAS Belirtecini düzenli olarak yenilemek için Harita hesabı kaynağında izin verilen kaynakların belirli bir listesini yapılandırmanızdır.
Type:
apiKey
In:
header
Örnekler
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
}
Tanımlar
Name | Description |
---|---|
Error |
Kaynak yönetimi hatası ek bilgileri. |
Error |
Hata ayrıntısı. |
Error |
Hata yanıtı |
Geofence |
Bu nesne bir bölge sınırı yakınlık çağrısından döndürülür. |
Geofence |
Coğrafi sınırlama geometrisi. |
Geofence |
Zaman uyumsuz olay mekanizmasının coğrafi sınırlama modu. |
Geo |
Geçerli |
Geo |
Geçerli |
Geo |
Geçerli |
Geo |
Geçerli |
Geo |
Geçerli |
Geo |
Geçerli |
Geo |
Geçerli |
Geo |
Geçerli |
Geo |
Geçerli |
Geo |
Geçerli |
Json |
Yanıtın istenen biçimi. Yalnızca |
ErrorAdditionalInfo
Kaynak yönetimi hatası ek bilgileri.
Name | Tür | Description |
---|---|---|
info |
object |
Ek bilgiler. |
type |
string |
Ek bilgi türü. |
ErrorDetail
Hata ayrıntısı.
Name | Tür | Description |
---|---|---|
additionalInfo |
Hata ek bilgileri. |
|
code |
string |
Hata kodu. |
details |
Hata ayrıntıları. |
|
message |
string |
Hata iletisi. |
target |
string |
Hata hedefi. |
ErrorResponse
Hata yanıtı
Name | Tür | Description |
---|---|---|
error |
Hata nesnesi. |
Geofence
Bu nesne bir bölge sınırı yakınlık çağrısından döndürülür.
Name | Tür | Description |
---|---|---|
expiredGeofenceGeometryId |
string[] |
İstekteki kullanıcı zamanına göre süresi dolan coğrafi konumun geometri kimliğinin Listeler. |
geometries |
Koordinat konumunu içeren çit geometrilerini Listeler veya konumun etrafındaki ara ara kutusunu üst üste bindirin. |
|
invalidPeriodGeofenceGeometryId |
string[] |
İstekteki kullanıcı zamanına göre geçersiz dönemde olan coğrafi konumun geometri kimliğinin Listeler. |
isEventPublished |
boolean |
Azure Haritalar olay abonesine en az bir olay yayımlanırsa True, Azure Haritalar olay abonesine hiçbir olay yayımlanmazsa false. Bu yalnızca 'isAsync' sorgu parametresi true olarak ayarlandığında yanıt olarak sunulur. |
GeofenceGeometry
Coğrafi sınırlama geometrisi.
Name | Tür | Description |
---|---|---|
deviceId |
string |
Cihazın kimliği. |
distance |
number |
Koordinattan coğrafi boşluğun en yakın kenarlığına olan uzaklık (-999/999 özel değerlerinin kullanılması dışında metre olarak). Pozitif, koordinatın bölge sınırı dışında olduğu anlamına gelir. Koordinat bölge sınırının dışındaysa ancak searchBuffer değerinin en yakın bölge sınırından uzaktaysa, değer 999 olur. Negatif, koordinatın bölge içinde olduğu anlamına gelir. Koordinat çokgen içindeyse ancak searchBuffer değerinin en yakın coğrafi sınırdan uzakta olması durumunda değer -999 olur. 999 değeri, koordinatın bölge sınırı dışında olduğuna dair büyük bir güven olduğu anlamına gelir. -999 değeri, koordinatın coğrafi bölge içinde iyi olduğundan büyük bir güven olduğu anlamına gelir. |
geometryId |
string |
Benzersiz kimlik bir geometri tanımlar. |
nearestLat |
number |
Geometrinin en yakın noktasının enlemi. |
nearestLon |
number |
Geometrinin en yakın noktasının boylamı. |
nearestZ |
number |
2B ekstrüzyon geometrisindeki en yakın noktanın metresinde deniz seviyesi. Bu yalnızca istekte 'zInMeter' için değer sağlandığında yanıt olarak sunulur. |
udId |
string |
Geçerli bir GeoJSON FeatureCollection nesnesini karşıya yüklemek için Veri kayıt defteri oluştururken kullanılan benzersiz kimlik. Ayrıntılar için lütfen RFC 7946'ya bakın. Özelliğin tüm özellikleri, geometriyi tanımlamak için kullanılan ve büyük/küçük harfe duyarlı olan öğesini içermelidir |
GeofenceMode
Zaman uyumsuz olay mekanizmasının coğrafi sınırlama modu.
Name | Tür | Description |
---|---|---|
All |
string |
Tüm sorgu sonuçlarını Azure Haritalar hesap olayı aboneliğinde yayımlayın. |
EnterAndExit |
string |
Yalnızca kullanıcı konumu sınırlayıcı geçiş olarak kabul edildiğinde yayımlama sonucu. |
GeoJsonFeature
Geçerli GeoJSON Feature
bir nesne türü. Ayrıntılar için lütfen RFC 7946'ya bakın.
Name | Tür | Description |
---|---|---|
featureType |
string |
Özelliğin türü. Değer, geçerli özelliğin parçası olduğu veri modeline bağlıdır. Bazı veri modellerinin değeri boş olabilir. |
geometry | GeoJsonGeometry: |
Geçerli |
id |
string |
Özelliğin tanımlayıcısı. |
type |
string:
Feature |
|
GeoJsonFeatureCollection
Geçerli GeoJSON FeatureCollection
bir nesne türü. Ayrıntılar için lütfen RFC 7946'ya bakın.
Name | Tür | Description |
---|---|---|
features |
Geçerli |
|
type |
string:
Feature |
|
GeoJsonGeometry
Geçerli GeoJSON
bir geometri nesnesi. Tür yedi geçerli GeoJSON geometri türünden biri olmalıdır: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon ve GeometryCollection. Ayrıntılar için lütfen RFC 7946'ya bakın.
Name | Tür | Description |
---|---|---|
type |
Geo |
|
GeoJsonGeometryCollection
Geçerli GeoJSON GeometryCollection
bir nesne türü. Ayrıntılar için lütfen RFC 7946'ya bakın.
Name | Tür | Description |
---|---|---|
geometries | GeoJsonGeometry[]: |
Geçerli |
type |
string:
Geometry |
|
GeoJsonLineString
Geçerli GeoJSON LineString
bir geometri türü. Ayrıntılar için lütfen RFC 7946'ya bakın.
Name | Tür | Description |
---|---|---|
coordinates |
number[] |
Geometrinin |
type |
string:
Line |
|
GeoJsonMultiLineString
Geçerli GeoJSON MultiLineString
bir geometri türü. Ayrıntılar için lütfen RFC 7946'ya bakın.
Name | Tür | Description |
---|---|---|
coordinates |
number[] |
Geometrinin |
type |
string:
Multi |
|
GeoJsonMultiPoint
Geçerli GeoJSON MultiPoint
bir geometri türü. Ayrıntılar için lütfen RFC 7946'ya bakın.
Name | Tür | Description |
---|---|---|
coordinates |
number[] |
Geometrinin |
type |
string:
Multi |
|
GeoJsonMultiPolygon
Geçerli GeoJSON MultiPolygon
bir nesne türü. Ayrıntılar için lütfen RFC 7946'ya bakın.
Name | Tür | Description |
---|---|---|
coordinates |
number[] |
Geçerli |
type |
string:
Multi |
|
GeoJsonPoint
Geçerli GeoJSON Point
bir geometri türü. Ayrıntılar için lütfen RFC 7946'ya bakın.
Name | Tür | Description |
---|---|---|
coordinates |
number[] |
A |
type |
string:
Point |
|
GeoJsonPolygon
Geçerli GeoJSON Polygon
bir geometri türü. Ayrıntılar için lütfen RFC 7946'ya bakın.
Name | Tür | Description |
---|---|---|
coordinates |
number[] |
Geometri türü için |
type |
string:
Polygon |
|
JsonFormat
Yanıtın istenen biçimi. Yalnızca json
biçim desteklenir.
Name | Tür | Description |
---|---|---|
json |
string |