Amazon S3
O Amazon S3 é um sistema de armazenamento altamente escalável oferecido pela Amazon Web Services.
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
| Requisito | Descrição |
|---|---|
| Conta Amazon S3 | Você precisa de uma conta Amazon S3 para aproveitar essa parceria. |
| Bucket S3 dedicado | Antes de fazer a integração com o Amazon S3, você precisa criar um bucket S3 para seu app. Se você já tem um bucket S3, ainda recomendamos criar um novo bucket especificamente para a Braze, para que você possa limitar as permissões. Confira as instruções a seguir sobre como criar um novo bucket. |
| Currents | Para exportar dados de volta para o Amazon S3, é necessário ter o Braze Currents configurado na sua conta. O Currents não é necessário se você estiver configurando apenas o arquivamento de mensagens. |
Criar um novo bucket S3
Para criar um bucket para seu app, faça o seguinte:
- Abra o console do Amazon S3 e siga as instruções para fazer login ou criar uma conta na AWS.
- Depois de fazer login, selecione S3 na categoria Storage & Content Delivery.
- Selecione Create Bucket na próxima tela.
- 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 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 a alterar do lado da Braze.
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 de CSV ou relatórios de engajamento). As duas integrações aceitam dois métodos diferentes de autenticação ou autorização:
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 que permitem à Braze se autenticar como um usuário na sua conta da AWS para gravar dados no seu bucket.
Etapa 1: Criar usuário
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, porque você vai 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. Depois, selecione Create Your Own Policy. Isso concede permissões limitadas, para que a Braze só possa acessar os buckets especificados.
O Currents e a exportação de dados do dashboard exigem políticas diferentes. A permissão s3:GetObject é necessária para que o backend da Braze possa fazer o tratamento de erros.
Defina um nome de política à sua escolha e insira o snippet de código a seguir 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.
Se você estiver configurando apenas o arquivamento de mensagens, use o snippet de código na guia Dashboard Data Export.
{
"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/*"]
}
]
}
{
"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ê já pode vincular suas credenciais da AWS à sua conta da Braze.
Etapa 5: Vincular a Braze à AWS
Se você estiver configurando apenas o arquivamento de mensagens, siga as etapas na guia 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, confira se a opção Chave de acesso secreta da AWS está selecionada e insira seu ID de acesso do S3, sua chave de acesso secreta da AWS e o nome do seu 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.
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 são descartados e os dados são perdidos permanentemente.
Você também pode adicionar as seguintes personalizações, de acordo com suas necessidades:
- Caminho da pasta: O padrão é
currents. Se essa pasta não existir, a Braze cria uma automaticamente para você. - Criptografia AES-256 em repouso no lado do servidor: O padrão é DESATIVADO e inclui o cabeçalho
x-amz-server-side-encryption.
Selecione Iniciar 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, confira se a opção Chave de acesso secreta da AWS está selecionada e insira seu ID de acesso da AWS, sua chave de acesso secreta da AWS e o nome do seu bucket S3 da AWS 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.
Você pode obter novas credenciais a qualquer momento acessando seu usuário e selecionando Create Access Key na guia Security Credentials do AWS Console.
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 da função 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 AWS, selecione Policies na barra de navegação e selecione Create Policy.
O Currents e a exportação de dados do dashboard exigem políticas diferentes. A permissão s3:GetObject é necessária para que o backend da Braze faça 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.
Se você estiver configurando apenas o arquivamento de mensagens, use o snippet de código da guia Dashboard Data Export.
{
"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/*"]
}
]
}
{
"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 Braze e o ID externo na sua conta 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ê encontra 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ê encontra os identificadores necessários para criar sua função. (Crie suas funções aqui se você estiver configurando apenas o arquivamento de mensagens.)
De volta ao Console AWS, selecione Another AWS Account como tipo de seletor de entidade confiável. Informe o ID da sua conta 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 ao lado dela para anexá-la. Selecione Next quando terminar.
Dê um nome e uma descrição à função e selecione Create Role.
Agora, a função recém-criada aparece na lista.
Etapa 4: Vincular à AWS da Braze
No Console 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 Braze e copie o ARN da função no campo indicado.
Se você estiver configurando apenas o arquivamento de mensagens, siga as etapas da guia 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. Depois, na seção Credenciais, confirme que ARN da função AWS está selecionado e informe o ARN da função e o nome do bucket 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.
Você também pode adicionar as seguintes personalizações, conforme suas necessidades:
- Caminho da pasta (o padrão é
currents) - Criptografia AES-256 em repouso no lado do servidor (o padrão é DESATIVADO) - Inclui o cabeçalho
x-amz-server-side-encryption
Selecione Iniciar Current para continuar. Uma notificação informa se suas credenciais foram validadas com sucesso. O AWS S3 agora está configurado para o Braze Currents.
Se você receber o erro “S3 credentials are invalid”, isso pode acontecer por fazer a integração muito rápido depois de criar uma função na AWS. Aguarde e tente novamente. Se a mensagem mencionar acesso PutObject ou criptografia no lado do servidor em exportações de dados do dashboard, consulte Solução de problemas de erros de credencial do S3.
Na Braze, acesse a página Parceiros de tecnologia em Integrações e selecione Amazon S3.
Na página Credenciais AWS, confirme que o botão de opção ARN da função AWS está selecionado e insira o ARN da função e o nome do bucket AWS S3 nos campos indicados. Primeiro, selecione Testar credenciais para confirmar que suas credenciais funcionam corretamente. Depois, selecione Salvar se o teste for bem-sucedido.
Você pode obter novas credenciais a qualquer momento acessando seu usuário e selecionando Create Access Key na guia Security Credentials do Console AWS.
Uma notificação informa se suas credenciais foram validadas com sucesso. O AWS S3 agora está integrado à sua conta Braze.
Considerações de segurança para o método de ARN da função
Quando você seleciona Another AWS Account e insere o ID da conta 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:ExternalIdna 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
Principalpelo 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 geralmente é 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 de acordo com 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 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 trocar o bucket do arquivamento de mensagens
O arquivamento de mensagens continua funcionando enquanto você troca para um novo bucket S3 ou uma nova função IAM. A Braze só salva suas novas configurações depois que o teste de credenciais é aprovado. Assim, o arquivamento sempre aponta para um destino que está funcionando.
A alteração não entra em vigor imediatamente. Por um curto período depois que você salva, a Braze ainda pode usar suas configurações anteriores:
- Seu bucket anterior ainda pode receber algumas mensagens arquivadas, por exemplo, de envios que já estavam em andamento.
- Sua função IAM anterior ainda pode ser usada para gravar no novo bucket, se você usa autenticação baseada em função e alterou o ARN da função.
Não remova o acesso ao bucket ou à função anterior até que novos arquivos estejam chegando ao novo bucket por vários minutos. Isso confirma que a migração foi concluída. Se você alterar o ARN da função, garanta que a função anterior também possa gravar no novo bucket até lá. Caso contrário, as mensagens arquivadas durante a troca podem não ser salvas, e não haverá nova tentativa.
Como o Currents faz upload de arquivos para o S3
O Currents fecha cada arquivo Avro quando ele atinge o limite de gravação do Avro. Em seguida, faz upload do arquivo concluído para o seu bucket usando o upload multiparte do Amazon S3, em partes de 5 MB. O upload multiparte é separado do limite de gravação e normalmente termina poucos segundos depois que o arquivo é fechado.
O Amazon S3 não expõe como objeto um upload multiparte que ainda está em andamento. Um arquivo do Currents só fica visível para ListObjectsV2 e GetObject depois que o upload é concluído. Portanto, os processos downstream que leem o seu bucket pelas APIs padrão do S3 não veem arquivos enviados parcialmente.
Comportamento de exportação
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 comportamento:
- Nenhuma exportação de API retorna um URL de download no corpo da resposta. Esses arquivos devem ser recuperados pelo armazenamento de dados.
- Todos os relatórios do dashboard e relatórios CSV são enviados ao e-mail do usuário para download (não é necessário ter permissões de armazenamento) e ficam salvos como 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, pode ser que a chave não tenha a permissão GetObject, o que impede a Braze de gerar links de download.
Atualize sua política 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.
Requisito de formato JSON: Nas 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 válido único. 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), e 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 dados ao seu bucket S3, pode usar as mesmas credenciais, mas precisa especificar um caminho de pasta diferente para cada um. Você pode criar esses conectores no mesmo espaço de trabalho ou distribuí-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 abaixo ao salvar as credenciais do Amazon S3 para exportações de dados do dashboard, a causa pode ser permissões incorretas ou configurações de criptografia do lado do servidor.
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 do lado do servidor
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
Se você receber essa mensagem de erro do suporte da Braze ou nos seus logs da AWS, 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 isso, desative a SSE-KMS no seu bucket S3.
A Braze oferece suporte à criptografia do 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.