View a markdown version of this page

Sviluppando AWS IoT TwinMaker connettori dati per serie temporali - AWS IoT TwinMaker
AWS IoT TwinMaker prerequisiti per il connettore dati di serie temporaliTime-series sfondo del connettore datiSviluppo di un connettore dati per serie temporaliMiglioramento del connettore datiTest del connettoreSicurezzaCreazione in corso AWS IoT TwinMaker risorseCosa c'è dopo

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Sviluppando AWS IoT TwinMaker connettori dati per serie temporali

Questa sezione spiega come sviluppare un connettore dati per serie temporali in un processo dettagliato. Inoltre, presentiamo un esempio di connettore dati di serie temporali basato sull'intero campione di cookie factory, che include modelli 3D, entità, componenti, allarmi e connettori. La fonte di esempio di cookie factory è disponibile nel repository degli AWS IoT TwinMaker esempi GitHub .

Argomenti

AWS IoT TwinMaker prerequisiti per il connettore dati di serie temporali

Prima di sviluppare il connettore dati per serie temporali, ti consigliamo di completare le seguenti attività:

Nota

Per un esempio di connettore completamente implementato, consulta il nostro esempio di implementazione di cookie factory.

Time-series sfondo del connettore dati

Immagina di lavorare in una fabbrica che ha un set di miscelatori per biscotti e un serbatoio d'acqua. Vorresti creare gemelli AWS IoT TwinMaker digitali di queste entità fisiche in modo da poterne monitorare gli stati operativi controllando varie metriche di serie temporali.

Avete configurato dei sensori in loco e state già trasmettendo i dati di misurazione in un database Timestream. Vuoi essere in grado di visualizzare e organizzare i dati di misurazione AWS IoT TwinMaker con un sovraccarico minimo. È possibile eseguire questa operazione utilizzando un connettore dati per serie temporali. L'immagine seguente mostra un esempio di tabella di telemetria, che viene popolata mediante l'uso di un connettore per serie temporali.

Un esempio di dati della tabella di telemetria che include l'ID dell'asset, il tipo, la misura, l'ora e i valori.

I set di dati e la tabella Timestream utilizzati in questa schermata sono disponibili nel repository degli esempi. AWS IoT TwinMaker GitHub Vedi anche il connettore di esempio di cookie factory per l'implementazione, che produce il risultato mostrato nella schermata precedente.

Time-series flusso di dati del connettore dati

Per le interrogazioni sul piano dati, AWS IoT TwinMaker recupera le proprietà corrispondenti dei componenti e dei tipi di componenti dalle definizioni dei componenti e dei tipi di componenti. AWS IoT TwinMaker inoltra le proprietà alle AWS Lambda funzioni insieme a tutti i parametri di interrogazione API contenuti nella query.

AWS IoT TwinMaker utilizza le funzioni Lambda per accedere e risolvere le query provenienti da fonti di dati e restituire i risultati di tali query. Le funzioni Lambda utilizzano le proprietà del componente e del tipo di componente del piano dati per risolvere la richiesta iniziale.

I risultati della query Lambda vengono mappati su una risposta API e restituiti all'utente.

AWS IoT TwinMaker definisce l'interfaccia del connettore dati e la utilizza per interagire con le funzioni Lambda. Utilizzando i connettori di dati, puoi interrogare la tua fonte di dati dall' AWS IoT TwinMaker API senza alcuna operazione di migrazione dei dati. L'immagine seguente illustra il flusso di dati di base descritto nei paragrafi precedenti.

Le richieste e le risposte API utilizzano le richieste e le risposte di 3P Connector che accedono a una fonte di dati.

Sviluppo di un connettore dati per serie temporali

La procedura seguente delinea un modello di sviluppo che si trasforma in modo incrementale in un connettore dati funzionale per serie temporali. I passaggi di base sono i seguenti:

  1. Crea un tipo di componente di base valido

    In un tipo di componente, definisci proprietà comuni condivise tra i tuoi componenti. Per ulteriori informazioni sulla definizione dei tipi di componenti, vedere Utilizzo e creazione di tipi di componenti.

    AWS IoT TwinMaker utilizza un modello di modellazione di entità e componente in modo che ogni componente sia collegato a un'entità. Si consiglia di modellare ogni elemento fisico come un'entità e di modellare diverse fonti di dati con i propri tipi di componenti.

    L'esempio seguente mostra un tipo di componente del modello Timestream con una proprietà:

    {"componentTypeId": "com.example.timestream-telemetry",
    "workspaceId": "MyWorkspace",
    "functions": {
        "dataReader": {
            "implementedBy": {
                "lambda": {
                    "arn": "lambdaArn"
                }
            }
        }
    },
    "propertyDefinitions": {
        "telemetryType": {
            "dataType": { "type": "STRING" },
            "isExternalId": false,
            "isStoredExternally": false,
            "isTimeSeries": false,
            "isRequiredInEntity": true
        },
        "telemetryId": {
            "dataType": { "type": "STRING" },
            "isExternalId": true,
            "isStoredExternally": false,
            "isTimeSeries": false,
            "isRequiredInEntity": true
        },
        "Temperature": {
            "dataType": { "type": "DOUBLE" },
            "isExternalId": false,
            "isTimeSeries": true,
            "isStoredExternally": true,
            "isRequiredInEntity": false
        }
    }
}

    Gli elementi chiave del tipo di componente sono i seguenti:

    • La telemetryId proprietà identifica la chiave univoca dell'elemento fisico nell'origine dati corrispondente. Il connettore dati utilizza questa proprietà come condizione di filtro per interrogare solo i valori associati all'elemento specificato. Inoltre, se includi il valore della telemetryId proprietà nella risposta dell'API del piano dati, il lato client acquisisce l'ID e può eseguire una ricerca inversa, se necessario.

    • Il lambdaArn campo identifica la funzione Lambda con cui interagisce il tipo di componente.

    • Il isRequiredInEntity flag impone la creazione dell'ID. Questo flag è obbligatorio in modo che quando il componente viene creato, venga creato anche l'ID dell'elemento.

    • TelemetryIdViene aggiunto al tipo di componente come ID esterno in modo che l'elemento possa essere identificato nella tabella Timestream.

  2. Crea un componente con il tipo di componente

    Per utilizzare il tipo di componente creato, è necessario creare un componente e collegarlo all'entità da cui si desidera recuperare i dati. I passaggi seguenti descrivono in dettaglio il processo di creazione di quel componente:

    1. Passare alla console AWS IoT TwinMaker.

    2. Selezionate e aprite lo stesso spazio di lavoro in cui avete creato i tipi di componenti.

    3. Passate alla pagina delle entità.

    4. Crea una nuova entità o seleziona un'entità esistente dalla tabella.

    5. Dopo aver selezionato l'entità che desideri utilizzare, scegli Aggiungi componente per aprire la pagina Aggiungi componente.

    6. Assegna un nome al componente e per il Tipo, scegli il tipo di componente che hai creato con il modello in 1. Crea un tipo di componente di base valido.

  3. Fai in modo che il tuo tipo di componente chiami un connettore Lambda

    Il connettore Lambda deve accedere all'origine dati e generare l'istruzione di interrogazione in base all'input e inoltrarla all'origine dati. L'esempio seguente mostra un modello di richiesta JSON che esegue questa operazione. 

    {
  "workspaceId": "MyWorkspace",
  "entityId": "MyEntity",
  "componentName": "TelemetryData",
  "selectedProperties": ["Temperature"],
  "startTime": "2022-08-25T00:00:00Z",
  "endTime": "2022-08-25T00:00:05Z",
  "maxResults": 3,
  "orderByTime": "ASCENDING",
  "properties": {
      "telemetryType": {
          "definition": {
              "dataType": { "type": "STRING" },
              "isExternalId": false,
              "isFinal": false,
              "isImported": false,
              "isInherited": false,
              "isRequiredInEntity": false,
              "isStoredExternally": false,
              "isTimeSeries": false
          },
          "value": {
              "stringValue": "Mixer"
          }
      },
      "telemetryId": {
          "definition": {
              "dataType": { "type": "STRING" },
              "isExternalId": true,
              "isFinal": true,
              "isImported": false,
              "isInherited": false,
              "isRequiredInEntity": true,
              "isStoredExternally": false,
              "isTimeSeries": false
          },
          "value": {
              "stringValue": "item_A001"
          }
      },
      "Temperature": {
          "definition": {
              "dataType": { "type": "DOUBLE", },
              "isExternalId": false,
              "isFinal": false,
              "isImported": true,
              "isInherited": false,
              "isRequiredInEntity": false,
              "isStoredExternally": false,
              "isTimeSeries": true
          }
      }
  }
}

    Gli elementi chiave della richiesta:

    • selectedPropertiesÈ un elenco da compilare con le proprietà per le quali desideri le misurazioni Timestream.

    • I endTime campistartDateTime, startTimeEndDateTime, e specificano un intervallo di tempo per la richiesta. Questo determina l'intervallo di campionamento per le misurazioni restituite.

    • entityIdÈ il nome dell'entità da cui si stanno interrogando i dati.

    • componentNameÈ il nome del componente da cui si stanno interrogando i dati.

    • Utilizza il orderByTime campo per organizzare l'ordine in cui vengono visualizzati i risultati.

    Nella precedente richiesta di esempio, ci aspetteremmo di ottenere una serie di campioni per le proprietà selezionate durante la finestra temporale specificata per l'articolo specificato, con l'ordine temporale selezionato. La dichiarazione di risposta può essere riassunta come segue:

    {
  "propertyValues": [
    {
      "entityPropertyReference": {
        "entityId": "MyEntity",
        "componentName": "TelemetryData",
        "propertyName": "Temperature"
      },
      "values": [
        {
          "time": "2022-08-25T00:00:00Z",
          "value": {
            "doubleValue": 588.168
          }
        },
        {
          "time": "2022-08-25T00:00:01Z",
          "value": {
            "doubleValue": 592.4224
          }
        },
        {
          "time": "2022-08-25T00:00:02Z",
          "value": {
            "doubleValue": 594.9383
          }
        }
      ]
    }
  ],
  "nextToken": "..."
}

  4. Aggiorna il tipo di componente in modo che abbia due proprietà

    Il seguente modello JSON mostra un tipo di componente valido con due proprietà:

    {
    "componentTypeId": "com.example.timestream-telemetry",
    "workspaceId": "MyWorkspace",
    "functions": {
        "dataReader": {
            "implementedBy": {
                "lambda": {
                    "arn": "lambdaArn"
                }
            }
        }
    },
    "propertyDefinitions": {
        "telemetryType": {
            "dataType": { "type": "STRING" },
            "isExternalId": false,
            "isStoredExternally": false,
            "isTimeSeries": false,
            "isRequiredInEntity": true
        },
        "telemetryId": {
            "dataType": { "type": "STRING" },
            "isExternalId": true,
            "isStoredExternally": false,
            "isTimeSeries": false,
            "isRequiredInEntity": true
        },
        "Temperature": {
            "dataType": { "type": "DOUBLE" },
            "isExternalId": false,
            "isTimeSeries": true,
            "isStoredExternally": true,
            "isRequiredInEntity": false
        },
        "RPM": {
            "dataType": { "type": "DOUBLE" },
            "isExternalId": false,
            "isTimeSeries": true,
            "isStoredExternally": true,
            "isRequiredInEntity": false
        }
    }
}

  5. Aggiorna il connettore Lambda per gestire la seconda proprietà

    L'API del piano AWS IoT TwinMaker dati supporta l'interrogazione di più proprietà in un'unica richiesta e AWS IoT TwinMaker segue una singola richiesta a un connettore fornendo un elenco di. selectedProperties

    La seguente richiesta JSON mostra un modello modificato che ora supporta una richiesta per due proprietà.

    {
  "workspaceId": "MyWorkspace",
  "entityId": "MyEntity",
  "componentName": "TelemetryData",
  "selectedProperties": ["Temperature", "RPM"],
  "startTime": "2022-08-25T00:00:00Z",
  "endTime": "2022-08-25T00:00:05Z",
  "maxResults": 3,
  "orderByTime": "ASCENDING",
  "properties": {
      "telemetryType": {
          "definition": {
              "dataType": { "type": "STRING" },
              "isExternalId": false,
              "isFinal": false,
              "isImported": false,
              "isInherited": false,
              "isRequiredInEntity": false,
              "isStoredExternally": false,
              "isTimeSeries": false
          },
          "value": {
              "stringValue": "Mixer"
          }
      },
      "telemetryId": {
          "definition": {
              "dataType": { "type": "STRING" },
              "isExternalId": true,
              "isFinal": true,
              "isImported": false,
              "isInherited": false,
              "isRequiredInEntity": true,
              "isStoredExternally": false,
              "isTimeSeries": false
          },
          "value": {
              "stringValue": "item_A001"
          }
      },
      "Temperature": {
          "definition": {
              "dataType": { "type": "DOUBLE" },
              "isExternalId": false,
              "isFinal": false,
              "isImported": true,
              "isInherited": false,
              "isRequiredInEntity": false,
              "isStoredExternally": false,
              "isTimeSeries": true
          }
      },
      "RPM": {
          "definition": {
              "dataType": { "type": "DOUBLE" },
              "isExternalId": false,
              "isFinal": false,
              "isImported": true,
              "isInherited": false,
              "isRequiredInEntity": false,
              "isStoredExternally": false,
              "isTimeSeries": true
          }
      }
  }
}

    Analogamente, viene aggiornata anche la risposta corrispondente, come mostrato nell'esempio seguente:

    {
  "propertyValues": [
    {
      "entityPropertyReference": {
        "entityId": "MyEntity",
        "componentName": "TelemetryData",
        "propertyName": "Temperature"
      },
      "values": [
        {
          "time": "2022-08-25T00:00:00Z",
          "value": {
            "doubleValue": 588.168
          }
        },
        {
          "time": "2022-08-25T00:00:01Z",
          "value": {
            "doubleValue": 592.4224
          }
        },
        {
          "time": "2022-08-25T00:00:02Z",
          "value": {
            "doubleValue": 594.9383
          }
        }
      ]
    },
    {
      "entityPropertyReference": {
        "entityId": "MyEntity",
        "componentName": "TelemetryData",
        "propertyName": "RPM"
      },
      "values": [
        {
          "time": "2022-08-25T00:00:00Z",
          "value": {
            "doubleValue": 59
          }
        },
        {
          "time": "2022-08-25T00:00:01Z",
          "value": {
            "doubleValue": 60
          }
        },
        {
          "time": "2022-08-25T00:00:02Z",
          "value": {
            "doubleValue": 60
          }
        }
      ]
    }
  ],
  "nextToken": "..."
}
    Nota

    In termini di impaginazione, in questo caso, la dimensione della pagina nella richiesta si applica a tutte le proprietà. Ciò significa che con cinque proprietà nella query e una dimensione della pagina di 100, se ci sono abbastanza punti dati nell'origine, dovresti aspettarti di vedere 100 punti dati per proprietà, con 500 punti dati in totale.

    Per un esempio di implementazione, vedi Esempio di connettore Snowflake su. GitHub

Miglioramento del connettore dati

Gestione delle eccezioni

È sicuro che il connettore Lambda generi eccezioni. Nella chiamata API del piano dati, il AWS IoT TwinMaker servizio attende che la funzione Lambda restituisca una risposta. Se l'implementazione del connettore genera un'eccezione, AWS IoT TwinMaker traduce il tipo di eccezione in «Sì»ConnectorFailure, informando il client API che si è verificato un problema all'interno del connettore.

Gestione dell'impaginazione

Nell'esempio, Timestream fornisce una funzione di utilità che può aiutare a supportare l'impaginazione in modo nativo. Tuttavia, per alcune altre interfacce di interrogazione, come SQL, potrebbe essere necessario un ulteriore sforzo per implementare un algoritmo di impaginazione efficiente. C'è un esempio di connettore Snowflake che gestisce l'impaginazione in un'interfaccia SQL.

Quando il nuovo token viene restituito AWS IoT TwinMaker tramite l'interfaccia di risposta del connettore, il token viene crittografato prima di essere restituito al client API. Quando il token è incluso in un'altra richiesta, lo AWS IoT TwinMaker decrittografa prima di inoltrarlo al connettore Lambda. Ti consigliamo di evitare di aggiungere informazioni sensibili al token.

Test del connettore

Sebbene sia ancora possibile aggiornare l'implementazione dopo aver collegato il connettore al tipo di componente, consigliamo vivamente di verificare il connettore Lambda prima dell'integrazione con. AWS IoT TwinMaker

Esistono diversi modi per testare il connettore Lambda: puoi testare il connettore Lambda nella console Lambda o localmente nel. AWS CDK

Per ulteriori informazioni sul test delle funzioni Lambda, consulta Testare le funzioni Lambda e Testare localmente le applicazioni. AWS CDK

Sicurezza

Per la documentazione sulle best practice di sicurezza con Timestream, consulta Security in Timestream.

Per un esempio di prevenzione delle iniezioni SQL, vedete il seguente script Python in Samples Repository. AWS IoT TwinMaker GitHub

Creazione in corso AWS IoT TwinMaker risorse

Dopo aver implementato la funzione Lambda, puoi creare AWS IoT TwinMaker risorse come tipi di componenti, entità e componenti tramite la AWS IoT TwinMaker console o l'API.

Nota

Se segui le istruzioni di configurazione nell' GitHub esempio, tutte le AWS IoT TwinMaker risorse sono disponibili automaticamente. È possibile controllare le definizioni dei tipi di componente nell'AWS IoT TwinMaker GitHub esempio. Una volta che il tipo di componente viene utilizzato da qualsiasi componente, le definizioni delle proprietà e le funzioni del tipo di componente non possono essere aggiornate.

Test di integrazione

Consigliamo di eseguire un test integrato AWS IoT TwinMaker per verificare che la query sul piano dati funzioni dall'inizio alla fine. Puoi eseguirlo tramite GetPropertyValueHistory API o facilmente nella AWS IoT TwinMaker console.

Una pagina della console di informazioni sui TwinMaker componenti mostra il nome, il tipo, lo stato e così via del componente.

Nella AWS IoT TwinMaker console, vai ai dettagli del componente e poi sotto Test, vedrai che tutte le proprietà del componente sono elencate lì. L'area Test della console consente di testare le proprietà delle serie temporali e le proprietà non relative alle serie temporali. Per le proprietà delle serie temporali puoi anche utilizzare l' GetPropertyValueHistoryAPI e per le proprietà non relative alle serie temporali utilizzare l'API. GetPropertyValue Se il connettore Lambda supporta l'interrogazione di più proprietà, puoi scegliere più di una proprietà.

Una parte della pagina della console informativa sui TwinMaker componenti che mostra il test di un componente.

Cosa c'è dopo

Ora puoi configurare una dashboard AWS IoT TwinMaker Grafana per visualizzare le metriche. Puoi anche esplorare altri esempi di connettori dati nel GitHub repository degli AWS IoT TwinMaker esempi per vedere se si adattano al tuo caso d'uso.