Configurare le regole

Articolo
07/17/2024

Le regole in IoT Central fungono da strumento di risposta personalizzabile che attiva gli eventi monitorati attivamente dai dispositivi connessi. Le sezioni seguenti descrivono come vengono valutate le regole. È possibile definire una o più azioni che si verificano quando si attiva una regola, questo articolo descrive i gruppi di azioni di posta elettronica, webhook e Monitoraggio di Azure. Per informazioni su altri tipi di azioni, vedere Usare i flussi di lavoro per integrare l'applicazione Azure IoT Central con altri servizi cloud.

Selezionare i dispositivi di destinazione

Usare la sezione Dispositivi di destinazione per selezionare il tipo di dispositivo a cui viene applicata questa regola. I filtri consentono di limitare ulteriormente i dispositivi da includere. I filtri usano le proprietà nel modello di dispositivo per filtrare il set di dispositivi. I filtri in sé non attivano un'azione. Nello screenshot seguente la regola è destinata ai dispositivi Frigorifero. Il filtro indica che la regola deve includere solo i frigoriferi la cui proprietà Manufactured State (Stato di produzione) è uguale a Washington.

Usare più condizioni

Le condizioni determinano i dispositivi in cui viene attivata la regola. È possibile aggiungere più condizioni a una regola e specificare se per l’attivazione della regola devono verificarsi tutte le condizioni o sia sufficiente il verificarsi di una condizione qualsiasi.

Nello screenshot seguente le condizioni verificano quando la temperatura è superiore a 70° F e l'umidità è minore del 10%. Quando una delle condizioni è vera, la regola restituisce true e attiva un'azione.

Nota

Attualmente sono supportate solo le condizioni di telemetria.

Usare una proprietà cloud in un campo Valore

È possibile fare riferimento a una proprietà cloud dal modello di dispositivo nel campo Valore di una condizione. Il valore della proprietà cloud e quello dei dati di telemetria devono essere di tipi simili. Se, ad esempio, Temperatura è un valore Double, nell'elenco a discesa Valore vengono visualizzate come opzioni solo le proprietà cloud di tipo Double.

Se si sceglie un valore di telemetria di tipo evento, l'elenco a discesa Valore include l'opzione Qualsiasi. L'opzione Qualsiasi indica che la regola viene attivata quando l'applicazione riceve un evento di quel tipo, indipendentemente dal payload.

Usare gli intervalli di tempo di aggregazione

È possibile specificare un'aggregazione temporale per attivare la regola in base a un intervallo di tempo. Le condizioni delle regole controllano le finestre temporali di aggregazione in base ai dati di telemetria, come le finestre a cascata. Se nella regola sono presenti filtri inerenti alle proprietà, tali filtri vengono applicati allo scadere dell'intervallo di tempo. Nello screenshot seguente l'intervallo di tempo è di cinque minuti. Ogni cinque minuti, la regola valuta gli ultimi cinque minuti di dati di telemetria. I dati vengono valutati solo una volta nell'intervallo di tempo a cui corrispondono.

Diagramma che mostra come vengono definite le finestre a cascata.

Creare un'azione di posta elettronica

Quando si crea un'azione di posta elettronica, l'indirizzo di posta elettronica deve essere un ID utente nell'applicazione e tale utente deve aver eseguito almeno una volta l'accesso all'applicazione. È inoltre possibile specificare una nota da includere nel messaggio di posta elettronica. IoT Central mostra un esempio dell'aspetto del messaggio di posta elettronica quando la regola viene attivata:

Creare un'azione webhook

I webhook consentono di connettere l'app IoT Central ad altre applicazioni e servizi per il monitoraggio remoto e le notifiche. I webhook inviano automaticamente notifiche ad altre applicazioni e servizi a cui ci si connette ogni volta che viene attivata una regola nell'app IoT Central. Ogni volta che viene attivata una regola, l'app IoT Central invia una richiesta POST all'endpoint HTTP dell'altra applicazione. Il payload contiene i dettagli del dispositivo e del trigger di regola.

In questo esempio ci si connette a RequestBin per testare la notifica:

Andare a RequestBin.
Selezionare Crea un elemento RequestBin.
Accedere con uno dei metodi disponibili.
Copiare l'URL dell'endpoint RequestBin.
Aggiungere un'azione alla regola:
Scegliere l'azione webhook, immettere un nome visualizzato e incollare l'URL di RequestBin come URL di callback.
Salva la regola.

A questo punto, quando viene attivata la regola, viene visualizzata una nuova richiesta in RequestBin.

Payload

Quando una regola viene attivata, effettua una richiesta HTTP POST all'URL di callback. La richiesta contiene un payload JSON con i dettagli relativi a telemetria, dispositivo, regola e applicazione. Il payload è simile al frammento JSON seguente:

{
    "timestamp": "2020-04-06T00:20:15.06Z",
    "action": {
        "id": "<id>",
        "type": "WebhookAction",
        "rules": [
            "<rule_id>"
        ],
        "displayName": "Webhook 1",
        "url": "<callback_url>"
    },
    "application": {
        "id": "<application_id>",
        "displayName": "Contoso",
        "subdomain": "contoso",
        "host": "contoso.azureiotcentral.com"
    },
    "device": {
        "id": "<device_id>",
        "etag": "<etag>",
        "displayName": "Refrigerator Monitor - 1yl6vvhax6c",
        "instanceOf": "<device_template_id>",
        "simulated": true,
        "provisioned": true,
        "approved": true,
        "cloudProperties": {
            "City": {
                "value": "Seattle"
            }
        },
        "properties": {
            "deviceinfo": {
                "firmwareVersion": {
                    "value": "1.0.0"
                }
            }
        },
        "telemetry": {
            "<interface_instance_name>": {
                "humidity": {
                    "value": 47.33228889360127
                }
            }
        }
    },
    "rule": {
        "id": "<rule_id>",
        "displayName": "Humidity monitor"
    }
}

Se la regola monitora i dati di telemetria aggregati in un periodo di tempo, il payload contiene una sezione di telemetria simile alla seguente:

{
    "telemetry": {
        "<interface_instance_name>": {
            "Humidity": {
                "avg": 39.5
            }
        }
    }
}

Avviso di modifica del formato dati

Se sono stati creati e salvati uno o più webhook prima del 3 aprile 2020, eliminare il webhook e crearne uno nuovo. I webhook meno recenti usano un formato di payload deprecato:

{
    "id": "<id>",
    "displayName": "Webhook 1",
    "timestamp": "2019-10-24T18:27:13.538Z",
    "rule": {
        "id": "<id>",
        "displayName": "High temp alert",
        "enabled": true
    },
    "device": {
        "id": "rm1",
        "displayName": "Refrigerator Monitor - rm1",
        "instanceOf": "<device-template-id>",
        "simulated": true,
        "provisioned": true,
        "approved": true
    },
    "data": [{
        "@id": "<id>",
        "@type": ["Telemetry"],
        "name": "temperature",
        "displayName": "Temperature",
        "value": 66.27310467496761,
        "interfaceInstanceName": "sensors"
    }],
    "application": {
        "id": "<id>",
        "displayName": "x - Store Analytics Checkout",
        "subdomain": "<subdomain>",
        "host": "<host>"
    }
}

Creare un gruppo di azioni di Monitoraggio di Azure

Questa sezione descrive come usare gruppi di azioni di Monitoraggio di Azure per associare più azioni a una regola di IoT Central. È possibile associare un gruppo di azioni a più regole. Un gruppo di azioni è una raccolta delle preferenze di notifica definite dal proprietario di una sottoscrizione di Azure.

È possibile creare e gestire gruppi di azioni nel portale di Azure o con un modello di Azure Resource Manager.

Un gruppo di azioni consente di:

Inviare notifiche, ad esempio un messaggio di posta elettronica, un SMS o una chiamata vocale.
Eseguire un'azione, ad esempio la chiamata di un webhook.

Lo screenshot seguente mostra un gruppo di azioni che invia notifiche tramite posta elettronica e SMS e chiama un webhook:

Per usare un gruppo di azioni in una regola di IoT Central, il gruppo di azioni deve trovarsi nella stessa sottoscrizione di Azure dell'applicazione IoT Central.

Quando si aggiunge un'azione alla regola in IoT Central, selezionare Gruppi di azioni di Monitoraggio di Azure.

Scegliere un gruppo di azioni dalla sottoscrizione di Azure:

Seleziona Salva. Il gruppo di azioni viene ora visualizzato nell'elenco di azioni da eseguire quando viene attivata la regola.

La tabella seguente riepiloga le informazioni inviate ai tipi di azione supportati:

Tipo di azione	Formato di output
E-mail	Modello di posta elettronica IoT Central standard
SMS	Avviso di Azure IoT Central: `${applicationName} - "${ruleName}" triggered on "${deviceName}" at ${triggerDate} ${triggerTime}`
Voce	Avviso di Azure IoT Central: regola `"${ruleName}" triggered on device "${deviceName}" at ${triggerDate} ${triggerTime}, in application ${applicationName}`
Webhook	`{ "schemaId" : "AzureIoTCentralRuleWebhook", "data": {"regular webhook payload"}}`

Il testo seguente è un messaggio SMS di esempio di un gruppo di azioni:

iotcentral: Azure IoT Central alert: Contoso - "Low pressure alert" triggered on "Motion sensor 2" at March 20, 2019 10:12 UTC

Usare le regole con i moduli IoT Edge

Le regole applicate ai moduli IoT Edge sono soggette a una restrizione. Le regole sui dati di telemetria di moduli diversi non vengono valutate come regole valide. Con riferimento all'esempio seguente, la prima condizione della regola riguarda i dati di telemetria della temperatura del modulo A e la seconda condizione riguarda i dati di telemetria dell'umidità nel modulo B. Poiché le due condizioni provengono da moduli diversi, questo set di condizioni non è valido. La regola non è valida e genera un errore quando si prova a salvarla.

Passaggi successivi

Ora che si è appreso come configurare una regola nell'applicazione Azure IoT Central, è possibile apprendere come configurare le regole avanzate usando Power Automate o App per la logica di Azure.

Condividi tramite