Comprensión de los prefijos personalizados para los objetos de Amazon S3 - Amazon Data Firehose
espacio de nombres timestampespacio de nombres firehoseEspacios de nombres partitionKeyFromLambda y partitionKeyFromQueryReglas semánticasEjemplos de prefijos

Comprensión de los prefijos personalizados para los objetos de Amazon S3

Los objetos entregados a Amazon S3 siguen el formato de nombre de <prefijo evaluado><sufijo>. Puede especificar un prefijo personalizado que incluya expresiones que se evalúan en tiempo de ejecución. El prefijo personalizado que especifique anulará el prefijo predeterminado de YYYY/MM/dd/HH.

Puede utilizar expresiones de las siguientes formas en el prefijo personalizado: !{namespace:value}, donde namespace puede ser una de estas opciones, tal como se explica en las secciones siguientes.

  • firehose

  • timestamp

  • partitionKeyFromQuery

  • partitionKeyFromLambda

Si un prefijo termina por una barra inclinada, aparece como una carpeta en el bucket de Amazon S3. Para obtener más información, consulte Formato de nombre de objetos de Amazon S3 en la Guía para desarrolladores de Amazon Data Firehose.

espacio de nombres timestamp

Los valores válidos para este espacio de nombres son cadenas DateTimeFormatter de Java válidas. Por ejemplo, en el año 2018, la expresión !{timestamp:yyyy} se evalúa como 2018.

Cuando se evalúan marcas de tiempo, Firehose utiliza la marca de tiempo de llegada aproximada del registro más antiguo incluido en el objeto de Amazon S3 que se va a escribir.

De forma predeterminada, la marca de tiempo está en UTC. Sin embargo, puede especificar la zona horaria que prefiera. Por ejemplo, puede configurar la zona horaria en Asia/Tokio en la AWS Management Console o en la configuración de parámetros de la API (CustomTimeZone) si desea utilizar la hora estándar de Japón en lugar de UTC. Para ver la lista de zonas horarias compatibles, consulte Formato de nombre de objeto de Amazon S3.

Si se utiliza el espacio de nombres timestamp más de una vez en la misma expresión de prefijo, cada instancia se evalúa como el mismo instante en el tiempo.

espacio de nombres firehose

Hay dos valores que se pueden utilizar con este espacio de nombres: error-output-type y random-string. En la tabla siguiente, se explica cómo hacerlo.

Los valores del espacio de nombres firehose
Conversion (Conversión) Descripción Ejemplo de entrada Ejemplo de resultado Notas
error-output-type Se evalúa como una de las siguientes cadenas, en función de la configuración del flujo de Firehose y el motivo del error: {processing-failed, AmazonOpenSearchService-failed, splunk-failed, format-conversion-failed, http-endpoint-failed}.

Si lo utiliza más de una vez en la misma expresión, cada instancia se evalúa como la misma cadena de error.

 myPrefix/result=!{firehose:error-output-type}/!{timestamp:yyyy/MM/dd} myPrefix/result=processing-failed/2018/08/03 El valor error-output-type solo se puede utilizar en el campo ErrorOutputPrefix.
random-string

Se evalúa como una cadena aleatoria de 11 caracteres. Si lo utiliza más de una vez en la misma expresión, cada instancia se evalúa como una cadena aleatoria nueva.

 myPrefix/!{firehose:random-string}/ myPrefix/046b6c7f-0b/ Puede utilizarlo con ambos tipos de prefijos.

Puede colocarlo al principio de la cadena de formato para obtener un prefijo aleatorio, que a veces es necesario para alcanzar un rendimiento extremadamente alto con Amazon S3.

Espacios de nombres partitionKeyFromLambda y partitionKeyFromQuery

En el caso del particionamiento dinámico, debe usar el siguiente formato de expresión en el prefijo de bucket de S3: !{namespace:value}, donde el espacio de nombres puede ser partitionKeyFromQuery, partitionKeyFromLambda o ambos. Si utiliza el análisis en línea para crear las claves de particionamiento para sus datos de origen, debe especificar un valor de prefijo de bucket de S3 que conste de expresiones especificadas en el siguiente formato: "partitionKeyFromQuery:keyID". Si utiliza una función de AWS Lambda para crear claves de particionamiento para sus datos de origen, debe especificar un valor de prefijo de bucket de S3 que conste de expresiones especificadas en el siguiente formato: "partitionKeyFromLambda:keyID". Para obtener más información, consulte “Elección de Amazon S3 como destino” en Creación de un flujo de Firehose.

Reglas semánticas

Las siguientes reglas se aplican a las expresiones Prefix y ErrorOutputPrefix.

  • En el espacio de nombres timestamp, se evalúa cualquier carácter que no esté entre comillas simples. En otras palabras, cualquier cadena encerrada entre comillas simples en el campo de valor se interpreta literalmente.

  • Si se especifica un prefijo que no contiene una expresión de espacio de nombres de marca de tiempo, Firehose agrega la expresión !{timestamp:yyyy/MM/dd/HH/} al valor del campo Prefix.

  • La secuencia !{ solo puede aparecer en expresiones !{namespace:value}.

  • ErrorOutputPrefix únicamente puede ser null si Prefix no contiene ninguna expresión. En este caso, Prefix evalúa a <specified-prefix>yyyy/MM/DDD/HH/ y ErrorOutputPrefix evalúa a <specified-prefix><error-output-type>YYYY/MM/DDD/HH/. DDD representa el día del año.

  • Si especifica una expresión para ErrorOutputPrefix, debe incluir al menos una instancia de !{firehose:error-output-type}.

  • Prefix no puede contener !{firehose:error-output-type}.

  • Una vez evaluados, ni Prefix ni ErrorOutputPrefix pueden tener una longitud superior a 512 caracteres.

  • Si el destino es Amazon Redshift, Prefix no debe contener expresiones y ErrorOutputPrefix debe ser null.

  • Si el destino es Amazon OpenSearch Service o Splunk y no se especifica ErrorOutputPrefix, Firehose utiliza el campo Prefix para los registros con errores.

  • Cuando el destino es Amazon S3, Prefix y ErrorOutputPrefix en la configuración de destino de Amazon S3 se utilizan para los registros correctos y los registros con errores, respectivamente. Si utiliza AWS CLI o la API, puede utilizar ExtendedS3DestinationConfiguration para especificar una configuración de copia de seguridad de Amazon S3 con sus propios valores de Prefix y ErrorOutputPrefix.

  • Cuando utiliza la AWS Management Console y establece el destino en Amazon S3, Firehose utiliza Prefix y ErrorOutputPrefix en la configuración de destino para los registros correctos y los registros con errores, respectivamente. Si especifica un prefijo mediante expresiones, debe especificar el prefijo de error que incluye !{firehose:error-output-type}.

  • Cuando utiliza ExtendedS3DestinationConfiguration con AWS CLI, la API o AWS CloudFormation, si especifica un valor de S3BackupConfiguration, Firehose no proporciona un valor predeterminado de ErrorOutputPrefix.

  • No puede usar los espacios de nombres partitionKeyFromLambda y partitionKeyFromQuery al crear expresiones ErrorOutputPrefix.

Ejemplos de prefijos

Ejemplos de Prefix y ErrorOutputPrefix
Entrada Prefijo evaluado (a las 10:30 h UTC del 27 de agosto de 2018)

Prefix: sin especificar

ErrorOutputPrefix: myFirehoseFailures/!{firehose:error-output-type}/

Prefix: 2018/08/27/10

ErrorOutputPrefix: myFirehoseFailures/processing-failed/

Prefix: !{timestamp:yyyy/MM/dd}

ErrorOutputPrefix: sin especificar

 Entrada no válida: ErrorOutputPrefix no puede ser null si Prefix contiene expresiones

Prefix: myFirehose/DeliveredYear=!{timestamp:yyyy}/anyMonth/rand=!{firehose:random-string}

ErrorOutputPrefix: myFirehoseFailures/!{firehose:error-output-type}/!{timestamp:yyyy}/anyMonth/!{timestamp:dd}

Prefix: myFirehose/DeliveredYear=2018/anyMonth/rand=5abf82daaa5

ErrorOutputPrefix: myFirehoseFailures/processing-failed/2018/anyMonth/10

Prefix: myPrefix/year=!{timestamp:yyyy}/month=!{timestamp:MM}/day=!{timestamp:dd}/hour=!{timestamp:HH}/

ErrorOutputPrefix: myErrorPrefix/year=!{timestamp:yyyy}/month=!{timestamp:MM}/day=!{timestamp:dd}/hour=!{timestamp:HH}/!{firehose:error-output-type}

Prefix: myPrefix/year=2018/month=07/day=06/hour=23/

ErrorOutputPrefix: myErrorPrefix/year=2018/month=07/day=06/hour=23/processing-failed

Prefix: myFirehosePrefix/

ErrorOutputPrefix: sin especificar

Prefix: myFirehosePrefix/2018/08/27/

ErrorOutputPrefix: myFirehosePrefix/processing-failed/2018/08/27/