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.
Tipos de contenido compatibles: JSON, Avro, Protobuf y bytes sin procesar
PutRawEventsacepta cualquier byte. Cada entrada SystemMetadata.ContentType indica EventBridge cuáles son los bytes. Ese valor decide si EventBridge deserializa la carga útil antes de filtrar y entregar el evento. En el caso de Avro y Protobuf, EventBridge deserializa la carga útil en un registro de esquemas que se indique en la solicitud. A continuación, los suscriptores filtran, transforman y reciben el evento como JSON. En el caso de los bytes opacos, EventBridge entrega la carga útil intacta.
ContentType |
¿ EventBridge Qué pasa con la carga | Schema Registry |
|---|---|---|
application/json |
Filtra y transforma el contenido de JSON | No se utiliza |
application/avro |
Deserializa el binario de Avro a JSON y, a continuación, filtra y transforma en ese JSON | Obligatorio |
application/protobuf |
Deserializa el binario de Protobuf a JSON y, a continuación, filtra y transforma en ese JSON | Obligatorio |
application/octet-stream |
No deserializa ni inspecciona la carga útil. Entrega los bytes tal como se enviaron | No se utiliza |
¿Cómo EventBridge deserializa una carga útil
Cuando una entrada ContentType es application/avro oapplication/protobuf, EventBridge realiza los siguientes pasos para esa entrada.
-
EventBridge lee el identificador de esquema que el serializador del registro escribió en los bytes de la carga útil.
-
EventBridge obtiene el esquema coincidente del registro al que se ha asignado el nombre y deserializa la
SchemaRegistryConfiguration.RegistryUricarga útil a JSON. Si EventBridge no puede encontrar o leer el esquema, o no puede deserializar la carga útil con él, la entrada falla y se produce un error por entrada. Las demás entradas de la solicitud no se ven afectadas. -
Si un suscriptor define filtros, los compara EventBridge con el JSON deserializado.
-
EventBridge aplica la transformación del suscriptor al JSON deserializado y entrega el JSON al destino.
En cada PutRawEvents solicitud, se asigna un nombre al registro, en. SchemaRegistryConfiguration.RegistryUri La configuración pertenece a la solicitud, no al bus, y la EventBridge omite para las entradas JSON de la misma solicitud. EventBridge lee el registro con las credenciales de la persona que llama, por lo que la identidad que publica necesita acceso de lectura al registro.
Tras la deserialización, el evento se comporta como cualquier otro evento de JSON publicado con él. PutRawEvents Un filtro con un ámbito de campos hace DATA coincidir los campos del registro deserializado por sus nombres de esquema. Un transformador JSonata los direcciona bajo JSON y un $events.Data objetivo recibe JSON. EventBridge también establece tres claves en la unidad entregada. SystemMetadata
-
aws:SchemaId: el identificador del esquema EventBridge deserializado con; un UUID para AWS Glue, un entero para Confluent. -
aws:RegistryType: el registro que decodificó el evento, o.GlueConfluentLos eventos publicados conPutEventsnunca lo incluyen. -
ContentType: el tipo de contenido de la entrada publicada, por ejemploapplication/avro.
Elegir cómo se EventBridge entrega tu carga
ContentTypeselecciona una de las dos rutas de entrega.
-
Deserializar a JSON. Establézcalo
ContentTypeenapplication/avroo.application/protobufEventBridge deserializa la carga útil comparándola con tu registro de esquemas y los suscriptores la filtran, laDATAtransforman con JSonata y reciben JSON. Use esta ruta cuando desee enrutar y remodelar eventos codificados en esquemas basados en el contenido. -
Entregue los bytes intactos. Establecido
ContentTypeen.application/octet-streamEventBridge no deserializa ni inspecciona la carga útil, no implica ningún registro de esquemas y el suscriptor recibe exactamente los bytes que usted envió. Utilice esta ruta cuando deserialice usted mismo la carga útil en el destino o cuando el contenido esté en un formato que no se deserialice. EventBridge
Deserializar con AWS Registro de Glue Schema
RegistryUriConfigúrelo en el ARN del registro, del formulario. arn:aws:glue: Antes de publicarla, codifica la carga útil con el serializador AWS Glue Schema Registry para tu idioma. El serializador incorpora la referencia de esquema que se EventBridge utiliza para resolver y deserializar el evento.region:account-id:registry/name
EventBridge lee el esquema como el autor de la llamada, por lo que debe concederse a la identidad de publicación acceso de lectura al registro y a sus esquemas. La siguiente política concede el permiso mínimo, limitado a un registro.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "glue:GetSchemaVersion", "Resource": [ "arn:aws:glue:us-east-1:111122223333:registry/orders", "arn:aws:glue:us-east-1:111122223333:schema/orders/*" ] } ] }
Publique los bytes codificados en el esquema con el ARN del registro de Glue incluido. RegistryUri
aws eventsv2 put-raw-events \ --event-bus-arn arn:aws:events:us-east-1:111122223333:event-busv2/orders/EXAMPLE1234567890abcdef \ --schema-registry-configuration RegistryUri=arn:aws:glue:us-east-1:111122223333:registry/orders \ --entries '[ { "Data": "base64-encoded-avro-bytes", "SystemMetadata": { "ContentType": "application/avro", "EventGroupId": "order-1001" } } ]'
A continuación, un suscriptor filtra el registro deserializado. Si el esquema de Avro tiene un campo denominadoorderId, el siguiente filtro coincide con un orden.
{ "Scope": "DATA", "Pattern": "{\"orderId\":[\"1001\"]}" }
Deserialización con un registro de esquemas confluentes
RegistryUriConfigúrelo en la URL HTTPS del registro. Un registro HTTPS también requiere el SchemaRegistryConfiguration.ConfluentPublicRegistryConfiguration.ConnectionArn ARN de una EventBridge conexión que contenga la clave API del registro o las credenciales de OAuth. La conexión debe pertenecer a la cuenta que realiza la llamada; se rechaza una conexión entre cuentas. Cree la conexión antes de la primera publicación. Antes de publicar, codifique la carga útil con el serializador Confluent para su idioma. El serializador incorpora la referencia de esquema que se utiliza para resolver y deserializar el evento. EventBridge
EventBridge lee las credenciales de registro a través de la conexión que usted nombre. Conceda permiso a la identidad de publicación para leer las credenciales de esa conexión.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "events:RetrieveConnectionCredentials", "Resource": "arn:aws:events:us-east-1:111122223333:connection/confluent-registry/*" }, { "Effect": "Allow", "Action": ["secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"], "Resource": "arn:aws:secretsmanager:us-east-1:111122223333:secret:events!connection/confluent-registry/*", "Condition": { "Bool": { "aws:ViaAWSService": "true" } } } ] }
Si el secreto de conexión está cifrado con una AWS KMS clave gestionada por el cliente, conceda kms:Decrypt también esa clave.
Publique los bytes codificados en el esquema con la URL de Confluent y el ARN de conexión.
aws eventsv2 put-raw-events \ --event-bus-arn arn:aws:events:us-east-1:111122223333:event-busv2/orders/EXAMPLE1234567890abcdef \ --schema-registry-configuration '{ "RegistryUri": "https://psrc-example.us-east-1.aws.confluent.cloud", "ConfluentPublicRegistryConfiguration": { "ConnectionArn": "arn:aws:events:us-east-1:111122223333:connection/confluent-registry/EXAMPLE-1234-5678-abcd" } }' \ --entries '[ { "Data": "base64-encoded-protobuf-bytes", "SystemMetadata": { "ContentType": "application/protobuf" } } ]'
Opciones de autenticación de conexión
Configure la conexión con el tipo de autenticación que espera el registro de Confluent. EventBridge lee solo los encabezados de autenticación que produce la conexión; nunca ve el secreto sin procesar y actualiza los tokens de OAuth automáticamente.
Clave de API. Confluent Schema Registry suele utilizar la autenticación HTTP básica con la clave de API del registro de esquemas como nombre de usuario y el secreto de la API como contraseña.
aws events create-connection \ --name confluent-registry \ --authorization-type API_KEY \ --auth-parameters '{ "ApiKeyAuthParameters": { "ApiKeyName": "Authorization", "ApiKeyValue": "Basicbase64(srApiKey:srApiSecret)" } }'
Credenciales de cliente de OAuth. EventBridge busca y actualiza el token. Debe incluirlo grant_type=client_credentials como parámetro principal; EventBridge no lo añade automáticamente.
aws events create-connection \ --name confluent-registry-oauth \ --authorization-type OAUTH_CLIENT_CREDENTIALS \ --auth-parameters '{ "OAuthParameters": { "AuthorizationEndpoint": "https://idp-domain/oauth/token", "HttpMethod": "POST", "ClientParameters": { "ClientID": "oauth-client-id", "ClientSecret": "oauth-client-secret" }, "OAuthHttpParameters": { "BodyParameters": [ { "Key": "grant_type", "Value": "client_credentials", "IsValueSecret": false } ] } } }'
EventBridge almacena cualquiera de las credenciales en un secreto de Secrets Manager gestionado (events!connection/...), que la conexión lee en tu nombre.
Entregando bytes sin deserializarlos
Para que EventBridge entregue una carga útil exactamente como se envió, defina la entrada en. SystemMetadata.ContentType application/octet-stream Se trata de un campo en cada entrada, no de un encabezado HTTP. EventBridge no deserializa ni inspecciona los bytes y no implica ningún registro de esquemas. Cualquier formato funciona, incluidos Avro o Protobuf, que puedes deserializar tú mismo en el lugar de destino.
Como el contenido es opaco, un DATA filtro no puede igualarlo. Distribuya dichos eventos con los filtros activadosMETADATA, utilizando las teclas que haya establecido en el Metadata mapa de la entrada, o activándolosSYSTEM_METADATA. Content-based La deduplicación sigue funcionando y procesa los bytes exactamente como los envió. En un transformador, la carga útil aparece como una cadena de Base64; consulte. Transformación de eventos con JSonata
Filtrar y transformar eventos deserializados
Una vez que EventBridge se deserializa un evento en JSON, la carga útil fluye por la canalización normal. Un filtro con un alcance de hace DATA coincidir los campos deserializados por sus nombres de esquema, y un transformador JSonata los direcciona bajo. $events.Data Un evento publicado como Avro o Protobuf recibe el mismo enrutamiento basado en el contenido y la misma remodelación por suscriptor que un evento publicado como JSON simple. Escribe patrones de filtro en función del JSON deserializado, teniendo en cuenta dos reglas de conversión.
-
Avro se deserializa a JSON estándar. La conversión es unidireccional: el JSON no se puede volver a convertir en un objeto Avro.
-
Protobuf se deserializa a JSON con los nombres de campo definidos en el esquema, en lugar de convertirlos a minúsculas como suelen hacer las herramientas de Protobuf. Coincide con los nombres de los campos del esquema.
Deduplicar eventos en todos los formatos
EventBridge admite dos modos de deduplicación: ID-based uno DeduplicationId en la entrada y otro basado en el contenido, en el que se EventBridge calcula un SHA-256 hash del contenido del evento. En el caso de los eventos deserializados, la deduplicación basada en contenido crea un hash en los bytes del cable Avro o Protobuf originales, no en el JSON deserializado. Dos eventos se duplican solo cuando sus cargas útiles originales son idénticas en bytes. EventBridge por lo tanto, no deduplica el mismo evento lógico publicado en formatos diferentes. Los bytes de Avro, los bytes de Protobuf y el JSON sin procesar difieren a lo largo del cable incluso cuando se deserializan con los mismos datos. Consulte Ordenar y deduplicar eventos en un bus de eventos personalizado.
Errores
-
Una entrada de Avro o Protobuf publicada sin
SchemaRegistryConfigurationerrores es un error por entrada con un signo de y un mensaje que lo indica.ErrorCodeVALIDATION_ERRORSchemaRegistryConfiguration is requiredLas demás entradas de la solicitud no se ven afectadas. -
Una conexión
ConnectionArnque no indique el nombre de una conexión utilizable o que pertenezca a otra cuenta, fallará en la entradaVALIDATION_ERRORy en un mensaje que indique el nombre del registro. -
Un esquema que no se puede encontrar ni leer, o una carga útil que no se puede deserializar con él, no admite esa entrada.
VALIDATION_ERROREste error no se puede volver a intentar; corrija la solicitud o el acceso al registro de la persona que llama antes de volver a publicarlo. -
Si no se puede acceder a un registro, se produce un error en la solicitud.
SchemaRegistryUnavailableExceptionEn la ruta OAuth de Confluent, esto puede ocurrir mientras se actualiza el token de acceso al registro. Este error es transitorio; vuelva a intentar la solicitud con un retraso.
Para ver los resultados por entrada y una guía general para reintentarlo, consulte. Publicación de eventos en un bus de eventos personalizado