Documentazione dell'infrastruttura Oracle Cloud

Creazione di un adattatore Digital Twin

Creare un adattatore digital twin per convertire i payload di dati raw provenienti da e verso un dispositivo fisico o un sistema esterno in dati di telemetria normalizzati basati sul modello digital twin.

I dati vengono passati all'adattatore gemello digitale come oggetto JSON contenente i dati e il mapping.

Concetti

Quando si utilizzano i dati strutturati, è necessario un adattatore digital twin.

Ci sono due modi per utilizzare un adattatore digital twin, a seconda che il dispositivo con cui si sta lavorando possa essere programmato per inviare dati:

  • Formato adattatore predefinito: se il dispositivo può essere programmato per inviare i dati nel formato che si desidera utilizzare, creare un adattatore gemello digitale senza specificare inbound-envelope o inbound-routes. La risposta conterrà i dati nel formato predefinito del dispositivo. Se il mapping dell'envelope viene specificato e contiene un valore timeObserved, receivedTime viene utilizzato come valore timeObserved. Per un esempio specifico, vedere Scenario: invio di dati strutturati in un formato predefinito mediante HTTP.
  • Formato adattatore personalizzato: per i dispositivi che non possono essere programmati per l'invio di dati, è possibile creare un adattatore digital twin personalizzato definendo un inbound-envelope e un envelope-mapping personalizzati che trasformano il payload e i metadati per ottenere l'output che si desidera utilizzare. Per un esempio specifico, vedere Scenario: invio di dati strutturati in un formato personalizzato mediante HTTP.
  • ID autenticazione: quando si crea un adattatore digital twin se si connette un dispositivo, l'istanza digital twin associata deve utilizzare un parametro ID autenticazione, con un certificato o un segreto per autenticare il dispositivo.
  • Chiave esterna: dopo aver creato un adattatore gemello digitale, è possibile aggiornare l'adattatore gemello digitale per modificare la chiave esterna di un dispositivo. Quando si inviano dati, utilizzare la chiave esterna come nome utente per il dispositivo.
  • Limite: il numero massimo di instradamenti in entrata per un adattatore digital twin è 128.
Esempio di input del payload del dispositivo, mapping JSON e risultato trasformato

È possibile provare a eseguire il mapping dell'adattatore in JQ Playground incollando il payload come input della query, aggiungendo il mapping JSON nella sezione JSON, quindi visualizzare il risultato dell'output.

Esempio JSON payload del dispositivo:

{ "time": "<timestamp>", "temp": 65, "hum": 55 }

Utilizzare un'espressione JQ o la notazione JsonPath per creare un output di mapping JSON del payload dell'adattatore.

In questo esempio viene utilizzata un'espressione JQ: 
{ "temperature": ".temp", "humidity": ".hum", "timeObserved": ".time" }
In questo esempio viene utilizzata la notazione JsonPath per creare un output di mapping JSON del payload dell'adattatore:
{ "temperature": "$.temp", "humidity": "$.hum", "timeObserved": "$.time" }
Risultato dell'output trasformato:
{ "temperature": 65, "humidity": 55, "timeObserved": "<timestamp>" }

Per ulteriori esempi, vedere Riferimento: espressioni JQ per adattatori gemelli digitali e Scenari.

  • Se il dispositivo invia o riceve dati non strutturati, non è necessario specificare un adattatore digital twin.

    1. Nella pagina elenco Domini IoT selezionare il dominio IoT da utilizzare. Per assistenza nella ricerca della pagina di elenco dei domini IoT, vedere Elenco dei domini IoT.
    2. Selezionare la scheda Adattatori gemelli digitali, quindi selezionare Crea.
    3. Immettere un nome e, facoltativamente, una Descrizione. Evitare di fornire informazioni riservate.
    4. Per trovare il modello gemello digitale da associare, effettuare le operazioni riportate di seguito.
      • Seleziona modello: consente di cercare il modello gemello digitale in base al nome.
      • Seleziona con URI specifica modello: consente di cercare il modello gemello digitale utilizzando DTMI. Ad esempio, dtmi:com:example:iot:demo;1
    5. Dipende se il dispositivo con cui si sta lavorando può essere programmato per inviare dati in formati specifici:
      • Se il dispositivo può essere programmato per inviare dati in un formato specifico, non è necessario specificare l'envelope e gli instradamenti dell'adattatore, l'adattatore viene generato dal payload del dispositivo.
      • Se il dispositivo non può essere programmato per inviare i dati nel formato desiderato, specificare un adattatore per convertire il payload in entrata nel formato dati che si desidera utilizzare. Attivare l'opzione Specifica buste e instradamenti in entrata:
        • Carica file .json dell'envelope in entrata: carica un file .json contenente l'envelope in entrata per questo adattatore.
        • Incolla JSON dell'envelope in entrata: aggiunge il formato JSON dell'envelope in entrata a questo adattatore.
    6. Specifica instradamenti in entrata: aggiunge una lista di definizioni di instradamento con condizioni e mapping di payload facoltativi. I cicli vengono valutati in ordine.
      • Carica file .json degli instradamenti in entrata: carica gli instradamenti in entrata in un file .json.
      • Incolla JSON instradamenti in entrata: aggiunge gli instradamenti in entrata in formato JSON.
    7. Tag: (facoltativo) aggiungere una o più tag all'adattatore gemello digitale. Se si dispone delle autorizzazioni per creare una risorsa, si dispone anche delle autorizzazioni per applicare tag in formato libero a tale risorsa. Per applicare una tag definita, è necessario disporre delle autorizzazioni per utilizzare lo spazio di nomi tag. Per ulteriori informazioni sull'applicazione di tag, vedere Tag risorsa. Se non sei sicuro di applicare i tag, salta questa opzione o chiedi a un amministratore. È possibile applicare le tag in un secondo momento.
    8. Selezionare Crea.

  • Utilizzare il comando oci iot digital-twin-adapter create e i parametri necessari per creare un adattatore digital twin.

    Per creare un adattatore digital twin per i dati strutturati in un formato predefinito: se il dispositivo può essere programmato, creare un adattatore digital twin senza specificare inbound-envelope o envelope-mapping, di conseguenza i dati predefiniti provenienti dal dispositivo vengono accettati nella risposta.

    Due opzioni per associare il modello gemello digitale:

    • Utilizzo di DTMI:

      Nell'esempio seguente viene utilizzato il parametro URI DTMI per associare l'adattatore al modello gemello digitale. Sostituire <digital-twin-model-spec-uri> con l'URI DTMI per il modello gemello digitale associato. 
      oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri '<digital-twin-model-spec-uri>'
    • Uso dell'OCID del modello digital twin:
      In alternativa, l'esempio riportato di seguito utilizza il parametro --digital-twin-model-id con <digital-twin-model-OCID> per il modello gemello digitale che si desidera associare a un adattatore gemello digitale.
      oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-id <digital-twin-model-OCID>

    Per creare un adattatore gemello digitale per i dati strutturati in un formato personalizzato:

    Utilizzare il comando oci iot digital-twin-adapter create e il parametro --iot-domain-id richiesto. Per creare un adattatore digital twin personalizzato, definire uno specifico valore inbound-envelope o inbound-route per ottenere l'output che si desidera utilizzare, per definire il mapping del payload personalizzato per il digital twin utilizzando un file <file://inbound-envelope.json> e un file <file://inbound-routes.json> utilizzando le espressioni JQ.

    Sostituire <digital-twin-model-spec-uri> con l'URI DTMI per il modello gemello digitale associato e sostituire <iot-domain-OCID> con l'OCID dominio IoT che si desidera associare a questo adattatore gemello digitale:

    oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri '<digital-twin-model-spec-uri>' --inbound-envelope <file://inbound-envelope.json> --inbound-routes <file://inbound-routes.json>

    Per ulteriori informazioni sui file di riferimento, vedere Uso di un file JSON per l'input complesso.

    Per un elenco completo dei parametri e dei valori per i comandi CLI, vedere CLI Command Reference.

  • Eseguire l'operazione CreateDigitalTwinAdapter per creare un adattatore gemello digitale nel dominio IoT specificato.