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

2020-01-17

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, visita la Documentazione attiva di Azure Digital Twins.

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

Questa guida presenta un esempio di come rilevare ed emettere un allerta su ogni lettura che supera una certa temperatura da 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_DELLA_TUA_ISTANZA	Nome della tua istanza di Azure Digital Twins
LA_TUA_POSIZIONE	La regione in cui è ospitata la tua istanza

Informazioni di riferimento sulla libreria client

Le funzioni disponibili come funzioni di supporto nel runtime delle funzioni definite dall'utente sono elencate nella documentazione di riferimento della libreria client.

Creare un corrisponditore

I matcher sono oggetti grafico che determinano le funzioni definite dall'utente eseguite per un determinato messaggio di telemetria.

Confronti validi delle condizioni del matcher.
- Equals
- NotEquals
- Contains
Obiettivi validi della condizione del confronto
- Sensor
- SensorDevice
- SensorSpace

Il seguente matcher di esempio restituisce true per qualsiasi evento di telemetria del sensore in cui il valore del tipo di dati è "Temperature". È possibile creare più matcher in una funzione definita dall'utente effettuando una richiesta HTTP POST autenticata per:

YOUR_MANAGEMENT_API_URL/matchers

Con il 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 implica l'esecuzione di una richiesta HTTP multipart per le API di gestione di Gemelli digitali di Azure.

Nota

Le richieste multipart richiedono in genere tre parti:

L'intestazione Content-Type:
- application/json; charset=utf-8
- multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
Disposizione del contenuto:
- form-data; name="metadata"
Contenuto del file da caricare

Content-Type e Content-Disposition variano a seconda dello scenario d'uso.

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

Importante

Le richieste multipart effettuate alle API di gestione di Gemelli digitali di Azure in genere hanno due parti:

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

Nessuna delle due parti è necessaria per le richieste PATCH . Entrambi sono necessari per le operazioni POST o di creazione.

Il codice sorgente di Occupancy Quickstart contiene esempi C# completi che illustrano come effettuare richieste multipart alle API di gestione di Gemelli digitali di Azure.

Dopo aver creato i corrispondenti, caricare il frammento di funzione con la seguente richiesta HTTP POST multipart autenticata:

YOUR_MANAGEMENT_API_URL/userdefinedfunctions

Utilizzare il seguente corpo:

--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
CONFINE_DEFINITO_DALL'UTENTE	Nome del confine del contenuto a più parti
YOUR_SPACE_IDENTIFIER	Identificatore dello spazio
YOUR_MATCHER_IDENTIFIER	ID del matcher da usare

Verificare che le intestazioni includano: Content-Type: multipart/form-data; boundary="USER_DEFINED_BOUNDARY".
Verificare che il corpo sia multipart:
- La prima parte contiene i metadati di funzione definiti dall'utente necessari.
- La seconda parte contiene la logica di calcolo JavaScript.
Nella sezione USER_DEFINED_BOUNDARY sostituire i valori spaceId (YOUR_SPACE_IDENTIFIER) e matcher (YOUR_MATCHER_IDENTIFIER).
Verificare che la funzione javaScript definita dall'utente sia fornita come Content-Type: text/javascript.

Funzioni di esempio

Impostare i dati di telemetria del sensore direttamente per il sensore con tipo di dati Temperature, 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 gli attributi seguenti:

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

Nell'esempio seguente viene registrato 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 dalle 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 aumenta al di sopra della costante predefinita:

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, vedere la guida introduttiva Occupancy.

Creare un'assegnazione di ruolo

Creare un'assegnazione di ruolo per la funzione definita dall'utente in cui eseguire. Se non esiste alcuna assegnazione di ruolo per la funzione definita dall'utente, non avrà le autorizzazioni appropriate per interagire con l'API di gestione o avere accesso per eseguire azioni sugli oggetti grafico. Le azioni che possono essere eseguite da una funzione definita dall'utente vengono specificate e definite tramite il controllo degli accessi in base al ruolo all'interno delle API di gestione di Gemelli digitali di Azure. Ad esempio, le funzioni definite dall'utente possono essere limitate nell'ambito specificando determinati ruoli o determinati percorsi di controllo di accesso. Per altre informazioni, vedere la documentazione sul controllo degli accessi in base al ruolo .

Eseguire una query sull'API di sistema per tutti i ruoli per ottenere l'ID ruolo che si desidera assegnare alla funzione definita dall'utente. A tale scopo, effettuare una richiesta HTTP GET autenticata per:
```
YOUR_MANAGEMENT_API_URL/system/roles
```
Mantenere l'ID ruolo desiderato. Verrà passato come attributo roleId nel corpo JSON (YOUR_DESIRED_ROLE_IDENTIFIER) qui sotto.
objectId (YOUR_USER_DEFINED_FUNCTION_ID) sarà l'ID funzione definito dall'utente creato in precedenza.
Trova il valore di path (YOUR_ACCESS_CONTROL_PATH) eseguendo una query nei tuoi spazi con fullpath.
Copiare il valore restituito spacePaths . Lo userai di seguito. Effettuare una richiesta HTTP GET autenticata per:
```
YOUR_MANAGEMENT_API_URL/spaces?name=YOUR_SPACE_NAME&includes=fullpath
```
Valore Sostituire con

YOUR_SPACE_NAME Nome dello spazio che si desidera utilizzare

Valore	Sostituire con
YOUR_SPACE_NAME	Nome dello spazio che si desidera utilizzare

Incollare il valore restituito spacePaths nel percorso per creare un'assegnazione di ruolo funzione definita dall'utente effettuando una richiesta HTTP POST autenticata per:

YOUR_MANAGEMENT_API_URL/roleassignments

Con il 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	ID per la funzione definita dall'utente che si vuole usare
YOUR_USER_DEFINED_FUNCTION_TYPE_ID	ID che specifica il tipo di funzione definito dall'utente (`UserDefinedFunctionId`)
PERCORSO_DI_CONTROLLO_ACCESSI	Percorso di controllo di accesso

Suggerimento

Per altre informazioni sulle operazioni e sugli endpoint dell'API di gestione delle funzioni definite dall'utente, vedere l'articolo Come creare e gestire le assegnazioni di ruolo .

Inviare dati di telemetria da elaborare

Il sensore definito nel grafico di intelligenza spaziale invia dati di telemetria. A sua volta, i dati di telemetria attivano l'esecuzione della funzione definita dall'utente caricata. Il responsabile del trattamento dei dati preleva i dati di telemetria. Viene quindi creato un piano di esecuzione per la chiamata della funzione definita dall'utente.

Recuperare gli strumenti di confronto per il sensore da cui è stata ottenuta la lettura.
A seconda dei matcher che sono stati valutati correttamente, recuperare le relative funzioni definite dall'utente.
Eseguire ogni funzione definita dall'utente.

Passaggi successivi

Informazioni su come creare endpoint di Gemelli digitali di Azure a cui inviare eventi.
Per ulteriori dettagli sul routing di Azure Digital Twins, leggi Routing di eventi e messaggi.
Esaminare la documentazione di riferimento della libreria client.

Condividi tramite