Azure Digital Twins'de kullanıcı tanımlı işlevler oluşturma
Ö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 |
Üst bilgilerin şunları içerdiğini doğrulayın:
Content-Type: multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
.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.
USER_DEFINED_BOUNDARY bölümünde spaceId (
YOUR_SPACE_IDENTIFIER
) ve eşleştirici (YOUR_MATCHER_IDENTIFIER
) değerlerini değiştirin.JavaScript kullanıcı tanımlı işlevinin olarak
Content-Type: text/javascript
sağ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.
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.objectId (
YOUR_USER_DEFINED_FUNCTION_ID
), daha önce oluşturulmuş kullanıcı tanımlı işlev kimliği olacaktır.ile
fullpath
boşluklarınızı sorgulayarak yolun (YOUR_ACCESS_CONTROL_PATH
) değerini bulun.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ı 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.
- Okumanın oluşturulduğu algılayıcı için eşleştiricileri alın.
- Hangi eşleştiricilerin başarıyla değerlendirildiğine bağlı olarak, ilişkili kullanıcı tanımlı işlevleri alın.
- Kullanıcı tanımlı her işlevi yürütür.
Sonraki adımlar
Olayları göndermek için Azure Digital Twins uç noktaları oluşturmayı öğrenin.
Azure Digital Twins'de yönlendirme hakkında daha fazla ayrıntı için Bkz . Olayları ve iletileri yönlendirme.
İstemci kitaplığı başvuru belgelerini gözden geçirin.