Transferências do Amazon S3

Com o serviço de transferência de dados do BigQuery para Amazon S3, é possível programar e gerenciar automaticamente jobs de carregamento recorrentes do Amazon S3 para o BigQuery.

Antes de começar

Antes de criar uma transferência do Amazon S3, faça o seguinte:

Limitações

As transferências do Amazon S3 estão sujeitas às limitações a seguir:

  • Atualmente, a parte do intervalo do URI do Amazon S3 não pode ser parametrizada.
  • As transferências do Amazon S3 são sempre acionadas com a preferência WRITE_APPEND, que anexa dados à tabela de destino. Consulte configuration.load.writeDisposition na configuração do job de carregamento para mais detalhes.
  • Dependendo do formato dos dados de origem do Amazon S3, pode haver outras limitações. Veja mais informações em:

Permissões exigidas

Antes de criar uma transferência do Amazon S3, siga estas recomendações:

  • Certifique-se de que a pessoa que está criando a transferência tenha as seguintes permissões obrigatórias no BigQuery:

    • Permissões bigquery.transfers.update para criar a transferência
    • Permissões bigquery.datasets.update no conjunto de dados de destino

    O papel predefinido bigquery.admin do Cloud IAM inclui as permissões bigquery.transfers.update e bigquery.datasets.update. Para mais informações sobre os papéis do Cloud IAM no serviço de transferência de dados do BigQuery, consulte a Referência do controle de acesso.

  • Consulte a documentação do Amazon S3 para garantir que você tenha configurado as permissões necessárias para ativar a transferência. No mínimo, os dados de origem do Amazon S3 precisam ter a política AmazonS3ReadOnlyAccess (em inglês) gerenciada pela AWS.

Como configurar uma transferência de dados do Amazon S3

Para criar uma transferência de dados do Amazon S3:

Console

  1. Acesse a IU da Web do BigQuery no Console do Cloud.

    Acessar o Console do Cloud

  2. Clique em Transferências.

  3. Clique em Criar uma transferência.

  4. Na página Criar transferência:

    • Na seção Tipo de origem, em Origem, escolha Amazon S3.

      Fonte da transferência

    • No campo Nome da configuração de transferência da seção Nome de exibição, insira um nome para a transferência, como My Transfer. Esse nome pode ter qualquer valor que identifique facilmente a transferência, caso seja necessário modificá-la futuramente.

      Nome da transferência

    • Na seção Opções de programação, não altere o valor padrão de Programação (Começar agora). Se preferir, clique em Começar no horário definido.

      • Em Repetições, escolha uma opção para a frequência de execução da transferência. As opções incluem:

        • Diário (padrão)
        • Semanal
        • Mensal
        • Personalizada
        • Sob demanda

        Se você escolher uma opção diferente de "Diário", outras opções estarão disponíveis. Por exemplo, se você escolher "Semanal", aparecerá uma opção para selecionar o dia da semana.

      • Para Data e hora de início, insira a data e a hora para iniciar a transferência. Se você escolher Iniciar agora, essa opção ficará desativada.

        Programação da transferência

    • Na seção Configurações de destino, em Conjunto de dados de destino, escolha o conjunto criado para armazenar seus dados.

      Transferir conjunto de dados

    • Na seção Detalhes da origem de dados:

      • Em Tabela de destino, insira o nome da tabela criada para armazenar os dados no BigQuery. Os nomes de tabelas de destino aceitam parâmetros.
      • Em URI do Amazon S3, insira o URI neste formato: s3://mybucket/myfolder/.... Os URIs também aceitam parâmetros.
      • Em ID da chave de acesso, insira seu ID da chave de acesso.
      • Em Chave de acesso secreta, insira sua chave de acesso secreta.
      • Em Formato de arquivo, escolha seu formato de dados: JSON delimitado por nova linha, CSV, Avro, Parquet ou ORC.

        Detalhes da fonte do S3

    • Na seção Opções de transferência, em Número de erros permitidos, insira um valor inteiro para o número máximo de registros inválidos que podem ser ignorados.

      Número de erros permitido

    • Se você escolheu CSV ou JSON como seu formato de arquivo, na seção JSON, CSV, marque Ignorar valores desconhecidos para aceitar linhas que contenham valores que não correspondam ao esquema. Valores desconhecidos são ignorados. Para arquivos CSV, essa opção ignora valores extras no final de uma linha.

      Ignorar valores desconhecidos

    • Se você escolheu CSV como seu formato de arquivo, na seção CSV, insira outras opções de CSV para carregar os dados.

      Opções de CSV

    • Opcional: na seção Opções de notificação:

      • Clique no botão para ativar as notificações por e-mail. Quando você ativa essa opção, o administrador de transferência recebe uma notificação por e-mail quando uma execução de transferência falha.
      • Em Selecionar um tópico do Pub/Sub, escolha o nome do seu tópico ou clique em Criar um tópico. Essa opção configura notificações de execução do Pub/Sub para sua transferência.
  5. Clique em Save.

IU clássica

  1. Acesse a IU da Web do BigQuery.

    Acessar a IU da Web do BigQuery

  2. Clique em Transferências.

  3. Clique em Adicionar transferência.

  4. Na página Nova transferência, siga estas etapas:

    • Em Origem, escolha Amazon S3.
    • Em Display Name, insira um nome para a transferência, como My Transfer. Esse nome pode ser qualquer valor de fácil identificação. Ele será necessário, caso precise ser modificado mais tarde.
    • (Opcional) Em Programação, deixe o valor padrão Diário (a cada 24 horas, com base no horário da criação) ou clique em Editar para alterar esse valor. Também é possível alterar o intervalo para "Semanal", "Mensal" ou "Personalizado". Se você selecionar "Personalizado", especifique um horário em estilo Cron, como every 12 hours. O período mais curto permitido é de 12 horas. Veja o campo schedule em TransferConfig para saber outros valores de API válidos.
    • Em Destination dataset, escolha o conjunto apropriado.
    • Em Tabela de destino, insira o nome da tabela. Ela precisa seguir as regras de nomenclatura de tabela. O nome da tabela de destino também aceita parâmetros.
    • Em URI do Amazon S3, insira o URI do Amazon S3. Caracteres curinga e parâmetros são aceitos.
    • Em ID da chave de acesso, insira seu ID da chave de acesso.
    • Em Chave de acesso secreta, insira sua chave de acesso secreta.
    • Em Formato de arquivo, escolha seu formato de dados: JSON delimitado por nova linha, CSV, Avro, Parquet ou ORC.
    • Na seção Opções de transferência — Todos os formatos:
      • Em Número de erros permitidos, insira o número máximo de registros corrompidos que o BigQuery pode ignorar ao executar o job. Se o número de registros corrompidos exceder esse valor, o erro "inválido" é retornado no resultado do job. O valor padrão é 0.
    • Se você escolheu CSV ou JSON como seu formato de dados, na seção Opções de Transferência — JSON, CSV:
      • Marque a caixa Ignorar valores desconhecidos se quiser que a transferência elimine dados que não se ajustem ao esquema da tabela de destino.
    • Se você escolheu CSV como seu formato de dados, na seção Opções de Transferência - CSV:

      • Em Field delimiter, insira o caractere que separa os campos. O valor padrão é a vírgula.
      • Em Linhas de cabeçalho a serem ignoradas, insira o número de linhas de cabeçalho nos arquivos de origem, se você não quiser importá-las. O valor padrão é 0.
      • Em Permitir novas linhas com consulta, marque a caixa se quiser permitir novas linhas dentro dos campos entre aspas.
      • Marque a caixa Permitir linhas dentadas se quiser permitir a transferência de linhas com colunas NULLABLE ausentes.
    • (Opcional) Expanda a seção Advanced e configure as notificações de execução para a transferência.

    • Em Cloud Pub/Sub topic, insira o nome do seu tópico do Cloud Pub/Sub, por exemplo, projects/myproject/topics/mytopic.

    • Marque Send email notifications para permitir notificações por e-mail sobre falhas na execução da transferência.

      Tópico do Cloud Pub/Sub

  5. Clique em Adicionar.

CLI

Insira o comando bq mk e forneça a sinalização de criação da transferência --transfer_config.

    bq mk \
    --transfer_config \
    --project_id=project_id \
    --data_source=data_source \
    --display_name=name \
    --target_dataset=dataset \
    --params='parameters'
    

Onde:

  • project_id: opcional. É o ID do seu projeto no Google Cloud. Se --project_id não for fornecido para especificar um determinado projeto, o projeto padrão será usado;
  • data_source: obrigatório. É a fonte de dados: amazon_s3;
  • display_name: obrigatório. O nome de exibição da configuração de transferência. Ele pode ter qualquer valor que identifique facilmente a transferência, caso seja necessário modificá-la no futuro;
  • dataset: obrigatório. É o conjunto de dados de destino na configuração da transferência;
  • parameters: obrigatório. São os parâmetros da configuração de transferência criada no formato JSON. Por exemplo, --params='{"param":"param_value"}'. Veja a seguir os parâmetros de uma transferência do Amazon S3:

    • destination_table_name_template: obrigatório. É o nome da tabela de destino;
    • data_path: obrigatório. É o URI do Amazon S3 neste formato:

      s3://mybucket/myfolder/...

      Os URIs também aceitam parâmetros.

    • access_key_id: obrigatório. É o ID da chave de acesso;

    • secret_access_key: obrigatório. É a chave de acesso secreta;

    • file_format: opcional. Indica o tipo de arquivo que você quer transferir: CSV, JSON, AVRO, PARQUET ou ORC. O valor padrão é CSV.

    • max_bad_records: opcional. É o número de registros inválidos permitidos. O padrão é 0;

    • ignore_unknown_values: opcional e ignorado se file_format não e JSON ou CSV. Define se valores desconhecidos nos seus dados serão ignorados.

    • field_delimiter: opcional e aplicado somente quando file_format for CSV. É o caractere que separa os campos. O valor padrão é uma vírgula.

    • skip_leading_rows: opcional e aplicado somente quando file_format é CSV. Indica o número de linhas de cabeçalho que você não quer importar. O valor padrão é 0.

    • allow_quoted_newlines: opcional e aplicado somente quando file_format é CSV. Indica se novas linhas são permitidas dentro de campos entre aspas.

    • allow_jagged_rows: opcional e aplicado somente quando file_format é CSV. Indica se você aceitará linhas em que as colunas opcionais no final estejam faltando. Os valores ausentes são preenchidos com NULLs.

Por exemplo, com o comando a seguir, você cria uma transferência do Amazon S3 chamada My Transfer. Nela, são usados o valor s3://mybucket/myfile/*.csv em data_path_template, o conjunto de dados de destino mydataset e o file_format CSV. Este exemplo inclui valores não padrão para os parâmetros opcionais associados ao "file_format" CSV.

A transferência é criada no projeto padrão:

bq mk --transfer_config \
    --target_dataset=mydataset \
    --display_name='My Transfer' \
    --params='{"data_path_template":"s3://mybucket/myfile/*.csv",
    "destination_table_name_template":"MyTable",
    "file_format":"CSV",
    "max_bad_records":"1",
    "ignore_unknown_values":"true",
    "field_delimiter":"|",
    "skip_leading_rows":"1",
    "allow_quoted_newlines":"true",
    "allow_jagged_rows":"false",
    "delete_source_files":"true"}' \
    --data_source=amazon_s3
    

Após executar o comando, você recebe uma mensagem semelhante a esta:

[URL omitted] Please copy and paste the above URL into your web browser and follow the instructions to retrieve an authentication code.

Siga as instruções e cole o código de autenticação na linha de comando.

API

Use o método projects.locations.transferConfigs.create e forneça uma instância do recurso TransferConfig.

Como consultar dados

Quando os dados são transferidos para o BigQuery, eles são gravados em tabelas particionadas por tempo de processamento. Para mais informações, consulte Introdução às tabelas particionadas.

Use a pseudocoluna _PARTITIONTIME para consultar direto as tabelas, em vez de usar visualizações geradas automaticamente. Para mais informações, veja Como consultar tabelas particionadas.

Impacto da correspondência de prefixos e de caracteres curinga

A API do Amazon S3 é compatível com a correspondência de prefixos, e não com a de caracteres curinga. Todos os arquivos do Amazon S3 que correspondem a um prefixo são transferidos para o Google Cloud. No entanto, só aqueles que correspondem ao URI do Amazon S3 na configuração de transferência são realmente carregados no BigQuery. Isso pode gerar custos de saída excessivos do Amazon S3 relacionados aos arquivos que são transferidos, mas não são carregados no BigQuery.

Por exemplo, veja este caminho de dados:

s3://bucket/folder/*/subfolder/*.csv
    

Com esses arquivos no local de origem também estão:

s3://bucket/folder/any/subfolder/file1.csv
    s3://bucket/folder/file2.csv
    

Isso faz com que todos os arquivos do Amazon S3 com o prefixo s3://bucket/folder/ sejam transferidos para o Google Cloud. Nesse exemplo, os itens file1.csv e file2.csv serão transferidos.

No entanto, somente arquivos correspondentes a s3://bucket/folder/*/subfolder/*.csv serão carregados no BigQuery. Nesse exemplo, apenas file1.csv será carregado no BigQuery.

Resolver problemas

Veja a seguir informações sobre erros comuns e as soluções recomendadas.

Erros "PERMISSION_DENIED" do Amazon S3

Erro Ação recomendada
O ID da chave de acesso da AWS fornecido não existe em nossos registros. Verifique se a chave de acesso existe, e se o ID está correto.
A assinatura da solicitação que calculamos não corresponde à assinatura fornecida. Verifique sua chave e método de assinatura. Verifique se a configuração de transferência tem a chave de acesso secreta correspondente correta.
Falha ao receber o local do intervalo de origem do S3. Mais detalhes: acesso negado

Falha ao receber o local do intervalo de origem do S3. Mais detalhes: HTTP/1.1 403 Forbidden

Mensagem de erro do S3: acesso negado
Verifique se o usuário do IAM da AWS tem permissão para executar o seguinte:
  • listar o intervalo do Amazon S3;
  • ver a localização do intervalo;
  • ler os objetos no intervalo.
O servidor não conseguiu inicializar o upload de objeto. InvalidObjectState: a operação não é válida para a classe de armazenamento do objeto

Falha ao receber o local do intervalo de origem do S3. Mais detalhes: todo o acesso a este objeto foi desativado
Restaure todos os objetos arquivados no Amazon Glacier. Objetos no Amazon S3 que são arquivados no Amazon Glacier não ficam acessíveis até que sejam restaurados
Todo acesso a este objeto foi desativado. Confirme se o URI do Amazon S3 na configuração de transferência está correto

Erros de limite de transferência do Amazon S3

Erro Ação recomendada
O número de arquivos na transferência excede o limite de 10.000. Avalie se é possível reduzir o número de caracteres curinga no URI do Amazon S3 a apenas um. Se isso for possível, tente novamente com uma nova configuração de transferência, já que o número máximo de arquivos por execução de transferência será maior.

Avalie se é possível dividir a configuração de transferência em várias, cada uma transferindo uma parte dos dados de origem.
O tamanho dos arquivos na transferência excede o limite de 16.492.674.416.640 bytes. Avalie se é possível dividir a configuração de transferência em várias, cada uma transferindo uma parte dos dados de origem.

Problemas gerais

Erro Ação recomendada
Os arquivos são transferidos do Amazon S3, mas não são carregados no BigQuery. Os registros de transferência podem ser semelhantes a este:

Mover dados do Amazon S3 para o Google Cloud: <NNN> objetos movidos.
Nenhum arquivo novo encontrado correspondente ao <URI do Amazon S3>.
Confirme se o URI do Amazon S3 na configuração de transferência está correto.

Se a configuração de transferência foi feita para carregar todos os arquivos com um prefixo comum, verifique se o URI do Amazon S3 termina com um caractere curinga.
Por exemplo, para carregar todos os arquivos em s3://my-bucket/my-folder/, o URI do Amazon S3 na configuração de transferência precisa ser s3://my-bucket/my-folder/*, e não apenas s3://my-bucket/my-folder/.
Outros problemas Consulte Solução de problemas nas configurações de transferência.

A seguir