Utilisation des charges utiles binaires - AWS IoT Core
Exemples de charge utile binaireDécodage des charges utiles des messages protobuf

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Utilisation des charges utiles binaires

Pour traiter la charge utile de votre message comme des données binaires brutes (plutôt que comme un objet JSON), vous pouvez utiliser l’opérateur * pour y faire référence dans une clause SELECT.

Exemples de charge utile binaire

Lorsque vous utilisez * pour désigner la charge utile du message sous forme de données binaires brutes, vous pouvez ajouter des données à la règle. Si vous avez une charge utile vide ou une charge utile JSON, des données peuvent être ajoutées à la charge utile résultante à l’aide de la règle. Vous trouverez ci-dessous des exemples de clauses SELECT prises en charge.

  • Vous pouvez utiliser les clauses SELECT suivantes avec uniquement un * pour les charges utiles binaires.

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

  • Vous pouvez également ajouter des données et utiliser les clauses SELECT suivantes.

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

  • Vous pouvez également utiliser ces clauses SELECT avec des charges utiles binaires.

    • Ce qui suit fait référence à device_type dans la clause WHERE.

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

    • Les éléments suivants sont pris en charge.

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

Les actions de règles suivantes ne prennent pas en charge les charges utiles binaires. Vous devez donc les décoder.

  • Certaines actions de règles ne prennent pas en charge les données utiles binaires, comme les actions Lambda, et vous devez donc décoder les données utiles binaires. L’action de la règle Lambda peut recevoir des données binaires si elles sont codées en base64 et placées dans une charge utile JSON. Pour cela, apportez les modifications suivantes à la règle :

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

  • L’instruction SQL ne prend pas en charge les chaînes en entrée. Pour convertir une chaîne en JSON, vous pouvez exécuter la commande suivante.

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

Décodage des charges utiles des messages protobuf

Protocol Buffers (protobuf) est un format de données open source utilisé pour sérialiser des données structurées sous une forme binaire compacte. Il est utilisé pour transmettre des données sur des réseaux ou pour les stocker dans des fichiers. Protobuf vous permet d'envoyer des données sous forme de petits paquets et à un rythme plus rapide que les autres formats de messagerie. AWS IoT Core Les règles prennent en charge protobuf en fournissant la fonction SQL decode (value, decodingScheme), qui vous permet de décoder les charges utiles des messages codés par protobuf au format JSON et de les acheminer vers les services en aval. Cette section détaille le step-by-step processus de configuration du décodage protobuf dans Rules. AWS IoT Core

Prérequis

Création de fichiers descripteurs

Si vous disposez déjà de fichiers descripteurs, vous pouvez ignorer cette étape. Un fichier descripteur (.desc) est une version compilée d’un fichier .proto, qui est un fichier texte qui définit les structures de données et les types de messages à utiliser dans une sérialisation protobuf. Pour générer un fichier descripteur, vous devez définir un fichier .proto et utiliser le compilateur protoc pour le compiler.

  1. Créez des fichiers .proto qui définissent les types de messages. Un fichier .proto manifeste peut ressembler à l’exemple suivant :

    syntax = "proto3";

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

    Dans cet exemple de fichier .proto, vous utilisez la syntaxe proto3 et définissez le type de message Person. La définition du message Person spécifie trois champs (nom, identifiant et e-mail). Pour plus d’informations sur les formats de message de fichier .proto, veuillez consulter le Guide des langues (proto3).

  2. Utilisez le compilateur protoc pour compiler les fichiers.proto et générer un fichier de descripteurs. La création d’un fichier (.desc) descripteur est illustrée ci-dessous :

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

    Cet exemple de commande génère un fichier descripteur que <FILENAME>.desc AWS IoT Core Rules peut utiliser pour décoder les charges utiles protobuf conformes à la structure de données définie dans. <PROTO_FILENAME>.proto

    • --descriptor_set_out

      Spécifie le nom du fichier (<FILENAME>.desc) descripteur qui doit être généré.

    • --proto_path

      Spécifie l’emplacement de tous les fichiers .proto importés référencés par le fichier en cours de compilation. Vous pouvez spécifier l’indicateur plusieurs fois si vous avez plusieurs fichiers .proto importés avec des emplacements différents.

    • --include_imports

      Spécifie que tous les fichiers .proto importés doivent également être compilés et inclus dans le fichier <FILENAME>.desc descripteur.

    • <PROTO_FILENAME>.proto

      Spécifie le nom du fichier .proto que vous souhaitez compiler.

    Pour de plus amples informations sur la référence protoc, veuillez consulter Référence de l’API.

Charger les fichiers descripteurs dans un compartiment S3

Après avoir créé vos fichiers descripteurs<FILENAME>.desc, chargez-les dans un compartiment Amazon S3 <FILENAME>.desc à l'aide de l' AWS API, du AWS SDK ou du. AWS Management Console

Considérations Importantes

  • Assurez-vous de télécharger les fichiers descripteurs dans un compartiment Amazon S3 situé dans le même compartiment que celui Compte AWS dans Région AWS lequel vous souhaitez configurer vos règles.

  • Assurez-vous d'autoriser l' AWS IoT Core accès pour lire le contenu FileDescriptorSet de S3. Si le chiffrement côté serveur (SSE) est désactivé dans votre compartiment S3 ou s’il est chiffré à l’aide de clés gérées par Amazon S3 (SSE-S3), aucune configuration de stratégie supplémentaire n’est requise. Cela peut être accompli à l’aide de l’exemple de politique de compartiment :

    {
	"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"
		}
	]
}

  • Si votre compartiment S3 est chiffré à l'aide d'une AWS Key Management Service clé (SSE-KMS), assurez-vous d' AWS IoT Core autoriser l'utilisation de la clé lors de l'accès à votre compartiment S3. Pour ce faire, vous pouvez ajouter cette déclaration à votre stratégie de clé :

    {
	"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"
	
}

Configurer le décodage protobuf dans Règles

Après avoir chargé les fichiers descripteurs dans votre compartiment Amazon S3, configurez une Règle capable de décoder le format de charge utile de votre message protobuf à l’aide de la fonction SQL decode (value, decodingScheme). Une signature de fonction détaillée et un exemple se trouvent dans la fonction SQL decode(value, decodingScheme) de la AWS IoT référence SQL.

Voici un exemple d’expression SQL utilisant la fonction decode (value, decodingScheme) :

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

Dans cet exemple d’expression :

  • Vous utilisez la fonction SQL decode (value, decodingScheme) pour décoder la charge utile du message binaire référencée par *. Il peut s’agir d’une charge utile binaire codée en protobuf ou d’une chaîne JSON représentant une charge utile protobuf codée en base64.

  • La charge utile du message fournie est codée à l’aide du type de message Person défini dans PROTO_FILENAME.proto.

  • Le compartiment Amazon S3 nommé BUCKET NAME contient le FILENAME.desc généré à partir de PROTO_FILENAME.proto.

Une fois la configuration terminée, publiez un message AWS IoT Core sur le sujet auquel la règle est abonnée.

Limites

AWS IoT Core Les règles prennent en charge protobuf avec les limitations suivantes :

  • Le décodage des charges utiles des messages protobuf dans les modèles de substitution n’est pas pris en charge.

  • Lorsque vous décodez les charges utiles des messages protobuf, vous pouvez utiliser la fonction SQL de décodage dans une seule expression SQL jusqu’à deux fois.

  • La taille maximale de la charge utile entrante est de 128 KiB (1 KiB = 1024 octets), la taille maximale de la charge utile sortante est de 128 KiB et la taille maximale d’un objet FileDescriptorSet stocké dans un compartiment Amazon S3 est de 32 KiB.

  • Les compartiments Amazon S3 chiffrés avec le chiffrement SSE-C ne sont pas pris en charge.

Bonnes pratiques

Voici quelques bonnes pratiques et des conseils de dépannage.

  • Sauvegardez vos fichiers proto dans le compartiment Amazon S3.

    Il est recommandé de sauvegarder vos fichiers proto en cas de problème. Par exemple, si vous modifiez incorrectement les fichiers proto sans sauvegarde lors de l’exécution de protoc, cela peut entraîner des problèmes dans votre stack de production. Il existe plusieurs méthodes pour sauvegarder vos fichiers dans un compartiment Amazon S3. Par exemple, vous pouvez utiliser la gestion des versions dans les compartiments S3. Pour plus d’informations sur la sauvegarde de fichiers dans des compartiments Amazon S3, veuillez consulter le manuel du développeur Amazon S3.

  • Configurez la AWS IoT journalisation pour afficher les entrées du journal.

    Il est recommandé de configurer la AWS IoT journalisation de manière à pouvoir consulter AWS IoT les journaux de votre compte CloudWatch. Lorsque la requête SQL d'une règle appelle une fonction externe, AWS IoT Core Rules génère une entrée de journal avec un eventType deFunctionExecution, qui contient le champ de raison qui vous aidera à résoudre les problèmes d'échec. Les erreurs possibles incluent un objet Amazon S3 introuvable ou un descripteur de fichier protobuf non valide. Pour plus d’informations sur la façon de configurer la journalisation AWS IoT et de consulter les entrées du journal, veuillez consulter Configurer la AWS IoT journalisation et les entrées du journal du moteur de règles.

  • Effectuez la mise à jour de FileDescriptorSet à l’aide d’une nouvelle clé d’objet et mettez à jour la clé d’objet dans votre règle.

    Vous pouvez effectuer une mise à jour de FileDescriptorSet en chargeant un fichier descripteur mis à jour dans votre compartiment Amazon S3. Vos mises à jour de FileDescriptorSet peuvent prendre jusqu’à 15 minutes pour être prises en compte. Pour éviter ce retard, il est recommandé de télécharger votre FileDescriptorSet mis à jour à l’aide d’une nouvelle clé d’objet et de mettre à jour la clé d’objet dans votre Règle.