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.

Escrito por Beth-Ann Sher

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 ou importá-lo 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:

  • 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. Este é 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 seu 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 Verificar.

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 Filtros. Para usar um bucket diferente, clique em Alterar bucket e insira os novos detalhes.

Nota: A verificação 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 Verificar.

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

Na aba Filtros, em Escolher arquivos e mapeamento de tipo de arquivo, 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 Importa como, escolha o que cada tipo de arquivo se torna no Fin.

Esta tabela mostra as opções de Importa como 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

Artigo público, Artigo interno, Trecho

Artigo público

PDF

Artigo público, Artigo interno, Trecho, Documento

Documento

DOCX

Artigo público, Artigo interno, Trecho, Documento

Documento

HTML

Página web

Página web

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

Em Escolher quais arquivos sincronizar, selecione pastas e arquivos na lista Arquivos para sincronizar:

  • 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 posteriormente.

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

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

A lista Arquivos para sincronizar mostra pastas e apenas os tipos de arquivo que você escolheu.

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

Em Filtrar por metadados do arquivo, você pode adicionar regras para escolher quais arquivos selecionados do Amazon S3 serão sincronizados. 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 são sincronizados. 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 Destino, em Escolher acesso ao conteúdo, escolha onde o Fin usa o conteúdo sincronizado do Amazon S3:

  • Fin AI Agent: o 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 o Fin usa o conteúdo sincronizado. Clique em Próximo para revisar suas configurações.

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

Na aba Revisão, verifique suas configurações da fonte Amazon S3 em Revisar e finalizar. Depois, em Modo de sincronização, escolha como o conteúdo se mantém atualizado:

  • Sincronização contínua: mantém o conteúdo atualizado com o bucket todos os dias.

  • Importação única: copia os arquivos uma vez. Alterações posteriores no bucket não são sincronizadas.

Clique em Sincronizar e publicar para uma sincronização contínua, ou Importar e publicar 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-sincronizar: lê o bucket novamente agora. Fin ignora arquivos que não foram alterados.

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

  • Remover esta fonte: remove a fonte e todo seu conteúdo sincronizado, incluindo pastas e subpastas, do seu workspace.

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

Importante: Remover uma fonte Amazon S3 exclui todo o seu 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, ID da conta e prefixo: para usar um bucket diferente, remova a fonte e crie uma nova.

  • Mapeamento de tipo de arquivo: 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.

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


Perguntas frequentes

Quais tipos de arquivo o conteúdo do Amazon S3 suporta para sincronização?

A sincronização de conteúdo do Amazon S3 suporta arquivos Markdown (.md), PDF (.pdf), Word (.docx) e HTML (.html, .htm). Outros tipos de arquivo, 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 de arquivo:

Tipo de arquivo

Tamanho máximo

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.

Nota: 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 prefixo, pastas ou filtros para restringir sua seleção, ou crie mais fontes.

É possível sincronizar um bucket Amazon S3 em 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 quando 2 workspaces pertencem à 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 a sincronização de conteúdo do Amazon S3 suporta?

A sincronização de conteúdo 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 pode 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á ao arquivo movido uma nova impressão digital, 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 a sincronização de conteúdo do Amazon S3 copia?

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

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 Amazon S3 pode estar em qualquer região AWS. Fin armazena o conteúdo sincronizado na região do seu workspace.

Respondeu à sua pergunta?