Passar para o conteúdo principal

Sincronizar conteúdo do Amazon S3

Sincronize arquivos Markdown, PDF, DOCX e HTML de um bucket Amazon S3 para Fin, Copilot e seu Help Center, diariamente ou uma única vez.

Use este artigo para conectar um bucket Amazon S3 ao Fin, escolher quais arquivos sincronizar e o que eles se tornam, e entender os limites da sincronização de conteúdo do Amazon S3.

A sincronização de conteúdo do Amazon S3 copia arquivos de 1 bucket Amazon S3 para o Fin, para que o Fin AI Agent, Copilot e seu Help Center possam usá-los. Você escolhe quais pastas e arquivos sincronizar, e o que cada tipo de arquivo se torna: um artigo público, um artigo interno, um snippet ou um documento. Você pode manter o conteúdo atualizado com uma sincronização diária, ativar atualizações em tempo real para que as alterações nos arquivos sincronizem em poucos minutos, ou importar uma única vez.

Nota: A sincronização de conteúdo do Amazon S3 está em beta aberto. Está disponível tanto para quem usa Fin com Intercom quanto com outro helpdesk.


O que você precisa antes de sincronizar conteúdo do Amazon S3

Para configurar a sincronização de conteúdo do Amazon S3, você precisa de:

  • O nome do bucket. Cada fonte Amazon S3 lê arquivos de 1 bucket, que pode estar em qualquer região AWS.

  • O ID da conta AWS da conta que possui o bucket. É um número de 12 dígitos.

  • Permissão para editar a política do bucket na conta AWS que possui o bucket.

  • Permissão para editar a política da chave do AWS Key Management Service (KMS), somente se seus arquivos estiverem criptografados com uma chave KMS gerenciada pelo cliente.

Você não precisa criar uma função AWS Identity and Access Management (IAM) ou uma chave de acesso para a sincronização de conteúdo do Amazon S3. O Fin usa sua própria função somente leitura, então nenhuma credencial AWS é armazenada no seu workspace. Você concede acesso a essa função na política do seu bucket, apenas para esta fonte.

Quais permissões a política do bucket Amazon S3 concede ao Fin?

O Fin gera as declarações da política do bucket para sua fonte Amazon S3 durante a configuração. Esta tabela mostra as 4 permissões somente leitura que as declarações concedem ao Fin:

Declaração

Permissão

O que permite o Fin fazer

Listar

s3:ListBucket

Listar os arquivos no bucket, ou apenas os arquivos sob seu prefixo

Localização

s3:GetBucketLocation

Encontrar a região AWS do bucket

Ler

s3:GetObject

Ler os arquivos

Tags

s3:GetObjectTagging

Ler tags dos arquivos, para que você possa filtrá-las

Nota: A política do bucket Amazon S3 não concede ao Fin nenhuma permissão para escrever, alterar ou excluir arquivos no seu bucket.

Este exemplo mostra as declarações da política do bucket geradas para uma fonte Amazon S3 que usa o prefixo docs/. Os valores em maiúsculas, como YOUR_BUCKET e SOURCE_ID, são espaços reservados. O Fin preenche os valores reais para sua fonte durante a configuração.

[
  {
    "Sid": "FinContentSyncListSOURCE_ID",
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::FIN_ACCOUNT_ID:role/s3-content-sync-role" },
    "Action": "s3:ListBucket",
    "Resource": "arn:aws:s3:::YOUR_BUCKET",
    "Condition": {
      "StringEquals": { "aws:userid": "FIN_ROLE_ID:SOURCE_ID" },
      "StringLike": { "s3:prefix": "docs/*" }
    }
  },
  {
    "Sid": "FinContentSyncLocationSOURCE_ID",
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::FIN_ACCOUNT_ID:role/s3-content-sync-role" },
    "Action": "s3:GetBucketLocation",
    "Resource": "arn:aws:s3:::YOUR_BUCKET",
    "Condition": {
      "StringEquals": { "aws:userid": "FIN_ROLE_ID:SOURCE_ID" }
    }
  },
  {
    "Sid": "FinContentSyncReadSOURCE_ID",
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::FIN_ACCOUNT_ID:role/s3-content-sync-role" },
    "Action": "s3:GetObject",
    "Resource": "arn:aws:s3:::YOUR_BUCKET/docs/*",
    "Condition": {
      "StringEquals": { "aws:userid": "FIN_ROLE_ID:SOURCE_ID" }
    }
  },
  {
    "Sid": "FinContentSyncTagsSOURCE_ID",
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::FIN_ACCOUNT_ID:role/s3-content-sync-role" },
    "Action": "s3:GetObjectTagging",
    "Resource": "arn:aws:s3:::YOUR_BUCKET/docs/*",
    "Condition": {
      "StringEquals": { "aws:userid": "FIN_ROLE_ID:SOURCE_ID" }
    }
  }
]

Sem um prefixo, a declaração List não tem condição s3:prefix, e as declarações Read e Tags usam o Amazon Resource Name (ARN) arn:aws:s3:::YOUR_BUCKET/* como recurso.

Se seus arquivos estiverem criptografados com uma chave KMS gerenciada pelo cliente, o Fin também gera 1 declaração de política de chave para sua fonte Amazon S3:

{
  "Sid": "FinContentSyncDecryptSOURCE_ID",
  "Effect": "Allow",
  "Principal": { "AWS": "arn:aws:iam::FIN_ACCOUNT_ID:role/s3-content-sync-role" },
  "Action": "kms:Decrypt",
  "Resource": "*",
  "Condition": {
    "StringEquals": {
      "aws:userid": "FIN_ROLE_ID:SOURCE_ID",
      "kms:ViaService": "s3.BUCKET_REGION.amazonaws.com"
    }
  }
}

A condição kms:ViaService significa que o Fin só pode usar a chave KMS para ler arquivos do Amazon S3 na região do seu bucket.


Como sincronizar conteúdo do Amazon S3

Passo 1: Adicione o Amazon S3 como fonte

Para adicionar o Amazon S3 como fonte de conteúdo, vá para Fin AI Agent > Train > Content. Em “Add content”, clique em From Amazon S3.

A configuração do Amazon S3 tem 4 abas: Connect, Filters, Target e Review.

Passo 2: Insira os detalhes do seu bucket Amazon S3

Na aba Connect, em Bucket, insira os detalhes do seu bucket Amazon S3:

  • Nome do bucket: por exemplo, my-help-docs-bucket.

  • ID da conta AWS: o ID de 12 dígitos da conta AWS que possui o bucket.

  • Prefixo (opcional): um caminho de pasta, por exemplo docs/, para sincronizar apenas de 1 pasta. O prefixo não pode conter *, ? ou $.

Clique em Next para ver a política do seu bucket.

Passo 3: Adicione a política do bucket e verifique o acesso

Depois de inserir os detalhes do seu bucket, o Fin mostra uma seção Bucket policy com as declarações geradas para sua fonte Amazon S3. Para dar acesso ao Fin ao seu bucket:

  1. Abra seu bucket no console Amazon S3 e edite a política do bucket.

  2. No Fin, copie as Bucket policy statements. Clique em Show full policy para ver todas.

  3. Adicione as declarações à lista Statement da política do seu bucket.

  4. Se seus arquivos usam uma chave KMS gerenciada pelo cliente, copie também a Key policy statement do Fin e adicione-a à política da chave dessa chave.

  5. Salve a política do bucket.

  6. No Fin, clique em Verify.

Importante: Adicione as declarações geradas à sua política de bucket existente. Não substitua toda a política do bucket, pois isso remove qualquer acesso que ela já concede a outros users e serviços.

Quando a verificação passar, o Fin abrirá a aba Filters. Para usar um bucket diferente, clique em Change bucket e insira os novos detalhes.

Nota: O Verify precisa de pelo menos 1 arquivo não vazio no seu bucket, ou sob seu prefixo, para testar o acesso do Fin. Se o bucket ou prefixo estiver vazio, adicione um arquivo antes de clicar em Verify.

Como ativar atualizações em tempo real para Amazon S3 (opcional)

Atualizações em tempo real para Amazon S3 sincronizam alterações de arquivos em poucos minutos em vez de uma vez por dia. Atualizações em tempo real usam um tópico de evento Amazon Simple Notification Service (SNS) na conta AWS que possui o bucket.

Para ativar atualizações em tempo real na aba Connect da sua fonte Amazon S3:

  1. Ative Real-time updates.

  2. Em CloudFormation (recommended), clique em Download template e implante a stack na Região AWS que o Fin mostra, na conta AWS que possui o bucket. Para configurar o tópico você mesmo, use Manual setup.

  3. Espere até que Topic subscribed mostre “Connected”.

  4. No console Amazon S3, adicione uma notificação de evento ao seu bucket. Defina o destino para o tópico SNS e use a saída TopicArn da sua stack (CloudFormation > sua stack > Outputs > TopicArn). Use o prefixo e eventos que o Fin mostra nas etapas de configuração: Todos os eventos de criação de objeto, Todos os eventos de remoção de objeto, Expiração do ciclo de vida e Todos os eventos de marcação de objeto.

Quando Topic subscribed e Bucket events mostrarem “Connected”, as atualizações em tempo real para Amazon S3 estarão configuradas. Last event mostra quando o Fin recebeu a última alteração do seu bucket.

Nota: Você pode terminar de configurar as atualizações em tempo real depois de salvar sua fonte Amazon S3. As atualizações em tempo real ficam aguardando até que eventos do seu bucket cheguem.

Passo 4: Escolha quais arquivos sincronizar e como eles serão importados

Na aba Filters, em Choose files and file type mapping, escolha quais tipos de arquivo sincronizar do Amazon S3 e o que cada um se torna no Fin:

  • Tipos de arquivo: escolha quais tipos de arquivo sincronizar: Markdown, PDF, DOCX e HTML. Todos os 4 estão selecionados por padrão.

  • Mapeamento de tipos de arquivo: na coluna Imports as, escolha o que cada tipo de arquivo se torna no Fin.

Esta tabela mostra as opções de Imports as e o padrão para cada tipo de arquivo na sincronização de conteúdo do Amazon S3:

Tipo de arquivo

Opções

Padrão

Markdown

Public article, Internal article, Snippet

Public article

PDF

Public article, Internal article, Snippet, Document

Document

DOCX

Public article, Internal article, Snippet, Document

Document

HTML

Webpage

Webpage

Nota: Arquivos PDF e DOCX convertidos para artigo ou snippet podem perder parte da formatação, como tabelas e imagens. Para manter o máximo da formatação original possível, mapeie-os para Document.

Em Choose which files to sync, selecione pastas e arquivos na lista Files to sync:

  • Para abrir uma pasta, clique na seta ao lado dela.

  • Para sincronizar uma pasta inteira, selecione-a. Pastas selecionadas também incluem arquivos adicionados a elas depois.

  • Para sincronizar tudo no bucket, ou tudo sob seu prefixo, selecione Select all.

  • Para ver mais arquivos em uma pasta grande, clique em Load more.

A lista Files to sync mostra pastas e apenas os tipos de arquivo que você escolheu.

Passo 5: Filtrar arquivos Amazon S3 por metadados (opcional)

Em Filter by file metadata, você pode adicionar regras para escolher quais arquivos Amazon S3 selecionados sincronizam. Você pode filtrar por estes campos de arquivo:

  • Caminho da pasta

  • Nome do arquivo

  • Tamanho (bytes)

  • Última modificação

  • Tags (por exemplo, owner=support)

O Fin mostra quantos arquivos correspondem às suas regras.

Nota: A contagem de arquivos durante a configuração não inclui regras de tags, porque o Fin só lê tags quando os arquivos sincronizam. O número de arquivos que realmente sincronizam pode ser menor que a contagem mostrada.

Passo 6: Escolha quem pode usar o conteúdo sincronizado

Na aba Target, em Choose content access, escolha onde Fin usa o conteúdo sincronizado do Amazon S3:

  • Fin AI Agent: Fin usa o conteúdo para responder aos clientes.

  • Copilot: colegas podem usar o conteúdo no Copilot.

  • Help Center: artigos públicos ficam visíveis para clientes no seu Help Center. Se ativar isso, selecione um help center.

Você também pode adicionar regras de público para limitar para quais clientes Fin usa o conteúdo sincronizado. Clique em Next para revisar suas configurações.

Passo 7: Escolha um modo de sincronização e finalize

Na aba Review, verifique as configurações da fonte Amazon S3 em Review and finish. Depois, em Sync mode, escolha como o conteúdo será mantido atualizado:

  • Ongoing sync: mantém o conteúdo atualizado com o bucket diariamente. Se você ativou atualizações em tempo real, as alterações nos arquivos sincronizam em poucos minutos.

  • One-time import: copia os arquivos uma vez. Alterações posteriores no bucket não são sincronizadas.

Clique em Sync and publish para uma sincronização contínua, ou Import and publish para uma importação única. Fin começa a ler seus arquivos e você receberá um e-mail quando a sincronização terminar.


Como re-sincronizar, editar ou remover uma fonte Amazon S3

Para gerenciar uma fonte Amazon S3, vá até a fonte e abra o menu Manage. Você pode escolher:

  • Re-sync: lê o bucket novamente agora. Fin ignora arquivos que não foram alterados.

  • Edit source: altera a seleção de arquivos, filtros, acesso ao conteúdo e modo de sincronização.

  • Remove this source: remove a fonte e todo seu conteúdo sincronizado, incluindo pastas e subpastas, do seu workspace.

Note: As opções do menu Manage não estão disponíveis enquanto a fonte Amazon S3 estiver sincronizando.

Important: Remover uma fonte Amazon S3 exclui todo o conteúdo sincronizado do seu workspace, e isso não pode ser desfeito. Seus arquivos no Amazon S3 não são afetados.

O que você não pode alterar ao editar uma fonte Amazon S3?

Ao editar uma fonte Amazon S3, algumas configurações não podem ser alteradas:

  • Bucket, account ID, and prefix: para usar um bucket diferente, remova a fonte e crie uma nova.

  • File type mapping: isso não pode ser alterado após a primeira importação. Para mudar, remova a fonte e conecte-a novamente.

  • Help center: o help center escolhido durante a configuração não pode ser alterado.

  • Content access: as mudanças se aplicam apenas ao conteúdo sincronizado recentemente. O conteúdo existente mantém suas configurações atuais.


FAQs

Quais tipos de arquivo o conteúdo sincronizado do Amazon S3 suporta?

O conteúdo sincronizado do Amazon S3 suporta arquivos Markdown (.md), PDF (.pdf), Word (.docx) e HTML (.html, .htm). Outros tipos, como .doc, não aparecem na lista Files to sync e não são sincronizados.

Um arquivo PDF, DOCX ou HTML também é ignorado quando seu metadado Content-Type no Amazon S3 não corresponde à extensão do arquivo. Por exemplo, um PDF armazenado com Content-Type text/html não é sincronizado.

Qual é o tamanho máximo de arquivo para sincronização de conteúdo do Amazon S3?

Arquivos do Amazon S3 que ultrapassam o tamanho máximo para seu tipo são ignorados e não sincronizados. Esta tabela mostra o tamanho máximo para cada tipo:

File type

Maximum size

PDF, DOCX

100 MB

HTML

16 MB

Markdown

5 MB

Arquivos PDF e DOCX mapeados para um artigo ou snippet têm um segundo limite: seu texto convertido deve ter 5 MB ou menos, ou o arquivo é ignorado.

Note: Se um arquivo Amazon S3 já sincronizado ultrapassar seu tamanho máximo, a sincronização falha até que você reduza o arquivo ou o remova da seleção.

Quantos arquivos uma fonte Amazon S3 pode sincronizar?

Uma fonte Amazon S3 sincroniza até 100.000 arquivos. Se sua seleção tiver mais, Fin sincroniza os primeiros 100.000 e não remove o conteúdo já sincronizado do restante. Para ficar dentro do limite, use prefixos, pastas ou filtros para restringir sua seleção, ou crie mais fontes.

É possível sincronizar um bucket Amazon S3 para mais de uma fonte ou workspace?

Cada fonte Amazon S3 lê 1 bucket. Você pode criar várias fontes no mesmo bucket em um workspace, mas seus prefixos não podem se sobrepor.

Um bucket Amazon S3 pode pertencer a apenas 1 workspace, mesmo que 2 workspaces pertençam à mesma empresa. Se outro workspace já usa o bucket, o Verify mostra “Outro workspace Fin já usa este bucket. Use um bucket diferente.” O bucket fica disponível novamente quando a última fonte nele for removida.

Quais tipos de criptografia o conteúdo sincronizado do Amazon S3 suporta?

O conteúdo sincronizado do Amazon S3 lê arquivos criptografados com chaves gerenciadas pelo Amazon S3 (SSE-S3) ou com uma chave KMS gerenciada pelo cliente. Fin não consegue ler arquivos criptografados com a chave gerenciada pela AWS (aws/s3). Para sincronizar esses arquivos, criptografe-os com SSE-S3 ou uma chave gerenciada pelo cliente.

O que acontece quando você move ou renomeia um arquivo no Amazon S3?

Quando você move ou renomeia um arquivo Amazon S3 dentro da sua seleção sem alterar seu conteúdo, Fin mantém o mesmo item sincronizado e atualiza seu título e pasta. Às vezes, a AWS dá uma nova impressão digital ao arquivo movido, por exemplo, quando um arquivo grande é copiado em partes. Nesse caso, Fin adiciona o arquivo como um novo item e remove o antigo.

Quantos níveis de pasta o conteúdo sincronizado do Amazon S3 copia?

A sincronização de conteúdo do Amazon S3 copia a estrutura da sua pasta até 10 níveis de profundidade. Arquivos em pastas mais profundas vão para a pasta copiada mais profunda.

Qual idioma e coleção os artigos públicos sincronizados do Amazon S3 usam?

Artigos públicos sincronizados do Amazon S3 usam o idioma do help center que você escolheu. Eles não são adicionados a uma coleção.

Onde o conteúdo sincronizado do Amazon S3 é armazenado?

Seu bucket do Amazon S3 pode estar em qualquer região da AWS. Fin armazena o conteúdo sincronizado na região do seu workspace.

Respondeu à sua pergunta?