Transferências do Armazenamento de Blobs

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

Antes de começar

Antes de criar uma transferência do Armazenamento de Blobs, realize estas ações:

Permissões necessárias

Para criar uma transferência do Armazenamento de Blobs, você precisa da permissão bigquery.transfers.update do Identity and Access Management (IAM). Você também precisa das permissões bigquery.datasets.get e bigquery.datasets.update no conjunto de dados de destino.

O papel predefinido bigquery.admin do IAM inclui as permissões necessárias para criar uma transferência do Armazenamento de Blobs.

Para mais informações sobre o IAM do BigQuery, consulte Controle de acesso com o IAM.

Para confirmar se você tem as permissões corretas no Armazenamento de Blobs para ativar a transferência, consulte Assinatura de acesso compartilhado (SAS).

Se você pretende configurar notificações de execução de transferência do Pub/Sub, precisa ter a permissão pubsub.topics.setIamPolicy. As permissões do Pub/Sub não são necessárias apenas para notificações por e-mail. Para mais informações, consulte Notificações de execução do serviço de transferência de dados do BigQuery.

Limitações

As transferências do Armazenamento de Blobs estão sujeitas a estas limitações:

Configurar uma transferência de dados do Armazenamento de Blobs

Selecione uma das seguintes opções:

Console

  1. No Console do Google Cloud, acesse a página BigQuery.

    Ir para o BigQuery

  2. No menu de navegação do BigQuery, clique em Transferências de dados.

  3. Clique em Criar transferência.

  4. Na página Criar transferência, realize estas ações:

    • Na seção Tipo de origem, em Origem, escolha Armazenamento de Blobs do Azure - Visualização.

      Tipo de origem da transferência

    • No campo Nome de exibição, na seção Nome de configuração da transferência, insira um nome para a transferência.

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

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

    • Na seção Detalhes da fonte de dados, faça o seguinte:

      • Para a 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 Nome da conta do armazenamento do Azure, insira o nome da conta do Armazenamento de Blobs.
      • Em Nome do contêiner, insira o nome do contêiner do Armazenamento de Blobs.
      • Em Caminho de dados, digite o caminho para filtrar os arquivos a serem transferidos. Confira exemplos.
      • Em Token SAS, insira o token SAS do Azure.
      • Em Formato do arquivo, escolha o formato dos dados de origem.
      • Em Disposição de gravação, selecione WRITE_APPEND para anexar novos dados à tabela de destino de maneira incremental ou WRITE_TRUNCATE para substituir na tabela de destino durante cada execução de transferência. WRITE_APPEND é o valor padrão para Disposição de gravação.

      Para mais informações sobre como o serviço de transferência de dados do BigQuery ingere dados usando WRITE_APPEND ou WRITE_TRUNCATE, consulte Ingestão de dados para Transferências do Amazon S3 Para mais informações sobre o campo writeDisposition, consulte JobConfigurationLoad.

      Detalhes da fonte de dados

    • Na seção Opções de transferência, realize estas ações:

      • Em Número de erros permitidos, insira um valor inteiro para o número máximo de registros inválidos que podem ser ignorados. O valor padrão é 0.
      • (Opcional) Em Tipos de destinos decimais, insira uma lista separada por vírgulas de possíveis tipos de dados SQL em que os valores decimais nos dados de origem são convertidos. O tipo de dados SQL selecionado para conversão depende destas condições:
        • Na ordem de NUMERIC, BIGNUMERIC e STRING, um tipo será escolhido se estiver na lista especificada e se for compatível com a precisão e a escala.
        • Se nenhum dos tipos de dados listados for compatível com a precisão e a escala, o tipo de dados compatível com o intervalo mais amplo da lista especificada será selecionado. 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 esse campo for deixado em branco, o tipo de dados será definido por padrão como NUMERIC,STRING para ORC e NUMERIC para outros formatos de arquivo.
        • Este campo não pode conter tipos de dados duplicados.
        • A ordem dos tipos de dados listados é ignorada.

    • Se você escolheu CSV ou JSON como formato do arquivo, na seção JSON, CSV, marque Ignorar valores desconhecidos para aceitar linhas que contenham valores que não correspondam ao esquema.

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

      Opções de CSV

    • Na seção Opções de notificação, é possível ativar as notificações por e-mail e do Pub/Sub.

      • Quando você ativa as notificações por e-mail, o administrador de transferência recebe uma notificação por e-mail quando uma execução de transferência falha.
      • Ao ativar as notificações do Pub/Sub, escolha um nome de tópico para publicar ou clique em Criar um tópico para criar um.

    • Se você usa CMEKs, na seção Opções avançadas, selecione Chave gerenciada pelo cliente. Uma lista das CMEKs disponíveis para escolha será exibida. Para informações sobre como as CMEKs funcionam com o serviço de transferência de dados do BigQuery, consulte Especificar a chave de criptografia com transferências.

  5. Clique em Save.

bq

Use o comando bq mk --transfer_config para criar uma transferência do Armazenamento de Blobs:

bq mk \
  --transfer_config \
  --project_id=PROJECT_ID \
  --data_source=DATA_SOURCE \
  --display_name=DISPLAY_NAME \
  --target_dataset=DATASET \
  --destination_kms_key=DESTINATION_KEY \
  --params=PARAMETERS

Substitua:

  • PROJECT_ID: (opcional) o ID do projeto que contém o conjunto de dados de destino. Se não for especificado, seu projeto padrão será usado.
  • DATA_SOURCE: azure_blob_storage.
  • DISPLAY_NAME: o nome de exibição da configuração da transferência. Ele pode ter qualquer valor que identifique facilmente a transferência, caso seja necessário modificá-la no futuro.
  • DATASET: o conjunto de dados de destino na configuração da transferência.
  • DESTINATION_KEY: (opcional) o ID de recurso da chave do Cloud KMS, por exemplo, projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name.
  • PARAMETERS: os parâmetros da configuração da transferência, listados no formato JSON. Por exemplo, --params={"param1":"value1", "param2":"value2"}. Confira a seguir os parâmetros para uma transferência do Armazenamento de Blobs:
    • destination_table_name_template: obrigatório. É o nome da tabela de destino.
    • storage_account: obrigatório. O nome da conta do Armazenamento de Blobs.
    • container: obrigatório. Nome do contêiner do Armazenamento de Blobs.
    • data_path: opcional. O caminho para filtrar os arquivos a serem transferidos. Confira exemplos.
    • sas_token: obrigatório. O token SAS do Azure.
    • file_format: opcional. O tipo de arquivo que você quer transferir: CSV, JSON, AVRO, PARQUET ou ORC. O valor padrão é CSV.
    • write_disposition: opcional. Selecione WRITE_APPEND para anexar dados à tabela de destino ou WRITE_TRUNCATE para substituir dados na tabela de destino. O valor padrão é WRITE_APPEND.
    • max_bad_records: opcional. O número de registros inválidos permitidos. O valor padrão é 0.
    • decimal_target_types: opcional. Uma lista separada por vírgulas de possíveis tipos de dados SQL em que os valores decimais nos dados de origem são 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: opcional e ignorado se file_format não for JSON ou CSV. Defina como true para aceitar linhas com valores que não correspondem ao esquema.
    • field_delimiter: opcional e aplicável somente quando file_format é CSV. É o caractere que separa os campos. O valor padrão é ,.
    • skip_leading_rows: opcional e aplicável 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 aplicável somente quando file_format é CSV. Indica se novas linhas são permitidas dentro de campos entre aspas.
    • allow_jagged_rows: opcional e aplicável somente quando file_format é CSV. Indica se você aceitará linhas que estão faltando em colunas opcionais. Os valores ausentes são preenchidos com NULL.

Por exemplo, o código a seguir cria uma transferência do Armazenamento de Blobs chamada mytransfer:

bq mk \
  --transfer_config \
  --data_source=azure_blob_storage \
  --display_name=mytransfer \
  --target_dataset=mydataset \
  --destination_kms_key=projects/myproject/locations/us/keyRings/mykeyring/cryptoKeys/key1
  --params={"destination_table_name_template":"mytable",
      "storage_account":"myaccount",
      "container":"mycontainer",
      "data_path":"myfolder/*.csv",
      "sas_token":"my_sas_token_value",
      "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"}

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 azure blob storage transfer config.
public class CreateAzureBlobStorageTransfer {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    final String displayName = "MY_TRANSFER_DISPLAY_NAME";
    final String datasetId = "MY_DATASET_ID";
    String tableId = "MY_TABLE_ID";
    String storageAccount = "MY_AZURE_STORAGE_ACCOUNT_NAME";
    String containerName = "MY_AZURE_CONTAINER_NAME";
    String dataPath = "MY_AZURE_FILE_NAME_OR_PREFIX";
    String sasToken = "MY_AZURE_SAS_TOKEN";
    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("storage_account", Value.newBuilder().setStringValue(storageAccount).build());
    params.put("container", Value.newBuilder().setStringValue(containerName).build());
    params.put("data_path", Value.newBuilder().setStringValue(dataPath).build());
    params.put("sas_token", Value.newBuilder().setStringValue(sasToken).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());
    createAzureBlobStorageTransfer(projectId, displayName, datasetId, params);
  }

  public static void createAzureBlobStorageTransfer(
      String projectId, String displayName, String datasetId, Map<String, Value> params)
      throws IOException {
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName(displayName)
            .setDataSourceId("azure_blob_storage")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    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("Azure Blob Storage transfer created successfully: " + config.getName());
    } catch (ApiException ex) {
      System.out.print("Azure Blob 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. Use uma CMEK para dar suporte a transferências do Armazenamento de Blobs do Azure.

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.

Resolver problemas na configuração da transferência

Se você tiver problemas para configurar a transferência, consulte Problemas de transferência no Armazenamento de blobs.

A seguir