Amazon S3

O Amazon S3 é um sistema de armazenamento altamente escalável oferecido pela Amazon Web Services.

Importante

Se estiver alternando entre provedores de armazenamento em nuvem, entre em contato com o seu CSM da Braze para obter mais assistência na configuração e validação da nova integração.

A integração da Braze com o Amazon S3 apresenta duas estratégias de integração:

• Alavancar o Currents, que permite armazenar dados até que você queira conectá-los a outras plataformas, ferramentas e locais.
• Usar exportações de dados do dashboard (como exportações CSV e relatórios de engajamento).

Pré-requisitos

Criação de um novo bucket S3

Para criar um bucket para seu app, faça o seguinte:

1. Abra o console do Amazon S3 e siga as instruções para fazer login ou criar uma conta na AWS.
2. Depois de fazer login, selecione S3 na categoria Armazenamento e entrega de conteúdo.
3. Selecione Criar bucket na próxima tela.
4. Quando solicitado, crie seu bucket e selecione uma região da AWS.

A Braze não permite escolher nem configurar uma região no dashboard. A região da AWS é definida pelo local onde você cria o bucket no console da AWS. A integração envia os dados para o nome do bucket que você informar, e a AWS encaminha automaticamente as solicitações para a região do bucket. Se o seu conector tentar se conectar a uma região diferente da desejada (por exemplo, eu-west-1 em vez de eu-central-1), crie ou use um bucket S3 na região desejada na AWS. Não há nada para alterar do lado da Braze.

Nota

O Currents não oferece suporte a buckets com Object Lock configurado.

Integração

A Braze tem duas estratégias de integração diferentes com o Amazon S3: uma para o Braze Currents e outra para todas as exportações de dados do dashboard (como exportações CSV ou relatórios de engajamento). As duas integrações aceitam dois métodos diferentes de autenticação ou autorização:

• Método de chave de acesso secreta da AWS
• Método de ARN de função da AWS

Método de autenticação com chave secreta da AWS

Esse método de autenticação gera uma chave secreta e um ID de chave de acesso. Com eles, a Braze se autentica como um usuário na sua conta da AWS para gravar dados no seu bucket.

Etapa 1: Criar usuário

Nota

Se você estiver configurando apenas o arquivamento de mensagens, siga as etapas na guia Dashboard Data Export.

Para obter seu ID de chave de acesso e sua chave de acesso secreta, crie um usuário IAM e um grupo de administradores na AWS.

Etapa 2: Obter credenciais

Depois de criar um novo usuário, selecione Show User Security Credentials para exibir seu ID de chave de acesso e sua chave de acesso secreta. Em seguida, anote essas credenciais em algum lugar ou selecione o botão Download Credentials, pois você precisará inseri-las no dashboard da Braze mais tarde.

Etapa 3: Criar política

Acesse Policies > Get Started > Create Policy para adicionar permissões ao seu usuário. Em seguida, selecione Create Your Own Policy. Isso concede permissões limitadas, então a Braze só pode acessar os buckets especificados.

Nota

O Currents e o Dashboard Data Export exigem políticas diferentes. A permissão s3:GetObject é necessária para que o backend da Braze faça o tratamento de erros.

Defina um nome de política à sua escolha e insira o seguinte snippet de código na seção Policy Document. Substitua INSERTBUCKETNAME pelo nome do seu bucket. Sem essas permissões, a integração falha na verificação de credenciais e não é criada.

Nota

Se você estiver configurando apenas o arquivamento de mensagens, use o snippet de código na guia 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"]
        }
    ]
}

Etapa 4: Anexar política

Depois de criar uma nova política, acesse Users e selecione seu usuário específico. Na guia Permissions, selecione Attach Policy e escolha a nova política que você criou. Agora você está pronto para vincular suas credenciais da AWS à sua conta da Braze.

Etapa 5: Vincular a Braze à AWS

Nota

Se você estiver configurando apenas o arquivamento de mensagens, siga as etapas na guia Dashboard Data Export.

• braze currents
• dashboard data export

Na Braze, acesse Integrações de parceiros > Currents.

Em seguida, selecione Criar novo Current e depois Exportação de dados do Amazon S3.

Dê um nome ao seu Current. Na seção Credenciais, confirme que Chave de acesso secreta da AWS está selecionada. Depois, insira seu ID de acesso do S3, sua chave de acesso secreta da AWS e o nome do bucket do AWS S3 nos campos indicados.

Forneça um e-mail de contato para notificações de erros de integração. A Braze envia notificações para esse endereço se a integração encontrar erros, como problemas de credencial ou de conectividade. Para garantir que as pessoas certas recebam os alertas, use uma lista de distribuição ou um endereço de e-mail de grupo.

Aviso

Mantenha seu ID de chave de acesso e sua chave de acesso secreta da AWS atualizados. Se as credenciais do seu conector expirarem, o conector para de enviar eventos. Se isso persistir por mais de 5 dias, os eventos do conector serão descartados e os dados serão perdidos permanentemente.

Você também pode adicionar as seguintes personalizações, conforme suas necessidades:

• Caminho da pasta: O padrão é currents. Se essa pasta não existir, a Braze a cria automaticamente para você.
• Criptografia AES-256 no lado do servidor, em repouso: O padrão é DESATIVADO e inclui o cabeçalho x-amz-server-side-encryption.

Selecione Lançar Current para continuar.

Uma notificação informa se suas credenciais foram validadas com sucesso. O AWS S3 agora está configurado para o Braze Currents.

Na Braze, acesse Integrações de parceiros > Parceiros de tecnologia e selecione Amazon S3.

Na página Credenciais da AWS, confirme que Chave de acesso secreta da AWS está selecionada. Depois, insira seu ID de acesso da AWS, sua chave de acesso secreta da AWS e o nome do bucket do AWS S3 nos campos indicados. Ao inserir sua chave secreta, selecione primeiro Testar credenciais para garantir que suas credenciais funcionam e, se o teste for bem-sucedido, selecione Salvar.

Dica

Você pode obter novas credenciais a qualquer momento: no Console da AWS, acesse seu usuário e selecione Create Access Key na guia Security Credentials.

Uma notificação informa se suas credenciais foram validadas com sucesso. O AWS S3 agora está integrado à sua conta da Braze.

Método de autenticação por ARN de função da AWS

Esse método de autenticação gera um Amazon Resource Name (ARN) de função que permite que a conta Amazon da Braze se autentique como membro da função que você criou para gravar dados no seu bucket.

Etapa 1: Criar política

Para começar, faça login no console de gerenciamento da AWS como administrador da conta. Acesse a seção IAM do Console da AWS, selecione Policies na barra de navegação e selecione Create Policy.

Nota

São necessárias políticas diferentes para o Currents e para a exportação de dados do dashboard. A permissão s3:GetObject é necessária para que o backend da Braze possa fazer o tratamento de erros.

Abra a guia JSON e insira o seguinte snippet de código na seção Policy Document. Substitua INSERTBUCKETNAME pelo nome do seu bucket. Selecione Review Policy quando terminar.

Nota

Se você estiver configurando apenas o arquivamento de mensagens, use o snippet de código da guia 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/*"]
        }
    ]
}

Em seguida, dê um nome e uma descrição à política e selecione Create Policy.

Etapa 2: Criar função

Na mesma seção IAM do console, selecione Roles > Create Role.

Obtenha o ID da conta da Braze e o ID externo na sua conta da Braze:

• Currents: Na Braze, acesse Integrações de parceiros > Currents. Em seguida, selecione Criar novo Current e depois Exportação de dados do Amazon S3. Aqui você encontrará os identificadores necessários para criar sua função.
• Exportação de dados do dashboard: Na Braze, acesse Integrações de parceiros > Parceiros de tecnologia e selecione Amazon S3. Aqui você encontrará os identificadores necessários para criar sua função. (Crie suas funções aqui se estiver configurando apenas o arquivamento de mensagens.)

De volta ao Console da AWS, selecione Another AWS Account como tipo de seletor de entidade confiável. Informe o ID da conta da Braze, marque a caixa Require external ID e insira o ID externo da Braze. Selecione Next quando terminar.

Etapa 3: Anexar política

Em seguida, anexe à função a política que você criou anteriormente. Pesquise a política na barra de pesquisa e marque a caixa de seleção ao lado dela para anexá-la. Selecione Next quando terminar.

Dê um nome e uma descrição à função e selecione Create Role.

Agora você verá a função recém-criada na lista.

Etapa 4: Vincular à AWS da Braze

No Console da AWS, encontre a função recém-criada na lista. Selecione o nome para abrir os detalhes dessa função.

Anote o Role ARN no topo da página de resumo da função.

Volte para sua conta da Braze e copie o ARN da função no campo indicado.

Nota

Se você estiver configurando apenas o arquivamento de mensagens, siga as etapas da guia Dashboard Data Export.

• braze currents
• dashboard data export

Na Braze, acesse Integrações de parceiros > Currents. Em seguida, selecione Criar novo Current e selecione Exportação de dados do Amazon S3.

Dê um nome ao seu Current. Depois, na seção Credenciais, confirme que AWS Role ARN está selecionado e informe o ARN da sua função e o nome do bucket S3 da AWS nos campos indicados.

Forneça um e-mail de contato para notificações de erros de integração. A Braze envia notificações para esse endereço se a integração encontrar erros, como problemas de credencial ou de conectividade. Para garantir que as pessoas certas recebam os alertas, use uma lista de distribuição ou um endereço de e-mail de grupo.

Você também pode adicionar as seguintes personalizações conforme suas necessidades:

• Caminho da pasta (o padrão é currents)
• Criptografia AES-256 do lado do servidor, em repouso (o padrão é DESATIVADO) - Inclui o cabeçalho x-amz-server-side-encryption

Selecione Iniciar Current para continuar. Uma notificação indica se suas credenciais foram validadas com sucesso. O AWS S3 agora está configurado para o Braze Currents.

Importante

Se você receber o erro “S3 credentials are invalid”, isso pode ter ocorrido porque a integração foi feita muito rapidamente após a criação da função na AWS. Aguarde e tente novamente. Se a mensagem mencionar acesso PutObject ou criptografia do lado do servidor em exportações de dados do dashboard, consulte Solução de problemas de erros de credenciais do S3.

Na Braze, acesse a página Parceiros de tecnologia em Integrações e selecione Amazon S3.

Na página Credenciais da AWS, confirme que o botão de opção AWS Role ARN está selecionado e insira o ARN da sua função e o nome do bucket S3 da AWS nos campos indicados. Primeiro, selecione Testar credenciais para confirmar que suas credenciais funcionam corretamente e, se der certo, selecione Salvar.

Dica

Você pode obter novas credenciais a qualquer momento acessando seu usuário e selecionando Create Access Key na guia Security Credentials do Console da AWS.

Uma notificação informa se suas credenciais foram validadas com sucesso. O AWS S3 agora está integrado à sua conta da Braze.

Considerações de segurança para o método de ARN de função

Quando você seleciona Another AWS Account e insere o ID da conta da Braze na Etapa 2, a AWS cria uma política de confiança cujo Principal é a raiz da conta AWS da Braze (arn:aws:iam::<BRAZE_ACCOUNT_ID>:root). Se sua equipe de segurança revisar essa política de confiança, observe o seguinte:

• A Braze usa um usuário IAM compartilhado para assumir sua função.
• O ID externo é obrigatório. Mantenha a condição sts:ExternalId na sua política de confiança, inclusive quando restringir o principal a um usuário IAM específico.
• Você pode restringir o principal a um usuário IAM específico. Se sua política de segurança não permitir confiar na raiz de uma conta, você pode substituir o Principal pelo ARN do usuário IAM da Braze. Para obter esse ARN para sua região, entre em contato com o suporte da Braze.
• O usuário IAM da Braze pode mudar. O principal costuma ser estável, mas a Braze pode alterá-lo no futuro. Se você restringir sua política de confiança a um usuário IAM específico e esse usuário mudar, a Braze não conseguirá assumir sua função até que você atualize a política de confiança.
• Os principais variam conforme o produto. O Currents e as exportações de dados do dashboard usam o mesmo usuário IAM da Braze. A ingestão de dados na nuvem usa um principal diferente, em outra conta da AWS, então configure a política de confiança dela separadamente.

Atualização das credenciais do Amazon S3 para Currents

Você pode atualizar as credenciais do Amazon S3 em um conector Braze Currents existente sem interromper a integração ou perder dados já exportados para o seu bucket.

Para atualizar as credenciais — ou para alternar entre AWS Secret Access Key e AWS Role ARN — conclua as etapas do lado do IAM e da AWS para o método escolhido descritas anteriormente neste artigo (políticas, usuário ou função e identificadores conforme necessário).

Quando terminar de preparar as credenciais na AWS, acesse Integrações de parceiros > Currents na Braze, localize seu conector Amazon S3 na lista, selecione Edit, atualize as Credentials e selecione Update Current. A Braze valida as credenciais inseridas; seu conector continua funcionando e os dados já no seu bucket permanecem disponíveis. Para saber mais, consulte Atualização de Currents em Configurar Currents.

Como o Currents faz upload de arquivos para o S3

O Currents fecha cada arquivo Avro quando ele atinge o limite de gravação Avro. Em seguida, faz o upload do arquivo concluído para o seu bucket usando o upload multiparte do Amazon S3 em partes de 5 MB. O upload multiparte é independente do limite de gravação e geralmente termina poucos segundos depois que o arquivo é fechado.

O Amazon S3 não expõe um upload multiparte em andamento como um objeto. Um arquivo do Currents só fica visível para ListObjectsV2 e GetObject depois que o upload é concluído. Portanto, os processos downstream que leem seu bucket pelas APIs padrão do S3 não veem arquivos parcialmente enviados.

Comportamento da exportação

Os usuários que integraram uma solução de armazenamento de dados em nuvem e exportam APIs, relatórios do dashboard ou relatórios CSV observam o seguinte:

• Nenhuma exportação de API retorna um URL de download no corpo da resposta. Esses arquivos precisam ser recuperados pelo armazenamento de dados.
• Todos os relatórios do dashboard e relatórios CSV são enviados para o e-mail do usuário para download (sem necessidade de permissões de armazenamento) e ficam com backup no armazenamento de dados.

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

Se você vir esse erro ao baixar uma exportação CSV, abra a integração com o Amazon S3 na página Parceiros de tecnologia e selecione Testar credenciais. O resultado explica o que falhou na validação. Por exemplo, a chave pode não ter a permissão GetObject, o que impede a Braze de gerar links de download.

Atualize sua política do IAM para que o usuário ou a função da integração possa chamar s3:GetObject no bucket S3 e no caminho de objeto configurados na sua integração com a Braze. Para outros problemas de exportação, consulte Solução de problemas de exportação.

Importante

Requisito de formato JSON: Para exportações em JSON, a Braze usa o formato JSONL (JSON delimitado por nova linha), em que cada linha contém um objeto JSON separado. Esse formato é diferente do JSON padrão, que é um único array ou objeto JSON. Cada linha do arquivo exportado é um objeto JSON válido, mas o arquivo como um todo não é um documento JSON único e válido. Ao processar esses arquivos, analise cada linha individualmente como um objeto JSON separado, em vez de tentar analisar o arquivo inteiro como um único documento JSON.

As exportações do Currents usam o formato Apache Avro (arquivos .avro), não JSON. Esse requisito de formato JSON se aplica às exportações de dados do dashboard e às exportações de API.

Vários conectores

Se você pretende criar mais de um conector do Currents para enviar ao seu bucket S3, pode usar as mesmas credenciais, mas precisa especificar um caminho de pasta diferente para cada um. Você pode criá-los no mesmo espaço de trabalho ou dividi-los entre vários espaços de trabalho. Também é possível criar uma política para cada integração ou uma única política que abranja as duas integrações.

Se você planeja usar o mesmo bucket S3 tanto para o Currents quanto para exportações de dados, precisa criar duas políticas separadas, pois cada integração exige permissões diferentes.

Solução de problemas

Erro: a conta não tem acesso PutObject

Se você vir o erro a seguir ao salvar as credenciais do Amazon S3 para exportações de dados do dashboard, o motivo pode ser permissões incorretas ou configurações de criptografia no lado do 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 esse problema, verifique os pontos a seguir.

Política de bucket incorreta

Confirme que você criou uma política com as permissões corretas, conforme descrito em Integração com o Amazon S3 (use a política Dashboard Data Export para o seu método de autenticação).

Criptografia no lado do 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

Você pode receber essa mensagem de erro do suporte da Braze ou encontrá-la nos seus logs da AWS. Nesse caso, seu bucket S3 está configurado com criptografia do AWS Key Management Service (SSE-KMS). A Braze não oferece suporte a SSE-KMS para Currents nem para exportações de dados do dashboard. Para resolver, desative a SSE-KMS no seu bucket S3.

Nota

A Braze oferece suporte à criptografia no lado do servidor com chaves gerenciadas pelo S3 (SSE-S3), que é compatível tanto com Currents quanto com exportações de dados do dashboard.

Verifique permissões adicionais

Confira se você tem as permissões necessárias, incluindo s3:GetBucketLocation e s3:PutObject.