Amazon S3

Amazon S3 es un sistema de almacenamiento altamente escalable ofrecido por Amazon Web Services.

Importante

Si vas a cambiar de proveedor de almacenamiento en el cloud, ponte en contacto con tu CSM de Braze para que te ayude a configurar y validar tu nueva integración.

La integración de Braze y Amazon S3 presenta dos estrategias de integración:

• Aprovecha Currents, que te permite almacenar datos allí hasta que quieras conectarlos a otras plataformas, herramientas y ubicaciones.
• Utiliza las exportaciones de datos del panel (como las exportaciones CSV y los informes de participación).

Requisitos previos

Crear un nuevo contenedor de S3

Para crear un contenedor para tu aplicación, haz lo siguiente:

1. Abre la consola de Amazon S3 y sigue las instrucciones para Iniciar sesión o Crear una cuenta en AWS.
2. Después de iniciar sesión, selecciona S3 en la categoría Almacenamiento y entrega de contenido.
3. Selecciona Crear contenedor en la siguiente pantalla.
4. Cuando se te solicite, crea tu contenedor y selecciona una región de AWS.

Braze no te permite elegir ni configurar una región en el panel. La región de AWS queda fijada por el lugar donde creas el contenedor en la consola de AWS. La integración envía los datos al nombre de contenedor que proporciones, y AWS enruta automáticamente las solicitudes a la región del contenedor. Si tu conector intenta conectarse a una región distinta de la que quieres (por ejemplo, eu-west-1 en lugar de eu-central-1), crea o utiliza un contenedor de S3 en la región que desees en AWS. No hay nada que cambiar por parte de Braze.

Nota

Currents no admite contenedores que tengan configurado Object Lock.

Integración

Braze tiene dos estrategias de integración diferentes con Amazon S3: una para Braze Currents y otra para todas las exportaciones de datos del panel (como exportaciones CSV o informes de participación). Ambas integraciones admiten dos métodos distintos de autenticación o autorización:

• Método de clave de acceso secreta de AWS
• Método de ARN de rol de AWS

Método de autenticación con clave secreta de AWS

Este método de autenticación genera una clave secreta y un ID de clave de acceso que permiten a Braze autenticarse como usuario en tu cuenta de AWS para escribir datos en tu contenedor.

Paso 1: Crear un usuario

Nota

Si solo estás configurando el archivado de mensajes, sigue los pasos de la pestaña Dashboard Data Export.

Para obtener tu ID de clave de acceso y tu clave de acceso secreta, crea un usuario de IAM y un grupo de administradores en AWS.

Paso 2: Obtener las credenciales

Después de crear un nuevo usuario, selecciona Show User Security Credentials para mostrar tu ID de clave de acceso y tu clave de acceso secreta. A continuación, anota estas credenciales en algún lugar o selecciona el botón Download Credentials, ya que tendrás que introducirlas más adelante en el panel de Braze.

Paso 3: Crear una política

Ve a Policies > Get Started > Create Policy para añadir permisos a tu usuario. A continuación, selecciona Create Your Own Policy. Esto otorga permisos limitados, de modo que Braze solo puede acceder a los contenedores especificados.

Nota

Se necesitan políticas distintas para Currents y para la exportación de datos del panel. Se requiere s3:GetObject para que el backend de Braze pueda gestionar los errores.

Especifica el nombre de política que prefieras e introduce el siguiente fragmento de código en la sección Policy Document. Asegúrate de sustituir INSERTBUCKETNAME por el nombre de tu contenedor. Sin estos permisos, la integración no superará la comprobación de credenciales y no se creará.

Nota

Si solo estás configurando el archivado de mensajes, utiliza el fragmento de código de la pestaña Dashboard Data Export.

• braze currents
• dashboard data export

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": ["s3:ListBucket", "s3:GetBucketLocation"],
            "Resource": ["arn:aws:s3:::INSERTBUCKETNAME"]
        },
        {
            "Effect": "Allow",
            "Action": ["s3:PutObject", "s3:GetObject"],
            "Resource": ["arn:aws:s3:::INSERTBUCKETNAME/*"]
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": ["s3:ListBucket", "s3:GetBucketLocation"],
            "Resource": ["arn:aws:s3:::INSERTBUCKETNAME"]
        },
        {
            "Effect": "Allow",
            "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
            "Resource": ["arn:aws:s3:::INSERTBUCKETNAME*", "arn:aws:s3:::INSERTBUCKETNAME/", "arn:aws:s3:::INSERTBUCKETNAME"]
        }
    ]
}

Paso 4: Asociar la política

Después de crear una nueva política, ve a Users y selecciona tu usuario. En la pestaña Permissions, selecciona Attach Policy y elige la nueva política que has creado. Ya puedes vincular tus credenciales de AWS a tu cuenta de Braze.

Paso 5: Vincular Braze con AWS

Nota

Si solo estás configurando el archivado de mensajes, sigue los pasos de la pestaña Dashboard Data Export.

• braze currents
• dashboard data export

En Braze, ve a Integraciones con partners > Currents.

A continuación, selecciona Crear nuevo Current y luego Exportación de datos de Amazon S3.

Ponle nombre a tu Current. En la sección Credenciales, asegúrate de que esté seleccionada la opción AWS Secret Access Key y, a continuación, introduce tu ID de acceso de S3, tu clave de acceso secreta de AWS y el nombre de tu contenedor de AWS S3 en los campos correspondientes.

Proporciona un correo electrónico de contacto para las notificaciones de errores de integración. Braze envía notificaciones a esta dirección si la integración encuentra errores, como problemas con las credenciales o de conectividad. Para ayudar a garantizar que las personas adecuadas reciban las alertas, utiliza una lista de distribución o una dirección de correo electrónico de grupo.

Advertencia

Mantén actualizados tu ID de clave de acceso y tu clave de acceso secreta de AWS. Si las credenciales de tu conector caducan, el conector dejará de enviar eventos. Si esta situación se prolonga durante más de 5 días, los eventos del conector se descartarán y los datos se perderán de forma permanente.

También puedes añadir la siguiente personalización según tus necesidades:

• Ruta de la carpeta: El valor predeterminado es currents. Si esta carpeta no existe, Braze la crea automáticamente por ti.
• Cifrado AES-256 del lado del servidor en reposo: Está desactivado de forma predeterminada e incluye el encabezado x-amz-server-side-encryption.

Selecciona Lanzar Current para continuar.

Una notificación te indicará si tus credenciales se han validado correctamente. AWS S3 ya está configurado para Braze Currents.

En Braze, ve a Integraciones con partners > Partners tecnológicos y selecciona Amazon S3.

En la página Credenciales de AWS, asegúrate de que esté seleccionada la opción AWS Secret Access Key y, a continuación, introduce tu ID de acceso de AWS, tu clave de acceso secreta de AWS y el nombre de tu contenedor de AWS S3 en los campos correspondientes. Al introducir tu clave secreta, selecciona primero Probar credenciales para comprobar que tus credenciales funcionan y, si todo va bien, selecciona Guardar.

Consejo

Siempre puedes obtener nuevas credenciales yendo a tu usuario y seleccionando Create Access Key en la pestaña Security Credentials de la consola de AWS.

Una notificación te indicará si tus credenciales se han validado correctamente. AWS S3 ya está integrado en tu cuenta de Braze.

Método de autenticación con ARN de rol de AWS

Este método de autenticación genera un nombre de recurso de Amazon (ARN) de rol que permite a la cuenta de Amazon de Braze autenticarse como miembro del rol que creaste para escribir datos en tu contenedor.

Paso 1: Crear la política

Para empezar, inicia sesión en la consola de administración de AWS como administrador de la cuenta. Ve a la sección IAM de la consola de AWS, selecciona Policies en la barra de navegación y selecciona Create Policy.

Nota

Currents y la exportación de datos del panel requieren políticas diferentes. s3:GetObject es necesario para que el backend de Braze pueda gestionar los errores.

Abre la pestaña JSON e introduce el siguiente fragmento de código en la sección Policy Document. Asegúrate de reemplazar INSERTBUCKETNAME por el nombre de tu contenedor. Cuando termines, selecciona Review Policy.

Nota

Si solo vas a configurar el archivado de mensajes, utiliza el fragmento de código de la pestaña Dashboard Data Export.

• braze currents
• dashboard data export

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": ["s3:ListBucket", "s3:GetBucketLocation"],
            "Resource": ["arn:aws:s3:::INSERTBUCKETNAME"]
        },
        {
            "Effect": "Allow",
            "Action": ["s3:PutObject", "s3:GetObject"],
            "Resource": ["arn:aws:s3:::INSERTBUCKETNAME/*"]
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": ["s3:ListBucket", "s3:GetBucketLocation"],
            "Resource": ["arn:aws:s3:::INSERTBUCKETNAME"]
        },
        {
            "Effect": "Allow",
            "Action": ["s3:PutObject", "s3:GetObject","s3:DeleteObject"],
            "Resource": ["arn:aws:s3:::INSERTBUCKETNAME/*"]
        }
    ]
}

A continuación, asigna un nombre y una descripción a la política y selecciona Create Policy.

Paso 2: Crear el rol

En la misma sección IAM de la consola, selecciona Roles > Create Role.

Obtén el ID de tu cuenta de Braze y el ID externo desde tu cuenta de Braze:

• Currents: En Braze, ve a Integraciones de socios > Currents. Después, selecciona Crear nuevo Current y luego Exportación de datos de Amazon S3. Aquí encontrarás los identificadores necesarios para crear tu rol.
• Exportación de datos del panel: En Braze, ve a Integraciones de socios > Socios tecnológicos y selecciona Amazon S3. Aquí encontrarás los identificadores necesarios para crear tu rol. (Crea tus roles aquí si solo vas a configurar el archivado de mensajes).

De vuelta en la consola de AWS, selecciona Another AWS Account como tipo de selector de entidad de confianza. Proporciona el ID de tu cuenta de Braze, marca la casilla Require external ID e introduce el ID externo de Braze. Cuando termines, selecciona Next.

Paso 3: Adjuntar la política

A continuación, adjunta al rol la política que creaste antes. Busca la política en la barra de búsqueda y marca la casilla junto a ella para adjuntarla. Cuando termines, selecciona Next.

Asigna un nombre y una descripción al rol, y selecciona Create Role.

Ahora verás el rol recién creado en la lista.

Paso 4: Vincular con Braze AWS

En la consola de AWS, busca el rol recién creado en la lista. Selecciona el nombre para abrir los detalles de ese rol.

Anota el Role ARN que aparece en la parte superior de la página de resumen del rol.

Vuelve a tu cuenta de Braze y copia el ARN del rol en el campo correspondiente.

Nota

Si solo vas a configurar el archivado de mensajes, sigue los pasos de la pestaña Dashboard Data Export.

• braze currents
• dashboard data export

En Braze, ve a Integraciones de socios > Currents. Después, selecciona Crear nuevo Current y selecciona Exportación de datos de Amazon S3.

Asigna un nombre a tu Current. Luego, en la sección Credenciales, asegúrate de que AWS Role ARN esté seleccionado y proporciona el ARN de tu rol y el nombre de tu contenedor de AWS S3 en los campos designados.

Proporciona un correo electrónico de contacto para las notificaciones de errores de integración. Braze envía notificaciones a esta dirección si la integración encuentra errores, como problemas con las credenciales o de conectividad. Para ayudar a garantizar que las personas adecuadas reciban las alertas, utiliza una lista de distribución o una dirección de correo electrónico de grupo.

También puedes añadir la siguiente personalización según tus necesidades:

• Ruta de la carpeta (predeterminada: currents)
• Cifrado AES-256 del lado del servidor en reposo (predeterminado: desactivado): incluye el encabezado x-amz-server-side-encryption

Selecciona Lanzar Current para continuar. Una notificación te indicará si tus credenciales se han validado correctamente. AWS S3 ya está configurado para Braze Currents.

Importante

Si recibes el error “Las credenciales de S3 no son válidas”, puede deberse a que hiciste la integración demasiado pronto después de crear un rol en AWS. Espera e inténtalo de nuevo. Si el mensaje menciona el acceso PutObject o el cifrado del lado del servidor en las exportaciones de datos del panel, consulta Solución de problemas de errores de credenciales de S3.

En Braze, ve a la página Socios tecnológicos en Integraciones y selecciona Amazon S3.

En la página Credenciales de AWS, asegúrate de que el botón de opción AWS Role ARN esté seleccionado y luego introduce el ARN de tu rol y el nombre de tu contenedor de AWS S3 en los campos designados. Selecciona primero Probar credenciales para confirmar que tus credenciales funcionan correctamente y, si la prueba es satisfactoria, selecciona Guardar.

Consejo

Siempre puedes obtener nuevas credenciales yendo a tu usuario y seleccionando Create Access Key en la pestaña Security Credentials de la consola de AWS.

Una notificación te informará si tus credenciales se han validado correctamente. AWS S3 ya está integrado en tu cuenta de Braze.

Consideraciones de seguridad para el método de ARN de rol

Cuando seleccionas Another AWS Account e introduces el ID de la cuenta de Braze en el Paso 2, AWS crea una política de confianza cuyo Principal es la raíz de la cuenta de AWS de Braze (arn:aws:iam::<BRAZE_ACCOUNT_ID>:root). Si tu equipo de seguridad revisa esta política de confianza, ten en cuenta lo siguiente:

• Braze utiliza un usuario de IAM compartido para asumir tu rol.
• El ID externo es obligatorio. Mantén la condición sts:ExternalId en tu política de confianza, también cuando limites el principal a un usuario de IAM específico.
• Puedes limitar el principal a un usuario de IAM específico. Si tu política de seguridad no permite confiar en la raíz de una cuenta, puedes reemplazar el Principal por el ARN del usuario de IAM de Braze. Para obtener ese ARN para tu región, ponte en contacto con el soporte de Braze.
• El usuario de IAM de Braze puede cambiar. Por lo general, el principal es estable, pero Braze podría cambiarlo en el futuro. Si limitas tu política de confianza a un usuario de IAM específico y ese usuario cambia, Braze no podrá asumir tu rol hasta que actualices la política de confianza.
• Los principales varían según el producto. Currents y las exportaciones de datos del panel utilizan el mismo usuario de IAM de Braze. La ingesta de datos en la nube utiliza un principal diferente en otra cuenta de AWS, así que configura su política de confianza por separado.

Actualización de credenciales de Amazon S3 para Currents

Puedes actualizar las credenciales de Amazon S3 en un conector de Braze Currents existente sin detener la integración ni perder los datos ya exportados a tu contenedor.

Para actualizar las credenciales, o para cambiar entre AWS Secret Access Key y AWS Role ARN, completa los pasos de IAM y AWS para el método elegido descritos anteriormente en este artículo (políticas, usuario o rol, e identificadores según sea necesario).

Cuando hayas terminado de preparar las credenciales en AWS, ve a Partner Integrations > Currents en Braze, localiza tu conector de Amazon S3 en la lista, selecciona Edit, actualiza las Credentials y selecciona Update Current. Braze valida las credenciales que introduces; tu conector sigue funcionando y los datos que ya están en tu contenedor permanecen disponibles. Para más información, consulta Actualización de Currents en Configurar Currents.

Cómo Currents carga archivos en S3

Currents cierra cada archivo Avro cuando alcanza el umbral de escritura de Avro y luego carga el archivo completo en tu contenedor mediante la carga multiparte de Amazon S3 en partes de 5 MB. La carga multiparte es independiente del umbral de escritura y suele terminar a los pocos segundos de cerrarse el archivo.

Amazon S3 no expone como objeto una carga multiparte en curso. Un archivo de Currents solo es visible para ListObjectsV2 y GetObject cuando se completa la carga, así que los procesos posteriores que leen tu contenedor con las API estándar de S3 no ven archivos cargados parcialmente.

Comportamiento de exportación

Los usuarios que han integrado una solución de almacenamiento de datos en el cloud y exportan API, informes del panel o informes CSV experimentan lo siguiente:

• Ninguna exportación de API devuelve una URL de descarga en el cuerpo de la respuesta, por lo que deben recuperarse a través del almacenamiento de datos.
• Todos los informes del panel y los informes CSV se envían al correo electrónico del usuario para su descarga (no se requieren permisos de almacenamiento) y se guardan como copia de seguridad en el almacenamiento de datos.

Error Unable to connect to S3, please validate that your credentials are correct

Si ves este error al descargar una exportación CSV, abre la integración de Amazon S3 en la página Socios tecnológicos y selecciona Probar credenciales. El resultado explica qué no superó la validación; por ejemplo, puede que a la clave le falte el permiso GetObject, lo que impide que Braze genere enlaces de descarga.

Actualiza tu política de IAM para que el usuario o rol de la integración pueda llamar a s3:GetObject en el contenedor de S3 y la ruta de objeto configurados en tu integración de Braze. Para otros problemas de exportación, consulta Solución de problemas de exportación.

Importante

Requisito de formato JSON: Para las exportaciones JSON, Braze utiliza el formato JSONL (JSON delimitado por saltos de línea), en el que cada línea contiene un objeto JSON independiente. Este formato difiere del JSON estándar, que es una única matriz u objeto JSON. Cada línea del archivo exportado es un objeto JSON válido, pero el archivo en su conjunto no es un único documento JSON válido. Al procesar estos archivos, analiza cada línea por separado como un objeto JSON independiente, en lugar de intentar analizar el archivo completo como un único documento JSON.

Las exportaciones de Currents utilizan el formato Apache Avro (archivos .avro), no JSON. Este requisito de formato JSON se aplica a las exportaciones de datos del panel y a las exportaciones de API.

Varios conectores

Si quieres crear más de un conector de Currents para enviar datos a tu contenedor de S3, puedes usar las mismas credenciales, pero debes especificar una ruta de carpeta distinta para cada uno. Puedes crearlos en el mismo espacio de trabajo o distribuirlos en varios espacios de trabajo. También tienes la opción de crear una política para cada integración o una sola política que cubra ambas integraciones.

Si piensas usar el mismo contenedor de S3 tanto para Currents como para las exportaciones de datos, necesitas crear dos políticas independientes, ya que cada integración requiere permisos diferentes.

Solución de problemas

Error: La cuenta no tiene acceso PutObject

Si ves el siguiente error al guardar las credenciales de Amazon S3 para las exportaciones de datos del panel, puede deberse a permisos incorrectos o a la configuración del cifrado del lado del servidor.

1

S3 Credentials are invalid because this account does not have 'PutObject access'. Please check the permissions and ensure that this key has access to 'PutObject' in the 'CUSTOMER-BUCKET-HERE' bucket.

Para resolver este problema, revisa los siguientes aspectos.

Política de contenedor incorrecta

Confirma que creaste una política con los permisos correctos, tal como se describe en Integración de Amazon S3 (utiliza la política Dashboard Data Export para tu método de autenticación).

Cifrado del lado del servidor

1

User: arn:aws:sts::XXX:assumed-role/braze-iam-role/braze is not authorized to perform: kms:GenerateDataKey on resource: arn:aws:XXX because no identity-based policy allows the kms:GenerateDataKey action

Si recibes este mensaje de error del soporte de Braze o en tus registros de AWS, tu contenedor de S3 está configurado con cifrado de AWS Key Management Service (SSE-KMS). Braze no admite SSE-KMS para Currents ni para las exportaciones de datos del panel. Para resolverlo, deshabilita SSE-KMS en tu contenedor de S3.

Nota

Braze admite el cifrado del lado del servidor mediante claves administradas por S3 (SSE-S3), que es compatible tanto con Currents como con las exportaciones de datos del panel.

Comprueba los permisos adicionales

Asegúrate de tener los permisos necesarios, incluidos s3:GetBucketLocation y s3:PutObject.