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)
En esta sección:
Requisitos previos
-
Conocimientos básicos de los búferes de protocolo (protobuf)
-
Los archivos
.proto
que definen los tipos de mensajes y las dependencias relacionadas -
Instalación del compilador Protobuf (protoc)
en su sistema
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
-
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 mensajePerson
. La definición del mensajePerson
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). -
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 enPROTO_FILENAME.proto
. -
El bucket de Amazon S3 llamado
BUCKET NAME
contiene elFILENAME.desc
generado desdePROTO_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 deFileDescriptorSet
pueden tardar hasta 15 minutos en reflejarse. Para evitar este retraso, se recomienda cargar las actualizaciones deFileDescriptorSet
con una clave de objeto nueva y actualizar la clave de objeto en la regla.