Azure Digital Twins'de kullanıcı tanımlı işlevler oluşturma

  • Makale

Önemli

Azure Digital Twins hizmetinin yeni bir sürümü yayımlandı. 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 Belgelerini ziyaret edin.

Kullanıcı tanımlı işlevler , kullanıcıların gelen telemetri iletilerinden ve uzamsal graf meta verilerinden yürütülecek özel mantığı yapılandırmalarına olanak tanır. Kullanıcılar önceden tanımlanmış uç noktalara da olay gönderebilir.

Bu kılavuz, alınan sıcaklık olaylarından belirli bir sıcaklığı aşan herhangi bir okumanın nasıl algılandığını ve uyarı alındığını gösteren bir örnekte yol gösterir.

Aşağıdaki örneklerde Digital YOUR_MANAGEMENT_API_URL Twins API'lerinin URI'sini ifade eder:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0
Name Şununla değiştir
YOUR_INSTANCE_NAME Azure Digital Twins örneğinizin adı
YOUR_LOCATION Örneğinizin barındırılıyor olduğu bölge

İstemci kitaplığı başvurusu

Kullanıcı tanımlı işlevler çalışma zamanında yardımcı yöntemler olarak kullanılabilen işlevler , istemci kitaplığı başvuru belgesinde listelenir.

Eşleştirici oluşturma

Eşleştiriciler, belirli bir telemetri iletisi için hangi kullanıcı tanımlı işlevlerin çalıştırıldığını belirleyen grafik nesneleridir.

  • Geçerli eşleştirici koşulu karşılaştırmaları:

    • Equals
    • NotEquals
    • Contains

  • Geçerli eşleştirici koşulu hedefleri:

    • Sensor
    • SensorDevice
    • SensorSpace

Aşağıdaki örnek eşleştirici, veri türü değeri olarak ile "Temperature" tüm algılayıcı telemetri olaylarında true olarak değerlendirilir. Kimliği doğrulanmış HTTP POST isteğinde bulunarak kullanıcı tanımlı bir işlevde birden çok eşleştirici oluşturabilirsiniz:

YOUR_MANAGEMENT_API_URL/matchers

JSON gövdesiyle:

{
  "id": "3626464-f39b-46c0-d9b0c-436aysj55",
  "name": "Temperature Matcher",
  "spaceId": "YOUR_SPACE_IDENTIFIER",
  "conditions": [
    {
      "id": "ag7gq35cfu3-e15a-4e9c-6437-sj6w68sy44s",
      "target": "Sensor",
      "path": "$.dataType",
      "value": "\"Temperature\"",
      "comparison": "Equals"
    }
  ]
}
Değer Şununla değiştir
YOUR_SPACE_IDENTIFIER Örneğinizin barındırıldığı sunucu bölgesi

Kullanıcı tanımlı işlev oluşturma

Kullanıcı tanımlı işlev oluşturmak için Azure Digital Twins Yönetim API'lerine çok parçalı HTTP isteği göndermeniz gerekir.

Not

Çok parçalı istekler genellikle üç parça gerektirir:

  • İçerik Türü üst bilgisi:
    • application/json; charset=utf-8
    • multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
  • İçerik Bırakma:
    • form-data; name="metadata"
  • Karşıya yüklenecek dosya içeriği

İçerik Türü ve İçerik Bırakma, kullanım senaryosuna bağlı olarak değişir.

Çok parçalı istekler program aracılığıyla (C# aracılığıyla), bir REST istemcisi veya Postman gibi bir araç aracılığıyla yapılabilir. REST istemci araçlarının karmaşık çok parçalı istekler için farklı destek düzeyleri olabilir. Yapılandırma ayarları araçtan ara çubuğuna biraz farklılık gösterebilir. Hangi aracın ihtiyaçlarınıza en uygun olduğunu doğrulayın.

Önemli

Azure Digital Twins Yönetim API'lerine yapılan çok parçalı istekler genellikle iki bölümden oluşur:

  • content-Type ve/veya Content-Disposition tarafından bildirilen blob meta verileri (ilişkili MIME türü gibi)
  • Karşıya yüklenecek dosyanın yapılandırılmamış içeriğini içeren blob içeriği

PATCH istekleri için iki bölümden hiçbiri gerekli değildir. Her ikisi de POST veya oluşturma işlemleri için gereklidir.

Doluluk Hızlı Başlangıç kaynak kodu, Azure Digital Twins Yönetim API'lerine karşı çok parçalı istekler yapmayı gösteren tam C# örnekleri içerir.

Eşleştiriciler oluşturulduktan sonra, aşağıdaki kimliği doğrulanmış çok parçalı HTTP POST isteğiyle işlev parçacığını şu şekilde karşıya yükleyin:

YOUR_MANAGEMENT_API_URL/userdefinedfunctions

Aşağıdaki gövdeyi kullanın:

--USER_DEFINED_BOUNDARY
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data; name="metadata"

{
  "spaceId": "YOUR_SPACE_IDENTIFIER",
  "name": "User Defined Function",
  "description": "The contents of this udf will be executed when matched against incoming telemetry.",
  "matchers": ["YOUR_MATCHER_IDENTIFIER"]
}
--USER_DEFINED_BOUNDARY
Content-Disposition: form-data; name="contents"; filename="userDefinedFunction.js"
Content-Type: text/javascript

function process(telemetry, executionContext) {
  // Code goes here.
}

--USER_DEFINED_BOUNDARY--
Değer Şununla değiştir
USER_DEFINED_BOUNDARY Çok parçalı içerik sınırı adı
YOUR_SPACE_IDENTIFIER Boşluk tanımlayıcısı
YOUR_MATCHER_IDENTIFIER Kullanmak istediğiniz eşleştiricinin kimliği

  1. Üst bilgilerin şunları içerdiğini doğrulayın: Content-Type: multipart/form-data; boundary="USER_DEFINED_BOUNDARY".

  2. Gövdenin çok parçalı olduğunu doğrulayın:

    • İlk bölüm gerekli kullanıcı tanımlı işlev meta verilerini içerir.
    • İkinci bölüm JavaScript işlem mantığını içerir.

  3. USER_DEFINED_BOUNDARY bölümünde spaceId (YOUR_SPACE_IDENTIFIER) ve eşleştirici (YOUR_MATCHER_IDENTIFIER) değerlerini değiştirin.

  4. JavaScript kullanıcı tanımlı işlevinin olarak Content-Type: text/javascriptsağlandığını doğrulayın.

Örnek işlevler

Algılayıcı telemetrisini doğrudan sensör için sıcaklıksensor.DataType veri türüne sahip olan şu şekilde ayarlayın:

function process(telemetry, executionContext) {

  // Get sensor metadata
  var sensor = getSensorMetadata(telemetry.SensorId);

  // Retrieve the sensor value
  var parseReading = JSON.parse(telemetry.Message);

  // Set the sensor reading as the current value for the sensor.
  setSensorValue(telemetry.SensorId, sensor.DataType, parseReading.SensorValue);
}

Telemetri parametresi, algılayıcı tarafından gönderilen bir iletiye karşılık gelen SensorId ve Message özniteliklerini kullanıma sunar. executionContext parametresi aşağıdaki öznitelikleri kullanıma sunar:

var executionContext = new UdfExecutionContext
{
    EnqueuedTime = request.HubEnqueuedTime,
    ProcessorReceivedTime = request.ProcessorReceivedTime,
    UserDefinedFunctionId = request.UserDefinedFunctionId,
    CorrelationId = correlationId.ToString(),
};

Sonraki örnekte, algılayıcı telemetri okuması önceden tanımlanmış eşiği aşıyorsa bir ileti günlüğe kaydederiz. Tanılama ayarlarınız Azure Digital Twins örneğinde etkinleştirildiyse, kullanıcı tanımlı işlevlerden gelen günlükler de iletilir:

function process(telemetry, executionContext) {

  // Retrieve the sensor value
  var parseReading = JSON.parse(telemetry.Message);

  // Example sensor telemetry reading range is greater than 0.5
  if(parseFloat(parseReading.SensorValue) > 0.5) {
    log(`Alert: Sensor with ID: ${telemetry.SensorId} detected an anomaly!`);
  }
}

Sıcaklık düzeyi önceden tanımlanmış sabitin üzerine çıkarsa aşağıdaki kod bir bildirim tetikler:

function process(telemetry, executionContext) {

  // Retrieve the sensor value
  var parseReading = JSON.parse(telemetry.Message);

  // Define threshold
  var threshold = 70;

  // Trigger notification 
  if(parseInt(parseReading) > threshold) {
    var alert = {
      message: 'Temperature reading has surpassed threshold',
      sensorId: telemetry.SensorId,
      reading: parseReading
    };

    sendNotification(telemetry.SensorId, "Sensor", JSON.stringify(alert));
  }
}

Daha karmaşık bir kullanıcı tanımlı işlev kodu örneği için , Doluluk hızlı başlangıcını okuyun.

Rol ataması oluşturma

Kullanıcı tanımlı işlevin altında çalışması için bir rol ataması oluşturun. Kullanıcı tanımlı işlev için rol ataması yoksa, Yönetim API'siyle etkileşime geçmek için uygun izinlere veya grafik nesneleri üzerinde eylem gerçekleştirme erişimine sahip olmaz. Kullanıcı tanımlı bir işlevin gerçekleştirebileceği eylemler, Azure Digital Twins Yönetim API'leri içindeki rol tabanlı erişim denetimi aracılığıyla belirtilir ve tanımlanır. Örneğin, kullanıcı tanımlı işlevler belirli roller veya belirli erişim denetimi yolları belirtilerek kapsam dahilinde sınırlanabilir. Daha fazla bilgi için Rol tabanlı erişim denetimi belgelerini okuyun.

  1. Kullanıcı tanımlı işlevinize atamak istediğiniz rol kimliğini almak için tüm roller için Sistem API'sini sorgular. Bunu yapmak için kimliği doğrulanmış bir HTTP GET isteği oluşturun:

    YOUR_MANAGEMENT_API_URL/system/roles

    İstenen rol kimliğini koruyun. Aşağıda JSON gövde özniteliği roleId (YOUR_DESIRED_ROLE_IDENTIFIER) olarak geçirilecektir.

  2. objectId (YOUR_USER_DEFINED_FUNCTION_ID), daha önce oluşturulmuş kullanıcı tanımlı işlev kimliği olacaktır.

  3. ile fullpathboşluklarınızı sorgulayarak yolun (YOUR_ACCESS_CONTROL_PATH) değerini bulun.

  4. Döndürülen spacePaths değeri kopyalayın. Bunu aşağıda kullanacaksınız. Kimliği doğrulanmış bir HTTP GET isteği oluşturun:

    YOUR_MANAGEMENT_API_URL/spaces?name=YOUR_SPACE_NAME&includes=fullpath
    Değer Şununla değiştir
    YOUR_SPACE_NAME Kullanmak istediğiniz alanın adı

  5. Kimliği doğrulanmış HTTP POST isteğinde bulunarak kullanıcı tanımlı işlev rolü ataması oluşturmak için döndürülen spacePaths değeri yola yapıştırın:

    YOUR_MANAGEMENT_API_URL/roleassignments

    JSON gövdesiyle:

    {
  "roleId": "YOUR_DESIRED_ROLE_IDENTIFIER",
  "objectId": "YOUR_USER_DEFINED_FUNCTION_ID",
  "objectIdType": "YOUR_USER_DEFINED_FUNCTION_TYPE_ID",
  "path": "YOUR_ACCESS_CONTROL_PATH"
}
    Değer Şununla değiştir
    YOUR_DESIRED_ROLE_IDENTIFIER İstenen rolün tanımlayıcısı
    YOUR_USER_DEFINED_FUNCTION_ID Kullanmak istediğiniz kullanıcı tanımlı işlevin kimliği
    YOUR_USER_DEFINED_FUNCTION_TYPE_ID Kullanıcı tanımlı işlev türünü belirten kimlik (UserDefinedFunctionId)
    YOUR_ACCESS_CONTROL_PATH Erişim denetimi yolu

İpucu

Kullanıcı tanımlı işlev Yönetimi API'sinin işlemleri ve uç noktaları hakkında daha fazla bilgi için Rol atamaları oluşturma ve yönetme makalesini okuyun.

İşlenecek telemetri gönderme

Uzamsal zeka grafında tanımlanan algılayıcı telemetri gönderir. Buna karşılık telemetri, karşıya yüklenen kullanıcı tanımlı işlevin yürütülmesini tetikler. Veri işlemcisi telemetriyi alır. Ardından, kullanıcı tanımlı işlevin çağrılması için bir yürütme planı oluşturulur.

  1. Okumanın oluşturulduğu algılayıcı için eşleştiricileri alın.
  2. Hangi eşleştiricilerin başarıyla değerlendirildiğine bağlı olarak, ilişkili kullanıcı tanımlı işlevleri alın.
  3. Kullanıcı tanımlı her işlevi yürütür.

Sonraki adımlar