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.

Aufgaben

Um die folgenden Schritte auszuführen, können Sie eine vorhandene IoT-Domain und eine IoT-Domaingruppe verwenden oder eine IoT-Domaingruppe und eine IoT-Domain erstellen und dann die folgenden Schritte ausführen.

  1. Erstellen einer digitalen Zwillingsinstanz
  2. Befehl in einer JSON-Datei definieren
  3. Raw-JSON-Befehl aufrufen
  4. MQTTX-Verbindung mit einem digitalen Zwilling über eine externe ID
  5. Ein Thema abonnieren, um Befehle zu erhalten
  6. Übermittlungsstatus des Befehls in APEX überwachen
  7. Anzeigen der Antwort eines Befehls in MQTTX

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 digitale Zwillingsinstanz ein Secret zu 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 mit den Parametern für den Anzeigenamen und die Authentifizierungs-ID:

    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 den folgenden externen Schlüsselwert in Schritt 3: MQTTX zur Verbindung mit einer externen ID verwenden:

    "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: Definieren des Befehls in einer JSON-Datei

Sie können den Befehl in einer JSON-Datei definieren und diese Datei im nächsten Schritt verwenden.

Die Datei command.json in diesem Beispiel enthält die folgenden Befehle, 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.
  • requestDuration: Die zulässige oder angeforderte Dauer für den Abschluss der Anforderung im ISO 8601-Dauerformat. PT3M, was 3 Minuten entspricht.
  • 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 3: 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.

Ersetzen Sie <digital-twin-instance-OCID> durch die OCID der digitalen Zwillingsinstanz aus Schritt 1: Digitale Zwillingsinstanz erstellen. In diesem Beispiel wird eine Anforderung für einen Temperaturwert vom Gerät mit dem JSON-Raw-Befehl angezeigt, der in der Datei command.json definiert ist, die in Schritt 2: Befehl in einer JSON-Datei definieren definiert ist.

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 4: MQTTX verwenden, um über eine externe ID eine Verbindung zum Gerät herzustellen

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, um eine neue Verbindung zu erstellen.
  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.
  5. Geben Sie den Host ein. Wählen Sie das Protokoll mqtts:// aus der Host-Dropdown-Liste, und geben Sie den Gerätehost <domain-short-id>.device.iot.<region>.oci.oraclecloud.com aus der Domain IoT ein.
  6. Geben Sie den Port ein. Beispiel: 8883
  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 eine Verbindung mit einem clean session herstellen, und setzen Sie die Option Last-Will-Retain auf false, damit Clientabonnements beibehalten werden können, wenn das Gerät kurz getrennt wird.
  11. Setzen Sie Last Will QoS auf 1.
  12. Wählen Sie Verbinden aus.

Diese Abbildung zeigt die 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.

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.

Schritt 5: Ein Thema abonnieren, um Antworten in MQTTX zu erhalten

Wenn das externe System oder Gerät IoT eine Nachricht im abonnierten Thema veröffentlicht, werden die eingehenden Nachrichten in MQTTX unter diesem Thema angezeigt. Wenn Sie auf eine Antwort von einem vorherigen Befehl warten, stellen Sie sicher, dass Sie das richtige Antwortthema abonniert haben, das in der Antwort der digitalen Zwillingsinstanz dynamisch als Wert <external-id> festgelegt ist.

  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: oracle-test-user-42
  • Benutzername: Externe ID.
  • Passwort: Geben Sie das Passwort des Geräts ein.
  • Geben Sie mqtts:// mit Gerätehost und Portnummer ein:

    mqtts://<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 6: Ü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.

Schritt 7: Anzeigen der Antwort des Befehls in MQTTX

Wählen Sie in MQTTX die Option "Verbinden", um die Antwort anzuzeigen:
{
    "test": 1
  }

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

Zeigen Sie in MQTTX die Befehlsantwortdaten an.