Documentazione dell'infrastruttura Oracle Cloud

Avvio rapido: creazione di un gemello digitale e invio dei dati

Questo scenario mostra come creare un'istanza digital twin e come eseguire il test della configurazione inviando dati di esempio utilizzando l'autenticazione di base.

Requisiti indispensabili

Un amministratore deve creare criteri affinché l'utente possa accedere alle risorse OCI con cui si desidera lavorare. Per impostare questo scenario sono necessari i criteri riportati di seguito. Per ulteriori informazioni sui criteri aggiuntivi correlati ad altri scenari IoT, vedere Prerequisiti.
Criteri IoT
Utilizzare questo criterio della famiglia IoT per consentire al gruppo di utenti specificato di gestire qualsiasi risorsa IoT in un compartimento specifico oppure l'amministratore può utilizzare i criteri IoT per impostare criteri specifici per risorse IoT specifiche:
Allow group <group-name> to manage iot-family in compartment <your-compartment-name>
Criteri segreti vault

Quando si utilizza il comando per il passo 3: creare un'istanza digital twin se si utilizza l'autenticazione di base, sarà necessario creare un segreto per eseguire questa operazione in base al criterio seguente.

Lasciare che qualsiasi utente IoT legga i segreti in un compartimento e vault specifici per un dominio IoT:
Allow any-user to {SECRET_BUNDLE_READ, SECRET_READ} in compartment <compartment-name> where ALL {request.principal.type = 'iotdomain', target.vault.id = '<vault-OCID>'}

Passo 1: creare un gruppo di domini IoT

Se si dispone di un gruppo di domini IoT o di un dominio IoT esistente con cui si desidera lavorare, saltare questo passo e utilizzare tali OCID per creare l'istanza digital twin associata. In alternativa, effettuare le operazioni riportate di seguito per creare un gruppo di domini IoT e un dominio IoT. Per un elenco completo delle opzioni, vedere Creazione di un gruppo di domini IoT.

    1. Nella pagina di elenco Gruppi di domini IoT, selezionare Crea gruppo di domini. Per assistenza nella ricerca della pagina di elenco, vedere Elenco dei gruppi di domini IoT.
    2. Nella pagina Crea gruppo di domini, immettere un nome riconoscibile dall'utente per il nuovo gruppo di domini e una descrizione facoltativa. Evitare di fornire informazioni riservate.
    3. Selezionare un compartimento in cui si desidera memorizzare il nuovo gruppo di domini. Il gruppo di domini IoT e il dominio IoT possono trovarsi in compartimenti diversi. Tutte le risorse IoT devono trovarsi nella stessa area.
    4. Selezionare un tipo di gruppo di domini. Sviluppatore è il tipo predefinito. Non è possibile modificare il tipo di gruppo di domini, ma creare un nuovo gruppo di domini.
      • Sviluppatore: utilizza per lo sviluppo e il test, riduce i costi e utilizza meno risorse.
      • Standard: per i gruppi di domini di produzione, disattivare l'opzione sviluppatore per ridimensionare le risorse e abilitare l'alta disponibilità con failover automatico.
      Nota

      Non è possibile modificare il tipo di gruppo di domini, ma creare un nuovo gruppo di domini.
    5. Selezionare Crea.
  • Utilizzare il comando oci iot domain-group create e il parametro --compartment-id richiesto per creare un gruppo di domini IoT in un compartimento specifico. Sostituire il valore <compartment-OCID> con l'OCID del compartimento:
    oci iot domain-group create --compartment-id <compartment-OCID>

    Opzione Tipo:
    • Se non si specifica un --type, il tipo di gruppo di domini predefinito è lightweight, per lo sviluppo e il test di un gruppo di domini leggero che costa meno e utilizza meno risorse. Quando si desidera creare un gruppo di domini di produzione, utilizzare l'opzione standard.
    • Per un gruppo di domini di produzione, utilizzare il parametro --type con il valore standard per creare un gruppo di domini standard con scalabilità High Availability e failover automatico.

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

  • Eseguire l'operazione CreateIotDomainGroup per creare un gruppo di domini IoT in un compartimento.

Passo 2: creare un dominio IoT

    1. Nella pagina elenco IoT Dominio selezionare un compartimento in cui si desidera memorizzare i domini IoT. Il gruppo di domini IoT e il dominio IoT possono trovarsi in compartimenti diversi. Le tue IoT risorse digital twin possono trovarsi in compartimenti diversi e devono trovarsi nella stessa area. Se è necessaria assistenza per trovare la pagina di elenco dei domini IoT, vedere Elenco dei domini IoT.
    2. Selezionare Crea dominio.
    3. Immettere un nome riconoscibile dall'utente per il dominio IoT. Evitare di fornire informazioni riservate.
    4. Immettere una descrizione (facoltativo).
    5. Selezionare il compartimento del gruppo di domini associato e selezionare il gruppo di domini che si desidera associare a questo dominio.
    6. Selezionare Crea.
    7. Visualizzare e copiare gli endpoint per l'host dispositivo del dominio IoT, l'host dispositivo visualizza l'ID breve del dominio. Selezionare Copia per copiare questo endpoint da utilizzare nel passo successivo.

      device-host:<domain-short-id>.device.iot.<region>.oci.oraclecloud.com

      Per un elenco completo delle opzioni, vedere Creazione di un dominio IoT.

    1. Utilizzare il comando oci iot domain create e i parametri richiesti per creare un dominio IoT.
    2. Sostituire <iot-domain-group-OCID> con il gruppo di domini IoT che si desidera associare al dominio IoT. Sostituire il file <compartment-OCID> con l'OCID del compartimento per il dominio IoT: 
      oci iot domain create --compartment-id <compartment-OCID> --iot-domain-group-id <iot-domain-group-OCID>
      Per un elenco completo dei parametri e dei valori per i comandi CLI, vedere CLI Command Reference.
  • Eseguire l'operazione CreateIotDomain per creare un dominio IoT.

Passo 3: creare un'istanza Digital Twin

In questo esempio, l'istanza digital twin non è associata a un modello digital twin o a un adattatore digital twin. È possibile utilizzare questo metodo se si sta solo testando l'impostazione dei gemelli digitali o se si sta impostando un'istanza digital twin per la connessione a un dispositivo che invia dati non strutturati. Per un elenco completo delle opzioni, vedere Creazione di un'istanza Digital Twin.

  • Opzioni chiave esterna: la chiave esterna è il nome utente del dispositivo quando ci si connette a un dispositivo per inviare dati nel passo 5. Se non si include un parametro --external-key, la chiave esterna viene generata nella risposta. Se si specifica la chiave esterna, si consiglia di non utilizzare le virgolette con il valore della chiave esterna.
  • Opzioni di autenticazione: quando si crea un'istanza digital twin, l'autenticazione è facoltativa e necessaria solo se si inviano dati a o da un dispositivo. Aggiungere l'autenticazione all'istanza digital twin utilizzando il parametro --auth-id.
Nell'esempio seguente viene utilizzato un comando secret per l'autenticazione. È possibile utilizzare un segreto per un ambiente di test. Per un ambiente di produzione sicuro, l'istanza digital twin deve utilizzare un certificato mTLS per l'autenticazione.
    1. Nella pagina elenco Domini IoT selezionare il dominio IoT da utilizzare. Se è necessaria assistenza per trovare la pagina dell'elenco dei domini IoT, vedere Elenca domini IoT.
    2. Selezionare la scheda Istanze gemelle digitali, quindi selezionare Crea.
    3. Immettere un nome e, facoltativamente, una Descrizione. Evitare di fornire informazioni riservate.
    4. Facoltativa. Immettere una chiave esterna che sia un identificativo univoco. Se non si specifica una chiave esterna, questa viene generata quando si salva questa istanza del gemello digitale. Utilizzare la chiave esterna come nome utente del dispositivo quando ci si connette o si inviano dati al dispositivo.
    5. Selezionare il tipo:
      • Connesso direttamente: connette un dispositivo o un'entità direttamente al dominio IoT. Se il dispositivo o l'entità invia dati strutturati, selezionare un adattatore. La selezione di un adattatore associa questa istanza digital twin a un livello di trasformazione che converte i payload dei dispositivi in entrata nella struttura DTDL del modello digital twin associato prevista dall'istanza.
      • Non connesso: utilizzare questa opzione per creare un'istanza gemella digitale di sola simulazione senza l'inclusione dei dati. Un modello gemello digitale è obbligatorio e non deve contenere telemetria o proprietà. Dopo aver creato questa istanza di digital twin, è possibile aggiungere relazioni digital twin per simulare l'ambiente IoT senza la complessità dell'inclusione o dell'autenticazione dei dati.
      • ID autenticazione: se il dispositivo o l'entità invia o riceve dati, è necessario specificare un ID autenticazione. Per i test, creare un ID di autenticazione segreto vault e per la produzione creare un certificato mTLS per l'ID di autenticazione dell'istanza del gemello digitale.
        • Seleziona ID autenticazione: selezionare l'opzione Segreto o Certificato. Per un segreto, selezionare il compartimento del vault, il vault e il segreto. Per un certificato, selezionare il compartimento del certificato, quindi selezionare il certificato.
        • Incolla OCID autenticazione: incollare l'OCID del certificato o del segreto.
      • 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.
    6. Selezionare Crea.
    1. Utilizzare il comando oci iot digital-twin-instance create e questi parametri per creare un'istanza digital twin.
    2. Sostituire <iot-domain-OCID> con il dominio IoT che si desidera associare a questa istanza digital twin IoT. Sostituire <secret-or-certificate-OCID> con l'OCID segreto del vault:
      oci iot digital-twin-instance create --auth-id <secret-OCID> --iot-domain-id <iot-domain-OCID>
    Per un elenco completo dei parametri e dei valori, consultare i riferimenti al comando CLI IoT e CLI Command Reference.
  • Eseguire l'operazione CreateDigitalTwinInstance per creare un'istanza gemella digitale.

Passo 4: ottenere i dettagli del dominio IoT

Se si dispone dell'endpoint host dispositivo per il dominio IoT che si desidera utilizzare, saltare questo passaggio.

I dettagli del dominio IoT contengono l'host del dispositivo, incluso l'ID breve del dominio, per ulteriori informazioni su come ottenere i dettagli di un dominio IoT,

    1. Nella pagina elenco IoT Domini, selezionare il dominio da utilizzare. Se è necessaria assistenza per trovare la pagina di elenco dei domini IoT o i domini IoT, vedere Elenco dei domini IoT.
    2. Dettagli: consente di visualizzare o modificare il nome del dominio e la descrizione, copiare l'endpoint OCID, l'host del dispositivo, visualizzare il compartimento e l'indicatore orario della creazione del dominio.
      host-dispositivo: <domain-short-id>.device.iot.<region>.oci.oraclecloud.com
    3. Accedere alle varie risorse e task associati al dominio selezionando i collegamenti o le schede. Per una descrizione delle impostazioni del dominio, vedere Creazione di un dominio IoT

  • Utilizzare il comando oci iot domain get e il parametro richiesto per ottenere i dettagli di un dominio IoT, incluso l'host del dispositivo con l'ID breve del dominio:

    oci iot domain get --iot-domain-id <iot-domain-OCID>

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

  • Eseguire l'operazione GetIotDomain per ottenere i dettagli di un dominio.

Passo 5: inviare i dati

Inviare dati di esempio all'istanza digital twin creata nel Passo 3 precedente: creazione di un'istanza Digital Twin.
  • Nome utente dispositivo: utilizzare external key dell'istanza gemella digitale come nome utente del dispositivo.
  • Password dispositivo: è associata all'ID di autenticazione per l'istanza gemello digitale. Se l'istanza digital twin utilizza un OCID segreto vault per l'autenticazione, utilizzare il contenuto dei segreti in testo semplice come password del dispositivo. Vedere Creazione di un segreto e Ottenimento del contenuto di un segreto. L'uso di un segreto del vault come password è consigliato solo per i test e non per la produzione.
Nell'esempio seguente viene utilizzato un segreto per l'autenticazione. In alternativa, per la produzione l'istanza digital twin deve utilizzare un certificato mTLS per l'autenticazione.

  • Uso di Curl

    Shell in stile POSIX: utilizzare questo comando curl quando si utilizzano bash, zsh, terminale macOS, Linux o Git Bash in Windows. 
    curl 
  -u '<digital-twin-instance-external-key>:<device-password>' \
  -H 'Content-Type: text/plain' \
  -d 'sample data 1' \
  'https://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic'

    Windows Powershell: utilizzare questo comando curl in questo esempio, utilizzare -G per effettuare una richiesta GET e aggiungere all'URL i dati forniti con --data-urlencode come parametri di query. Oppure puoi usare le variabili ambientali. 

    curl.exe -u "<digital-twin-instance-external-key>:<device-password>" `
  -H "Content-Type: text/plain" `
  -d "sample data 1" `
  "https://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic"

    Quando si completa il Passo 3: Creazione di un'istanza Digital Twin, se è stato definito il valore del parametro chiave esterna con virgolette, è necessario includere i preventivi quando si inviano i dati: "external-key". Per informazioni sulle procedure ottimali per la presentazione dei preventivi, vedere Risoluzione dei problemi.

  • Utilizzare qualsiasi client MQTT, questo esempio utilizza MQTTX con le seguenti impostazioni.
    1. Il download e la configurazione di MQTTX seguono queste istruzioni, vedere Guida introduttiva a MQTTX. Apri MQTTX.
    2. Per creare una nuova connessione, selezionare + Nuova connessione.
    3. Immettere il valore <unique-id> della chiave esterna come nome utente. È possibile trovare la chiave esterna nella risposta oci iot digital-twin-instance create, dal precedente Passo 3: creazione di un'istanza Digital Twin:
      "external-key": "<unique-id>"
    4. Immettere la password del dispositivo. Se si esegue il test, utilizzare il segreto del vault, questo deve essere il contenuto del segreto in testo semplice. Oppure, per un ambiente di produzione sicuro, utilizzare un certificato mTLS.
    5. Immettere l'host. Selezionare il protocollo mqtts:// dall'elenco a discesa host e immettere l'host del dispositivo: <domain-short-id>.device.iot.<region>.oci.oraclecloud.com dal dominio IoT.
    6. Immettere la porta, ad esempio: 8883
      Nota

      Al momento, MQTT Secure (MQTTS) è supportato solo utilizzando la porta 8883.
    7. Attivare l'opzione di attivazione/disattivazione SSL/TLS.
    8. Attivare l'opzione SSL Secure.
    9. Per il certificato, selezionare l'opzione Certificato server con firma CA.
    10. Quando si configura la connessione MQTTX, assicurarsi di connettersi utilizzando un clean session e impostare l'opzione Last-Will-Retain su false per consentire la conservazione delle sottoscrizioni client se il dispositivo si disconnette brevemente.
    11. Impostare Ultima esecuzione QoS su 1.
    12. Selezionare Connetti.

    Al termine di questi passi, nella piattaforma IoT è disponibile un'istanza digital twin in grado di ricevere dati da un dispositivo.