Vytvoření uživatelem definovaných funkcí ve službě Azure Digital Twins

Důležité

Byla vydána nová verze služby Azure Digital Twins. Vzhledem k rozšířeným funkcím nové služby byla původní služba Azure Digital Twins (popsaná v této sadě dokumentace) vyřazena.

Pokud chcete zobrazit dokumentaci k nové službě, navštivte aktivní dokumentaci ke službě Azure Digital Twins.

Uživatelem definované funkce umožňují uživatelům konfigurovat vlastní logiku, která se má spouštět z příchozích zpráv telemetrie a metadat prostorového grafu. Uživatelé můžou také odesílat události do předdefinovaných koncových bodů.

Tento průvodce vás provede příkladem, který ukazuje, jak zjistit a upozornit na jakékoli čtení, které překračuje určitou teplotu z přijatých událostí teploty.

V následujících YOUR_MANAGEMENT_API_URL příkladech se odkazuje na identifikátor URI rozhraní API služby Digital Twins:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0

Název	Nahradit hodnotou
YOUR_INSTANCE_NAME	Název instance služby Azure Digital Twins
YOUR_LOCATION	Oblast, ve které je vaše instance hostovaná

Referenční informace k klientské knihovně

Funkce dostupné jako pomocné metody v modulu runtime uživatelem definovaných funkcí jsou uvedeny v referenčním dokumentu klientské knihovny .

Vytvoření matcheru

Matchers jsou grafové objekty, které určují, které uživatelem definované funkce se spouští pro danou zprávu telemetrie.

• Platné porovnání podmínek shody:

  • Equals
  • NotEquals
  • Contains

• Platné cíle podmínky shody:

  • Sensor
  • SensorDevice
  • SensorSpace

Následující příklad porovnávání se vyhodnotí jako true u jakékoli události telemetrie senzoru s "Temperature" hodnotou datového typu. Pro uživatelem definovanou funkci můžete vytvořit několik shod, a to tak, že provedete ověřený požadavek HTTP POST na:

YOUR_MANAGEMENT_API_URL/matchers

S textem JSON:

{
  "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"
    }
  ]
}

Hodnota	Nahradit hodnotou
YOUR_SPACE_IDENTIFIER	Na které oblasti serveru je vaše instance hostovaná

Vytvoření funkce definované uživatelem

Vytvoření uživatelem definované funkce zahrnuje vytvoření vícedílné žádosti HTTP pro rozhraní API pro správu Služby Azure Digital Twins.

Poznámka

Vícedílné požadavky obvykle vyžadují tři části:

• Hlavička typu obsahu :
  • application/json; charset=utf-8
  • multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
• Rozložení obsahu:
  • form-data; name="metadata"
• Obsah souboru, který se má nahrát

Typ obsahu a rozložení obsahu se budou lišit v závislosti na scénáři použití.

Vícedílné požadavky je možné provádět programově (prostřednictvím C#), prostřednictvím klienta REST nebo nástroje, jako je Postman. Klientské nástroje REST můžou mít různé úrovně podpory složitých vícedílných požadavků. Nastavení konfigurace se také může mírně lišit od nástroje po nástroj. Ověřte, který nástroj je nejvhodnější pro vaše potřeby.

Důležité

Multipart requests made to the Azure Digital Twins Management APIs obvykle mají dvě části:

• Metadata objektů blob (například přidružený typ MIME), která je deklarována typem obsahu a /nebo typem obsahu
• Obsah objektu blob, který obsahuje nestrukturovaný obsah souboru, který se má nahrát

Pro požadavky PATCH se nevyžaduje žádná ze dvou částí. Oba jsou vyžadovány pro operace POST nebo vytvoření.

Zdrojový kód pro rychlé zprovoznění obsazenosti obsahuje kompletní příklady jazyka C#, které ukazují, jak provádět žádosti o více částí v rozhraních API pro správu Služby Azure Digital Twins.

Po vytvoření matcherů nahrajte fragment funkce s následujícím ověřeným požadavkem HTTP POST s více částmi:

YOUR_MANAGEMENT_API_URL/userdefinedfunctions

Použijte následující text:

--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--

Hodnota	Nahradit hodnotou
USER_DEFINED_BOUNDARY	Název hranice obsahu s více částmi
YOUR_SPACE_IDENTIFIER	Identifikátor mezery
YOUR_MATCHER_IDENTIFIER	ID matcheru, který chcete použít

1. Ověřte, že záhlaví zahrnují: Content-Type: multipart/form-data; boundary="USER_DEFINED_BOUNDARY".

2. Ověřte, že tělo je více částí:

   • První část obsahuje požadovaná uživatelsky definovaná metadata funkcí.
   • Druhá část obsahuje logiku výpočetních prostředků JavaScriptu.

3. V části USER_DEFINED_BOUNDARY nahraďte hodnoty spaceId (YOUR_SPACE_IDENTIFIER) a matchers (YOUR_MATCHER_IDENTIFIER).

4. Ověřte, že je uživatelem definovaná funkce JavaScriptu zadána jako Content-Type: text/javascript.

Ukázkové funkce

Nastavení telemetrie senzoru přímo pro senzor s datovým typem Teplota, což je 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);
}

Parametr telemetrie zveřejňuje atributy SensorId a Message , které odpovídají zprávě odeslané senzorem. Parametr executionContext zveřejňuje následující atributy:

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

V dalším příkladu zaznamenáme zprávu, pokud čtení telemetrie senzoru překročí předdefinovanou prahovou hodnotu. Pokud je nastavení diagnostiky povolené v instanci Služby Azure Digital Twins, protokoly z uživatelem definovaných funkcí se také přeposílají:

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

Následující kód aktivuje oznámení, pokud se úroveň teploty zvýší nad předdefinovanou konstantu:

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

Složitější ukázku kódu funkce definované uživatelem najdete v rychlém startu o obsazenosti.

Vytvoření přiřazení role

Vytvořte přiřazení role pro uživatelem definovanou funkci, která se má spustit v části. Pokud pro uživatelem definovanou funkci neexistuje žádné přiřazení role, nebude mít správná oprávnění k interakci s rozhraním API pro správu nebo mít přístup k provádění akcí u objektů grafu. Akce, které může funkce definovaná uživatelem provádět, se určují a definují prostřednictvím řízení přístupu na základě role v rámci rozhraní API pro správu Služby Azure Digital Twins. Uživatelem definované funkce mohou být například omezeny v oboru zadáním určitých rolí nebo určitých cest řízení přístupu. Další informace najdete v dokumentaci k řízení přístupu na základě role .

1. Pokud chcete získat ID role, které chcete přiřadit k uživatelem definované funkci, nastavte dotaz na systémové rozhraní API pro všechny role. Proveďte to tak, že provedete ověřený požadavek HTTP GET na:

   YOUR_MANAGEMENT_API_URL/system/roles
   

   Ponechte id požadované role. Předá se jako id role hlavního atributu JSON (YOUR_DESIRED_ROLE_IDENTIFIER) níže.

2. objectId (YOUR_USER_DEFINED_FUNCTION_ID) bude ID uživatelem definované funkce, které bylo vytvořeno dříve.

3. Najděte hodnotu cesty (YOUR_ACCESS_CONTROL_PATH) dotazováním mezer pomocí fullpathpříkazu .

4. Zkopírujte vrácenou spacePaths hodnotu. Použijete ho níže. Proveďte ověřený požadavek HTTP GET na:

   YOUR_MANAGEMENT_API_URL/spaces?name=YOUR_SPACE_NAME&includes=fullpath
   

   Hodnota	Nahradit hodnotou
   YOUR_SPACE_NAME	Název prostoru, který chcete použít

5. Vložte vrácenou spacePaths hodnotu do cesty a vytvořte přiřazení role role definované uživatelem tím, že provedete ověřený požadavek HTTP POST na:

   YOUR_MANAGEMENT_API_URL/roleassignments
   

   S textem JSON:

   {
     "roleId": "YOUR_DESIRED_ROLE_IDENTIFIER",
     "objectId": "YOUR_USER_DEFINED_FUNCTION_ID",
     "objectIdType": "YOUR_USER_DEFINED_FUNCTION_TYPE_ID",
     "path": "YOUR_ACCESS_CONTROL_PATH"
   }
   

   Hodnota	Nahradit hodnotou
   YOUR_DESIRED_ROLE_IDENTIFIER	Identifikátor požadované role
   YOUR_USER_DEFINED_FUNCTION_ID	ID uživatelem definované funkce, kterou chcete použít
   YOUR_USER_DEFINED_FUNCTION_TYPE_ID	ID určující typ uživatelem definované funkce (UserDefinedFunctionId)
   YOUR_ACCESS_CONTROL_PATH	Cesta řízení přístupu

Tip

Další informace o operacích a koncových bodech rozhraní API pro správu funkcí definovaných uživatelem najdete v článku Vytvoření a správa přiřazení rolí .

Odeslání telemetrie, která se má zpracovat

Senzor definovaný v grafu prostorové inteligence odesílá telemetrii. Telemetrie zase aktivuje spuštění uživatelem definované funkce, která se nahrála. Zpracovatel dat převezme telemetrii. Pak se vytvoří plán provádění pro vyvolání uživatelem definované funkce.

1. Načtení shodovačů pro senzor, ze které se čtení vygenerovalo.
2. V závislosti na tom, které shody byly úspěšně vyhodnoceny, načtěte přidružené uživatelem definované funkce.
3. Spusťte každou uživatelem definovanou funkci.

Další kroky

• Zjistěte, jak vytvořit koncové body Služby Azure Digital Twins pro odesílání událostí.

• Další podrobnosti o směrování ve službě Azure Digital Twins najdete v tématu Události směrování a zprávy.

• Projděte si referenční dokumentaci ke klientské knihovně.