Vytvář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 se původní služba Azure Digital Twins (popsaná v této sadě dokumentace) vyřadila z provozu.

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

Tato příručka vás provede příkladem, který ukazuje, jak detekovat a upozorňovat na všechna čtení, která překročí určitou teplotu z přijatých událostí teploty.

V následujících příkladech YOUR_MANAGEMENT_API_URL 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 za
NÁZEV_VAŠEHO_INSTANCE	Název instance služby Azure Digital Twins
VAŠE_MÍSTO	Oblast, ve které je vaše instance hostovaná

Referenční informace ke 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řte porovnávač

Matchers jsou grafové objekty, které určují, které uživatelsky definované funkce se spouštějí pro konkrétní zprávu telemetrie.

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

  • Equals
  • NotEquals
  • Contains

• Platné podmínky pro cíle porovnávání:

  • Sensor
  • SensorDevice
  • SensorSpace

Následující příklad shodovacího algoritmu vyhodnotí hodnotu true pro každou událost telemetrie senzoru s hodnotou datového typu "Temperature". V uživatelem definované funkci můžete vytvořit více matcherů tak, že provedete ověřený požadavek HTTP POST na:

YOUR_MANAGEMENT_API_URL/matchers

S tělem 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 za
YOUR_SPACE_IDENTIFIER	V jaké oblasti serveru je vaše instance hostovaná

Vytvoření uživatelem definované funkce

Vytvoření uživatelem definované funkce zahrnuje vytvoření požadavku HTTP s více částmi do 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 Content-Type :
  • application/json; charset=utf-8
  • multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
• Content-Disposition:
  • 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í.

Žádosti s více částmi je možné provádět programově (prostřednictvím jazyka 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 požadavků na vícedílné části. 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é

Žádosti typu "multipart" zasílané do rozhraní API pro správu služby Azure Digital Twins typicky obsahují dvě části:

• Metadata objektů blob (například přidružený typ MIME), která jsou deklarována podle typu obsahu nebo content-disposition
• Obsah objektu blob, který obsahuje nestrukturovaný obsah souboru, který se má nahrát

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

Zdrojový kód projektu Occupancy Quickstart obsahuje kompletní příklady v jazyce C#, které demonstrují, jak provádět multipartní žádosti na rozhraní API pro správu služby Azure Digital Twins.

Po vytvoření porovnávačů nahrajte fragment funkčního kódu s následujícím ověřeným vícedílným požadavkem HTTP POST:

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 za
UŽIVATELEM_DEFINOVANÁ_HRANICE	Název hranice pro obsah s více částmi
YOUR_SPACE_IDENTIFIER	Identifikátor mezery
identifikátor pro vaše porovnávače	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 ve více částech.

   • První část obsahuje požadovaná metadata uživatelem definované funkce.
   • Druhá část obsahuje výpočetní logiku 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 Jazyka JavaScript zadána jako Content-Type: text/javascript.

Příklady funkcí

Nastavte telemetrická data 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 jsou pro instanci služby Azure Digital Twins povolená vaše nastavení diagnostiky, přeposílají se také protokoly z uživatelem definovaných funkcí:

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

Pro složitější vzorový kód pro uživatelsky definovanou funkci si přečtěte rychlý start pro obsazenost.

Vytvořte přiřazení role

Vytvořte přiřazení role, pro které se má spustit uživatelsky definovaná funkce. 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í s objekty grafu. Akce, které může uživatelem definovaná funkce provádět, se zadají a definují prostřednictvím řízení přístupu na základě role v rozhraních 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. Zadejte dotaz na systémové rozhraní API pro všechny role a získejte ID role, které chcete přiřadit k uživatelem definované funkci. Provedete 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 atributu těla JSON (YOUR_DESIRED_ROLE_IDENTIFIER) níže.

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

3. Hodnotu cesty (YOUR_ACCESS_CONTROL_PATH) zjistíte dotazem ve vašich prostorech pomocí fullpath.

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

   YOUR_MANAGEMENT_API_URL/spaces?name=YOUR_SPACE_NAME&includes=fullpath
   

   Hodnota	Nahradit za
   NÁZEV_VAŠEHO_PROSTORU	Název prostoru, který chcete použít

5. Vložte vrácenou spacePaths hodnotu do parametru cesty a vytvořte přiřazení role funkce, kterou jste definovali sami, tím, že provedete ověřený požadavek HTTP POST na:

   YOUR_MANAGEMENT_API_URL/roleassignments
   

   S tělem 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 za
   VAŠE_POŽADOVANÁ_ROLE_IDENTIFIKÁTOR	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)
   VAŠE_CESTA_KE_KONTROLE_PŘÍSTUPU	Cesta řízení přístupu

Návod

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

Odeslání telemetrie ke zpracování

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

1. Načti shodovače pro senzor, ze kterého bylo měření získáno.
2. V závislosti na tom, které porovnávače byly úspěšně vyhodnoceny, načtěte příslušné uživatelsky definované funkce.
3. Spusťte každou uživatelem definovanou funkci.

Další kroky

• Naučte se vytvářet koncové body Azure Digital Twins k 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ě.