Come creare funzioni definite dall'utente in Gemelli digitali di Azure

Importante

È stata rilasciata una nuova versione del servizio Gemelli digitali di Azure. Alla luce delle funzionalità espanse del nuovo servizio, il servizio Gemelli digitali di Azure originale (descritto in questo set di documentazione) è stato ritirato.

Per visualizzare la documentazione per il nuovo servizio, visitare la documentazione attiva di Gemelli digitali di Azure.

Le funzioni definite dall'utente consentono agli utenti di configurare la logica da eseguire da messaggi di telemetria in ingresso e metadati del grafo spaziale. Gli utenti possono quindi inviare gli eventi a endpoint predefiniti.

Questa guida illustra un esempio che dimostra come rilevare e segnalare eventuali letture che superano una determinata temperatura dagli eventi di temperatura ricevuti.

Negli esempi seguenti, YOUR_MANAGEMENT_API_URL fa riferimento all'URI delle API di Gemelli digitali:

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

Nome	Sostituire con
NOME_ISTANZA_UTENTE	Nome dell'istanza di Gemelli digitali di Azure
POSIZIONE_UTENTE	Area in cui è ospitata l'istanza

Informazioni di riferimento sulla libreria client

Le funzioni disponibili come metodi helper nel runtime delle funzioni definite dall'utente sono elencate nel documento di riferimento sulla libreria client.

Creare un matcher

I matcher sono oggetti del grafico che determinano quali funzioni definite dall'utente eseguire per un messaggio di telemetria specifico.

• Confronti di condizione validi per i matcher:

  • Equals
  • NotEquals
  • Contains

• Destinazioni delle condizioni valide per i matcher:

  • Sensor
  • SensorDevice
  • SensorSpace

Il matcher di esempio seguente restituisce true per ogni evento di telemetria dei sensori con tipo di dati "Temperature". È possibile creare più matcher in una funzione definita dall'utente eseguendo una richiesta HTTP POST autenticata per:

YOUR_MANAGEMENT_API_URL/matchers

Con corpo 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"
    }
  ]
}

Valore	Sostituire con
YOUR_SPACE_IDENTIFIER	Area del server in cui è ospitata l'istanza

Creare una funzione definita dall'utente

La creazione di una funzione definita dall'utente comporta l'implementazione di una richiesta HTTP multipart per l'API di gestione di dispositivi Gemelli digitali di Azure.

Nota

Per le richieste multipart in genere sono necessari tre elementi:

• Un'intestazione Content-Type:
  • application/json; charset=utf-8
  • multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
• Eliminazione contenuto:
  • form-data; name="metadata"
• Il contenuto del file da caricare

Il contenuto di Content-Type e Content-Disposition varia in base allo scenario.

Le richieste multipart possono essere effettuate a livello di programmazione (tramite C#), mediante un client REST o con uno strumento come Postman. Gli strumenti client REST possono avere vari livelli di supporto per le richieste multipart complesse. Le impostazioni di configurazione possono inoltre variare leggermente da strumento a strumento. Verificare quale strumento è più adatto alle proprie esigenze.

Importante

Le richieste multipart inviate alle API Gestione di Gemelli digitali di Azure sono in genere suddivise in due parti:

• Metadati BLOB, ad esempio un tipo MIME associato, dichiarati da Content-Type e/o Content-Disposition
• Contenuto BLOB che include il contenuto non strutturato di un file da caricare

Per le richieste PATCH non è necessaria nessuna delle due parti, mentre entrambe sono necessarie per le operazioni POST o di creazione.

Il codice sorgente dell'avvio rapido relativo all'occupazione contiene esempi C# completi che illustrano come effettuare richieste multipart alle API di gestione di Gemelli digitali di Azure.

Dopo aver creato i matcher, caricare il frammento della funzione con la seguente richiesta HTTP POST autenticata:

YOUR_MANAGEMENT_API_URL/userdefinedfunctions

Usare il corpo seguente:

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

Valore	Sostituire con
USER_DEFINED_BOUNDARY	Nome di un limite di contenuto multipart
YOUR_SPACE_IDENTIFIER	Identificatore dello spazio
YOUR_MATCHER_IDENTIFIER	ID del matcher da usare

1. Verificare che le intestazioni includano: Content-Type: multipart/form-data; boundary="USER_DEFINED_BOUNDARY".

2. Verificare che il corpo sia costituito da più parti:

   • La prima parte contiene i necessari metadati di funzione definita dall'utente.
   • La seconda parte contiene la logica di calcolo JavaScript.

3. Nella sezione USER_DEFINED_BOUNDARY sostituire i valori spaceId () e matcher (YOUR_MATCHER_IDENTIFIERYOUR_SPACE_IDENTIFIER).

4. Verificare che la funzione JavaScript definita dall'utente sia fornita come Content-Type: text/javascript.

Funzioni di esempio

Impostare la lettura dei dati di telemetria del sensore direttamente per un sensore con tipo di dati Temperatura, ovvero 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);
}

Il parametro di telemetria espone gli attributi SensorId e Message , corrispondenti a un messaggio inviato da un sensore. Il parametro executionContext espone i seguenti attributi:

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

Nel prossimo esempio, registriamo un messaggio se la lettura dei dati di telemetria del sensore supera una soglia predefinita. Se le impostazioni di diagnostica sono abilitate nell'istanza di Gemelli digitali di Azure, vengono inoltrati anche i log delle funzioni definite dall'utente:

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

Il codice seguente attiva una notifica se il livello di temperatura sale sopra il valore costante predefinito:

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

Per un esempio di codice di funzione definito dall'utente più complesso, leggere la guida introduttiva Occupancy.

Creare un'assegnazione di ruolo

Creare un'assegnazione di ruolo per l'esecuzione della funzione definita dall'utente. Se non esiste alcuna assegnazione di ruolo per la funzione definita dall'utente, non si avranno le autorizzazioni appropriate per interagire con l'API Gestione o per eseguire azioni sugli oggetti grafo. Le azioni eseguite dalla funzione definita dall'utente non sono esenti dal controllo degli accessi in base al ruolo delle API di gestione di Gemelli digitali di Azure. Ad esempio, è possibile limitare l'ambito delle funzioni definite dall'utente specificando determinati ruoli o percorsi di controllo di accesso. Per altre informazioni, leggere la documentazione relativa al controllo degli accessi in base al ruolo .

1. Effettuare una query nell'API di sistema per fare in modo che tutti i ruoli ricevano l'ID da assegnare alle funzioni definite dall'utente. Eseguire questa operazione effettuando una richiesta HTTP GET autenticata a:

   YOUR_MANAGEMENT_API_URL/system/roles
   

   Mantenere l'ID del ruolo desiderato. Verrà passato come roleId () dell'attributo del corpo JSON (YOUR_DESIRED_ROLE_IDENTIFIER).

2. objectId (YOUR_USER_DEFINED_FUNCTION_ID) sarà l'ID funzione definito dall'utente creato in precedenza.

3. Trovare il valore del percorso (YOUR_ACCESS_CONTROL_PATH) eseguendo una query su spazi con fullpath.

4. Copiare il valore spacePaths restituito. Usare quello indicato di seguito. Effettuare una richiesta HTTP GET autenticata a:

   YOUR_MANAGEMENT_API_URL/spaces?name=YOUR_SPACE_NAME&includes=fullpath
   

   Valore	Sostituire con
   YOUR_SPACE_NAME	Nome dello spazio da usare

5. Incollare il valore spacePaths restituito in path per creare un'assegnazione di ruolo della funzione definita dall'utente, effettuando una richiesta HTTP POST autenticata a:

   YOUR_MANAGEMENT_API_URL/roleassignments
   

   Con corpo JSON:

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

   Valore	Sostituire con
   YOUR_DESIRED_ROLE_IDENTIFIER	Identificatore del ruolo desiderato
   YOUR_USER_DEFINED_FUNCTION_ID	L'ID per la funzione definita dall'utente da usare
   YOUR_USER_DEFINED_FUNCTION_TYPE_ID	ID che specifica il tipo di funzione definito dall'utente (UserDefinedFunctionId)
   YOUR_ACCESS_CONTROL_PATH	Percorso di controllo di accesso

Suggerimento

Per altre informazioni su operazioni ed endpoint dell'API Gestione collegati alla funzione definita dall'utente, leggere l'articolo Come creare e gestire le assegnazioni di ruolo.

Inviare i dati di telemetria da elaborare

Il sensore definito nel grafo intelligence spaziale invia dati di telemetria. A loro volta, i dati di telemetria attivano l'esecuzione della funzione definita dall'utente che è stata caricata. L'elaboratore di dati seleziona i dati di telemetria. Viene quindi creato un piano di esecuzione per la chiamata della funzione definita dall'utente.

1. Recuperare i matcher per il sensore da cui è stata generata la lettura.
2. A seconda dei matcher valutati correttamente, recuperare le funzioni definite dall'utente associate.
3. Eseguire ogni funzione definita dall'utente.

Passaggi successivi

• Informazioni su come creare endpoint di Gemelli digitali di Azure a cui inviare eventi.

• Per altre informazioni sul routing in Gemelli digitali di Azure, leggere Routing di eventi e messaggi.

• Esaminare la documentazione di riferimento della libreria client.