Erstellen von benutzerdefinierten Funktionen in Azure Digital Twins

Artikel
01/17/2020

Wichtig

Eine neue Version des Azure Digital Twins-Diensts wurde veröffentlicht. Angesichts der erweiterten Funktionen des neuen Diensts wurde der ursprüngliche Azure Digital Twins-Dienst (in diesem Dokumentationssatz beschrieben) eingestellt.

Um die Dokumentation für den neuen Dienst anzuzeigen, besuchen Sie die aktive Azure Digital Twins-Dokumentation.

Benutzerdefinierte Funktionen ermöglichen es Benutzern, benutzerdefinierte Logik so zu konfigurieren, dass sie aus eingehenden Telemetrienachrichten und Raumgraphmetadaten ausgeführt wird. Benutzer können auch Ereignisse an vordefinierte Endpunkte senden.

In diesem Leitfaden durchlaufen Sie ein Beispiel, das veranschaulicht, wie Sie jede Messung von empfangenen Temperaturereignissen erkennen, bei der eine bestimmte Temperatur überschritten wurde, und eine Warnung für eine solche Messung senden.

In den folgenden Beispielen bezieht sich YOUR_MANAGEMENT_API_URL auf den URI der Digital Twins-APIs:

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

Name	Ersetzen durch
YOUR_INSTANCE_NAME	Den Namen Ihrer Azure Digital Twins-Instanz
YOUR_LOCATION	Die Region, in der Ihre Instanz gehostet wird

Referenz zur Clientbibliothek

Die als Hilfsmethoden in der Runtime für benutzerdefinierte Funktionen verfügbaren Funktionen werden im Dokument Clientbibliotheksreferenz aufgeführt.

Erstellen eine Matchers

Matcher (Abgleicher) sind Graphobjekte, die bestimmen, welche benutzerdefinierten Funktionen für eine bestimmte Telemetrienachricht ausgeführt werden.

Gültige Matcherbedingungsvergleiche:
- Equals
- NotEquals
- Contains
Gültige Matcherbedingungsziele:
- Sensor
- SensorDevice
- SensorSpace

Der folgende Beispielmatcher besitzt den Ergebniswert TRUE für jedes Sensortelemetrieereignis, das den Datentyp "Temperature" aufweist. Sie können mehrere Matcher für eine benutzerdefinierte Funktion erstellen, indem Sie eine authentifizierte HTTP-POST-Anforderung an folgende URL stellen:

YOUR_MANAGEMENT_API_URL/matchers

Mit JSON-Text:

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

Wert	Ersetzen durch
YOUR_SPACE_IDENTIFIER	Die Serverregion, in der Ihre Instanz gehostet wird

Erstellen einer benutzerdefinierten Funktion

Das Erstellen einer benutzerdefinierten Funktion beinhaltet das Erstellen einer mehrteiligen HTTP-Anforderung an die Azure Digital Twins-Verwaltungs-APIs.

Hinweis

Mehrteilige Anforderungen umfassen in der Regel drei Informationselemente:

Einen Header vom Typ Content-Type:
- application/json; charset=utf-8
- multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
Eine Inhaltsverfügung:
- form-data; name="metadata"
Der hochzuladende Dateiinhalt

Content-Type und Content-Disposition variieren je nach Verwendungsszenario.

Mehrteilige Anforderungen können programmgesteuert vorgenommen werden (über C#), über einen REST-Client oder Tools wie z.B. Postman. REST-Clienttools weisen möglicherweise verschiedene Ebenen der Unterstützung für komplexe mehrteiligen Anforderungen auf. Konfigurationseinstellungen können von Tool zu Tool leicht variieren. Überprüfen Sie, welches Tool am besten für Ihre Anforderungen geeignet ist.

Wichtig

Mehrteilige Anforderungen an Verwaltungs-APIs von Azure Digital Twins bestehen normalerweise aus zwei Teilen:

Blobmetadaten (z.B. ein zugeordneter MIME-Typ), der von Content-Type und/oder Content-Disposition deklariert wird.
Blobinhalt einschließlich der unstrukturierten Inhalte einer hochzuladenden Datei

Bei PATCH-Anforderungen wird keiner der beiden Teile benötigt. Bei POST- oder Erstellungsvorgängen werden dagegen beide Teile benötigt.

Der Occupancy Quickstart-Quellcode enthält vollständige C#-Beispiele, die zeigen, wie mehrteilige Anforderungen an die Verwaltungs-APIs von digitalen Zwillingen in Azure gerichtet werden.

Nachdem die Matcher erstellt wurden, laden Sie den Funktionsocdeausschnitt mit der folgenden authentifizierten mehrteiligen HTTP-POST-Anforderung hoch:

YOUR_MANAGEMENT_API_URL/userdefinedfunctions

Verwenden Sie folgenden 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--

Wert	Ersetzen durch
USER_DEFINED_BOUNDARY	Name für die Begrenzung mehrteiliger Inhalte
YOUR_SPACE_IDENTIFIER	Den Raumbezeichner (Raum-ID)
YOUR_MATCHER_IDENTIFIER	Die ID des Matchers, den Sie verwenden möchten

Vergewissern Sie sich, dass die Header Folgendes enthalten: Content-Type: multipart/form-data; boundary="USER_DEFINED_BOUNDARY".
Vergewissern Sie sich, dass der Hauptteil mehrteilig ist:
- Der erste Teil enthält die erforderliche Metadaten für die benutzerdefinierte Funktion.
- Der zweite Teil enthält die JavaScript-Computelogik.
Ersetzen Sie im abschnitt USER_DEFINED_BOUNDARY die spaceId () und matchers (YOUR_MATCHER_IDENTIFIERYOUR_SPACE_IDENTIFIER) werte.
Vergewissern Sie sich, dass die benutzerdefinierte JavaScript-Funktion als Content-Type: text/javascript bereitgestellt wird.

Beispielfunktionen

Legen Sie den Sensortelemetriemesswert direkt für den Sensor mit dem Datentyp Temperature fest, der sensor.DataType entspricht:

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

Der Telemetrieparameter macht die SensorId - und Nachrichtenattribute verfügbar, die einer von einem Sensor gesendeten Nachricht entsprechen. Der executionContext-Parameter macht die folgenden Attribute verfügbar:

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

Im nächsten Beispiel protokollieren wir eine Nachricht, wenn der Sensortelemetriemesswert einen vordefinierten Schwellenwert überschreitet. Wenn Ihre Diagnoseeinstellungen in der Azure Digital Twins-Instanz aktiviert sind, werden Protokolle von benutzerdefinierten Funktionen ebenfalls weitergeleitet:

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

Im folgenden Code wird eine Benachrichtigung ausgelöst, wenn die Temperatur den festgelegten Wert der Konstanten überschreitet:

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

Wenn Sie ein komplexeres Codebeispiel für eine benutzerdefinierte Funktion kennenlernen möchten, lesen Sie den Belegungsschnellstart.

Erstellen einer Rollenzuweisung

Erstellen Sie eine Rollenzuweisung, unter der die benutzerdefinierte Funktion ausgeführt werden soll. Wenn für die benutzerdefinierte Funktion keine Rollenzuweisung vorhanden ist, verfügt sie nicht über die erforderlichen Berechtigungen für die Interaktion mit der Verwaltungs-API oder den Zugriff zum Ausführen von Aktionen an Graphobjekten. Aktionen, die eine benutzerdefinierte Funktion ausführen kann, werden über eine rollenbasierte Zugriffskontrolle innerhalb der Azure Digital Twins-Verwaltungs-APIs spezifiziert und definiert. Benutzerdefinierte Funktionen können beispielsweise hinsichtlich des Geltungsbereichs eingeschränkt werden, indem bestimmte Rollen oder bestimmte Zugriffssteuerungspfade angegeben werden. Wenn Sie weitere Informationen benötigen, lesen Sie die Dokumentation zur rollenbasierten Zugriffssteuerung.

Fragen Sie die System-API nach allen Rollen ab, um die Rollen-ID zu erhalten, die Sie Ihrer benutzerdefinierten Funktion zuweisen möchten. Stellen Sie hierzu eine authentifizierte HTTP-GET-Anforderung an:
```
YOUR_MANAGEMENT_API_URL/system/roles
```
Behalten Sie die gewünschten Rollen-ID. Es wird als JSON-Body-Attribut roleId () untenYOUR_DESIRED_ROLE_IDENTIFIER übergeben.
objectId (YOUR_USER_DEFINED_FUNCTION_ID) ist die benutzerdefinierte Funktions-ID, die zuvor erstellt wurde.
Suchen Sie den Wert des Pfads (YOUR_ACCESS_CONTROL_PATH) durch Abfragen ihrer Leerzeichen mit fullpath.
Kopieren Sie den zurückgegebenen spacePaths-Wert. Diesen verwenden Sie dann weiter unten. Stellen Sie eine authentifizierte HTTP-GET-Anforderung an:
```
YOUR_MANAGEMENT_API_URL/spaces?name=YOUR_SPACE_NAME&includes=fullpath
```
Wert Ersetzen durch

YOUR_SPACE_NAME Der Name des Raums, den Sie verwenden möchten

Wert	Ersetzen durch
YOUR_SPACE_NAME	Der Name des Raums, den Sie verwenden möchten

Fügen Sie den zurückgegebenen spacePaths-Wert in path ein, um eine benutzerdefinierte Funktionsrollenzuweisung zu erstellen, indem Sie eine authentifizierte HTTP-POST-Anforderung an folgende URL stellen:

YOUR_MANAGEMENT_API_URL/roleassignments

Mit JSON-Text:

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

Wert	Ersetzen durch
YOUR_DESIRED_ROLE_IDENTIFIER	Der Bezeichner für die gewünschte Rolle
YOUR_USER_DEFINED_FUNCTION_ID	Die ID für die benutzerdefinierte Funktion, die Sie verwenden möchten.
YOUR_USER_DEFINED_FUNCTION_TYPE_ID	Die ID, die den Typ der benutzerdefinierten Funktion angibt (`UserDefinedFunctionId`).
YOUR_ACCESS_CONTROL_PATH	Der Zugriffssteuerungspfad

Tipp

Weitere Informationen zu auf benutzerdefinierte Funktionen bezogenen Verwaltungs-API-Vorgängen und Endpunkten finden Sie in dem Artikel Erstellen und Verwalten von Rollenzuweisungen.

Senden der Telemetriedaten, die verarbeitet werden sollen

Der Raumintelligenzgraph definierte Sensor sendet Telemetriedaten. Im Gegenzug löst die Telemetrie die Ausführung der benutzerdefinierten Funktion aus, die hochgeladen wurde. Die Datenverarbeitung übernimmt die Telemetriedaten. Anschließend wird ein Ausführungsplan für den Aufruf der benutzerdefinierten Funktion erstellt.

Rufen Sie die Matcher für den Sensor ab, von dem der Messwert generiert wurde.
Je nachdem, welche Matcher erfolgreich ausgewertet wurden, rufen Sie die zugehörigen benutzerdefinierten Funktionen ab.
Führen Sie jede benutzerdefinierte Funktion aus.

Nächste Schritte

Informieren Sie sich über das Erstellen von Azure Digital Twins-Endpunkten, an die Ereignisse gesendet werden sollen.
Weitere Details zum Weiterleiten von Ereignissen in Azure Digital Twins finden Sie unter Weiterleiten von Ereignissen und Nachrichten.
Lesen Sie die Clientbibliotheksreferenz-Dokumentation.