Uso de las cargas binarias - AWS IoT Core
Ejemplos de carga binariaDescodificación de cargas de mensajes de protobuf

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Uso de las cargas binarias

Para tratar la carga del mensaje como datos binarios sin procesar (en lugar de como un objeto JSON), puede utilizar el operador * para hacer referencia a ella en una cláusula SELECT.

Ejemplos de carga binaria

Si utiliza * para hacer referencia a la carga del mensaje como datos binarios sin procesar, puede añadir datos a la regla. Si tiene una carga vacía o JSON, a la carga resultante se le pueden agregar datos mediante la regla. A continuación se muestran ejemplos de cláusulas SELECT admitidas.

  • Puede usar las siguientes cláusulas SELECT con solo un * para cargas binarias.

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

  • También puede agregar datos y utilizar las siguientes cláusulas SELECT.

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

  • También puede usar estas cláusulas SELECT con cargas binarias.

    • Lo siguiente hace referencia a device_type en la cláusula WHERE.

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

    • También se admite lo siguiente.

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

Las siguientes acciones de regla no admiten cargas binarias, por lo que debe descodificarlas.

  • Algunas acciones de regla no admiten la entrada de carga binaria, como la acción Lambda, por lo que debe descodificar las cargas binarias. La acción de regla Lambda puede recibir datos binarios si está codificada en base64 y en una carga JSON. Puede hacer esto cambiando la regla a lo siguiente.

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

  • La instrucción SQL no admite cadenas como entrada. Para convertir una entrada de cadena en JSON, puede ejecutar el siguiente comando.

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

Descodificación de cargas de mensajes de protobuf

Los búferes de protocolo (protobuf) son un formato de datos de código abierto que se utiliza para serializar datos estructurados en un formato binario compacto. Se utiliza para transmitir datos a través de redes o para almacenarlos en archivos. Protobuf le permite enviar datos en paquetes pequeños y a un ritmo más rápido que otros formatos de mensajería. AWS IoT Core Las reglas admiten protobuf al proporcionar la función SQL decode (value, decodingScheme), que permite decodificar las cargas útiles de mensajes codificadas por protobuf en formato JSON y enrutarlas a los servicios descendentes. En esta sección se detalla el proceso de configuración de la decodificación protobuf en Rules. step-by-step AWS IoT Core

Requisitos previos

Crear archivos descriptores

Si ya dispone de los archivos descriptores, puede omitir este paso. Un archivo descriptor (.desc) es una versión compilada de un archivo .proto, que es un archivo de texto que define las estructuras de datos y los tipos de mensajes que se utilizarán en una serialización de protobuf. Para generar un archivo descriptor, debe definir un archivo .proto y usar el compilador protoc para compilarlo.

  1. Crear archivos .proto que definan los tipos de mensajes. Un ejemplo de archivo .proto sería el siguiente:

    syntax = "proto3";

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

    En este archivo .proto de ejemplo, se utiliza la sintaxis proto3 y se define el tipo de mensaje Person. La definición del mensaje Person especifica tres campos (nombre, identificador y correo electrónico). Para obtener más información sobre los formatos de los mensajes de los archivos .proto, consulte la Guía de lenguaje (proto3).

  2. Utilice el compilador protoc para compilar los archivos .proto y generar un archivo descriptor. Un ejemplo de comando para crear un archivo descriptor (.desc) puede ser el siguiente:

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

    Este comando de ejemplo genera un archivo <FILENAME>.desc descriptor que AWS IoT Core Rules puede usar para decodificar las cargas útiles de protobuf que se ajusten a la estructura de datos definida en. <PROTO_FILENAME>.proto

    • --descriptor_set_out

      Especifica el nombre del archivo descriptor (<FILENAME>.desc) que se debe generar.

    • --proto_path

      Especifica las ubicaciones de los archivos .proto importados a los que hace referencia el archivo que se está compilando. Puede especificar la marca varias veces si tiene varios archivos .proto importados con ubicaciones diferentes.

    • --include_imports

      Especifica que todos los archivos .proto importados también se deben compilar e incluir en el archivo descriptor <FILENAME>.desc.

    • <PROTO_FILENAME>.proto

      Especifica el nombre del archivo .proto que desea compilar.

    Para obtener más información sobre la referencia protoc, consulte la Referencia de la API.

Cargar los archivos descriptores en un bucket de S3

Tras crear los archivos descriptores<FILENAME>.desc, cárguelos en un bucket de Amazon S3 mediante la AWS API, el AWS SDK o el. <FILENAME>.desc AWS Management Console

Consideraciones importantes

  • Asegúrese de cargar los archivos descriptores en un bucket de Amazon S3 en el mismo Región de AWS lugar Cuenta de AWS en el que pretende configurar sus reglas.

  • Asegúrese de conceder AWS IoT Core acceso para leer el contenido FileDescriptorSet de S3. Si su bucket de S3 tiene el cifrado del servidor (SSE) desactivado o si el bucket de S3 está cifrado con claves administradas por Amazon S3 (SSE-S3), no se requieren configuraciones de políticas adicionales. Esto se puede lograr con la política de bucket de ejemplo:

    {
	"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 su bucket de S3 está cifrado con una AWS Key Management Service clave (SSE-KMS), asegúrese de conceder AWS IoT Core permiso para usar la clave al acceder a su bucket de S3. Para ello, agregue esta instrucción a su política de claves:

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

Configurar la descodificación protobuf en las reglas

Tras cargar los archivos descriptores en su bucket de Amazon S3, configure una regla que pueda descodificar el formato de carga del mensaje protobuf mediante la función decode(value, decodingScheme) de SQL. Puede encontrar una firma y un ejemplo detallados de la función en la función decode(value, DecodingScheme) de SQL de la referencia de la SQL de AWS IoT .

A continuación se muestra un ejemplo de expresión SQL que utiliza la función decode(value, decodingScheme):

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

En este ejemplo de expresión:

  • Utiliza la función decode(value, decodingScheme) de SQL para descodificar la carga del mensaje binario a la que hace referencia *. Puede ser una carga binaria codificada por protobuf o una cadena JSON que representa una carga protobuf codificada en base64.

  • La carga del mensaje proporcionada se codifica con el tipo de mensaje Person definido en PROTO_FILENAME.proto.

  • El bucket de Amazon S3 llamado BUCKET NAME contiene el FILENAME.desc generado desde PROTO_FILENAME.proto.

Tras completar la configuración, publique un mensaje AWS IoT Core sobre el tema al que está suscrita la regla.

Limitaciones

AWS IoT Core Las reglas admiten protobuf con las siguientes limitaciones:

  • No se admite la descodificación de cargas de mensajes de protobuf en plantillas de sustitución.

  • Al descodificar las cargas de los mensajes de protobuf, puede utilizar la función de descodificación de SQL en una sola expresión SQL hasta dos veces.

  • El tamaño máximo de la carga de entrada es de 128 KiB (1 KiB = 1024 bytes), el tamaño máximo de la carga de salida es de 128 KiB y el tamaño máximo de un objeto FileDescriptorSet almacenado en un bucket de Amazon S3 es de 32 KiB.

  • No se admiten los buckets de Amazon S3 cifrados con cifrado SSE-C.

Prácticas recomendadas

Estas son algunas prácticas recomendadas y consejos de solución de problemas.

  • Haga una copia de seguridad de sus archivos proto en el bucket de Amazon S3.

    Se recomienda hacer copias de seguridad de los archivos proto en caso de que algo salga mal. Por ejemplo, si modifica incorrectamente los archivos proto sin copias de seguridad al ejecutar protoc, esto puede provocar problemas en su pila de producción. Existen varias formas de hacer copias de seguridad de los archivos en un bucket de Amazon S3. Por ejemplo, puede utilizar el control de versiones en buckets de S3. Para obtener más información sobre cómo hacer copias de seguridad de los archivos en los buckets de Amazon S3, consulte la Guía para desarrolladores de Amazon S3.

  • Configure el AWS IoT registro para ver las entradas del registro.

    Se recomienda configurar el AWS IoT registro para que puedas comprobar AWS IoT los registros de tu cuenta CloudWatch. Cuando la consulta SQL de una regla llama a una función externa, AWS IoT Core Rules genera una entrada de registro con un eventType deFunctionExecution, que contiene el campo del motivo, que le ayudará a solucionar errores. Los posibles errores incluyen un objeto de Amazon S3 no encontrado o un descriptor de archivo protobuf no válido. Para obtener más información sobre cómo configurar el registro de AWS IoT y ver las entradas de registro, consulte Configurar el registro de AWS IoT y Entradas del registro del motor de reglas.

  • Actualice FileDescriptorSet con una clave de objeto nueva y actualice la clave de objeto en su regla.

    Puede actualizar FileDescriptorSet cargando un archivo descriptor actualizado en su bucket de Amazon S3. Las actualizaciones de FileDescriptorSet pueden tardar hasta 15 minutos en reflejarse. Para evitar este retraso, se recomienda cargar las actualizaciones de FileDescriptorSet con una clave de objeto nueva y actualizar la clave de objeto en la regla.