Oracle Cloud Infrastructure-Dokumentation

Szenario: Befehle empfangen und Antworten mit MQTTs senden

Verwenden Sie dieses Szenario, um Befehle in der Cloud zu empfangen und Antworten mit dem MQTTs-Protokoll an ein Gerät zu senden, um mit Ihren Internet of Things-(IoT-)Geräten zu interagieren.

Schritt 1: Digitale Zwillingsinstanz erstellen

CLI verwenden

  1. Wenn Sie eine Instanz mit digitalem Zwilling erstellen, verwenden Sie ein Secret oder ein Zertifikat, damit sich die Instanz mit digitalem Zwilling sicher authentifizieren kann. Sie müssen ein Secret erstellen oder ein Zertifikat erstellen, um dieses Szenario abzuschließen. Oracle empfiehlt, für jede Instanz des digitalen Zwillings ein Secret zu verwenden. Für die Produktion sollte die Instanz des digitalen Zwillings ein mTLS-Zertifikat zur Authentifizierung verwenden.

  2. Verwenden Sie den Befehl oci iot digital-twin-instance create und die erforderlichen Parameter, um einen digitalen Zwilling zu erstellen. Das folgende Beispiel zeigt den Befehl, wie Sie den Parameter für die Authentifizierungs-ID mit dem erforderlichen Domainparameter IoT verwenden, um die Domain IoT mit der Instanz des digitalen Zwillings zu verknüpfen:

    oci iot digital-twin-instance create --auth-id <vault-secret-or-client-certificate-id> --iot-domain-id <iot-domain-OCID>

    Beachten Sie in dieser Beispielantwort den externen Schlüsselwert. Verwenden Sie diesen Wert für den externen Schlüssel, und beachten Sie den externen Schlüssel, den Sie im nächsten Schritt verwenden können:

    "external-key": "<unique-id>"
    {
  "data": {
    "auth-id": "<vault-secret-or-certificate-OCID>",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-05T18:03:15.264Z"
      }
    },
    "description": null,
    "digital-twin-adapter-id": null,
    "digital-twin-model-id": null,
    "digital-twin-model-spec-uri": null,
    "display-name": "HVAC-instance",
    "external-key": "<unique-id>",
    "freeform-tags": {},
    "id": "<iot-digital-twin-instance-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-08-05T18:03:15.870000+00:00",
    "time-updated": "2025-08-05T18:03:15.870000+00:00"
  },
  "etag": "<unique-id>"
}

Schritt 2: Richten Sie die MQTT-Session mit Brokerzugangsdaten ein

Verwenden Sie einen beliebigen MQTT-Client. In diesem Beispiel wird MQTTX mit den folgenden Einstellungen verwendet.
  1. Laden Sie MQTTX herunter, und richten Sie es ein. Befolgen Sie diese Anweisungen unter Erste Schritte mit MQTTX. Öffnen Sie MQTTX.
  2. Wählen Sie + Neue Verbindung aus, um eine neue Verbindung zu erstellen. Geben Sie einen Namen für die Verbindung ein. Geben Sie keine vertraulichen Informationen ein.
  3. Geben Sie den Wert Externer Schlüssel <unique-id> als Benutzername ein. Sie finden den externen Schlüssel in der Antwort oci iot digital-twin-instance create aus dem vorherigen Schritt 1: Digitale Zwillingsinstanz erstellen:
    "external-key": "<unique-id>"
  4. Geben Sie das Passwort für das Gerät ein. Wenn Sie Vault Secret verwenden, muss dies das Klartext-Secret sein, oder Sie können ein mTLS-Zertifikat verwenden.
  5. Geben Sie den Host ein. Wählen Sie das Protokoll mqtts:// aus der Dropdown-Liste "Host" aus, und geben Sie den Gerätehost <domain-short-id>.device.iot.<region>.oci.oraclecloud.com aus der Domain IoT ein. Informationen hierzu finden Sie unter Details einer IoT-Domain abrufen.
  6. Geben Sie den Port ein. Beispiel: 8883
    Hinweis

    Derzeit wird MQTT Secure (MQTTS) nur über Port 8883 unterstützt.
  7. Schalten Sie SSL/TLS ein.
  8. Aktivieren Sie SSL Secure umschalten.
  9. Wählen Sie für das Zertifikat die Option CA-signiertes Serverzertifikat.
  10. Wenn Sie die MQTTX-Verbindung konfigurieren, stellen Sie sicher, dass Sie Folgendes verwenden:
    • clean session: Setzen Sie die Option "Clean Session" auf true. Wenn "Clean Session" auf "true" gesetzt ist, speichert der Broker keine Informationen für den Client und verwirft vorherigen Status aus einer persistenten Session. Alle Sitzungsdaten werden gelöscht, sobald die Netzwerkverbindung beendet ist.
    • Setzen Sie die Option Last-Will-Retain auf false, damit Clientabonnements beibehalten werden können, wenn das Gerät kurzzeitig getrennt wird.
  11. Setzen Sie Last Will QoS auf 1. So definieren Sie die Zuverlässigkeit der Zustellung "Mindestens einmal" für Ihre Trennbenachrichtigung.
  12. Wählen Sie Verbinden aus.

Diese Abbildung zeigt diese Einstellungen in MQTTX. Klicken Sie mit der rechten Maustaste, und öffnen Sie sie in einer neuen Registerkarte, um einen größeren Screenshot anzuzeigen.

In MQTTX-Einstellungen zum Aufrufen eines Befehls.

Schritt 3: Thema abonnieren, um Antworten in MQTTX zu erhalten

Wenn ein externes System oder IoT-Gerät eine Nachricht an das abonnierte Thema veröffentlicht, werden in MQTTX die eingehenden Nachrichten unter diesem Thema angezeigt. Wenn Sie auf eine Antwort von einem vorherigen Befehl warten, stellen Sie sicher, dass Sie das richtige Antwortthema abonniert haben.

Definieren Sie die responseEndpoint im nächsten Schritt, wenn Sie den Befehl in einer JSON-Datei definieren. Die Zeichenfolge "responseEndpoint": "/endpoints/4321" stellt das Thema oder den Endpunktpfad dar, in dem das Gerät seine Antwort veröffentlichen soll. Wählen Sie einen logischen Endpunktpfad für Ihre digitalen Zwillingsrouten aus. Sie müssen denselben Pfad sowohl auf der Cloud-Seite (wenn Sie den Befehl senden) als auch auf der Geräteseite (wenn Sie die Antwort veröffentlichen) verwenden.

  1. Wählen Sie in MQTTX + Neues Abonnement aus.
  2. Geben Sie den Endpunkt als Thema ein.
  3. Wählen Sie im Dropdown-Menü QoS die Option 1 Mindestens einmal aus.
  4. Wählen Sie Bestätigen aus.
Verwenden Sie die folgenden Verbindungseinstellungen, um Nachrichten zu empfangen, die an einem Geräteendpunkt für die Instanz des digitalen Zwillings mit einer bestimmten externen ID veröffentlicht wurden:
  • Client-ID: your-client-ID
  • Benutzername: Externe ID.
  • Kennwort: Geben Sie das Gerätekennwort ein.
  • Geben Sie mqtts:// mit dem Gerätehost der IoT-Domain und Portnummer 8883 ein:

    mqtts://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com:8883

Um ein größeres Bildschirmfoto anzuzeigen, klicken Sie mit der rechten Maustaste und öffnen Sie es in einem neuen Tab

.Geben Sie in MQTTX den Endpunkt als Thema ein und bestätigen Sie das Abonnement.

Schritt 4: Definieren des Befehls in einer JSON-Datei

Sie können die Befehlsdetails in einer JSON-Datei definieren und diese Datei im nächsten Schritt Raw-JSON-Befehl auf einem Gerät aufrufen verwenden.

Speichern Sie dieses Snippet in diesem Beispiel in einer command.json-Datei, damit Sie es verwenden können, um den Befehl aufzurufen und die Antwort gemäß den Anweisungen in der Datei zu verarbeiten. 

{
  "requestEndpoint": "/endpoints/1234",
  "requestDuration": "PT3M",
  "requestDataFormat": "JSON",
  "requestData": {
    "temp": 33
  },
  "requestDataContentType": "application/json",
  "responseEndpoint": "/endpoints/4321",
  "responseDuration": "PT3M"
}
  • requestEndpoint: Der URL-Pfad /endpoints/1234, an den die Anforderung gesendet wird. Dies ist in der Regel ein API-Endpunkt oder eine Adresse, bei der die IoT-Plattform auf Befehle horcht.

    Wenn Sie bereits einen Endpunkt haben, der für Antworten dediziert ist. Beispiel: /endpoints/<external-id>/response verwenden diesen Pfad in responseEndpoint.

    Oder erstellen Sie eine neue endpoint/route für die digitale Zwillingsinstanz in den Regeln für das eingehende Routing des Digital Twin Adapters, in dem das Gerät veröffentlichen kann. Referenzieren Sie diesen Pfad in der Datei command.json. Halten Sie den Endpunktpfad konsistent. Der Pfad, den Sie in responseEndpoint definieren, wird zum MQTT-Thema, das der Client in Schritt 3 abonnieren muss, damit die Antwort des Befehls angezeigt wird.

  • requestDuration: Die zulässige oder angeforderte Dauer für den Abschluss der Anforderung im ISO 8601-Dauerformat. Beispiel: PT3M entspricht 3 Minuten.
  • requestDataFormat: Gibt das Datumsformat für die in der JSON-Anforderung gesendeten Daten an.
  • requestData: Die JSON-Payload, die mit einem Schlüssel/Wert-Paar gesendet wird, um einen Temperaturwert auf dem Gerät festzulegen:
    "temp": 33
Informationen, einschließlich Dateispeicherorten und Pfadtypen, finden Sie unter JSON-Datei für komplexe Eingaben verwenden.

Schritt 5: JSON-Raw-Befehl auf einem Gerät aufrufen

Sie können die CLI oder die API verwenden, um einen Befehl auf einem Gerät aufzurufen. Im folgenden Beispiel wird die CLI verwendet.

CLI verwenden

Verwenden Sie den Befehl oci iot digital-twin-instance invoke-raw-json-command und die Parameter, um einen Raw-JSON-Befehl auf einem Gerät aufzurufen. 

oci iot digital-twin-instance invoke-raw-json-command --digital-twin-instance-id <digital-twin-instance-OCID> --request-endpoint "/endpoints/1234" --from-json file://command.json
Weitere Informationen zu anderen Befehlstypen finden Sie unter Senden eines Raw-Befehls von einer digitalen Zwillingsinstanz.

Schritt 6: In MQTTX überprüfen

Beachten Sie in MQTTX die aufgerufenen Daten:
{
    "temp": 33
  }

Um ein größeres Bildschirmfoto anzuzeigen, klicken Sie mit der rechten Maustaste und öffnen Sie es in einem neuen Tab.

Wählen Sie in MQTTX connect.

Diese Abbildung zeigt, wie in MQTTX überprüft wird.

Befehlsantwortszenarios
SzenarioGerätestatusErwarteter BefehlsstatusKommentare
Nicht angemeldetNicht verbunden, nicht abonniert ABGELEHNT Befehlszustellung nicht erfolgreich
Verbunden, aber nicht abonniertVerbunden ABGELEHNTGerät ist online, empfängt jedoch keinen Befehl
Abonniert, aber nicht verbunden Nur abonniertAUSSTEHEND → ABGELAUFENBefehl wartet; läuft nach Timeout ab
Ursprünglich abonniert, aber nicht verbunden und wird vor Timeout verbunden Ursprünglich offline AUSSTEHEND → GESENDETBefehl empfangen
Verbunden und abonniertVerbunden und abonniert SENT Befehl empfangen
One-Way-Befehl (keine Antwort erwartet)Verbunden und abonniert ABGESCHLOSSEN Antwort wird nicht erwartet und verfolgt
Zwei-Wege-Befehl (keine Antwort empfangen)Verbunden und abonniert NOT_RESPONDEDGerät reagiert nicht innerhalb des Antwortdauer-Timeouts
Zwei-Wege-Befehl (Antwort empfangen) Verbunden und abonniert ABGESCHLOSSENGerät sendet Daten innerhalb der Antwortzeitüberschreitung und schließt den Ablauf ab

Schritt 7: Übermittlungsstatus des Befehls in APEX überwachen

Um Ihre IoT-Daten in APEX anzuzeigen, muss der Zugriff auf Ihre Daten konfiguriert werden. Nachdem diese Konfiguration abgeschlossen ist, können Sie APEX verwenden, um mit Ihren IoT-Daten zu arbeiten.

  1. Melden Sie sich in APEX beim Workspace der bestimmten IoT-Domain an. Verwenden Sie dazu den folgenden Workspace-Namen und den Datenbankbenutzernamen. Beachten Sie die beiden Unterstriche im Namen des Datenbankschemas:
    <domain-short-id-from-device-host>__IOT
    Gehen Sie zu SQL Workshop, und wählen Sie SQL Commands aus, um die IoT-Daten abzufragen.
  2. Geben Sie den folgenden Befehl ein, ersetzen Sie <digital-twin-instance-OCID> durch die OCID des digitalen Zwillings, und wählen Sie Ausführen aus, um die Raw-Befehlsdaten abzufragen: 
    select * from raw_command_data
where digital_twin_instance_id='<digital-twin-instance-OCID>'
  3. Zeigen Sie unter Ergebnisse die RESPONSE_DATA an:
    {"test":1}
Um ein größeres Bildschirmfoto anzuzeigen, klicken Sie mit der rechten Maustaste und öffnen Sie es in einem neuen Tab.Zeigen Sie die Antwortdaten des Geräts in APEX an.