Veri işleme ve kullanıcı tanımlı işlevleriData processing and user-defined functions

Azure dijital TWINS, gelişmiş işlem özellikleri sunar.Azure Digital Twins offers advanced compute capabilities. Geliştiriciler, önceden tanımlanmış uç noktalara olay göndermek için gelen telemetri iletilerine karşı özel işlevler tanımlayabilir ve çalıştırabilir.Developers can define and run custom functions against incoming telemetry messages to send events to predefined endpoints.

Veri işleme akışıData processing flow

Cihazların Azure dijital TWINS 'e telemetri verileri gönderdikten sonra, geliştiriciler verileri dört aşamada işleyebilir: doğrulama, eşleşme, işlemve dağıtım.After devices send telemetry data to Azure Digital Twins, developers can process data in four phases: validate, match, compute, and dispatch.

Azure dijital TWINS veri işleme akışını Azure Digital Twins data processing flow

  1. Doğrulama aşaması, gelen telemetri iletisini, yaygın olarak anlaşılan bir veri aktarımı nesne biçimine dönüştürür.The validate phase transforms the incoming telemetry message to a commonly understood data transfer object format. Bu aşama Ayrıca cihaz ve algılayıcı doğrulamasını yürütür.This phase also executes device and sensor validation.
  2. Eşleştirme aşaması, çalıştırılacak uygun Kullanıcı tanımlı işlevleri bulur.The match phase finds the appropriate user-defined functions to run. Önceden tanımlı eşleştiriciler, gelen telemetri iletisinden cihaz, algılayıcı ve alan bilgilerine göre Kullanıcı tanımlı işlevleri bulur.Predefined matchers find the user-defined functions based on the device, sensor, and space information from the incoming telemetry message.
  3. İşlem aşaması, önceki aşamada eşleşen kullanıcı tanımlı işlevleri çalıştırır.The compute phase runs the user-defined functions matched in the previous phase. Bu işlevler, uzamsal grafik düğümlerinde hesaplanan değerleri okuyabilir ve güncelleştirebilir ve özel bildirimler yayabilir.These functions might read and update computed values on spatial graph nodes and can emit custom notifications.
  4. Dağıtım aşaması, işlem aşamasından gelen özel bildirimleri grafikte tanımlanan uç noktalara yönlendirir.The dispatch phase routes any custom notifications from the compute phase to endpoints defined in the graph.

Veri işleme nesneleriData processing objects

Azure dijital TWINS 'de veri işleme üç nesne tanımlamayı içerir: eşleştiriciler, Kullanıcı tanımlı işlevlerve rol atamaları.Data processing in Azure Digital Twins consists of defining three objects: matchers, user-defined functions, and role assignments.

Azure dijital TWINS veri işleme nesneleri Azure Digital Twins data processing objects

EşleştiricilerMatchers

Eşleştiriciler, gelen algılayıcı telemetrisine göre hangi eylemlerin gerçekleşmekte olduğunu değerlendiren bir koşul kümesi tanımlar.Matchers define a set of conditions that evaluate what actions take place based on incoming sensor telemetry. Eşleşmeyi belirleme koşulları, sensörden, sensörün üst cihazından ve sensörün üst alanıyla eşleşen özellikler içerebilir.Conditions to determine the match might include properties from the sensor, the sensor's parent device, and the sensor's parent space. Koşullar, bu örnekte özetlenen bir JSON yoluna yönelik karşılaştırmalar olarak ifade edilir:The conditions are expressed as comparisons against a JSON path as outlined in this example:

  • Kaçan dize değeri ile temsil edilen veri türü sıcaklığının tüm sensör \"Temperature\"All sensors of datatype Temperature represented by the escaped String value \"Temperature\"
  • Bağlantı noktasında 01 olmaHaving 01 in their port
  • Genişletilmiş özellik anahtarı üreticisine sahip cihazlara ait olan, kaçan dize değeri olarak ayarlanmış olan cihazlara aittir \"Contoso\"Which belong to devices with the extended property key Manufacturer set to the escaped String value \"Contoso\"
  • Kaçan dize tarafından belirtilen türdeki boşluklara ait olan \"Venue\"Which belong to spaces of the type specified by the escaped String \"Venue\"
  • Üst Spaceıd 'nin alt öğeleri olan DE8F06CA-1138-4AD7-89F4-F782CC6F69FDWhich are descendants of parent SpaceId DE8F06CA-1138-4AD7-89F4-F782CC6F69FD
{
  "id": "23535afafd-f39b-46c0-9b0c-0dd3892a1c30",
  "name": "My custom matcher",
  "spaceId": "DE8F06CA-1138-4AD7-89F4-F782CC6F69FD",
  "description": "All sensors of datatype Temperature with 01 in their port that belong to devices with the extended property key Manufacturer set to the value Contoso and that belong to spaces of type Venue that are somewhere below space Id DE8F06CA-1138-4AD7-89F4-F782CC6F69FD",
  "conditions": [
    {
      "id": "43898sg43-e15a-4e9c-abb8-2gw464364",
      "target": "Sensor",
      "path": "$.dataType",
      "value": "\"Temperature\"",
      "comparison": "Equals"
    },
    {
      "id": "wt3th44-e15a-35sg-seg3-235wf3ga463",
      "target": "Sensor",
      "path": "$.port",
      "value": "01",
      "comparison": "Contains"
    },
    {
      "id": "735hs33-e15a-37jj-23532-db901d550af5",
      "target": "SensorDevice",
      "path": "$.properties[?(@.name == 'Manufacturer')].value",
      "value": "\"Contoso\"",
      "comparison": "Equals"
    },
    {
      "id": "222325-e15a-49fg-5744-463643644",
      "target": "SensorSpace",
      "path": "$.type",
      "value": "\"Venue\"",
      "comparison": "Equals"
    }
  ]
}

Önemli

  • JSON yolları büyük/küçük harfe duyarlıdır.JSON paths are case sensitive.
  • JSON yükü, tarafından döndürülen yük ile aynıdır:The JSON payload is the same as the payload that's returned by:
    • algılayıcı için /sensors/{id}?includes=properties,types./sensors/{id}?includes=properties,types for the sensor.
    • sensör üst cihazının /devices/{id}?includes=properties,types,sensors,sensorsproperties,sensorstypes./devices/{id}?includes=properties,types,sensors,sensorsproperties,sensorstypes for the sensor's parent device.
    • sensör üst alanı için /spaces/{id}?includes=properties,types,location,timezone./spaces/{id}?includes=properties,types,location,timezone for the sensor's parent space.
  • Karşılaştırmalar büyük/küçük harfe duyarlıdır.The comparisons are case insensitive.

Kullanıcı tanımlı işlevlerUser-defined functions

Kullanıcı tanımlı bir işlev, yalıtılmış bir Azure dijital TWINS ortamı içinde yürütülen özel bir işlevdir.A user-defined function is a custom function executed within an isolated Azure Digital Twins environment. Kullanıcı tanımlı işlevlerin, alındığı için ham algılayıcı telemetri iletisine erişimi vardır.User-defined functions have access to raw sensor telemetry message as it gets received. Kullanıcı tanımlı işlevlerin de uzamsal grafik ve dağıtıcı hizmetine erişimi vardır.User-defined functions also have access to the spatial graph and dispatcher service. Kullanıcı tanımlı işlev bir grafik içinde kaydedildikten sonra, işlevin ne zaman yürütüleceğini belirtmek için bir eşleştirici ( yukarıyaayrıntılı) oluşturulmalıdır.After the user-defined function is registered within a graph, a matcher (detailed above) must be created to specify when the function is executed. Örneğin, Azure dijital TWINS, belirli bir sensörden yeni telemetri aldığında, eşleşen kullanıcı tanımlı işlev, son birkaç algılayıcı okumasının hareketli ortalamasını hesaplayabilir.For example, when Azure Digital Twins receives new telemetry from a given sensor, the matched user-defined function can calculate a moving average of the last few sensor readings.

Kullanıcı tanımlı işlevler JavaScript 'te yazılabilir.User-defined functions can be written in JavaScript. Yardımcı yöntemler Kullanıcı tanımlı yürütme ortamında grafikle etkileşime geçin.Helper methods interact with the graph in the user-defined execution environment. Geliştiriciler, algılayıcı telemetri iletilerine karşı özel kod parçacıkları yürütebilir.Developers can execute custom snippets of code against sensor telemetry messages. Örneğin:Examples include:

  • Algılayıcısı grafik içindeki algılayıcı nesnesine doğrudan okumayı ayarlayın.Set the sensor reading directly onto the sensor object within the graph.
  • Grafikteki bir boşluk içindeki farklı algılayıcı okumaları temelinde bir eylem gerçekleştirir.Perform an action based on different sensor readings within a space in the graph.
  • Gelen algılayıcı okuma için belirli koşullar karşılandığında bir bildirim oluşturun.Create a notification when certain conditions are met for an incoming sensor reading.
  • Bir bildirim göndermeden önce algılayıcı okumaya grafik meta verileri ekleyin.Attach graph metadata to the sensor reading before sending out a notification.

Daha fazla bilgi için bkz. Kullanıcı tanımlı işlevleri kullanma.For more information, see How to use user-defined functions.

ÖrneklerExamples

Dijital TWINS C# örneği için GitHub deposu , Kullanıcı tanımlı işlevlere birkaç örnek içerir:The GitHub repo for the Digital Twins C# sample contains a few examples of the user-defined functions:

  • Bu işlev , Aralık içinde bu değerlerle kullanılabilir bir oda olup olmadığını belirlemede karbon dioksit, hareket ve sıcaklık değerlerini arar.This function looks for carbon dioxide, motion, and temperature values to determine whether a room is available with these values in range. Dijital TWINS öğreticileri , daha ayrıntılı bilgi için bu işlevi keşfedebilir.The tutorials for Digital Twins explore this function in more details.
  • Bu işlev , birden çok hareket sensörlerinden verileri arar ve hiçbir türlü hareketi algılamazsa alanın kullanılabilir olduğunu belirler.This function looks for data from multiple motion sensors, and determines that the space is available if none of them detect any motion. Dosyanın açıklamalar bölümünde bahsedilen değişiklikleri yaparak hızlıbaşlangıçta veya öğreticilerdekullanılan Kullanıcı tanımlı işlevi kolayca değiştirebilirsiniz.You can easily replace the user-defined function used in either the quickstart, or the tutorials, by making the changes mentioned in the comments section of the file.

Rol atamasıRole assignment

Kullanıcı tanımlı bir işlevin eylemleri, hizmet içindeki verilerin güvenliğini sağlamak için Azure dijital TWINS rol tabanlı erişim denetimine tabidir.A user-defined function's actions are subject to Azure Digital Twins role-based access control to secure data within the service. Rol atamaları, uzamsal grafikle ve varlıklarıyla etkileşimde bulunmak için hangi kullanıcı tanımlı işlevlerin uygun izinlere sahip olduğunu tanımlar.Role assignments define which user-defined functions have the proper permissions to interact with the spatial graph and its entities. Örneğin, Kullanıcı tanımlı bir işlev, belirli bir alanda grafik verileri oluşturma, okuma, güncelleştirmeveya silme özelliğine sahip olabilir.For example, a user-defined function might have the ability and permission to CREATE, READ, UPDATE, or DELETE graph data under a given space. Kullanıcı tanımlı işlev grafiğe veri istediğinde veya bir eylemi denediğinde Kullanıcı tanımlı bir işlevin erişim düzeyi denetlenir.A user-defined function's level of access is checked when the user-defined function asks the graph for data or attempts an action. Daha fazla bilgi için bkz. rol tabanlı erişim denetimi.For more information, see Role-based access control.

Bir Eşleştirici, rol ataması olmayan kullanıcı tanımlı bir işlevin tetiklenmesi mümkündür.It's possible for a matcher to trigger a user-defined function that has no role assignments. Bu durumda, Kullanıcı tanımlı işlev grafikten veri okuyamazsa.In this case, the user-defined function fails to read any data from the graph.

Sonraki adımlarNext steps