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, realize estas ações:

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.
  • Ao contrário dos carregamentos de dados individuais do Cloud Storage para o BigQuery, para transferências contínuas, é necessário criar a tabela de destino antes de configurar a transferência. Para arquivos CSV e JSON, também é necessário definir o esquema de tabela com antecedê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 definem o parâmetro referência de gravação como APPEND por padrão. Nesse modo, um arquivo não modificado só pode ser carregado no BigQuery uma vez. Se a propriedade last modification time do arquivo for atualizada, ele será recarregado.
  • 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. Você está sujeito às limitações a seguir ao carregar dados de um intervalo do Cloud Storage para o BigQuery:

  • Se o local do conjunto de dados estiver definido como um valor diferente da multirregião US, o bucket do Cloud Storage precisará estar na mesma região ou estar contido na mesma multirregião que o conjunto de dados.

  • O BigQuery não garante a consistência dos dados para fontes de dados externas. Alterações nos dados subjacentes enquanto uma consulta estiver em execução podem resultar em comportamentos inesperados.

  • O BigQuery não é compatível com o controle de versões de objetos do Cloud Storage. Se você incluir um número de geração no URI do Cloud Storage, o job de carregamento falhará.

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

  • O bucket do Cloud Storage precisa estar em um local compatível com a região ou a 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 retirados para transferência imediatamente, sem idade mínima de uso.
  • O intervalo mínimo 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 ou a conta de serviço que cria a transferência tem as seguintes permissões no BigQuery:

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

    O papel predefinido bigquery.admin do IAM inclui 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 o 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.

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 Google Cloud.

    Acesse a página do BigQuery

  2. Clique em Transferências de dados.

  3. Clique em Criar transferência.

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

    Origem da transferência

  5. No campo Nome de exibição da seção Transferir nome da configuração, insira um nome para a transferência, como My Transfer. O nome da transferência pode ser qualquer valor que permita identificá-la, caso você precise modificá-la mais tarde.

    Nome da transferência

  6. Na seção Opções de programação, faça o seguinte:

    • Selecione uma Frequência de repetição. Se você selecionar Horas, Dias, Semanas ou Meses, também precisará especificar uma frequência. Também é possível selecionar Personalizado para especificar uma frequência de repetição personalizada. Se você selecionar Sob demanda, essa transferência vai ser executada quando você acionar manualmente a transferência.

    • Se aplicável, selecione Começar agora ou Começar no horário definido e forneça uma data de início e um horário de execução.

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

  8. Na seção Detalhes da fonte de dados:

    1. 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.
    2. Em URI do Cloud Storage, digite o URI do Cloud Storage. Caracteres curinga e parâmetros são aceitos.
    3. Em Preferência de gravação, escolha:
      • APPEND para anexar novos dados à tabela de destino atual. APPEND é o valor padrão de Preferência de gravação.
      • MIRROR para substituir os dados na tabela de destino durante cada execução de transferência.

    Para mais informações sobre como o serviço de transferência de dados do BigQuery ingere dados usando APPEND ou MIRROR, consulte Ingestão de dados para transferências do Cloud Storage. Para mais informações sobre o campo writeDisposition, consulte JobConfigurationLoad.

    1. 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.
    2. Na seção Opções de transferência:

      1. Em Todos os formatos:
        1. 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.
        2. (Opcional) Em Tipos decimais de destino, 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 seguintes condições:
          • O tipo de dados selecionado para a conversão será o primeiro da lista a seguir, compatível com a precisão e a escala dos dados de origem, nesta ordem: NUMERIC, BIGNUMERIC e STRING.
          • Se nenhum dos tipos de dados listados for compatível com a precisão e a escala, será selecionado o tipo de dados que aceita o intervalo mais amplo na lista especificada. Se um valor exceder o intervalo compatível durante a leitura dos dados de origem, um erro será gerado.
          • O tipo de dados STRING é compatível com todos os valores de precisão e escala.
          • Se este 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.
      2. 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.
      3. Em AVRO:
        • Marque a caixa Usar tipos lógicos avro se quiser que a transferência converta tipos lógicos Avro nos tipos de dados correspondentes do BigQuery. O comportamento padrão é ignorar o atributo logicalType para a maioria dos tipos e, em vez disso, usar o tipo Avro subjacente.
      4. Em CSV:

        1. Em Delimitador de campo, insira o caractere que separa os campos. O valor padrão é uma vírgula.
        2. Em Caractere de aspas, insira o caractere usado para citar seções de dados em um arquivo CSV. O valor padrão é uma aspa dupla (").
        3. 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.
        4. Marque a caixa Permitir novas linhas entre aspas se quiser permitir novas linhas dentro dos campos entre aspas.
        5. Marque a caixa Permitir linhas dentadas se quiser permitir a transferência de linhas com colunas NULLABLE ausentes.
  9. No menu Conta de serviço, selecione uma conta de serviço nas contas de serviço associadas ao seu projeto do Google Cloud. É possível associar uma conta de serviço à transferência em vez de usar suas credenciais de usuário. Para mais informações sobre o uso de contas de serviço com transferências de dados, consulte Usar contas de serviço.

    • Se você fez login com uma identidade federada, é necessário uma conta de serviço para criar uma transferência. Se você fez login com uma Conta do Google, uma conta de serviço para a transferência é opcional.
    • A conta de serviço precisa ter as permissões necessárias para o BigQuery e o Cloud Storage.
  10. Opcional: na seção Opções de notificação

    1. Clique no botão para ativar as notificações por e-mail. Quando você ativa essa opção, o proprietário da configuração de transferência recebe uma notificação por e-mail quando uma execução de transferência falha.
    2. 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.
  11. Opcional: na seção Opções avançadas, faça o seguinte:

    • Se você usar CMEKs, selecione Chave gerenciada pelo cliente. Uma lista das CMEKs disponíveis será exibida.

    Para informações sobre como as CMEKs funcionam com o serviço de transferência de dados do BigQuery, consulte Especificar chave de criptografia com transferências.

  12. Clique em Save.

bq

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

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

Sinalizações opcionais:

  • --destination_kms_key: especifica o ID de recurso da chave para a chave do Cloud KMS se você usar uma chave de criptografia gerenciada pelo cliente (CMEK) para essa transferência. Para informações sobre como as CMEKs funcionam com o serviço de transferência de dados do BigQuery, consulte Especificar chave de criptografia com transferências.
  • --service_account_name: especifica uma conta de serviço a ser usada para a autenticação de transferência do Cloud Storage em vez da sua conta de usuário.
bq mk \
--transfer_config \
--project_id=PROJECT_ID \
--data_source=DATA_SOURCE \
--display_name=NAME \
--target_dataset=DATASET \
--destination_kms_key="DESTINATION_KEY" \
--params='PARAMETERS' \
--service_account_name=SERVICE_ACCOUNT_NAME

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, por exemplo, google_cloud_storage.
  • NAME é o nome de exibição da configuração de transferência. O nome da transferência pode ser qualquer valor que permita identificá-la facilmente, caso precise modificá-la mais tarde.
  • DATASET é o conjunto de dados de destino na configuração da transferência:
  • DESTINATION_KEY: o ID de recurso da chave do Cloud KMS. Por exemplo, projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name.
  • PARAMETERS contém os parâmetros da configuração da transferência criada no formato JSON. Por exemplo, --params='{"param":"param_value"}'.
    • destination_table_name_template: o nome da tabela de destino do BigQuery.
    • data_path_template: o URI do Cloud Storage que contém seus arquivos a serem transferidos, que podem incluir um caractere curinga.
    • write_disposition: determina se os arquivos correspondentes são anexados à tabela de destino ou espelhados totalmente. Os valores compatíveis são APPEND ou MIRROR. Para informações sobre como o serviço de transferência de dados do BigQuery anexa ou espelha dados em transferências do Cloud Storage, consulte Ingestão de dados para transferências do Cloud Storage.
    • file_format: o formato dos arquivos que você quer transferir. O formato pode ser CSV, JSON, AVRO, PARQUET ou ORC. O valor padrão é CSV.
    • max_bad_records: para qualquer valor file_format, o número máximo de registros inválidos que podem ser ignorados. O valor padrão é 0.
    • decimal_target_types: para qualquer valor file_format, uma lista separada por vírgulas de possíveis tipos de dados SQL em que os valores decimais de origem podem ser convertidos. Se esse campo não for configurado, o tipo de dados será definido por padrão como "NUMERIC,STRING" para ORC e "NUMERIC" para os outros formatos de arquivo.
    • ignore_unknown_values: para qualquer valor file_format, defina como TRUE para aceitar linhas que contenham valores que não correspondam ao esquema. Para mais informações, consulte os detalhes do campo ignoreUnknownvalues na tabela de referência JobConfigurationLoad.
    • use_avro_logical_types: para valores AVRO file_format, defina como TRUE para interpretar tipos lógicos nos tipos correspondentes (por exemplo, TIMESTAMP), em vez de usar apenas os tipos brutos (por exemplo, INTEGER).
    • parquet_enum_as_string: para valores PARQUET file_format, defina como TRUE para inferir o tipo lógico PARQUET ENUM como STRING em vez do padrão BYTES.
    • parquet_enable_list_inference: para valores PARQUET file_format, defina como TRUE para usar a inferência de esquema especificamente para o tipo lógico PARQUET LIST.
    • reference_file_schema_uri: um caminho de URI para um arquivo de referência com o esquema do leitor.
    • field_delimiter: para valores CSV file_format, um caractere que separa os campos. O valor padrão é uma vírgula.
    • quote: para valores CSV file_format, um caractere usado para citar seções de dados em um arquivo CSV. O valor padrão é uma aspa dupla (").
    • skip_leading_rows: para valores CSV file_format, indique o número de linhas de cabeçalho principais que você não quer importar. O valor padrão é 0.
    • allow_quoted_newlines: para valores CSV file_format, defina como TRUE para permitir novas linhas dentro dos campos entre aspas.
    • allow_jagged_rows : para valores CSV file_format, defina como TRUE para aceitar linhas sem colunas opcionais no final. Os valores ausentes são preenchidos com NULL.
    • preserve_ascii_control_characters: para valores CSV file_format, definido como TRUE para preservar todos os caracteres de controle ASCII incorporados.
    • encoding: especifica o tipo de codificação CSV. Os valores com suporte são UTF8, ISO_8859_1, UTF16BE, UTF16LE, UTF32BE e UTF32LE.
    • delete_source_files: defina como TRUE para excluir os arquivos de origem após cada transferência bem-sucedida. Os jobs de exclusão não serão executados novamente se a primeira tentativa de excluir o arquivo de origem falhar. O valor padrão é FALSE.
  • SERVICE_ACCOUNT_NAME é o nome da conta de serviço usado para autenticar a transferência. A conta de serviço precisa pertencer ao mesmo project_id usado para criar a transferência e ter todas as permissões necessárias.

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":"|",
"quote":";",
"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

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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());
    }
  }
}

Especificar a chave de criptografia com transferências

É possível especificar chaves de criptografia gerenciadas pelo cliente (CMEKs, na sigla em inglês) para criptografar dados de uma execução de transferência. É possível usar uma CMEK para dar suporte a transferências do Cloud Storage.

Quando você especifica uma CMEK com uma transferência, o serviço de transferência de dados do BigQuery aplica a CMEK a qualquer cache intermediário no disco de dados ingeridos para que todo o fluxo de trabalho de transferência de dados fique em conformidade com a CMEK.

Não é possível atualizar uma transferência atual para adicionar uma CMEK se a transferência não tiver sido criada originalmente com uma CMEK. Por exemplo, não é possível alterar uma tabela de destino que, originalmente, estava criptografada por padrão, para ser criptografada com CMEKs. Por outro lado, também não é possível alterar uma tabela de destino criptografada por CMEK para ter um tipo diferente de criptografia.

É possível atualizar uma CMEK para uma transferência se a configuração de transferência tiver sido criada originalmente com uma criptografia CMEK. Quando você atualiza uma CMEK para uma configuração de transferência, o serviço de transferência de dados do BigQuery propaga a CMEK para as tabelas de destino na próxima execução da transferência, em que o serviço de transferência de dados do BigQuery substitui todas as CMEKs desatualizadas pela nova CMEK durante a execução da transferência. Para saber mais, consulte Atualizar uma transferência.

Também é possível usar as chaves padrão do projeto. Quando você especifica uma chave padrão do projeto com uma transferência, o serviço de transferência de dados do BigQuery a usa como padrão para qualquer nova configuração de transferência.

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 da transferência for parametrizada do ambiente de execução, será necessário especificar um intervalo de datas para que outras transferências sejam iniciadas.

Para acionar uma transferência:

Console

  1. Acesse a página do BigQuery no console do Google Cloud.

    Acesse a página do BigQuery

  2. Clique em Transferências de dados.

  3. Selecione a transferência na lista.

  4. Clique em Executar transferência agora ou Programar preenchimento (para configurações de transferência parametrizada do ambiente de execução).

    • Se você clicou em Executar transferência agora, selecione Executar transferência única ou Executar em uma data específica, conforme aplicável. Se você selecionou Executar em uma data específica, selecione uma data e hora específicas:

      Executar transferência agora

    • Se você clicou em Programar preenchimento, selecione Executar uma transferência única ou Executar em um período, conforme aplicável. Se você selecionou Executar em um período, selecione uma data e hora de início e término:

      Programar preenchimento

  5. Clique em OK.

bq

Insira o comando bq mk e forneça a flag --transfer_run. É possível usar a flag --run_time ou as flags --start_time e --end_time.

bq mk \
--transfer_run \
--start_time='START_TIME' \
--end_time='END_TIME' \
RESOURCE_NAME
bq mk \
--transfer_run \
--run_time='RUN_TIME' \
RESOURCE_NAME

Em que:

  • START_TIME e END_TIME são carimbos de data/hora que terminam em Z ou contêm uma diferença de fuso horário válida. Exemplo:

    • 2017-08-19T12:11:35.00Z
    • 2017-05-25T00:00:00+00:00
  • RUN_TIME é um carimbo de data/hora que especifica o horário para programar a execução da transferência de dados. Se você quiser executar uma transferência única no horário atual, use a flag --run_time.

  • RESOURCE_NAME é o nome do recurso da transferência (também conhecido como configuração de transferência), por exemplo, projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7. Se você não souber o nome do recurso da transferência, execute o comando bq ls --transfer_config --transfer_location=LOCATION para encontrar o nome do recurso.

API

Use o método projects.locations.transferConfigs.startManualRuns e forneça o recurso de configuração de transferência por meio do parâmetro parent.

A seguir