Esta página foi traduzida pela API Cloud Translation.
Switch to English

Transferências do Cloud Storage

Com o serviço de transferência de dados do BigQuery para o Cloud Storage, você programa 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á. Alterações de esquema de tabela entre execuções também causam falha 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. Para mais informações, consulte a descrição do campo writeDisposition do objeto JobConfigurationLoad.
  • O serviço de transferência de dados do BigQuery não garante que todos os arquivos serão transferidos ou que não haja transferência duplicada caso haja utilização dos arquivos do Cloud Storage durante o processo.
  • Se o local do conjunto de dados estiver definido com um valor diferente de US, o bucket regional ou multirregional do Cloud Storage precisará estar na mesma região que o conjunto de dados.
  • O serviço de transferência de dados do BigQuery não garante a consistência de dados para fontes externas. Alterações nos dados subjacentes enquanto uma consulta estiver em execução podem resultar em comportamentos inesperados.

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

  • O bucket do Cloud Storage precisa estar em uma região ou multirregião compatível com a região ou multirregião do conjunto de dados de destino no BigQuery. Isso é conhecido como colocation. Consulte Locais de dados da transferência do Cloud Storage para detalhes.

Intervalos mínimos

  • Os arquivos de origem são escolhidos para transferência imediatamente, sem idade mínima.
  • O tempo mínimo de intervalo entre as transferências recorrentes é de 15 minutos. O intervalo padrão para uma transferência recorrente é a cada 24 horas.

Permissões necessárias

Ao carregar dados no BigQuery, você precisa de permissões 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 bucket que contém os dados. Verifique se você tem as permissões necessárias a seguir:

  • BigQuery: verifique se a pessoa que está criando a transferência tem as permissões a seguir no BigQuery:

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

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

  • Cloud Storage: permissões storage.objects.get são necessárias no bucket individual ou superior. Se você estiver usando um caractere curinga de URI, também precisará ter permissões 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 predefinido do Cloud IAM storage.objectAdmin 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 página do BigQuery no Console do Cloud.

    Acessar a página do BigQuery

  2. Clique em Transferências.

  3. Clique em Criar.

  4. Na página Criar transferência:

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

      Origem 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. O intervalo mínimo é de 15 minutos.
        • Diário (padrão)
        • Semanalmente
        • Mensal
        • Personalizado. Em Programação personalizada, insira uma frequência personalizada. por exemplo, every day 00:00. Consulte Como formatar a programação.
        • Sob demanda
      • Em 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.

      Conjunto de dados da transferência

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

      • 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.
      • Em Preferência de gravação, escolha:

        • ANEXAR para anexar novos dados à tabela de destino atual ou;
        • ESPELHAR para atualizar os dados na tabela de destino e refletir os dados modificados na origem. ESPELHAR substitui uma nova cópia dos dados na tabela de destino.
      • 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.
          • Opcional: em Tipos de destino decimal, insira uma lista separada por vírgulas de possíveis tipos de dados SQL em que os valores decimais de origem podem ser convertidos. O tipo de dados SQL selecionado para conversão depende das condições a seguir:
            • O tipo de dados selecionado para conversão será o primeiro tipo na lista a seguir, que aceita a precisão e a escala dos dados de origem, nesta ordem: NUMERIC, BIGNUMERIC e STRING.
            • Se nenhum dos tipos de dados listados aceitará a precisão e a escala, o tipo de dados compatível com o maior intervalo na lista especificada será selecionado. Se um valor exceder o intervalo aceito ao ler os dados de origem, um erro será gerado.
            • O tipo de dados STRING é compatível com todos os valores de precisão e escala.
            • Se esse campo for deixado em branco, o tipo de dados será padronizado como "NUMERIC,STRING" para ORC e "NUMERIC" para os outros formatos de arquivo.
            • Este campo não pode conter tipos de dados duplicados.
            • A ordem dos tipos de dados listados nesse campo é ignorada.
        • 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:

      • 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 se uma execução de transferência falhar.
      • Em Selecionar um tópico do Pub/Sub, escolha o nome do tópico ou clique em Criar um tópico. Essa opção configura notificações de execução do Pub/Sub da sua transferência.
  5. Clique em Salvar.

bq

Insira o comando bq mk e forneça a sinalização de execução da transferência --transfer_config. As sinalizações a seguir 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 ID do projeto. Se --project_id não for fornecido para especificar um projeto específico, o projeto padrão será usado.
  • data_source é a fonte de dados: google_cloud_storage.
  • name é o nome de exibição da configuração de transferência. Esse nome pode ser qualquer valor que identifique facilmente a transferência, caso seja necessário modificá-la futuramente.
  • dataset é o conjunto de dados de destino na configuração da transferência.
  • parameters contém os parâmetros da configuração da transferência criada no formato JSON. Por exemplo, --params='{"param":"param_value"}'.
    • Para o Cloud Storage, é preciso fornecer os parâmetros data_path_template, destination_table_name_template e file_format. data_path_template é o URI do Cloud Storage que contém seus arquivos a serem transferidos, que podem incluir um caractere curinga. destination_table_name_template é o nome da sua tabela de destino. Em file_format, indique o tipo de arquivo que você quer transferir: CSV, JSON, AVRO, PARQUET ou ORC. O valor padrão é CSV.
    • Para todos os valores de file_format, você pode incluir o parâmetro opcional max_bad_records. O valor padrão é 0.
    • Para todos os valores de file_format, você pode incluir o parâmetro opcional decimal_target_types. decimal_target_types é uma lista separada por vírgulas de possíveis tipos de dados SQL em que os valores decimais de origem podem ser convertidos. Se este campo não for fornecido, o tipo de dados será padronizado como "NUMERIC, STRING" para ORC e "NUMERIC" para os outros formatos de arquivo.
    • Para os valores JSON ou CSV em file_format, é possível incluir o parâmetro opcional ignore_unknown_values. Este parâmetro será ignorado se você não selecionou CSV ou JSON para file_format.
    • Para CSV file_format, você pode incluir o parâmetro opcional field_delimiter para o caractere que separa os campos. O valor padrão é uma vírgula. Este parâmetro será ignorado se você não tiver selecionado CSV para file_format.
    • Para CSV file_format, você pode incluir o parâmetro opcional skip_leading_rows para indicar as linhas do cabeçalho que não quer importar. O valor padrão é 0. Este parâmetro será ignorado se você não tiver selecionado CSV para file_format.
    • Para CSV file_format, você pode incluir o parâmetro opcional allow_quoted_newlines se quiser permitir novas linhas dentro dos campos entre aspas. Este parâmetro será ignorado se você não tiver selecionado CSV para file_format.
    • Para CSV file_format, você pode incluir o parâmetro opcional allow_jagged_rows se quiser aceitar linhas em que as colunas opcionais à direita estão ausentes. Os valores ausentes serão preenchidos com NULLs. Este parâmetro será ignorado se você não tiver selecionado CSV para 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 para delete_source_files é falso.

Por exemplo, o comando a seguir cria uma transferência do Cloud Storage chamada My Transfer usando o valor data_path_template de gs://mybucket/myfile/*.csv, o conjunto de dados de destino mydataset e file_format CSV. Este exemplo inclui valores não padrão para os parâmetros opcionais associados ao CSV file_format.

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.

Java

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create google cloud storage transfer config
public class CreateCloudStorageTransfer {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    String datasetId = "MY_DATASET_ID";
    String tableId = "MY_TABLE_ID";
    // GCS Uri
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
    String fileFormat = "CSV";
    String fieldDelimiter = ",";
    String skipLeadingRows = "1";
    Map<String, Value> params = new HashMap<>();
    params.put(
        "destination_table_name_template", Value.newBuilder().setStringValue(tableId).build());
    params.put("data_path_template", Value.newBuilder().setStringValue(sourceUri).build());
    params.put("write_disposition", Value.newBuilder().setStringValue("APPEND").build());
    params.put("file_format", Value.newBuilder().setStringValue(fileFormat).build());
    params.put("field_delimiter", Value.newBuilder().setStringValue(fieldDelimiter).build());
    params.put("skip_leading_rows", Value.newBuilder().setStringValue(skipLeadingRows).build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Google Cloud Storage Config Name")
            .setDataSourceId("google_cloud_storage")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createCloudStorageTransfer(projectId, transferConfig);
  }

  public static void createCloudStorageTransfer(String projectId, TransferConfig transferConfig)
      throws IOException {
    try (DataTransferServiceClient client = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .build();
      TransferConfig config = client.createTransferConfig(request);
      System.out.println("Cloud storage transfer created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Cloud storage transfer was not created." + ex.toString());
    }
  }
}

Como acionar manualmente uma transferência

Além das transferências programadas automaticamente do Cloud Storage, é possível acionar manualmente uma transferência para carregar outros arquivos de dados.

Se a configuração de transferência for runtime parametrizado, será necessário especificar um intervalo de datas para o qual as outras transferências serão iniciadas.

Para acionar uma transferência manualmente, faça o seguinte:

Console

  1. Acesse a página do BigQuery no Console do Cloud.

    Acesse a página do BigQuery

  2. Clique em Transferências de dados.

  3. Clique na sua transferência.

  4. Clique em EXECUTAR TRANSFER NOWNCIA AGORA ou RELAT RIO DE REMOVIDO (para configurações de transferência parametrizadas no ambiente de execução).

  5. Se aplicável, escolha a Data de início e a Data de término. Clique em OK para confirmar.

    EXECUTAR TRANSFER NOWNCIA AGORA

    Para configurações de transferência parametrizadas de tempo de execução, você verá opções de data ao clicar em PROGRAMAR BACKFILL.

    PROGRAMASCHEDULEO DE DESTAQUE

A seguir