Transferências do Cloud Storage

Com o serviço de transferência de dados do BigQuery para o Cloud Storage, você pode programar carregamentos de dados recorrentes do Cloud Storage para o BigQuery.

Antes de começar

Antes de criar uma transferência do Cloud Storage:

Limitações

As transferências recorrentes do Cloud Storage para o BigQuery estão sujeitas às seguintes limitações:

  • Todos os arquivos que correspondem aos padrões definidos por um caractere curinga ou por parâmetros de ambiente de execução para a transferência precisam compartilhar o mesmo esquema definido para a tabela de destino. Caso contrário, a transferência falhará. Mudanças no esquema da tabela entre execuções também causam falha na transferência.
  • Os arquivos de origem no Cloud Storage precisam ter pelo menos uma hora para serem incluídos na transferência.
  • Como os objetos do Cloud Storage podem ter controle de versão, é importante observar que os objetos arquivados do Cloud Storage não são compatíveis com transferências do BigQuery. Os objetos precisam estar ativos para serem transferidos.
  • Diferentemente de carregamentos de dados individuais do Cloud Storage para o BigQuery, para transferências contínuas, é preciso criar a tabela de destino e o esquema dela antes de configurar a transferência. O BigQuery não pode criar a tabela como parte do processo recorrente de transferência de dados.
  • As transferências do Cloud Storage sempre são acionadas com a preferência WRITE_APPEND, que acrescenta dados à tabela de destino. Consulte configuration.load.writeDisposition em configuração de carregamento para saber mais detalhes.
  • Se o local do conjunto de dados estiver definido com um valor diferente de US, o intervalo do Cloud Storage regional ou multirregional precisará estar na mesma região que o conjunto de dados.

Dependendo do formato dos dados de origem do Cloud Storage, pode haver outras limitações. Para mais informações, consulte:

Permissões exigidas

Ao carregar dados no BigQuery, você precisa de permissões para os envolvidos no projeto ou no nível do conjunto de dados para carregar dados em tabelas e partições novas ou existentes do BigQuery. Se você estiver carregando dados do Cloud Storage, também precisará acessar o intervalo que contém os dados. Verifique se você tem as seguintes permissões necessárias:

  • BigQuery: é necessário ter permissões de bigquery.transfers.update para criar a transferência programada. O papel de IAM bigquery.admin predefinido para envolvidos no projeto inclui as permissões de bigquery.transfers.update. Para saber mais informações sobre papéis de IAM no BigQuery, consulte Controle de acesso.
  • Cloud Storage: é necessário ter permissões de storage.objects.get para envolvidos no projeto ou no intervalo individual. Se você estiver usando um caractere curinga de URI, também precisará ter permissões de storage.objects.list. Se você quiser excluir os arquivos de origem após cada transferência bem-sucedida, também precisará de permissões de storage.objects.delete. O papel do IAM storage.objectAdmin em nível de projeto predefinido inclui todas essas permissões.

Como configurar uma transferência do Cloud Storage

Para criar uma transferência do Cloud Storage no serviço de transferência de dados do BigQuery:

Console

  1. Acesse a IU da Web do BigQuery.

    Acessar a IU da Web do BigQuery

  2. Clique em Transferências.

  3. Clique em + CRIAR.

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

    • Na seção Tipo de origem, em Origem, escolha Cloud Storage.

      Origem da transferência

    • Na seção Nome da configuração de transferência, em 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, em Programação, mantenha o valor padrão (Começar agora) ou clique em Começar em um horário definido.

      • Em Repetições, escolha uma opção para a frequência de execução da transferência.
        • Diariamente (padrão)
        • Semanal
        • Mensal
        • Personalizada
        • Sob demanda
      • Em Data e hora de início, insira essas informações para iniciar a transferência. Essa opção estará desativada se você tiver escolhido Começar agora.

        Programação de transferência

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

      Conjunto de dados da transferência

    • Na seção Detalhes da origem dos dados, siga estas etapas:

      • Em Tabela de destino, digite o nome da sua tabela de destino. Ela precisa seguir as regras de nomenclatura de tabela. O nome da tabela de destino também aceita parâmetros.
      • Em URI do Cloud Storage, digite o URI do Cloud Storage. Caracteres curinga e parâmetros são aceitos.
      • Marque a caixa Excluir os arquivos de origem após a transferência se quiser excluir os arquivos de origem após cada transferência bem-sucedida. Os jobs de exclusão trabalham com base no melhor esforço. Eles não tentarão novamente se o primeiro esforço para excluir os arquivos de origem falhar.
      • Na seção Opções de transferência:

        • Em Todos os formatos:
          • Em Número de erros permitidos, digite 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” será retornado no resultado do job, e ele falhará. O valor padrão é 0.
        • Em 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.
        • Em CSV:

          • Em Delimitador de campo, insira o caractere que separa os campos. O valor padrão é uma vírgula.
          • Em Linhas de cabeçalho a serem ignoradas, digite o número de linhas de cabeçalho nos arquivos de origem, se você não quiser importá-las. O valor padrão é 0.
          • Marque a caixa Permitir novas linhas entre aspas 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.

      Detalhes da origem do Cloud Storage

    • (Opcional) Na seção Opções de notificação, siga estas etapas:

      • Clique no botão para ativar as notificações por e-mail. Com essa opção ativada, o administrador de transferência receberá uma notificação por e-mail sempre que ocorrer uma falha na execução da transferência.
      • Em Selecione um tópico do Cloud Pub/Sub, escolha o nome do seu tópico ou clique em Criar um tópico. Essa opção configura as notificações de execução do Cloud Pub/Sub da sua transferência. No momento, essas notificações estão na versão Alfa.
  5. Clique em Salvar.

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:

    • Para Origem, escolha Cloud Storage.
    • Em Nome de exibição, digite 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.
    • (Opcional) Em Programação, deixe o valor padrão Diária (a cada 24 horas, com base na hora da criação) ou clique em Editar para alterar a hora. Também é possível alterar o intervalo para "Semanal", "Mensal" ou "Personalizado". Se você selecionar "Personalizado", especifique um horário em estilo "Cron", por exemplo, 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.

      programação de transferência

    • Em Conjunto de dados de destino, escolha o conjunto de dados apropriado.

    • Em Tabela de destino, digite o nome da sua tabela de destino. Ela precisa seguir as regras de nomenclatura de tabela. O nome da tabela de destino também aceita parâmetros.

    • Em URI do Cloud Storage, digite o URI do Cloud Storage. Caracteres curinga e parâmetros são aceitos.

    • Marque a caixa Excluir os arquivos de origem após a transferência se quiser excluir os arquivos de origem após cada transferência bem-sucedida. Os jobs de exclusão trabalham com base no melhor esforço. Eles não tentarão novamente se o primeiro esforço para excluir os arquivos de origem falhar.

    • Em Formato do arquivo, selecione o tipo de arquivo que você quer transferir.

    • Na seção Opções de transferência - Todos os formatos:

      • Em Número de erros permitidos, digite 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” será retornado no resultado do job, e ele falhará. O valor padrão é 0.
    • 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.
    • Na seção Opções de transferência - CSV:

      • Em Delimitador de campo, insira o caractere que separa os campos. O valor padrão é uma vírgula.
      • Em Linhas de cabeçalho a serem ignoradas, digite o número de linhas de cabeçalho nos arquivos de origem, se você não quiser importá-las. O valor padrão é 0.
      • Marque a caixa Permitir novas linhas entre aspas 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.

      Nova transferência do Cloud Storage

    • (Opcional) Expanda a seção Avançado e configure as notificações de execução da transferência. As notificações de execução de transferência estão na versão Alfa.

    • Em Tópico do Cloud Pub/Sub, digite o nome do tópico. Por exemplo, projects/myproject/topics/mytopic.

    • Marque Enviar notificações por e-mail 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.

Linha de comando

Digite o comando bq mk e forneça a sinalização de criação da transferência --transfer_config. As sinalizações abaixo também são obrigatórias:

  • --data_source
  • --display_name
  • --target_dataset
  • --params

    bq mk --transfer_config --project_id=[PROJECT_ID] --data_source=[DATA_SOURCE] --display_name=[NAME] --target_dataset=[DATASET] --params='[PARAMETERS]'
    

em que:

  • --project_id é o código do projeto. Se não for fornecido um --project_id para especificar um determinado projeto, isso significa que o projeto padrão é o utilizado;
  • --data_source é a fonte de dados — google_cloud_storage.
  • --display_name é o nome de exibição na configuração da transferência. Esse nome pode ter qualquer valor que identifique facilmente a transferência, caso seja necessário modificá-la futuramente;
  • --target_dataset é o conjunto de dados de destino na configuração da transferência;
  • --params contém os parâmetros da configuração da transferência criada no formato JSON. Por exemplo: --params='{"param":"param_value"}'.
    • No Cloud Storage, é necessário fornecer os parâmetros data_path_template, destination_table_name_template e file_format. O parâmetro data_path_template é o URI do Cloud Storage que contêm os arquivos a serem transferidos, podendo incluir um caractere curinga. O parâmetro destination_table_name_template é o nome da tabela de destino. Em file_format, indique os tipos de arquivos que você quer transferir: CSV, JSON, AVRO, PARQUET ou ORC. O valor padrão é CSV.
    • Em todos os valores de file_format, é possível incluir o parâmetro opcional max_bad_records. O valor padrão é 0.
    • Nos valores JSON ou CSV em file_format, é possível incluir o parâmetro opcional ignore_unknown_values. Esse parâmetro será ignorado se não for selecionado o valor CSV ou JSON como file_format.
    • No valor CSV em file_format, é possível incluir o parâmetro opcional field_delimiter como caractere que separa os campos. O valor padrão é uma vírgula. Esse parâmetro será ignorado se não for selecionado o valor CSV como file_format.
    • No valor CSV em file_format, é possível incluir o parâmetro opcional skip_leading_rows para indicar as linhas de cabeçalho que você não quer importar. O valor padrão é 0. Esse parâmetro será ignorado se não for selecionado o valor CSV como file_format.
    • No valor CSV em file_format, é possível incluir o parâmetro opcional allow_quoted_newlines para permitir novas linhas dentro de campos entre aspas. Esse parâmetro será ignorado se não for selecionado o valor CSV como file_format.
    • No valor CSV em file_format, é possível incluir o parâmetro opcional allow_jagged_rows para aceitar linhas em que as colunas opcionais no final estejam faltando. Os valores ausentes serão preenchidos com NULLs. Esse parâmetro será ignorado se não for selecionado o valor CSV como file_format.
    • O parâmetro opcional delete_source_files excluirá os arquivos de origem após cada transferência bem-sucedida. Os jobs de exclusão não farão uma nova tentativa se o primeiro esforço para excluir os arquivos de origem falhar. O valor padrão de delete_source_files é falso.

Por exemplo, o comando a seguir cria uma transferência do Cloud Storage denominada My Transfer, usando o valor data_path_template de gs://mybucket/myfile/*.csv, o conjunto de dados de destino mydataset e o file_format CSV. Este exemplo inclui valores diferentes do padrão nos 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":"gs://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=google_cloud_storage

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 configurar uma execução de atualização de uma transferência

Além de configurar uma transferência recorrente do Cloud Storage, também é possível configurar uma execução de atualização para coletar arquivos de outros dados.

Se a configuração da transferência estiver relacionada à data (parametrizada), o URI do Cloud Storage for parametrizado ou ambos, será possível executar a atualização em datas específicas.

Para configurar uma transferência de atualização:

Console

  1. Abra a IU da Web do BigQuery no Console do GCP.

    Acessar a IU da Web do BigQuery

  2. Clique em Transferências.

  3. Clique na sua transferência.

  4. Clique no menu MAIS e selecione Atualizar transferência.

  5. Na caixa de diálogo Programe um preenchimento, escolha sua data de início e data de término. Você pode usar a IU da Web do BigQuery para definir limites de tempo mais precisos.

    Definir datas de atualização

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 na sua transferência.

  4. Clique em Transferência de atualização.

    Atualizar transferência

  5. Na caixa de diálogo Execuções da transferência, escolha o Horário de início e o Horário de término.

    Definir datas de atualização

    Se sua configuração de transferência do Cloud Storage não for parametrizada, você não receberá opções de data ao clicar em Atualizar transferência. Em vez disso, a atualização acontecerá imediatamente.

    Atualizar imediatamente

  6. Clique em OK.

A seguir

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.