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

JsonFormat

Yanıtın istenen biçimi. Yalnızca json biçim desteklenir.

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 udid sağlandığında bu parametre gereklidir. Örneğin, Azure Haritalar Hesabı Doğu ABD'de bulunuyorsa, yalnızca bize yapılan coğrafya istekleri kabul edilir.

api-version
query True

string

Azure Haritalar API'sinin sürüm numarası.

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

isAsync
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

GeofenceMode

Zaman uyumsuz olay mekanizmasının coğrafi sınırlama modu.

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

userTime
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

GeoJsonFeature[]

Geçerli GeoJSON Feature nesnelerin listesini içerir.

type True string:

FeatureCollection

GeoJSON Türünü belirtir. Dokuz geçerli GeoJSON nesne türünden biri olmalıdır: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature ve FeatureCollection.

Yanıtlar

Name Tür Description
200 OK

Geofence

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

ErrorResponse

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.

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
ErrorAdditionalInfo

Kaynak yönetimi hatası ek bilgileri.

ErrorDetail

Hata ayrıntısı.

ErrorResponse

Hata yanıtı

Geofence

Bu nesne bir bölge sınırı yakınlık çağrısından döndürülür.

GeofenceGeometry

Coğrafi sınırlama geometrisi.

GeofenceMode

Zaman uyumsuz olay mekanizmasının coğrafi sınırlama modu.

GeoJsonFeature

Geçerli GeoJSON Feature bir nesne türü. Ayrıntılar için lütfen RFC 7946'ya bakın.

GeoJsonFeatureCollection

Geçerli GeoJSON FeatureCollection bir nesne türü. Ayrıntılar için lütfen RFC 7946'ya bakın.

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.

GeoJsonGeometryCollection

Geçerli GeoJSON GeometryCollection bir nesne türü. Ayrıntılar için lütfen RFC 7946'ya bakın.

GeoJsonLineString

Geçerli GeoJSON LineString bir geometri türü. Ayrıntılar için lütfen RFC 7946'ya bakın.

GeoJsonMultiLineString

Geçerli GeoJSON MultiLineString bir geometri türü. Ayrıntılar için lütfen RFC 7946'ya bakın.

GeoJsonMultiPoint

Geçerli GeoJSON MultiPoint bir geometri türü. Ayrıntılar için lütfen RFC 7946'ya bakın.

GeoJsonMultiPolygon

Geçerli GeoJSON MultiPolygon bir nesne türü. Ayrıntılar için lütfen RFC 7946'ya bakın.

GeoJsonPoint

Geçerli GeoJSON Point bir geometri türü. Ayrıntılar için lütfen RFC 7946'ya bakın.

GeoJsonPolygon

Geçerli GeoJSON Polygon bir geometri türü. Ayrıntılar için lütfen RFC 7946'ya bakın.

JsonFormat

Yanıtın istenen biçimi. Yalnızca json biçim desteklenir.

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

ErrorAdditionalInfo[]

Hata ek bilgileri.

code

string

Hata kodu.

details

ErrorDetail[]

Hata ayrıntıları.

message

string

Hata iletisi.

target

string

Hata hedefi.

ErrorResponse

Hata yanıtı

Name Tür Description
error

ErrorDetail

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

GeofenceGeometry[]

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 geometryId. Veri kayıt defteri hizmeti hakkında daha fazla bilgi için bkz. Veri kayıt defteri oluşturma.

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

id

string

Özelliğin tanımlayıcısı.

type string:

Feature

GeoJSON Türünü belirtir. Dokuz geçerli GeoJSON nesne türünden biri olmalıdır: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature ve FeatureCollection.

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

GeoJsonFeature[]

Geçerli GeoJSON Feature nesnelerin listesini içerir.

type string:

FeatureCollection

GeoJSON Türünü belirtir. Dokuz geçerli GeoJSON nesne türünden biri olmalıdır: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature ve FeatureCollection.

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

GeoJsonObjectType

GeoJSON Türünü belirtir. Dokuz geçerli GeoJSON nesne türünden biri olmalıdır: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature ve FeatureCollection.

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 GeoJSON geometri nesnelerinin listesini içerir. GeoJSON'daki koordinatların x, y sırada (boylam, enlem) olduğunu unutmayın.

type string:

GeometryCollection

GeoJSON Türünü belirtir. Dokuz geçerli GeoJSON nesne türünden biri olmalıdır: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature ve FeatureCollection.

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 GeoJson LineString koordinatları.

type string:

LineString

GeoJSON Türünü belirtir. Dokuz geçerli GeoJSON nesne türünden biri olmalıdır: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature ve FeatureCollection.

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 GeoJson MultiLineString koordinatları.

type string:

MultiLineString

GeoJSON Türünü belirtir. Dokuz geçerli GeoJSON nesne türünden biri olmalıdır: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature ve FeatureCollection.

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 GeoJson MultiPoint koordinatları.

type string:

MultiPoint

GeoJSON Türünü belirtir. Dokuz geçerli GeoJSON nesne türünden biri olmalıdır: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature ve FeatureCollection.

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 GeoJSON Polygon nesnelerin listesini içerir. GeoJSON'daki koordinatların x, y sırada (boylam, enlem) olduğunu unutmayın.

type string:

MultiPolygon

GeoJSON Türünü belirtir. Dokuz geçerli GeoJSON nesne türünden biri olmalıdır: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature ve FeatureCollection.

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 Position , iki veya daha fazla öğe içeren bir sayı dizisidir. İlk iki öğe boylam ve enlemdir ve tam olarak bu sıradadır. Rakım/Yükseklik isteğe bağlı bir üçüncü öğedir. Ayrıntılar için lütfen RFC 7946'ya bakın.

type string:

Point

GeoJSON Türünü belirtir. Dokuz geçerli GeoJSON nesne türünden biri olmalıdır: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature ve FeatureCollection.

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 GeoJson Polygon koordinatlar.

type string:

Polygon

GeoJSON Türünü belirtir. Dokuz geçerli GeoJSON nesne türünden biri olmalıdır: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature ve FeatureCollection.

JsonFormat

Yanıtın istenen biçimi. Yalnızca json biçim desteklenir.

Name Tür Description
json

string

JavaScript Nesne Gösterimi Veri Değişim Biçimi