Ordinare gli eventi di connessione dei dispositivi dall'hub IoT di Azure tramite Azure Cosmos DBOrder device connection events from Azure IoT Hub using Azure Cosmos DB

Griglia di eventi di Azure consente di compilare applicazioni basate su eventi e di integrare con facilità eventi IoT nelle soluzioni aziendali.Azure Event Grid helps you build event-based applications and easily integrate IoT events in your business solutions. Questo articolo illustra una procedura che consente di tenere traccia e archiviare lo stato di connessione più recente del dispositivo in Cosmos DB.This article walks you through a setup which can be used to track and store the latest device connection state in Cosmos DB. Verrà usato il numero di sequenza disponibile negli eventi di connessione e disconnessione del dispositivo e verrà archiviato lo stato più recente in Cosmos DB.We will use the sequence number available in the Device Connected and Device Disconnected events and store the latest state in Cosmos DB. Viene usata una stored procedure, ovvero una logica dell'applicazione eseguita su una raccolta di Cosmos DB.We are going to use a stored procedure, which is an application logic that is executed against a collection in Cosmos DB.

Il numero di sequenza è una rappresentazione in formato stringa di un numero esadecimale.The sequence number is a string representation of a hexadecimal number. È possibile usare il confronto tra stringhe per identificare il numero maggiore.You can use string compare to identify the larger number. Se si converte la stringa in formato esadecimale, il numero sarà a 256 bit.If you are converting the string to hex, then the number will be a 256-bit number. Il numero di sequenza è sempre in aumento e all'evento più recente viene associato un numero superiore rispetto a quello di altri eventi.The sequence number is strictly increasing, and the latest event will have a higher number than other events. Ciò è utile se le connessioni e le disconnessioni del dispositivo sono frequenti e se è necessario assicurarsi che solo l'evento più recente venga usato per attivare un'azione downstream, poiché Griglia di eventi di Azure non supporta l'ordinamento degli eventi.This is useful if you have frequent device connects and disconnects, and want to ensure only the latest event is used to trigger a downstream action, as Azure Event Grid doesn’t support ordering of events.

PrerequisitiPrerequisites

  • Un account Azure attivo.An active Azure account. Se non si ha un account, è possibile crearne uno gratuito.If you don't have one, you can create a free account.

  • Un account API SQL di Azure Cosmos DB attivo.An active Azure Cosmos DB SQL API account. Se non ne è ancora stato creato un', vedere la procedura dettagliata Creare un account di database.If you haven't created one yet, see Create a database account for a walkthrough.

  • Una raccolta nel database.A collection in your database. Vedere la procedura dettagliata Aggiungere una raccolta.See Add a collection for a walkthrough. Quando si crea la raccolta, usare /id per la chiave di partizione.When you create your collection, use /id for the partition key.

  • Un hub IoT in Azure.An IoT Hub in Azure. Se l'hub non è stato ancora creato, vedere Introduzione all'hub IoT per la procedura dettagliata.If you haven't created one yet, see Get started with IoT Hub for a walkthrough.

Creare una stored procedureCreate a stored procedure

In primo luogo creare una stored procedure e impostarlo fino all'esecuzione di una logica che confronti i numeri di sequenza degli eventi in arrivo e registri l'evento più recente per ogni dispositivo nel database.First, create a stored procedure and set it up to run a logic that compares sequence numbers of incoming events and records the latest event per device in the database.

  1. Nell'API SQL di Cosmos DB selezionare Data Explorer > Items > New Stored Procedure (Esplora dati > Elementi > Nuova stored procedure).In your Cosmos DB SQL API, select Data Explorer > Items > New Stored Procedure.

    Creare la stored procedure

  2. Immettere LatestDeviceConnectionState per l'ID della stored procedure e incollare il codice seguente nel corpo della stored procedure.Enter LatestDeviceConnectionState for the stored procedure ID and paste the following in the Stored Procedure body. Si noti che questo codice deve sostituire il codice esistente nel corpo della stored procedure.Note that this code should replace any existing code in the stored procedure body. Questo codice mantiene una riga per ogni ID dispositivo e registra lo stato di connessione più recente di tale ID identificando il numero di sequenza più alto.This code maintains one row per device ID and records the latest connection state of that device ID by identifying the highest sequence number.

    // SAMPLE STORED PROCEDURE
    function UpdateDevice(deviceId, moduleId, hubName, connectionState, connectionStateUpdatedTime, sequenceNumber) {
      var collection = getContext().getCollection();
      var response = {};
    
      var docLink = getDocumentLink(deviceId, moduleId);
    
      var isAccepted = collection.readDocument(docLink, function(err, doc) {
        if (err) {
          console.log('Cannot find device ' + docLink + ' - ');
          createDocument();
        } else {
          console.log('Document Found - ');
          replaceDocument(doc);
        }
      });
    
      function replaceDocument(document) {
        console.log(
          'Old Seq :' +
            document.sequenceNumber +
            ' New Seq: ' +
            sequenceNumber +
            ' - '
        );
        if (sequenceNumber > document.sequenceNumber) {
          document.connectionState = connectionState;
          document.connectionStateUpdatedTime = connectionStateUpdatedTime;
          document.sequenceNumber = sequenceNumber;
    
          console.log('replace doc - ');
    
          isAccepted = collection.replaceDocument(docLink, document, function(
            err,
            updated
          ) {
            if (err) {
              getContext()
                .getResponse()
                .setBody(err);
            } else {
              getContext()
                .getResponse()
                .setBody(updated);
            }
          });
        } else {
          getContext()
            .getResponse()
            .setBody('Old Event - current: ' + document.sequenceNumber + ' Incoming: ' + sequenceNumber);
        }
      }
      function createDocument() {
        document = {
          id: deviceId + '-' + moduleId,
          deviceId: deviceId,
          moduleId: moduleId,
          hubName: hubName,
          connectionState: connectionState,
          connectionStateUpdatedTime: connectionStateUpdatedTime,
          sequenceNumber: sequenceNumber
        };
        console.log('Add new device - ' + collection.getAltLink());
        isAccepted = collection.createDocument(
          collection.getAltLink(),
          document,
          function(err, doc) {
            if (err) {
              getContext()
                .getResponse()
                .setBody(err);
            } else {
              getContext()
                .getResponse()
                .setBody(doc);
            }
          }
        );
      }
    
      function getDocumentLink(deviceId, moduleId) {
        return collection.getAltLink() + '/docs/' + deviceId + '-' + moduleId;
      }
    }
    
  3. Salvare la stored procedure:Save the stored procedure:

    Salvare la stored procedure

Creare un'app per la logicaCreate a logic app

Per prima cosa, creare un'app per la logica e aggiungere un trigger di Griglia di eventi che monitori il gruppo di risorse per la macchina virtuale.First, create a logic app and add an Event grid trigger that monitors the resource group for your virtual machine.

Creare una risorsa di App per la logicaCreate a logic app resource

  1. Nel portale di Azure, selezionare +Crea una risorsa, Integrazione e quindi App per la logica.In the Azure portal, select +Create a resource, select Integration and then Logic App.

    Creare l'app per la logica

  2. Assegnare all'app per la logica un nome che sia univoco nella sottoscrizione e quindi selezionare la stessa sottoscrizione, lo stesso gruppo di risorse e la stessa posizione dell'hub IoT.Give your logic app a name that's unique in your subscription, then select the same subscription, resource group, and location as your IoT hub.

    Nuova app per la logica

  3. Fare clic su Crea per creare l'app per la logica.Select Create to create the logic app.

    È stata creata ora una risorsa di Azure per l'app per la logica.You've now created an Azure resource for your logic app. Al termine della distribuzione dell'app per la logica, Progettazione app per la logica mostra i modelli comuni disponibili per poter iniziare più rapidamente.After Azure deploys your logic app, the Logic Apps Designer shows you templates for common patterns so you can get started faster.

    Nota

    Per trovare e aprire di nuovo l'app per la logica, selezionare Gruppi di risorse e selezionare il gruppo di risorse che si sta usando per questa procedura.To find and open your logic app again, select Resource groups and select the resource group you are using for this how-to. Selezionare quindi la nuova app per la logica.Then select your new logic app. Viene aperta la finestra di progettazione delle app per la logica.This opens the Logic App Designer.

  4. Nella finestra di progettazione dell'app per la logica scorrere verso destra fino a visualizzare i trigger comuni.In the Logic App Designer, scroll to the right until you see common triggers. In Modelli scegliere App per la logica vuota per poter creare l'app per la logica da zero.Under Templates, choose Blank Logic App so that you can build your logic app from scratch.

Selezionare un triggerSelect a trigger

Un trigger è un evento specifico che avvia l'app per la logica.A trigger is a specific event that starts your logic app. Per questa esercitazione, il trigger che attiva il flusso di lavoro riceve una richiesta tramite HTTP.For this tutorial, the trigger that sets off the workflow is receiving a request over HTTP.

  1. Nella barra di ricerca dei trigger e dei connettori digitare HTTP e premere Invio.In the connectors and triggers search bar, type HTTP and hit Enter.

  2. Selezionare Richiesta - Alla ricezione di una richiesta HTTP come trigger.Select Request - When an HTTP request is received as the trigger.

    Selezionare il trigger di richiesta HTTP

  3. Selezionare Usare il payload di esempio per generare lo schema.Select Use sample payload to generate schema.

    Usare il payload di esempio per generare uno schema

  4. Incollare l'esempio di codice JSON seguente nella casella di testo e quindi selezionare Fine:Paste the following sample JSON code into the text box, then select Done:

    [{
     "id": "fbfd8ee1-cf78-74c6-dbcf-e1c58638ccbd",
     "topic":
       "/SUBSCRIPTIONS/DEMO5CDD-8DAB-4CF4-9B2F-C22E8A755472/RESOURCEGROUPS/EGTESTRG/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/MYIOTHUB",
     "subject": "devices/Demo-Device-1",
     "eventType": "Microsoft.Devices.DeviceConnected",
     "eventTime": "2018-07-03T23:20:11.6921933+00:00",
     "data": {
       "deviceConnectionStateEventInfo": {
         "sequenceNumber":
           "000000000000000001D4132452F67CE200000002000000000000000000000001"
       },
       "hubName": "MYIOTHUB",
       "deviceId": "48e44e11-1437-4907-83b1-4a8d7e89859e",
       "moduleId": ""
     },
     "dataVersion": "1",
     "metadataVersion": "1"
    }]
    

    Incollare un payload JSON di esempio

  5. È possibile che venga inviata una notifica popup con la dicitura Ricordare di includere nella richiesta un'intestazione Content-Type impostata su application/json.You may receive a pop-up notification that says, Remember to include a Content-Type header set to application/json in your request. Questo suggerimento può essere tranquillamente ignorato ed è possibile passare alla sezione successiva.You can safely ignore this suggestion, and move on to the next section.

Creare una condizioneCreate a condition

Nel flusso di lavoro dell'app per la logica, le condizioni consentono di eseguire azioni specifiche dopo il superamento di una determinata condizione.In your logic app workflow, conditions help run specific actions after passing that specific condition. Dopo che la condizione è soddisfatta, è possibile definire un'azione desiderata.Once the condition is met, a desired action can be defined. Per questa esercitazione, la condizione consiste nel controllare se il tipo di evento (eventType) è la connessione o la disconnessione del dispositivo.For this tutorial, the condition is to check whether eventType is device connected or device disconnected. L'azione consiste invece nell'esecuzione della stored procedure nel database.The action will be to execute the stored procedure in your database.

  1. Selezionare + Nuovo passaggio quindi Incorporata, quindi individuare e selezionare Condizione.Select + New step then Built-in, then find and select Condition. Fare clic su Scegli un valore per visualizzare una casella che mostra il contenuto dinamico, ovvero i campi che è possibile selezionare.Click in Choose a value and a box will pop up showing the Dynamic content -- the fields that can be selected. Compilare i campi come illustrato di seguito per l'esecuzione esclusiva degli eventi di connessione e disconnessione dei dispositivi:Fill in the fields as shown below to only execute this for Device Connected and Device Disconnected events:

    • Scegliere un valore eventType: selezionare questo valore nei campi del contenuto dinamico visualizzati quando si fa clic su questo campo.Choose a value: eventType -- select this from the fields in the dynamic content that appear when you click on this field.

    • Modificare "uguale a" in termina con.Change "is equal to" to ends with.

    • Scegliere un valore: nected.Choose a value: nected.

      Specificare una condizione

  2. Nella finestra di dialogo se true fare clic su Aggiungi un'azione.In the if true dialog, click on Add an action.

    Aggiunta di un'azione se la condizione è vera

  3. Cercare Cosmos DB e selezionare Azure Cosmos DB - Esegui stored procedureSearch for Cosmos DB and select Azure Cosmos DB - Execute stored procedure

    Ricerca di CosmosDB

  4. Compilare cosmosdb-connection di connessione per Nome connessione e selezionare la voce nella tabella, quindi selezionare Crea.Fill in cosmosdb-connection for the Connection Name and select the entry in the table, then select Create. Viene visualizzato il pannello Esegui stored procedure.You see the Execute stored procedure panel. Immettere i valori per i campi:Enter the values for the fields:

    ID database: ToDoListDatabase ID: ToDoList

    ID raccolta: ItemsCollection ID: Items

    ID stored procedure: LatestDeviceConnectionStateSproc ID: LatestDeviceConnectionState

  5. Selezionare Aggiungi nuovo parametro.Select Add new parameter. Nell'elenco a discesa visualizzato selezionare le caselle accanto a Chiave di partizione e Parametri per la stored procedure, quindi fare clic in un punto qualsiasi dello schermo; verrà aggiunto un campo per il valore della chiave di partizione e un campo per i parametri per la stored procedure.In the dropdown that appears, check the boxes next to Partition key and Parameters for the stored procedure, then click anywhere else on the screen; it adds a field for partition key value and a field for parameters for the stored procedure.

    Screenshot mostra un elemento EXECUTE stored procedure con Aggiungi nuovo parametro selezionato.

  6. Immettere ora il valore della chiave di partizione e i parametri come illustrato di seguito.Now enter the partition key value and parameters as shown below. Assicurarsi di effettuare l'inserimento tra parentesi quadre e virgolette doppie, come illustrato.Be sure to put in the brackets and double-quotes as shown. Potrebbe essere necessario fare clic su Aggiungi contenuto dinamico per ottenere i valori validi che è possibile usare qui.You may have to click Add dynamic content to get the valid values you can use here.

    Screenshot mostra un elemento EXECUTE stored procedure con i parametri immessi.

  7. Nella parte superiore del riquadro in cui viene indicato Per ogni, in Seleziona un output dai passaggi precedenti, assicurarsi di selezionare Corpo.At the top of the pane where it says For Each, under Select an output from previous steps, make sure it Body is selected.

    popolare per ogni app per la logica

  8. Salvare l'app per la logica.Save your logic app.

Copiare l'URL HTTPCopy the HTTP URL

Prima di uscire da Progettazione app per la logica, copiare l'URL su cui è in ascolto l'app per la logica per un trigger.Before you leave the Logic Apps Designer, copy the URL that your logic app is listening to for a trigger. Questo URL viene usato per configurare Griglia di eventi.You use this URL to configure Event Grid.

  1. Espandere la casella di configurazione del trigger Alla ricezione di una richiesta HTTP facendo clic sull'opzione.Expand the When a HTTP request is received trigger configuration box by clicking on it.

  2. Copiare il valore di URL POST HTTP facendo clic sul pulsante di copia che si trova accanto.Copy the value of HTTP POST URL by selecting the copy button next to it.

    Copiare l'URL POST HTTP

  3. Salvare l'URL per poterlo usare nella sezione successiva.Save this URL so that you can refer to it in the next section.

Configurare la sottoscrizione degli eventi dell'hub IoTConfigure subscription for IoT Hub events

In questa sezione viene configurato l'hub IoT per la pubblicazione degli eventi che si verificano.In this section, you configure your IoT Hub to publish events as they occur.

  1. Nel portale di Azure passare all'hub IoT.In the Azure portal, navigate to your IoT hub.

  2. Selezionare Eventi.Select Events.

    Aprire i dettagli di Griglia di eventi

  3. Selezionare + Sottoscrizione di eventi.Select + Event subscription.

    Creare una nuova sottoscrizione di eventi

  4. Compilare i Dettagli sottoscrizione evento: fornire un nome descrittivo e selezionare Schema Griglia di eventi.Fill in Event Subscription Details: Provide a descriptive name and select Event Grid Schema.

  5. Compilare i campi Tipi di evento.Fill in the Event Types fields. Nell'elenco a discesa selezionare solo Dispositivo connesso e Dispositivo disconnesso dal menu.In the dropdown list, select only Device Connected and Device Disconnected from the menu. Fare clic in un punto qualsiasi della schermata per chiudere l'elenco e salvare le selezioni.Click anywhere else on the screen to close the list and save your selections.

    Impostare i tipi di evento da cercare

  6. Per Dettagli endpoint: come Tipo di endpoint selezionare Webhook, fare clic su Selezione endpoint, incollare l'URL copiato dall'app per la logica e confermare la selezione.For Endpoint Details, select Endpoint Type as Web Hook and click on select endpoint and paste the URL that you copied from your logic app and confirm selection.

    URL di Selezione endpoint

  7. Il modulo dovrebbe avere un aspetto simile all'esempio seguente:The form should now look similar to the following example:

    Modulo sottoscrizione di eventi di esempio

    Selezionare Crea per salvare la sottoscrizione di eventi.Select Create to save the event subscription.

Osservare gli eventiObserve events

Ora che la sottoscrizione dell'evento è configurata, è possibile testare la connessione di un dispositivo.Now that your event subscription is set up, let's test by connecting a device.

Registrare un dispositivo nell'hub IoTRegister a device in IoT Hub

  1. Nell'hub IoT selezionare IoT Devices (Dispositivi IoT).From your IoT hub, select IoT Devices.

  2. Nella parte superiore del riquadro selezionare +Aggiungi.Select +Add at the top of the pane.

  3. In ID dispositivo immettere Demo-Device-1.For Device ID, enter Demo-Device-1.

  4. Selezionare Salva.Select Save.

  5. È possibile aggiungere più dispositivi con ID dispositivo diversi.You can add multiple devices with different device IDs.

    Dispositivi aggiunti all'hub

  6. Fare di nuovo clic sul dispositivo. Verranno ora compilate le stringhe di connessione e le chiavi.Click on the device again; now the connection strings and keys will be filled in. Copiare il valore di Stringa di connessione -- Chiave primaria per usarlo in seguito.Copy the Connection string -- primary key for later use.

    ConnectionString per il dispositivo

Avviare il simulatore Raspberry PiStart Raspberry Pi simulator

È possibile usare il simulatore Web Raspberry Pi per simulare la connessione del dispositivo.Let's use the Raspberry Pi web simulator to simulate device connection.

Avviare il simulatore Raspberry PiStart Raspberry Pi simulator

Eseguire un'applicazione di esempio nel simulatore Web Raspberry PiRun a sample application on the Raspberry Pi web simulator

Viene attivato un evento di connessione del dispositivo.This will trigger a device connected event.

  1. Nell'area di scrittura del codice sostituire il segnaposto nella riga 15 con la stringa di connessione del dispositivo dell'hub IoT di Azure salvata al termine della sezione precedente.In the coding area, replace the placeholder in Line 15 with your Azure IoT Hub device connection string that you saved at the end of the previous section.

    Incollare la stringa di connessione del dispositivo

  2. Eseguire l'applicazione selezionando Esegui.Run the application by selecting Run.

Dovrebbe essere visibile un output simile al seguente che mostra i dati del sensore e i messaggi inviati all'hub IoT.You see something similar to the following output that shows the sensor data and the messages that are sent to your IoT hub.

Esecuzione dell'applicazione

Fare clic su Arresta per arrestare il simulatore e attivare un evento Dispositivo disconnesso.Click Stop to stop the simulator and trigger a Device Disconnected event.

È stata eseguita un'applicazione di esempio per raccogliere i dati del sensore da inviare all'hub IoT.You have now run a sample application to collect sensor data and send it to your IoT hub.

Osservare gli eventi in Cosmos DBObserve events in Cosmos DB

È possibile visualizzare i risultati della stored procedure eseguita in un documento di Cosmos DB.You can see results of the executed stored procedure in your Cosmos DB document. Com'è possibile osservare,Here's what it looks like. per tutti i dispositivi ogni riga contiene lo stato più recente della connessione del dispositivo stesso.Each row contains the latest device connection state per device.

Come ottenere un risultato

Utilizzare l’interfaccia della riga di comando di AzureUse the Azure CLI

Anziché tramite il portale di Azure, è possibile eseguire le procedure relative all'hub IoT usando l'interfaccia della riga di comando di Azure.Instead of using the Azure portal, you can accomplish the IoT Hub steps using the Azure CLI. Per informazioni dettagliate, vedere le pagine relative all'interfaccia della riga di comando di Azure per la creazione di una sottoscrizione di eventi e la creazione di un dispositivo IoT.For details, see the Azure CLI pages for creating an event subscription and creating an IoT device.

Pulire le risorseClean up resources

Questa esercitazione ha usato risorse che generano addebiti sulla sottoscrizione di Azure.This tutorial used resources that incur charges on your Azure subscription. Al termine dell'esercitazione e dopo aver testato i risultati ottenuti, disabilitare o eliminare le risorse che non si vogliono mantenere.When you're finished trying out the tutorial and testing your results, disable or delete resources that you don't want to keep.

Per non perdere il lavoro fatto, è possibile disabilitare l'app per la logica anziché eliminarla.If you don't want to lose the work on your logic app, disable it instead of deleting it.

  1. Passare all'app per la logica.Navigate to your logic app.

  2. Nel pannello Panoramica selezionare Elimina o Disabilita.On the Overview blade, select Delete or Disable.

    Ogni sottoscrizione può avere un unico hub IoT gratuito.Each subscription can have one free IoT hub. Se per questa esercitazione è stato creato un hub gratuito, non è necessario eliminarlo per impedire eventuali addebiti.If you created a free hub for this tutorial, then you don't need to delete it to prevent charges.

  3. Passare all'hub IoT.Navigate to your IoT hub.

  4. Nel pannello Panoramica selezionare Elimina.On the Overview blade, select Delete.

    Anche se si mantiene l'hub IoT, può essere opportuno eliminare la sottoscrizione di eventi creata.Even if you keep your IoT hub, you may want to delete the event subscription that you created.

  5. Nell'hub IoT selezionare Griglia di eventi.In your IoT hub, select Event Grid.

  6. Selezionare la sottoscrizione di eventi da rimuovere.Select the event subscription that you want to remove.

  7. Selezionare Elimina.Select Delete.

Per rimuovere un account Azure Cosmos DB dal portale di Azure, fare clic con il pulsante destro del mouse sul nome dell'account e quindi fare clic su Elimina account.To remove an Azure Cosmos DB account from the Azure portal, right-click the account name and click Delete account. Vedere le istruzioni dettagliate per eliminare un account di Azure Cosmos DB.See detailed instructions for deleting an Azure Cosmos DB account.

Passaggi successiviNext steps