Så här skapar du användardefinierade funktioner i Azure Digital Twins

Viktigt

En ny version av Azure Digital Twins-tjänsten har släppts. Mot bakgrund av den nya tjänstens utökade funktioner har den ursprungliga Azure Digital Twins-tjänsten (som beskrivs i den här dokumentationsuppsättningen) dragits tillbaka.

Om du vill visa dokumentationen för den nya tjänsten går du till den aktiva Dokumentationen om Azure Digital Twins.

Med användardefinierade funktioner kan användare konfigurera anpassad logik som ska köras från inkommande telemetrimeddelanden och spatiala grafmetadata. Användare kan också skicka händelser till fördefinierade slutpunkter.

Den här guiden går igenom ett exempel som visar hur du identifierar och varnar för alla avläsningar som överskrider en viss temperatur från mottagna temperaturhändelser.

I exemplen nedan YOUR_MANAGEMENT_API_URL refererar till URI för Digital Twins-API:erna:

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

Name	Ersätt med
YOUR_INSTANCE_NAME	Namnet på din Azure Digital Twins-instans
YOUR_LOCATION	Den region som din instans finns på

Referens för klientbibliotek

Funktioner som är tillgängliga som hjälpmetoder i den användardefinierade funktionskörningen visas i referensdokumentet för klientbiblioteket .

Skapa en matchare

Matchare är grafobjekt som avgör vilka användardefinierade funktioner som körs för ett visst telemetrimeddelande.

• Giltiga matchningsvillkorsjämförelser:

  • Equals
  • NotEquals
  • Contains

• Giltiga mål för matchningsvillkor:

  • Sensor
  • SensorDevice
  • SensorSpace

Följande exempelmatchare utvärderas till true för alla sensortelemetrihändelser med "Temperature" som datatypsvärde. Du kan skapa flera matchare på en användardefinierad funktion genom att göra en autentiserad HTTP POST-begäran för att:

YOUR_MANAGEMENT_API_URL/matchers

Med JSON-brödtext:

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

Värde	Ersätt med
YOUR_SPACE_IDENTIFIER	Den serverregion som instansen finns i

Skapa en användardefinierad funktion

Att skapa en användardefinierad funktion innebär att göra en HTTP-begäran i flera delar till Azure Digital Twins Management-API:erna.

Anteckning

Flerapartsbegäranden kräver vanligtvis tre delar:

• Ett innehållstypshuvud :
  • application/json; charset=utf-8
  • multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
• En innehållsdisposition:
  • form-data; name="metadata"
• Filinnehållet som ska laddas upp

Innehållstyp och innehållsdisposition varierar beroende på användningsscenario.

Flerapartsbegäranden kan göras programmatiskt (via C#), via en REST-klient eller ett verktyg som Postman. REST-klientverktyg kan ha olika stödnivåer för komplexa begäranden med flera delar. Konfigurationsinställningarna kan också variera något från verktyg till verktyg. Kontrollera vilket verktyg som passar bäst för dina behov.

Viktigt

Flerapartsbegäranden som görs till Azure Digital Twins Management-API:erna har vanligtvis två delar:

• Blobmetadata (till exempel en associerad MIME-typ ) som deklareras av innehållstyp och/eller innehållsdisposition
• Blobinnehåll som innehåller det ostrukturerade innehållet i en fil som ska laddas upp

Ingen av de två delarna krävs för PATCH-begäranden . Båda krävs för POST- eller create-åtgärder.

Occupancy-källkoden för snabbstart innehåller fullständiga C#-exempel som visar hur du gör flerapartsbegäranden mot Azure Digital Twins Management-API:erna.

När matcharna har skapats laddar du upp funktionsfragmentet med följande autentiserade HTTP POST-begäran för flera delar till:

YOUR_MANAGEMENT_API_URL/userdefinedfunctions

Använd följande brödtext:

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

Värde	Ersätt med
USER_DEFINED_BOUNDARY	Ett gränsnamn för flera delar av innehållet
YOUR_SPACE_IDENTIFIER	Blankstegsidentifieraren
YOUR_MATCHER_IDENTIFIER	ID:t för den matchning som du vill använda

1. Kontrollera att rubrikerna innehåller: Content-Type: multipart/form-data; boundary="USER_DEFINED_BOUNDARY".

2. Kontrollera att brödtexten är flera delar:

   • Den första delen innehåller nödvändiga användardefinierade funktionsmetadata.
   • Den andra delen innehåller JavaScript-beräkningslogik.

3. I avsnittet USER_DEFINED_BOUNDARY ersätter du värdena spaceId (YOUR_SPACE_IDENTIFIER) och matchers (YOUR_MATCHER_IDENTIFIER).

4. Kontrollera att den användardefinierade JavaScript-funktionen anges som Content-Type: text/javascript.

Exempelfunktioner

Ange sensortelemetriavläsning direkt för sensorn med datatypen Temperatur, vilket är 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);
}

Telemetriparametern exponerar attributen SensorId och Message, som motsvarar ett meddelande som skickas av en sensor. Parametern executionContext visar följande attribut:

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

I nästa exempel loggar vi ett meddelande om sensortelemetriläsningen överskrider ett fördefinierat tröskelvärde. Om dina diagnostikinställningar är aktiverade på Azure Digital Twins-instansen vidarebefordras även loggar från användardefinierade funktioner:

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

Följande kod utlöser ett meddelande om temperaturnivån stiger över den fördefinierade konstanten:

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

Ett mer komplext exempel på användardefinierad funktionskod finns i snabbstarten Occupancy.

Skapa en rolltilldelning

Skapa en rolltilldelning för den användardefinierade funktion som ska köras under. Om det inte finns någon rolltilldelning för den användardefinierade funktionen har den inte rätt behörighet att interagera med hanterings-API:et eller ha åtkomst till att utföra åtgärder på grafobjekt. Åtgärder som en användardefinierad funktion kan utföra anges och definieras via rollbaserad åtkomstkontroll i Azure Digital Twins Management-API:erna. Till exempel kan användardefinierade funktioner begränsas i omfånget genom att ange vissa roller eller vissa sökvägar för åtkomstkontroll. Mer information finns i dokumentationen om rollbaserad åtkomstkontroll .

1. Fråga system-API:et om alla roller för att få det roll-ID som du vill tilldela till din användardefinierade funktion. Gör det genom att göra en autentiserad HTTP GET-begäran för att:

   YOUR_MANAGEMENT_API_URL/system/roles
   

   Behåll önskat roll-ID. Det skickas som JSON-brödtextattributet roleId (YOUR_DESIRED_ROLE_IDENTIFIER) nedan.

2. objectId (YOUR_USER_DEFINED_FUNCTION_ID) är det användardefinierade funktions-ID som skapades tidigare.

3. Hitta värdet för sökvägen (YOUR_ACCESS_CONTROL_PATH) genom att fråga dina blanksteg med fullpath.

4. Kopiera det returnerade spacePaths värdet. Du använder det nedan. Gör en autentiserad HTTP GET-begäran för att:

   YOUR_MANAGEMENT_API_URL/spaces?name=YOUR_SPACE_NAME&includes=fullpath
   

   Värde	Ersätt med
   YOUR_SPACE_NAME	Namnet på det utrymme som du vill använda

5. Klistra in det returnerade spacePaths värdet i sökvägen för att skapa en användardefinierad funktionsrolltilldelning genom att göra en autentiserad HTTP POST-begäran till:

   YOUR_MANAGEMENT_API_URL/roleassignments
   

   Med JSON-brödtext:

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

   Värde	Ersätt med
   YOUR_DESIRED_ROLE_IDENTIFIER	Identifieraren för önskad roll
   YOUR_USER_DEFINED_FUNCTION_ID	ID:t för den användardefinierade funktion som du vill använda
   YOUR_USER_DEFINED_FUNCTION_TYPE_ID	ID:t som anger den användardefinierade funktionstypen (UserDefinedFunctionId)
   YOUR_ACCESS_CONTROL_PATH	Sökvägen för åtkomstkontroll

Tips

Läs artikeln Så här skapar och hanterar du rolltilldelningar för mer information om användardefinierade api-åtgärder och slutpunkter för funktionshantering.

Skicka telemetri som ska bearbetas

Sensorn som definieras i grafen för rumslig intelligens skickar telemetri. Telemetrin utlöser i sin tur körningen av den användardefinierade funktionen som laddades upp. Dataprocessorn hämtar telemetrin. Sedan skapas en körningsplan för anropet av den användardefinierade funktionen.

1. Hämta matcharna för sensorn som avläsningen genererades från.
2. Beroende på vilka matchare som har utvärderats hämtar du de associerade användardefinierade funktionerna.
3. Kör varje användardefinierad funktion.

Nästa steg

• Lär dig hur du skapar Azure Digital Twins-slutpunkter att skicka händelser till.

• Mer information om routning i Azure Digital Twins finns i Routningshändelser och meddelanden.

• Läs referensdokumentationen för klientbiblioteket.