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

Wenn Nachrichtennutzlasten als unformatierte binäre Daten behandelt werden sollen (und nicht als JSON-Objekt), können Sie den Operator * verwenden, um darauf in einer SELECT-Klausel 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-Nutzlast haben, können der resultierenden Nutzlast 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.

    • Das Folgende bezieht sich auf device_type in der WHERE-Klausel.

      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äre Daten empfangen, wenn sie base64-kodiert und in einer JSON-Nutzlast enthalten sind. 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 String-Eingabe in JSON zu konvertieren, 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 in das JSON-Format dekodieren und an nachgeschaltete Dienste weiterleiten können. 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 über die Protoc-Referenz finden Sie unter API-Referenz.

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 der AWS API, des AWS SDK oder der in einen Amazon S3 S3-Bucket hoch. 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 im 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 mit der SQL-Funktion decode (value, decodingScheme) dekodieren kann. Eine ausführliche Funktionssignatur und ein Beispiel finden Sie in der SQL-Funktion decode (value, decodingScheme) der SQL-Referenz.AWS IoT

Im Folgenden finden Sie ein Beispiel für einen SQL-Ausdruck, 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. Dies kann eine binäre protobuf-kodierte Nutzlast oder eine JSON-Zeichenfolge sein, die eine 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 AWS IoT Core dem Thema, das die Regel abonniert hat.

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.

  • Beim Dekodieren von protobuf-Nachrichtennutzlasten können Sie die Funktion „SQL dekodieren“ innerhalb eines einzelnen SQL-Ausdrucks bis zu zweimal verwenden.

  • 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 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.