Aracılığıyla paylaş

Azure Digital Twins yönetim API'lerini kullanma

  • Makale

Önemli

Azure Digital Twins hizmetinin yeni bir sürümü yayınlandı. Yeni hizmetin genişletilmiş özellikleri ışığında özgün Azure Digital Twins hizmeti (bu belge kümesinde açıklanmıştır) kullanımdan kaldırılmıştır.

Yeni hizmetin belgelerini görüntülemek için etkin Azure Digital Twins Belgeleri'ni ziyaret edin.

Azure Digital Twins yönetim API'leri, IoT uygulamalarınız için güçlü işlevler sağlar. Bu makalede API yapısında nasıl gezindiğiniz gösterilmektedir.

API özeti

Aşağıdaki listede Digital Twins API'lerinin bileşenleri gösterilmektedir.

  • /spaces: Bu API'ler kurulumunuzda fiziksel konumlarla etkileşim kurar. Bunlar, fiziksel konumlarınızın dijital eşlemelerini uzamsal grafik biçiminde oluşturmanıza, silmenize ve yönetmenize yardımcı olur.

  • /devices: Bu API'ler kurulumunuzda cihazlarla etkileşim kurar. Bu cihazlar bir veya daha fazla algılayıcıyı yönetebilir. Örneğin, bir cihaz telefonunuz, Raspberry Pi algılayıcı podu veya Lora ağ geçidi vb. olabilir.

  • /sensors: Bu API'ler, cihazlarınızla ve fiziksel konumlarınızla ilişkili algılayıcılarla iletişim kurmanıza yardımcı olur. Algılayıcılar, uzamsal ortamınızı işlemek için kullanılabilecek ortam değerlerini kaydeder ve gönderir.

  • /resources: Bu API'ler, Digital Twins örneğiniz için IoT hub'ı gibi kaynakları ayarlamanıza yardımcı olur.

  • /types: Bu API'ler, bu nesnelere belirli özellikler eklemek için genişletilmiş türleri Digital Twins nesnelerinizle ilişkilendirmenize olanak tanır. Bu türler, kullanıcı arabirimindeki nesnelerin ve telemetri verilerinizi işleyen özel işlevlerin kolayca filtrelenmesine ve gruplanmasına olanak sağlar. Genişletilmiş türlere örnek olarak DeviceType, SensorType, SensorDataType, SpaceType, SpaceSubType, SpaceBlobType, SpaceResourceType vb. verilebilir.

  • /ontologies: Bu API'ler, genişletilmiş tür koleksiyonları olan ontolojileri yönetmenize yardımcı olur. Ontolojiler, temsil ettikleri fiziksel alana göre nesne türleri için adlar sağlar. Örneğin, BACnet ontology algılayıcı türleri, veri türleri, datasubtypes ve dataunittypes için belirli adlar sağlar. Ontolojiler hizmet tarafından yönetilir ve oluşturulur. Kullanıcılar, ontolojileri yükleyebilir ve kaldırabilir. Bir ontoloji yüklendiğinde, ilişkili tüm tür adları etkinleştirilir ve uzamsal grafiğinizde sağlanacak şekilde hazır olur.

  • /propertyKeys: Alanlarınız, cihazlarınız, kullanıcılarınız ve algılayıcılarınız için özel özellikler oluşturmak için bu API'leri kullanabilirsiniz. Bu özellikler anahtar/değer çiftleri olarak oluşturulur. PrimitiveDataType'larını ayarlayarak bu özelliklerin veri türünü tanımlayabilirsiniz. Örneğin, algılayıcılarınız için uint türünde BasicTemperatureDeltaProcessingRefreshTime adlı bir özellik tanımlayabilir ve ardından algılayıcılarınızın her biri için bu özellik için bir değer atayabilirsiniz. Özelliği oluştururken bu değerler için Kısıtlamalar da ekleyebilirsiniz( Min ve Max aralıklarının yanı sıra ValidationData olarak izin verilen değerler gibi).

  • /matchers: Bu API'ler, gelen cihaz verilerinizden değerlendirmek istediğiniz koşulları belirtmenize olanak sağlar. Daha fazla bilgi için bu makaleye bakın.

  • /userDefinedFunctions: Bu API'ler, eşleştiriciler tarafından tanımlanan koşullar oluştuğunda, kurulumunuzdan gelen verileri işlemek için yürütülecek özel bir işlev oluşturmanıza, silmenize veya güncelleştirmenize olanak tanır. Kullanıcı tanımlı işlevler olarak da adlandırılan bu özel işlevler hakkında daha fazla bilgi için bu makaleye bakın.

  • /endpoints: Bu API'ler, Digital Twins çözümünüzün veri depolama ve analiz için diğer Azure hizmetleriyle iletişim kurabilmesi için uç noktalar oluşturmanıza olanak tanır. Daha fazla bilgi için bu makaleyi okuyun.

  • /keyStores: Bu API'ler, alanlarınız için güvenlik anahtarı depolarını yönetmenize olanak sağlar. Bu depolar bir güvenlik anahtarları koleksiyonunu barındırabilir ve en son geçerli anahtarları kolayca almanıza olanak sağlar.

  • /users: Bu API'ler, gerektiğinde bu bireyleri bulmak için kullanıcıları alanlarınızla ilişkilendirmenize olanak sağlar.

  • /system: Bu API'ler, varsayılan alan ve algılayıcı türleri gibi sistem genelinde ayarları yönetmenize olanak sağlar.

  • /roleAssignments: Bu API'ler rolleri kullanıcı kimliği, kullanıcı tanımlı işlev kimliği vb. varlıklarla ilişkilendirmenizi sağlar. Her rol ataması ilişkilendirilecek varlığın kimliğini, varlık türünü, ilişkilendirilecek rolün kimliğini, kiracı kimliğini ve varlığın bu ilişkilendirmeyle erişebileceği kaynağın üst sınırını tanımlayan yolu içerir. Daha fazla bilgi için bu makaleyi okuyun.

API gezintisi

Digital Twins API'leri, aşağıdaki parametreleri kullanarak uzamsal grafınız genelinde filtrelemeyi ve gezinmeyi destekler:

  • spaceId: API sonuçları verilen alan kimliğine göre filtreler. Buna ek olarak, useParentSpace boole bayrağı /spaces API'leri için geçerlidir ve bu da verilen alan kimliğinin geçerli alan yerine üst alana başvurduğunu gösterir.

  • minLevel ve maxLevel: Kök boşlukların 1. düzeyde olduğu kabul edilir. Üst boşluğu n düzeyinde olan boşluklar n+1 düzeyindedir. Bu değerler ayarlandığında, sonuçları belirli düzeylerde filtreleyebilirsiniz. Bunlar ayarlandığında kapsayıcı değerlerdir. Cihazlar, algılayıcılar ve diğer nesneler, en yakın alanlarıyla aynı düzeyde kabul edilir. Belirli bir düzeydeki tüm nesneleri almak için hem minLevel hem de maxLevel değerlerini aynı değere ayarlayın.

  • minrelative ve maxRelative: Bu filtreler verildiğinde, ilgili düzey verilen alan kimliğinin düzeyine göre belirlenir:

    • Göreli düzey 0 , verilen alan kimliğiyle aynı düzeydir.
    • Göreli düzey 1 , verilen alan kimliğinin alt öğeleriyle aynı düzeydeki boşlukları temsil eder. Göreli düzey n , n düzeye göre belirtilen alandan daha düşük olan boşlukları temsil eder.
    • Göreli düzey -1 , belirtilen alanın üst alanıyla aynı düzeydeki boşlukları temsil eder.

  • traverse: Aşağıdaki değerler tarafından belirtildiği gibi, belirli bir boşluk kimliğinden her iki yönde de dolaşmanıza olanak tanır.

    • Hiçbiri: Bu varsayılan değer verilen alan kimliğine göre filtrelenir.
    • Aşağı: Bu, verilen alan kimliğine ve alt öğelerine göre filtrelenir.
    • Yukarı: Bu, verilen alan kimliğine ve üstlerine göre filtrelenir.
    • Span: Bu, uzamsal grafiğin yatay bir bölümünü verilen alan kimliğiyle aynı düzeyde filtreler. Bunun için minRelative veya maxRelative değerinin true olarak ayarlanması gerekir.

Örnekler

Aşağıdaki listede /devices API'leri aracılığıyla gezintiye ilişkin bazı örnekler gösterilmektedir. Yer tutucusunun YOUR_MANAGEMENT_API_URL , Biçimindeki Digital Twins API'lerinin URI'sine https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0/başvurduğunu ve burada YOUR_INSTANCE_NAME Azure Digital Twins örneğinizin adı olduğunu ve YOUR_LOCATION örneğinizin barındırıldığı bölge olduğunu unutmayın.

  • YOUR_MANAGEMENT_API_URL/devices?maxLevel=1 , kök alanlara bağlı tüm cihazları döndürür.
  • YOUR_MANAGEMENT_API_URL/devices?minLevel=2&maxLevel=4 2, 3 veya 4 düzeylerindeki boşluklara bağlı tüm cihazları döndürür.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId doğrudan mySpaceId'ye bağlı tüm cihazları döndürür.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down mySpaceId veya alt öğelerinden birine bağlı tüm cihazları döndürür.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&minLevel=1&minRelative=true mySpaceId hariç mySpaceId alt öğelerine bağlı tüm cihazları döndürür.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&minLevel=1&minRelative=true&maxLevel=1&maxRelative=true mySpaceId'nin hemen alt öğelerine bağlı tüm cihazları döndürür.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Up&maxLevel=-1&maxRelative=true mySpaceId'nin atalarından birine bağlı tüm cihazları döndürür.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&maxLevel=5 mySpaceId'nin 5'ten küçük veya 5'e eşit düzeydeki alt öğelerine bağlı tüm cihazları döndürür.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Span&minLevel=0&minRelative=true&maxLevel=0&maxRelative=true mySpaceId ile aynı düzeydeki boşluklara bağlı tüm cihazları döndürür.

OData desteği

/spaces üzerinde GET çağrısı gibi koleksiyonlar döndüren API'lerin çoğu, genel OData sistem sorgu seçeneklerinin aşağıdaki alt kümesini destekler:

  • $filter
  • $orderby
  • $top
  • $skip - Koleksiyonun tamamını görüntülemeyi planlıyorsanız, bunu tek bir çağrıda tüm küme olarak istemeli ve ardından uygulamanızda disk belleği gerçekleştirmelisiniz.

Not

Bazı OData seçenekleri ( sorgu seçenekleri $count, $expand ve $search gibi) şu anda desteklenmemektedir.

Örnekler

Aşağıdaki listede geçerli OData söz dizimine sahip çeşitli sorgular yer alıyor:

  • YOUR_MANAGEMENT_API_URL/devices?$top=3&$orderby=Name desc
  • YOUR_MANAGEMENT_API_URL/keystores?$filter=endswith(Description,'space')
  • YOUR_MANAGEMENT_API_URL/devices?$filter=TypeId eq 2
  • YOUR_MANAGEMENT_API_URL/resources?$filter=StatusId ne 1
  • YOUR_MANAGEMENT_API_URL/users?$top=4&$filter=endswith(LastName,'k')&$orderby=LastName
  • YOUR_MANAGEMENT_API_URL/spaces?$orderby=Name desc&$top=3&$filter=substringof('Floor',Name)

Sonraki adımlar

Bazı yaygın API sorgu desenlerini öğrenmek için bkz. Yaygın görevler için Azure Digital Twins API'lerini sorgulama.

API uç noktalarınız hakkında daha fazla bilgi edinmek için Digital Twins Swagger'ı kullanma bölümüne bakın.

OData söz dizimlerini ve kullanılabilir karşılaştırma işleçlerini gözden geçirmek için Azure Bilişsel Arama'da OData karşılaştırma işleçlerini okuyun.