Jak tworzyć funkcje zdefiniowane przez użytkownika w usłudze Azure Digital Twins

Ważne

Wydano nową wersję usługi Azure Digital Twins. W świetle rozszerzonych możliwości nowej usługi oryginalna usługa Azure Digital Twins (opisana w tym zestawie dokumentacji) została wycofana.

Aby wyświetlić dokumentację nowej usługi, odwiedź aktywną dokumentację usługi Azure Digital Twins.

Funkcje zdefiniowane przez użytkownika umożliwiają użytkownikom konfigurowanie niestandardowej logiki do wykonywania z przychodzących komunikatów telemetrycznych i metadanych grafu przestrzennego. Użytkownicy mogą również wysyłać zdarzenia do wstępnie zdefiniowanych punktów końcowych.

W tym przewodniku przedstawiono przykład pokazujący sposób wykrywania i zgłaszania alertów dotyczących odczytu, który przekracza określoną temperaturę od odebranych zdarzeń temperatury.

W poniższych YOUR_MANAGEMENT_API_URL przykładach odwołuje się do identyfikatora URI interfejsów API usługi Digital Twins:

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

Nazwa	Zamień na
YOUR_INSTANCE_NAME	Nazwa wystąpienia usługi Azure Digital Twins
YOUR_LOCATION	Region, w którym jest hostowane twoje wystąpienie

Dokumentacja biblioteki klienta

Funkcje dostępne jako metody pomocnika w środowisku uruchomieniowym funkcji zdefiniowanych przez użytkownika są wymienione w dokumencie referencyjnym biblioteki klienta .

Tworzenie dopasowania

Matchers to obiekty grafu, które określają, jakie funkcje zdefiniowane przez użytkownika są uruchamiane dla danego komunikatu telemetrii.

• Prawidłowe porównania warunków dopasowania:

  • Equals
  • NotEquals
  • Contains

• Prawidłowe elementy docelowe warunku dopasowania:

  • Sensor
  • SensorDevice
  • SensorSpace

Poniższy przykładowy element matcher oblicza wartość true dla dowolnego zdarzenia telemetrii czujnika z wartością "Temperature" typu danych. Możesz utworzyć wiele elementów matcherów w funkcji zdefiniowanej przez użytkownika, wysyłając uwierzytelnione żądanie HTTP POST do:

YOUR_MANAGEMENT_API_URL/matchers

Treść 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"
    }
  ]
}

Wartość	Zamień na
YOUR_SPACE_IDENTIFIER	Region serwera, w którym jest hostowane używane wystąpienie

Tworzenie funkcji zdefiniowanej przez użytkownika

Tworzenie funkcji zdefiniowanej przez użytkownika obejmuje tworzenie wieloczęściowego żądania HTTP do interfejsów API zarządzania usługą Azure Digital Twins.

Uwaga

Żądania wieloczęściowe zwykle wymagają trzech elementów:

• Nagłówek typu zawartości :
  • application/json; charset=utf-8
  • multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
• Dyspozycja zawartości:
  • form-data; name="metadata"
• Zawartość pliku do przekazania

Typ zawartości i dyspozycja zawartości będą się różnić w zależności od scenariusza użycia.

Żądania wieloczęściowe można wykonywać programowo (za pośrednictwem języka C#), za pośrednictwem klienta REST lub narzędzia, takiego jak Postman. Narzędzia klienckie REST mogą mieć różne poziomy obsługi złożonych żądań wieloczęściowych. Ustawienia konfiguracji mogą również różnić się nieco od narzędzia do narzędzia. Sprawdź, które narzędzie najlepiej nadaje się do Twoich potrzeb.

Ważne

Żądania wieloczęściowe wysyłane do interfejsów API zarządzania usługą Azure Digital Twins zwykle mają dwie części:

• Metadane obiektu blob (takie jak skojarzony typ MIME) zadeklarowane przez typ zawartości i/lub dyspozycję zawartości
• Zawartość obiektu blob zawierająca zawartość pliku bez struktury do przekazania

Żadna z dwóch części nie jest wymagana w przypadku żądań PATCH . Oba są wymagane w przypadku operacji POST lub tworzenia.

Kod źródłowy szybkiego startu zajętości zawiera kompletne przykłady języka C# pokazujące, jak wykonywać żądania wieloczęściowe względem interfejsów API zarządzania usługą Azure Digital Twins.

Po utworzeniu elementów matchers przekaż fragment kodu funkcji przy użyciu następującego uwierzytelnioowanego żądania HTTP POST z wieloma częściami do:

YOUR_MANAGEMENT_API_URL/userdefinedfunctions

Użyj następującej treści:

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

Wartość	Zamień na
USER_DEFINED_BOUNDARY	Nazwa granicy zawartości wieloczęściowej
YOUR_SPACE_IDENTIFIER	Identyfikator przestrzeni
YOUR_MATCHER_IDENTIFIER	Identyfikator dopasowania, którego chcesz użyć

1. Sprawdź, czy nagłówki obejmują: Content-Type: multipart/form-data; boundary="USER_DEFINED_BOUNDARY".

2. Sprawdź, czy treść jest wieloczęściowa:

   • Pierwsza część zawiera wymagane metadane funkcji zdefiniowanej przez użytkownika.
   • Druga część zawiera logikę obliczeniową języka JavaScript.

3. W sekcji USER_DEFINED_BOUNDARY zastąp wartości spaceId (YOUR_SPACE_IDENTIFIER) i matchers (YOUR_MATCHER_IDENTIFIER).

4. Sprawdź, czy funkcja zdefiniowana przez użytkownika języka JavaScript jest dostarczana jako Content-Type: text/javascript.

Przykładowe funkcje

Ustaw dane telemetryczne czujnika bezpośrednio dla czujnika z typem danych Temperatura, czyli 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 telemetrii uwidacznia atrybuty SensorId i Message odpowiadające komunikatowi wysyłanemu przez czujnik. Parametr executionContext uwidacznia następujące atrybuty:

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

W następnym przykładzie rejestrujemy komunikat, jeśli odczyt telemetrii czujnika przekroczy wstępnie zdefiniowany próg. Jeśli ustawienia diagnostyczne są włączone w wystąpieniu usługi Azure Digital Twins, dzienniki z funkcji zdefiniowanych przez użytkownika są również przekazywane:

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

Poniższy kod wyzwala powiadomienie, jeśli poziom temperatury wzrośnie powyżej wstępnie zdefiniowanej stałej:

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

Aby zapoznać się z bardziej złożonym przykładem kodu funkcji zdefiniowanego przez użytkownika, przeczytaj przewodnik Szybki start dotyczący zajętości.

Tworzenie przypisania roli

Utwórz przypisanie roli dla funkcji zdefiniowanej przez użytkownika do uruchomienia w obszarze. Jeśli nie istnieje przypisanie roli dla funkcji zdefiniowanej przez użytkownika, nie będzie mieć odpowiednich uprawnień do interakcji z interfejsem API zarządzania ani mieć dostępu do wykonywania akcji na obiektach grafu. Akcje, które może wykonywać funkcja zdefiniowana przez użytkownika, są określane i definiowane za pośrednictwem kontroli dostępu opartej na rolach w interfejsach API zarządzania usługą Azure Digital Twins. Na przykład funkcje zdefiniowane przez użytkownika mogą być ograniczone w zakresie, określając określone role lub niektóre ścieżki kontroli dostępu. Aby uzyskać więcej informacji, zapoznaj się z dokumentacją kontroli dostępu opartą na rolach .

1. Wykonaj zapytanie względem interfejsu API systemu dla wszystkich ról, aby uzyskać identyfikator roli, który chcesz przypisać do funkcji zdefiniowanej przez użytkownika. W tym celu należy wykonać uwierzytelnione żądanie HTTP GET w celu:

   YOUR_MANAGEMENT_API_URL/system/roles
   

   Zachowaj żądany identyfikator roli. Zostanie on przekazany jako atrybut JSON body roleId (YOUR_DESIRED_ROLE_IDENTIFIER) poniżej.

2. objectId (YOUR_USER_DEFINED_FUNCTION_ID) będzie identyfikatorem funkcji zdefiniowanej przez użytkownika, który został utworzony wcześniej.

3. Znajdź wartość ścieżki (YOUR_ACCESS_CONTROL_PATH), wysyłając zapytanie o spacje za pomocą fullpathpolecenia .

4. Skopiuj zwróconą spacePaths wartość. Użyjesz tego poniżej. Utwórz uwierzytelnione żądanie HTTP GET, aby:

   YOUR_MANAGEMENT_API_URL/spaces?name=YOUR_SPACE_NAME&includes=fullpath
   

   Wartość	Zamień na
   YOUR_SPACE_NAME	Nazwa przestrzeni, której chcesz użyć

5. Wklej zwróconą spacePaths wartość do ścieżki , aby utworzyć przypisanie roli funkcji zdefiniowanej przez użytkownika, wysyłając uwierzytelnione żądanie HTTP POST do:

   YOUR_MANAGEMENT_API_URL/roleassignments
   

   Treść JSON:

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

   Wartość	Zamień na
   YOUR_DESIRED_ROLE_IDENTIFIER	Identyfikator żądanej roli
   YOUR_USER_DEFINED_FUNCTION_ID	Identyfikator funkcji zdefiniowanej przez użytkownika, której chcesz użyć
   YOUR_USER_DEFINED_FUNCTION_TYPE_ID	Identyfikator określający typ funkcji zdefiniowanej przez użytkownika (UserDefinedFunctionId)
   YOUR_ACCESS_CONTROL_PATH	Ścieżka kontroli dostępu

Porada

Przeczytaj artykuł How to create and manage role assignments (Jak tworzyć przypisania ról i zarządzać nimi), aby uzyskać więcej informacji na temat operacji i punktów końcowych interfejsu API zarządzania funkcjami zdefiniowanymi przez użytkownika.

Wysyłanie danych telemetrycznych do przetworzenia

Czujnik zdefiniowany na wykresie analizy przestrzennej wysyła dane telemetryczne. Z kolei dane telemetryczne wyzwalają wykonanie przekazanej przez użytkownika funkcji. Procesor danych pobiera dane telemetryczne. Następnie jest tworzony plan wykonania na potrzeby wywołania funkcji zdefiniowanej przez użytkownika.

1. Pobierz matchery dla czujnika, z którego został wygenerowany odczyt.
2. W zależności od tego, które elementy dopasowania zostały pomyślnie ocenione, pobierz skojarzone funkcje zdefiniowane przez użytkownika.
3. Wykonaj każdą funkcję zdefiniowaną przez użytkownika.

Następne kroki

• Dowiedz się, jak tworzyć punkty końcowe usługi Azure Digital Twins w celu wysyłania zdarzeń do.

• Aby uzyskać więcej informacji na temat routingu w usłudze Azure Digital Twins, przeczytaj Routing zdarzeń i komunikatów.

• Zapoznaj się z dokumentacją referencyjną biblioteki klienta.