Arbeiten mit binären Nutzlasten - AWS IoT Core
Beispiele für binäre NutzlastenPayloads von protobuf-Nachrichten entschlüsseln

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Arbeiten mit binären Nutzlasten

Um Ihre Nachrichtennutzdaten als rohe Binärdaten (und nicht als JSON Objekt) zu behandeln, können Sie den Operator * verwenden, um in einer SELECT Klausel darauf zu verweisen.

Beispiele für binäre Nutzlasten

Wenn Sie * verwenden, um die Nachrichtennutzlast als unformatierte Binärdaten zu bezeichnen, können Sie der Regel Daten hinzufügen. Wenn Sie eine leere oder eine JSON Payload haben, können der resultierenden Payload mithilfe der Regel Daten hinzugefügt werden. Es folgen Beispiele unterstützter SELECT-Klauseln.

  • Sie können die folgenden SELECT-Klauseln nur mit einem Sternchen (*) für binäre Payloads verwenden.

    • SELECT * FROM 'topic/subtopic'
    • SELECT * FROM 'topic/subtopic' WHERE timestamp() % 12 = 0

  • Sie können auch Daten hinzufügen und die folgenden SELECT-Klauseln verwenden.

    • SELECT *, principal() as principal, timestamp() as time FROM 'topic/subtopic'
    • SELECT encode(*, 'base64') AS data, timestamp() AS ts FROM 'topic/subtopic'

  • Sie können diese SELECT-Klauseln auch mit binären Payloads verwenden.

    • In der Klausel wird device_type auf Folgendes WHERE verwiesen.

      SELECT * FROM 'topic/subtopic' WHERE device_type = 'thermostat'

    • Folgendes wird ebenfalls unterstützt.

      {
	"sql": "SELECT * FROM 'topic/subtopic'",
	"actions": [
		{
			"republish": {
				"topic": "device/${device_id}"
			}
		}
	]
}

Die folgenden Regelaktionen unterstützen keine binären Payloads, sodass Sie sie dekodieren müssen.

  • Für Regelaktionen, die die Eingabe binärer Nutzlast nicht unterstützen, wie z. B. die -Maßnahme, müssen Sie binäre Nutzlasten dekodieren. Die Lambda-Regelaktion kann Binärdaten empfangen, wenn sie base64-codiert sind und sich in einer Nutzlast befinden. JSON Dazu müssen Sie die Regel folgendermaßen ändern:

    SELECT encode(*, 'base64') AS data FROM 'my_topic'

  • Die SQL Anweisung unterstützt keine Zeichenfolge als Eingabe. Um eine Zeichenketteneingabe in zu konvertierenJSON, können Sie den folgenden Befehl ausführen.

    SELECT decode(encode(*, 'base64'), 'base64') AS payload FROM 'topic'

Payloads von protobuf-Nachrichten entschlüsseln

Protocol Buffers (protobuf) ist ein Open-Source-Datenformat, das zur Serialisierung strukturierter Daten in kompakter, binärer Form verwendet wird. Es wird verwendet, um Daten über Netzwerke zu übertragen oder in Dateien zu speichern. Mit Protobuf können Sie Daten in kleinen Paketgrößen und mit einer schnelleren Geschwindigkeit als mit anderen Nachrichtenformaten senden. AWS IoT Core Regeln unterstützen Protobuf, indem sie die SQL Funktion decode (value,decodingScheme) bereitstellen, mit der Sie Protobuf-kodierte Nachrichtennutzdaten dekodieren können, um sie zu formatieren und an nachgeschaltete Dienste weiterzuleiten. JSON In diesem Abschnitt wird der Prozess zur Konfiguration der Protobuf-Decodierung in Regeln beschrieben. step-by-step AWS IoT Core

Voraussetzungen

Deskriptordateien erstellen

Wenn Sie bereits über die Deskriptordateien verfügen, können Sie diesen Schritt überspringen. Eine Deskriptordatei (.desc) ist eine kompilierte Version einer .proto-Datei, bei der es sich um eine Textdatei handelt, die die Datenstrukturen und Nachrichtentypen definiert, die bei einer protobuf-Serialisierung verwendet werden sollen. Um eine Deskriptordatei zu generieren, müssen Sie eine .proto-Datei definieren und sie mit dem protoc-Compiler kompilieren.

  1. Erstellen Sie .proto-Dateien, die die Nachrichtentypen definieren. Ein Beispiel .proto könnte folgendermaßen aussehen:

    syntax = "proto3";

message Person {
  optional string name = 1;
  optional int32 id = 2;
  optional string email = 3;
}

    In dieser .proto-Beispieldatei verwenden Sie die Proto3-Syntax und definieren den Nachrichtentyp Person. Die Person-Nachrichtendefinition spezifiziert drei Felder (Name, ID und E-Mail). Weitere Informationen zu .proto-Dateiformaten im Language Guide (proto3).

  2. Verwenden Sie den Protoc-Compiler, um die .proto Dateien zu kompilieren und eine Deskriptordatei zu generieren. Ein Beispielbefehl zum Erstellen einer Deskriptordatei (.desc) kann der folgende sein:

    protoc --descriptor_set_out=<FILENAME>.desc \
    --proto_path=<PATH_TO_IMPORTS_DIRECTORY> \
    --include_imports \
    <PROTO_FILENAME>.proto

    Dieser Beispielbefehl generiert eine Deskriptordatei<FILENAME>.desc, mit der AWS IoT Core Rules Protobuf-Payloads dekodieren kann, die der in definierten Datenstruktur entsprechen. <PROTO_FILENAME>.proto

    • --descriptor_set_out

      Gibt den Namen der Deskriptordatei (<FILENAME>.desc) an, die generiert werden soll.

    • --proto_path

      Gibt die Speicherorte aller importierten .proto-Dateien an, auf die in der kompilierten Datei verwiesen wird. Sie können das Kennzeichen mehrfach angeben, wenn Sie mehrere importierte .proto-Dateien mit unterschiedlichen Speicherorten haben.

    • --include_imports

      Gibt an, dass alle importierten .proto-Dateien ebenfalls kompiliert und in die <FILENAME>.desc-Deskriptordatei aufgenommen werden sollen.

    • <PROTO_FILENAME>.proto

      Gibt den Namen der .proto-Datei an, die Sie kompilieren möchten.

    Weitere Informationen zur Protokollreferenz finden Sie unter Referenz. API

So laden Sie die Dateien zu einem S3-Bucket hoch

Nachdem Sie Ihre Deskriptordateien erstellt haben<FILENAME>.desc, laden Sie die Deskriptordateien <FILENAME>.desc mithilfe von, oder in einen Amazon S3 S3-Bucket hoch. AWS API AWS SDK AWS Management Console

Wichtige Überlegungen

  • Stellen Sie sicher, dass Sie die Deskriptordateien in einen Amazon S3 S3-Bucket AWS-Konto in derselben Umgebung hochladen AWS-Region , in der Sie Ihre Regeln konfigurieren möchten.

  • Stellen Sie sicher, dass Sie AWS IoT Core Zugriff auf das Lesen FileDescriptorSet von S3 gewähren. Wenn in Ihrem S3-Bucket die serverseitige Verschlüsselung (SSE) deaktiviert ist oder wenn Ihr S3-Bucket mit von Amazon S3 verwalteten Schlüsseln (SSE-S3) verschlüsselt ist, sind keine zusätzlichen Richtlinienkonfigurationen erforderlich. Dies kann mit der Beispiel-Bucket-Richtlinie erreicht werden:

    {
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "Statement1",
			"Effect": "Allow",
			"Principal": {
				"Service": "iot.amazonaws.com"
			},
			"Action": "s3:Get*",
                      "Resource": "arn:aws:s3:::<BUCKET NAME>/<FILENAME>.desc"
		}
	]
}

  • Wenn Ihr S3-Bucket mit einem AWS Key Management Service Schlüssel (SSE-KMS) verschlüsselt ist, stellen Sie sicher, dass Sie beim Zugriff auf Ihren S3-Bucket die AWS IoT Core Erlaubnis zur Verwendung des Schlüssels erteilen. Dazu müssen Sie diese Erklärung zu Ihrer Schlüsselrichtlinie hinzufügen:

    {
	"Sid": "Statement1",
	"Effect": "Allow",
	"Principal": {
		"Service": "iot.amazonaws.com"
	},
	"Action": [
		"kms:Decrypt",
		"kms:GenerateDataKey*",
		"kms:DescribeKey"
	],
        "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
	
}

Konfigurieren Sie die protobuf-Dekodierung in Regeln.

Nachdem Sie die Deskriptordateien in Ihren Amazon S3 S3-Bucket hochgeladen haben, konfigurieren Sie eine Regel, die Ihr Protobuf-Nachrichtennutzdatenformat mithilfe der Funktion decode (value,) dekodieren kann. decodingScheme SQL Eine ausführliche Funktionssignatur und ein Beispiel finden Sie in der Funktion decode (value,) der Referenz. decodingScheme SQL AWS IoT SQL

Im Folgenden finden Sie einen SQL Beispielausdruck, der die Funktion decode (value,decodingScheme) verwendet:

SELECT VALUE decode(*, 'proto', '<BUCKET NAME>', '<FILENAME>.desc', '<PROTO_FILENAME>', '<PROTO_MESSAGE_TYPE>') FROM '<MY_TOPIC>'

In diesem Beispielausdruck:

  • Sie verwenden die SQL Funktion decode (value,decodingScheme), um die Nutzdaten der binären Nachricht zu dekodieren, auf die von verwiesen wird. * Dabei kann es sich um eine binäre Protobuf-kodierte Payload oder um eine Zeichenfolge handeln, die eine JSON Base64-kodierte Protobuf-Nutzlast darstellt.

  • Die bereitgestellte Nachrichtennutzlast ist mit dem Nachrichtentyp Person definierten in PROTO_FILENAME.proto kodiert.

  • Der benannte Amazon S3 S3-Bucket BUCKET NAME enthält das FILENAME.desc generierte von PROTO_FILENAME.proto.

Nachdem Sie die Konfiguration abgeschlossen haben, veröffentlichen Sie eine Nachricht zu dem Thema, das die Regel abonniert hat. AWS IoT Core

Einschränkungen

AWS IoT Core Regeln unterstützen Protobuf mit den folgenden Einschränkungen:

  • Die Dekodierung von protobuf-Nachrichtennutzlasten innerhalb von Ersatzvorlagen wird nicht unterstützt.

  • Bei der Dekodierung von Payloads von Protobuf-Nachrichten können Sie die SQLDecodierungsfunktion innerhalb eines einzigen Ausdrucks bis zu zweimal verwenden. SQL

  • Die maximale Größe der eingehenden Nutzlast beträgt 128 KiB (1 = 1024 Byte), die maximale Größe der ausgehenden Nutzlast beträgt 128 KiB und die maximale Größe für ein FileDescriptorSet-Objekt, das in einem Amazon S3-Bucket gespeichert ist, beträgt 32 KiB.

  • Mit SSE -C-Verschlüsselung verschlüsselte Amazon S3 S3-Buckets werden nicht unterstützt.

Bewährte Methoden

Nachfolgend Best Practices und Tipps zur Fehlerbehebung.

  • Laden Sie die proto-Dateien in den Amazon S3 Bucket hoch.

    Es empfiehlt sich, die proto-Dateien zu sichern, falls etwas schief geht. Wenn Sie z. B. bei der Ausführung von protoc die proto-Dateien fälschlicherweise ohne Sicherungen ändern, kann dies zu Problemen in Ihrem Produktionsstapel führen. Es gibt mehrere Möglichkeiten, Dateien in einem Amazon S3-Bucket zu sichern. Sie können beispielsweise die Versionierung in S3-Buckets verwenden. Weitere Informationen zum Sichern von Dateien in Amazon S3-Buckets im Amazon S3 Developer Guide.

  • Konfigurieren Sie die AWS IoT Protokollierung, um Protokolleinträge anzuzeigen.

    Es empfiehlt sich, die AWS IoT Protokollierung so zu konfigurieren, dass Sie die AWS IoT Protokolle für Ihr Konto überprüfen können CloudWatch. Wenn die SQL Abfrage einer Regel eine externe Funktion aufruft, generiert AWS IoT Core Rules einen Protokolleintrag mit dem Wert eventType ofFunctionExecution, der das Feld „Grund“ enthält, das Ihnen bei der Behebung von Fehlern hilft. Zu den möglichen Fehlern gehören ein Amazon S3 S3-Objekt, das nicht gefunden wurde, oder ein ungültiger protobuf-Dateideskriptor. Weitere Informationen zur Konfiguration der AWS IoT -Protokollierung und zum Anzeigen der Protokolleinträge unter AWS IoT Protokollierung konfigurieren und Protokolleinträge der Rules Engine.

  • Aktualisieren Sie FileDescriptorSet mit einem neuen Objektschlüssel und aktualisieren Sie den Objektschlüssel in der Regel.

    Zum Aktualisieren von FileDescriptorSet laden Sie eine aktualisierte Deskriptordatei in den Amazon S3 S3-Bucket hoch. Es kann bis zu 15 Minuten dauern, bis FileDescriptorSet-Aktualisierungen angezeigt werden. Es empfiehlt sich, die aktualisierte FileDescriptorSet mit einem neuen Objektschlüssel hochzuladen und den Objektschlüssel in der Regel zu aktualisieren.