Azure dijital TWINS 'de Kullanıcı tanımlı işlevler oluşturmaHow to create user-defined functions in Azure Digital Twins

Kullanıcı tanımlı işlevler , kullanıcıların gelen telemetri iletilerinden ve uzamsal grafik meta verilerinden yürütülmesi için özel mantık yapılandırmasına olanak sağlar.User-defined functions enable users to configure custom logic to be executed from incoming telemetry messages and spatial graph metadata. Kullanıcılar ayrıca, önceden tanımlı uç noktalaraolay gönderebilir.Users can also send events to predefined endpoints.

Bu kılavuzda, alınan sıcaklık olaylarından belirli bir sıcaklığın aşıldığı herhangi bir okumayı nasıl tespit ve uyaracağınızı gösteren bir örnek gösterilmektedir.This guide walks through an example demonstrating how to detect and alert on any reading that exceeds a certain temperature from received temperature events.

Aşağıdaki örneklerde YOUR_MANAGEMENT_API_URL, dijital TWINS API 'Lerinin URI 'sine başvurur:In the examples below, YOUR_MANAGEMENT_API_URL refers to the URI of the Digital Twins APIs:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0
AdName Şununla değiştirReplace with
YOUR_INSTANCE_NAMEYOUR_INSTANCE_NAME Azure dijital TWINS örneğinizin adıThe name of your Azure Digital Twins instance
YOUR_LOCATIONYOUR_LOCATION Örneğinizin barındırıldığı bölgeThe region your instance is hosted on

İstemci kitaplığı başvurusuClient library reference

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.Functions available as helper methods in the user-defined functions runtime are listed in the client library reference document.

Bir eşleştirici oluşturmaCreate a matcher

Eşleştiriciler, belirli bir telemetri iletisi için hangi kullanıcı tanımlı işlevlerin çalıştırılacağını tespit eden grafik nesneleridir.Matchers are graph objects that determine what user-defined functions run for a given telemetry message.

  • Geçerli Eşleştiricisi koşul karşılaştırmaları:Valid matcher condition comparisons:

    • Equals
    • NotEquals
    • Contains
  • Geçerli Eşleştiricisi koşul hedefleri:Valid matcher condition targets:

    • Sensor
    • SensorDevice
    • SensorSpace

Aşağıdaki örnek Eşleştiricisi, veri türü değeri olarak "Temperature" tüm algılayıcı telemetri olaylarından doğru olarak değerlendirilir.The following example matcher evaluates to true on any sensor telemetry event with "Temperature" as its data type value. Kimliği doğrulanmış bir HTTP POST isteği yaparak, Kullanıcı tanımlı bir işlevde birden fazla eşleşme oluşturabilirsiniz:You can create multiple matchers on a user-defined function by making an authenticated HTTP POST request to:

YOUR_MANAGEMENT_API_URL/matchers

JSON gövdesi ile:With JSON body:

{
  "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ğerValue Şununla değiştirReplace with
YOUR_SPACE_IDENTIFIERYOUR_SPACE_IDENTIFIER Örneğiniz üzerinde barındırılıyorsa hangi sunucu bölgeWhich server region your instance is hosted on

Kullanıcı tanımlı işlev oluşturmaCreate a user-defined function

Kullanıcı tanımlı bir işlev oluşturmak, Azure Digital TWINS yönetim API 'Lerine çok parçalı bir HTTP isteği yapmayı içerir.Creating a user-defined function involves making a multipart HTTP request to the Azure Digital Twins Management APIs.

Not

Çok parçalı istekler genellikle üç parça gerektirir:Multipart requests typically require three pieces:

  • Bir Content-Type üst bilgisi:A Content-Type header:
    • application/json; charset=utf-8
    • multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
  • Bir içerik-değerlendirme:A Content-Disposition:
    • form-data; name="metadata"
  • Karşıya yüklenecek dosya içeriğiThe file content to upload

Içerik türü ve Content-Disposition , kullanım senaryosuna göre değişir.Content-Type and Content-Disposition will vary depending on use scenario.

Çok parçalı istekler, bir REST istemcisi veya C# Postmangibi bir araç aracılığıyla programlı bir şekilde yapılabilir.Multipart requests can be made programmatically (through C#), through a REST client, or tool such as Postman. REST istemci araçları karmaşık çok parçalı istekler için farklı destek düzeylerine sahip olabilir.REST client tools may have varying levels of support for complex multipart requests. Yapılandırma ayarları ayrıca araç ve araç arasında biraz farklılık gösterebilir.Configuration settings may also vary slightly from tool to tool. İhtiyaçlarınıza en uygun aracı doğrulayın.Verify which tool is best suited for your needs.

Önemli

Azure Digital TWINS yönetim API 'Lerine yapılan çok parçalı isteklerin genellikle iki bölümü vardır:Multipart requests made to the Azure Digital Twins Management APIs typically have two parts:

  • Content-Type ve/veya Content-Disposition tarafından belirtilen blob meta verileri (ÖRNEĞIN, ilişkili bir MIME türü)Blob metadata (such as an associated MIME type) that's declared by Content-Type and/or Content-Disposition
  • Karşıya yüklenecek bir dosyanın yapılandırılmamış içeriğini içeren blob içeriğiBlob contents which include the unstructured contents of a file to be uploaded

Düzeltme Eki istekleri için iki bölümden hiçbiri gerekli değildir.Neither of the two parts is required for PATCH requests. Post veya Create işlemleri için her ikisi de gereklidir.Both are required for POST or create operations.

Doluluk hızlı başlangıç kaynak kodu , Azure C# Digital TWINS yönetim API 'lerinde çok parçalı isteklerin nasıl yapılacağını gösteren tüm örnekleri içerir.The Occupancy Quickstart source code contains complete C# examples demonstrating how to make multipart requests against the Azure Digital Twins Management APIs.

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ı karşıya yükleyin:After the matchers are created, upload the function snippet with the following authenticated multipart HTTP POST request to:

YOUR_MANAGEMENT_API_URL/userdefinedfunctions

Aşağıdaki gövdesini kullanın:Use the following body:

--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ğerValue Şununla değiştirReplace with
USER_DEFINED_BOUNDARYUSER_DEFINED_BOUNDARY Çok parçalı bir içerik sınır adıA multipart content boundary name
YOUR_SPACE_IDENTIFIERYOUR_SPACE_IDENTIFIER Alan tanımlayıcısıThe space identifier
YOUR_MATCHER_IDENTIFIERYOUR_MATCHER_IDENTIFIER Kullanmak istediğiniz eşleştirici KIMLIĞIThe ID of the matcher you want to use
  1. Üstbilgilerin şunları içerdiğini doğrulayın: Content-Type: multipart/form-data; boundary="USER_DEFINED_BOUNDARY".Verify that the headers include: Content-Type: multipart/form-data; boundary="USER_DEFINED_BOUNDARY".

  2. Gövdenin çok parçalı olduğunu doğrulayın:Verify that the body is multipart:

    • İlk bölüm, gerekli Kullanıcı tanımlı işlev meta verilerini içerir.The first part contains the required user-defined function metadata.
    • İkinci bölüm JavaScript işlem mantığını içerir.The second part contains the JavaScript compute logic.
  3. USER_DEFINED_BOUNDARY bölümünde, spaceıd (YOUR_SPACE_IDENTIFIER) ve Matchers (YOUR_MATCHER_IDENTIFIER) değerlerini değiştirin.In the USER_DEFINED_BOUNDARY section, replace the spaceId (YOUR_SPACE_IDENTIFIER) and matchers (YOUR_MATCHER_IDENTIFIER) values.

  4. JavaScript Kullanıcı tanımlı işlevinin Content-Type: text/javascriptolarak verildiğini doğrulayın.Verify that the JavaScript user-defined function is supplied as Content-Type: text/javascript.

Örnek işlevlerExample functions

Algılayıcı telemetrisini, sensor.DataTypeveri türü sıcaklıkile doğrudan algılayıcı için okuma olarak ayarlayın:Set the sensor telemetry reading directly for the sensor with data type Temperature, which is sensor.DataType:

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, bir algılayıcı tarafından gönderilen iletiye karşılık gelen sensorıd ve ileti özniteliklerini gösterir.The telemetry parameter exposes the SensorId and Message attributes, corresponding to a message sent by a sensor. ExecutionContext parametresi aşağıdaki öznitelikleri kullanıma sunar:The executionContext parameter exposes the following attributes:

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

Sonraki örnekte, algılayıcı telemetri okuma işi önceden tanımlanmış bir eşiği geçerse bir ileti günlüğe kaydedilir.In the next example, we log a message if the sensor telemetry reading surpasses a predefined threshold. Azure dijital TWINS örneğinde tanılama ayarlarınız etkinleştirilmişse, Kullanıcı tanımlı işlevlerden alınan Günlükler de iletilir:If your diagnostic settings are enabled on the Azure Digital Twins instance, logs from user-defined functions are also forwarded:

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!`);
  }
}

Aşağıdaki kod, sıcaklık düzeyi önceden tanımlanmış sabitin üzerine yükselse bir bildirimi tetikler:The following code triggers a notification if the temperature level rises above the predefined constant:

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 bkz. doluluk hızlıbaşlangıcı.For a more complex user-defined function code sample, see the Occupancy quickstart.

Rol ataması oluşturmaCreate a role assignment

Kullanıcı tanımlı işlevin altında çalışacağı bir rol ataması oluşturun.Create a role assignment for the user-defined function to run under. Kullanıcı tanımlı işlev için herhangi bir rol ataması yoksa, yönetim API 'SI ile etkileşim kurmak için gerekli izinlere sahip olmaz veya grafik nesnelerinde eylem gerçekleştirmeye yönelik erişime sahip olmaz.If no role assignment exists for the user-defined function, it won't have the proper permissions to interact with the Management API or have access to perform actions on graph objects. Kullanıcı tanımlı bir işlevin gerçekleştirebileceği eylemler, Azure Digital TWINS yönetim API 'Leri içinde rol tabanlı erişim denetimi aracılığıyla belirtilir ve tanımlanır.Actions that a user-defined function may perform are specified and defined via role-based access control within the Azure Digital Twins Management APIs. Örneğin, Kullanıcı tanımlı işlevler belirli roller veya belirli erişim denetimi yolları belirtilerek kapsamda sınırlandırılabilir.For example, user-defined functions can be limited in scope by specifying certain roles or certain access control paths. Daha fazla bilgi için bkz. rol tabanlı erişim denetimi belgeleri.For more information, see the Role-based access control documentation.

  1. Kullanıcı tanımlı işlevinizde atamak istediğiniz rol KIMLIĞINI almak için tüm roller için SISTEM API 'Sini sorgulayın .Query the System API for all roles to get the role ID you want to assign to your user-defined function. Şunları yapmak için kimliği doğrulanmış bir HTTP GET isteği yaparak:Do so by making an authenticated HTTP GET request to:

    YOUR_MANAGEMENT_API_URL/system/roles
    

    İstenen rol KIMLIĞINI koruyun.Keep the desired role ID. Aşağıdaki JSON gövde özniteliği rol kimliği (YOUR_DESIRED_ROLE_IDENTIFIER) olarak geçirilir.It will be passed as the JSON body attribute roleId (YOUR_DESIRED_ROLE_IDENTIFIER) below.

  2. ObjectID (YOUR_USER_DEFINED_FUNCTION_ID), daha önce oluşturulmuş Kullanıcı TANıMLı işlev kimliği olacaktır.objectId (YOUR_USER_DEFINED_FUNCTION_ID) will be the user-defined function ID that was created earlier.

  3. fullpathile alanları sorgulayarak yolun (YOUR_ACCESS_CONTROL_PATH) değerini bulun.Find the value of path (YOUR_ACCESS_CONTROL_PATH) by querying your spaces with fullpath.

  4. Döndürülen spacePaths değerini kopyalayın.Copy the returned spacePaths value. Bunu aşağıda kullanacaksınız.You'll use that below. Kimliği doğrulanmış bir HTTP GET isteği oluşturmak için:Make an authenticated HTTP GET request to:

    YOUR_MANAGEMENT_API_URL/spaces?name=YOUR_SPACE_NAME&includes=fullpath
    
    DeğerValue Şununla değiştirReplace with
    YOUR_SPACE_NAMEYOUR_SPACE_NAME Kullanmak istediğiniz alanın adıThe name of the space you wish to use
  5. Kimliği doğrulanmış bir HTTP POST isteği yaparak Kullanıcı tanımlı bir işlev rolü ataması oluşturmak için döndürülen spacePaths değerini yola yapıştırın:Paste the returned spacePaths value into path to create a user-defined function role assignment by making an authenticated HTTP POST request to:

    YOUR_MANAGEMENT_API_URL/roleassignments
    

    JSON gövdesi ile:With JSON body:

    {
      "roleId": "YOUR_DESIRED_ROLE_IDENTIFIER",
      "objectId": "YOUR_USER_DEFINED_FUNCTION_ID",
      "objectIdType": "YOUR_USER_DEFINED_FUNCTION_TYPE_ID",
      "path": "YOUR_ACCESS_CONTROL_PATH"
    }
    
    DeğerValue Şununla değiştirReplace with
    YOUR_DESIRED_ROLE_IDENTIFIERYOUR_DESIRED_ROLE_IDENTIFIER İstenen rolün tanımlayıcısıThe identifier for the desired role
    YOUR_USER_DEFINED_FUNCTION_IDYOUR_USER_DEFINED_FUNCTION_ID Kullanmak istediğiniz kullanıcı tanımlı işlevin KIMLIĞIThe ID for the user-defined function you want to use
    YOUR_USER_DEFINED_FUNCTION_TYPE_IDYOUR_USER_DEFINED_FUNCTION_TYPE_ID Kullanıcı tanımlı işlev türünü belirten KIMLIKThe ID specifying the user-defined function type
    YOUR_ACCESS_CONTROL_PATHYOUR_ACCESS_CONTROL_PATH Erişim denetimi yoluThe access control path

İpucu

Kullanıcı tanımlı işlev yönetimi API işlemleri ve uç noktaları hakkında daha fazla bilgi için rol atamaları oluşturma ve yönetme makalesini okuyun.Read the article How to create and manage role assignments for more information about user-defined function Management API operations and endpoints.

İşlenmek üzere telemetri gönderSend telemetry to be processed

Uzamsal zeka grafiğinde tanımlanan algılayıcı telemetri gönderir.The sensor defined in the spatial intelligence graph sends telemetry. Buna karşılık telemetri, yüklenen Kullanıcı tanımlı işlevin yürütülmesini tetikler.In turn, the telemetry triggers the execution of the user-defined function that was uploaded. Veri işlemcisi Telemetriyi seçer.The data processor picks up the telemetry. Ardından, Kullanıcı tanımlı işlevin çağrılması için bir yürütme planı oluşturulur.Then an execution plan is created for the invocation of the user-defined function.

  1. Okumayı oluşturan algılayıcı için eşleştiriciler alın.Retrieve the matchers for the sensor the reading was generated from.
  2. Hangi eşleştiriciler başarıyla değerlendirildiğine bağlı olarak, ilişkili kullanıcı tanımlı işlevleri alın.Depending on what matchers were evaluated successfully, retrieve the associated user-defined functions.
  3. Kullanıcı tanımlı her işlevi yürütün.Execute each user-defined function.

Sonraki adımlarNext steps