Configurare le regole

  • Articolo

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 dispositivi a cui si applica 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 Refrigerator . Il filtro indica che la regola deve includere solo i frigoriferi la cui proprietà Manufactured State (Stato di produzione) è uguale a Washington.

Screenshot that shows a filter definition in a rule.

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 controllano quando la temperatura è maggiore di 70° F e l'umidità è inferiore al 10%. Quando una di queste istruzioni è true, la regola restituisce true e attiva un'azione.

Screenshot shows a refrigerator monitor with conditions specified for temperature and humidity.

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.

A diagram showing how tumbling windows are defined.

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 l'utente deve aver eseguito l'accesso all'applicazione almeno una volta. È 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:

Screenshot that shows an email action for a rule.

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. L'app IoT Central invia una richiesta POST all'endpoint HTTP dell'altra applicazione ogni volta che viene attivata una regola. Il payload contiene i dettagli del dispositivo e i dettagli del trigger della regola.

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

  1. Passare a RequestBin.

  2. Selezionare Create a RequestBin (Crea un elemento RequestBin).

  3. Accedere con uno dei metodi disponibili.

  4. Copiare l'URL dell'endpoint RequestBin.

  5. Aggiungere un'azione alla regola:

    Screenshot that shows the webhook creation screen.

  6. Scegliere l'azione webhook, immettere un nome visualizzato e incollare l'URL RequestBin come URL di callback.

  7. Salva la regola.

Ora, quando la regola viene attivata, 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 dati di telemetria, il dispositivo, la regola e i dettagli dell'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'azione di gruppo di Monitoraggio di Azure

Questa sezione descrive come usare i gruppi di azioni di Monitoraggiodi Azure per associare più azioni a una regola di IoT Central. È possibile collegare 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 può:

  • Inviare notifiche, ad esempio un messaggio di posta elettronica, un SMS o effettuare 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:

Screenshot that shows an action group in the Azure portal.

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:

Screenshot that shows an action group in an IoT Central rule.

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}
Chiamata vocale Avviso di Azure I.O.T 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. Si prenda l'esempio seguente, la prima condizione della regola si trova in una telemetria della temperatura dal modulo A. La seconda condizione della regola si trova in una telemetria di umidità nel modulo B. Poiché le due condizioni provengono da moduli diversi, si dispone di un set di condizioni non valido. La regola non è valida e genera un errore quando si tenta di salvare la regola.

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.