Gerenciar transferências

Neste documento, mostramos como gerenciar as configurações de transferência de dados atuais.

Também é possível acionar manualmente uma transferência existente, processo conhecido também como iniciar uma execução de preenchimento.

Mostrar suas transferências

Confira as configurações de transferência atuais por meio de informações sobre cada transferência, listando todas as transferências existentes e consultando o histórico de execução de transferências ou as mensagens de registro.

Funções exigidas

Para receber as permissões necessárias para ver os detalhes da transferência, peça ao administrador para conceder a você o papel do IAM de Usuário do BigQuery (roles/bigquery.user) no projeto. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Além disso, para ver as mensagens de registro no console do Google Cloud, você precisa ter permissões para ver os dados do Cloud Logging. O papel Visualizador de registros (roles/logging.viewer) oferece acesso somente leitura a todos os recursos do Logging. Para mais informações sobre as permissões e os papéis do Identity and Access Management (IAM) que se aplicam aos dados de registros da nuvem, consulte o guia de controle de acesso do Cloud Logging.

Para mais informações sobre os papéis do IAM no serviço de transferência de dados do BigQuery, consulte Referência de controle de acesso.

Mostrar detalhes da transferência

Depois de criar uma transferência, você pode conseguir informações sobre a configuração dela. A configuração inclui os valores fornecidos quando você criou a transferência, bem como outras informações importantes, como nomes de recursos.

Para conseguir informações sobre uma configuração de transferência:

Console

Acesse a página Transferências de dados.

Acesse Transferências de dados
Selecione a transferência para conferir os detalhes.
Para ver a configuração da transferência e os detalhes da fonte de dados, clique em Configuração na página Detalhes da transferência. Confira no exemplo a seguir as propriedades de configuração de uma transferência do Google Ads.

bq

Digite o comando bq show e insira o nome do recurso da configuração da transferência. A sinalização --format pode ser usada para controlar o formato da saída.

bq show \
--format=prettyjson \
--transfer_config resource_name

Substitua resource_name pelo nome do recurso da transferência, também conhecido como configuração da transferência. Se você não souber o nome do recurso da transferência, encontre o nome do recurso com: bq ls --transfer_config --transfer_location=location.

Por exemplo, insira o comando a seguir para exibir a configuração da transferência para projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7.

bq show \
--format=prettyjson \
--transfer_config projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

API

Use o método projects.locations.transferConfigs.get e forneça a configuração da transferência por meio do parâmetro name.

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.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.GetTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import java.io.IOException;

// Sample to get config info.
public class GetTransferConfigInfo {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    // i.e projects/{project_id}/transferConfigs/{config_id}` or
    // `projects/{project_id}/locations/{location_id}/transferConfigs/{config_id}`
    getTransferConfigInfo(configId);
  }

  public static void getTransferConfigInfo(String configId) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      GetTransferConfigRequest request =
          GetTransferConfigRequest.newBuilder().setName(configId).build();
      TransferConfig info = dataTransferServiceClient.getTransferConfig(request);
      System.out.print("Config info retrieved successfully." + info.getName() + "\n");
    } catch (ApiException ex) {
      System.out.print("config not found." + ex.toString());
    }
  }
}

listar configurações de transferência;

Para listar todas as configurações de transferência existentes em um projeto:

Console

No console do Google Cloud, acesse a página "Transferências de dados".

Acesse Transferências de dados
Se houver configurações de transferência no projeto, uma lista delas será exibida na lista de transferências de dados.

bq

Para listar todas as configurações de transferência de um projeto por local, insira o comando bq ls e forneça as sinalizações --transfer_location e --transfer_config. Também é possível fornecer a sinalização --project_id para especificar um projeto determinado. Se --project_id não for especificado, o projeto padrão será usado. A sinalização --format pode ser usada para controlar o formato da saída.

Para listar configurações de transferência de fontes de dados específicas, forneça a sinalização --filter.

Para ver um número específico de configurações de transferência no formato paginado, forneça a sinalização --max_results para determinar o número de transferências. O comando retorna um token de página que você fornece usando a sinalização --page_token para ver as próximas N configurações. Há um limite de 1.000 configurações que serão retornadas se --max_results for omitido, e --max_results não aceitará valores maiores que 1.000. Se o projeto tiver mais de 1.000 configurações, use --max_results e --page_token para iterar todas elas.

bq ls \
--transfer_config \
--transfer_location=location \
--project_id=project_id \
--max_results=integer \
--filter=dataSourceIds:data_sources

Substitua:

location é o local das configurações de transferência. O local é especificado quando você cria uma transferência.
project_id é o ID do projeto;
integer é o número de resultados a serem exibidos por página;
data_sources é um ou mais dos seguintes itens:
- amazon_s3 - Transferência de dados do Amazon S3
- azure_blob_storage: transferência de dados do Armazenamento de Blobs do Azure
- dcm_dt - Transferência de dados do Campaign Manager
- google_cloud_storage - Transferência de dados do Cloud Storage
- cross_region_copy - Cópia do conjunto de dados
- dfp_dt- Transferência de dados do Google Ad Manager
- adwords - Transferência de dados do Google Ads
- google_ads – Transferência de dados do Google Ads (visualização)
- merchant_center - Transferência de dados do Google Merchant Center
- play - Transferência de dados do Google Play
- scheduled_query - Transferência de dados de consultas programadas
- doubleclick_search- Transferência de dados do Search Ads 360
- youtube_channel - Transferência de dados do canal do YouTube
- youtube_content_owner - Transferência de dados do proprietário do conteúdo do YouTube
- redshift - Migração do Amazon Redshift
- on_premises - Migração da Teradata

Exemplos:

Insira o comando a seguir para exibir todas as configurações de transferência nos EUA do projeto padrão. A saída é controlada com o uso da sinalização --format.

bq ls \
--format=prettyjson \
--transfer_config \
--transfer_location=us

Insira o comando a seguir para exibir todas as configurações de transferência nos EUA para o ID do projeto myproject.

bq ls \
--transfer_config \
--transfer_location=us \
--project_id=myproject

Insira o comando a seguir para listar as três configurações de transferência mais recentes.

bq ls \
--transfer_config \
--transfer_location=us \
--project_id=myproject \
--max_results=3

O comando retorna o token da próxima página. Copie o token da página e forneça-o no comando bq ls para ver os próximos três resultados.

bq ls \
--transfer_config \
--transfer_location=us \
--project_id=myproject \
--max_results=3 \
--page_token=AB1CdEfg_hIJKL

Insira o comando a seguir para listar as configurações de transferência do Ads e Campaign Manager para o ID do projeto myproject.

bq ls \
--transfer_config \
--transfer_location=us \
--project_id=myproject \
--filter=dataSourceIds:dcm_dt,google_ads

API

Use o método projects.locations.transferConfigs.list e insira o ID do projeto por meio do parâmetro parent.

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.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ListTransferConfigsRequest;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import java.io.IOException;

// Sample to get list of transfer config
public class ListTransferConfigs {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    listTransferConfigs(projectId);
  }

  public static void listTransferConfigs(String projectId) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      ListTransferConfigsRequest request =
          ListTransferConfigsRequest.newBuilder().setParent(parent.toString()).build();
      dataTransferServiceClient
          .listTransferConfigs(request)
          .iterateAll()
          .forEach(config -> System.out.print("Success! Config ID :" + config.getName() + "\n"));
    } catch (ApiException ex) {
      System.out.println("Config list not found due to error." + ex.toString());
    }
  }
}

Python

Antes de testar esta amostra, siga as instruções de configuração do Python 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 Python.

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

from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

project_id = "my-project"
parent = transfer_client.common_project_path(project_id)

configs = transfer_client.list_transfer_configs(parent=parent)
print("Got the following configs:")
for config in configs:
    print(f"\tID: {config.name}, Schedule: {config.schedule}")

Mostrar o histórico de execução da transferência

À medida que as transferências programadas são executadas, um histórico de execução é mantido para cada configuração de transferência que inclui tanto execuções de transferência bem-sucedidas quanto que apresentam falha. As execuções de transferência com mais de 90 dias são excluídas automaticamente do histórico de execução.

Para ver o histórico de execução de uma configuração de transferência:

Console

No console do Google Cloud, acesse a página "Transferências de dados".

Acesse Transferências de dados
Clique na transferência na lista correspondente.
Você estará na página EXECUTAR HISTÓRICO da transferência selecionada.

bq

Para listar as execuções de transferência de uma configuração específica, digite o comando bq ls e insira a sinalização --transfer_run. Também é possível inserir a sinalização --project_id para especificar um projeto determinado. Se resource_name não contiver informações do projeto, o valor --project_id será usado. Se --project_id não for especificado, o projeto padrão será usado. A sinalização --format pode ser usada para controlar o formato da saída.

Para visualizar um número específico de execuções de transferência, forneça a sinalização --max_results. O comando retorna um token de página que você fornece usando a sinalização --page_token para ver as próximas N configurações.

Para listar execuções de transferência com base no estado delas, forneça a sinalização --filter.

bq ls \
--transfer_run \
--max_results=integer \
--transfer_location=location \
--project_id=project_id \
--filter=states:state, ... \
resource_name

Substitua:

integer é o número de resultados que serão retornados;
location é o local das configurações de transferência. O local é especificado quando você cria uma transferência.
project_id é o ID do projeto;
state, ... é uma das listas a seguir ou uma lista separada por vírgulas:
- SUCCEEDED
- FAILED
- PENDING
- RUNNING
- CANCELLED
resource_name é o nome do recurso da transferência, também conhecido como configuração da transferência. Se você não souber o nome do recurso da transferência, encontre o nome do recurso com: bq ls --transfer_config --transfer_location=location.

Exemplos:

Insira o comando a seguir para exibir as três execuções mais recentes da configuração de transferência projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7. A saída é controlada com o uso da sinalização --format.

bq ls \
--format=prettyjson \
--transfer_run \
--max_results=3 \
--transfer_location=us \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

O comando retorna o token da próxima página. Copie o token da página e forneça-o no comando bq ls para ver os próximos três resultados.

bq ls \
--format=prettyjson \
--transfer_run \
--max_results=3 \
--page_token=AB1CdEfg_hIJKL \
--transfer_location=us \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

Insira o comando a seguir para exibir todas as execuções com falha na configuração de transferência projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7.

bq ls \
--format=prettyjson \
--transfer_run \
--filter=states:FAILED \
--transfer_location=us \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

API

Use o método projects.locations.transferConfigs.runs.list e especifique o ID do projeto por meio do parâmetro parent.

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.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ListTransferRunsRequest;
import java.io.IOException;

// Sample to get run history from transfer config.
public class RunHistory {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    // i.e projects/{project_id}/transferConfigs/{config_id}` or
    // `projects/{project_id}/locations/{location_id}/transferConfigs/{config_id}`
    runHistory(configId);
  }

  public static void runHistory(String configId) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      ListTransferRunsRequest request =
          ListTransferRunsRequest.newBuilder().setParent(configId).build();
      dataTransferServiceClient
          .listTransferRuns(request)
          .iterateAll()
          .forEach(run -> System.out.print("Success! Run ID :" + run.getName() + "\n"));
    } catch (ApiException ex) {
      System.out.println("Run history not found due to error." + ex.toString());
    }
  }
}

Visualizar detalhes da execução de transferências e mensagens de registros

Quando uma execução de transferência aparece no histórico de execução, você pode ver os detalhes de execução, incluindo mensagens de registro, advertências e erros, o nome da execução e a hora de início e término.

Para mais detalhes da execução da transferência:

Console

No console do Google Cloud, acesse a página "Transferências de dados".

Acesse Transferências de dados
Clique na transferência na lista correspondente.
Você estará na página EXECUTAR HISTÓRICO da transferência selecionada.
Clique em uma execução individual da transferência, e o painel Detalhes da execução será aberto para essa execução da transferência.
Em Detalhes da execução, observe se há mensagens de erro. Essas informações são necessárias para entrar em contato com o Cloud Customer Care. Os detalhes da execução também incluem mensagens de registro e avisos.

bq

Para ver os detalhes da execução de transferência, digite o comando bq show e insira o nome da execução da transferência usando a sinalização --transfer_run. A sinalização --format pode ser usada para controlar o formato da saída.

bq show \
--format=prettyjson \
--transfer_run run_name

Substitua run_name pelo nome da execução de transferência. Use o comando bq ls para recuperar o nome da execução.

Exemplo:

Insira o comando a seguir para exibir os detalhes da execução de transferência projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7/runs/1a2b345c-0000-1234-5a67-89de1f12345g.

bq show \
--format=prettyjson \
--transfer_run \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7/runs/1a2b345c-0000-1234-5a67-89de1f12345g

Para ver as mensagens do registro de transferência de uma execução, insira o comando bq ls com a sinalização --transfer_log. Use a sinalização --message_type para filtrar mensagens de registro por tipo.

Para ver um determinado número de mensagens de registro, forneça a sinalização --max_results. O comando retorna um token de página que você fornece usando a sinalização --page_token para ver as próximas N mensagens.

bq ls \
--transfer_log \
--max_results=integer \
--message_type=messageTypes:message_type \
run_name

Substitua:

integer é o número de mensagens de registro que serão retornadas;
message_type é o tipo de mensagem de registro para visualizar (um valor único ou uma lista separada por vírgulas):
- INFO
- WARNING
- ERROR
run_name é o nome da execução de transferência. É possível recuperá-lo usando o comando bq ls.

Exemplos:

Insira o comando a seguir para visualizar as duas primeiras mensagens de registro da execução de transferência projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7/runs/1a2b345c-0000-1234-5a67-89de1f12345g.

bq ls \
--transfer_log \
--max_results=2 \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7/runs/1a2b345c-0000-1234-5a67-89de1f12345g

O comando retorna o token da próxima página. Copie o token da página e forneça-o no comando bq ls para ver os próximos dois resultados.

bq ls \
--transfer_log \
--max_results=2 \
--page_token=AB1CdEfg_hIJKL \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7/runs/1a2b345c-0000-1234-5a67-89de1f12345g

Insira o comando a seguir para visualizar somente mensagens de erro da execução de transferência projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7/runs/1a2b345c-0000-1234-5a67-89de1f12345g.

bq ls \
--transfer_log \
--message_type=messageTypes:ERROR \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7/runs/1a2b345c-0000-1234-5a67-89de1f12345g

API

Use o método projects.transferConfigs.runs.transferLogs.list e forneça o nome da execução de transferência por meio do parâmetro parent.

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.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.GetTransferRunRequest;
import com.google.cloud.bigquery.datatransfer.v1.TransferRun;
import java.io.IOException;

// Sample to get run details from transfer config.
public class RunDetails {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // runId examples:
    // `projects/{project_id}/transferConfigs/{config_id}/runs/{run_id}` or
    // `projects/{project_id}/locations/{location_id}/transferConfigs/{config_id}/runs/{run_id}`
    String runId = "MY_RUN_ID";
    runDetails(runId);
  }

  public static void runDetails(String runId) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      GetTransferRunRequest request = GetTransferRunRequest.newBuilder().setName(runId).build();
      TransferRun run = dataTransferServiceClient.getTransferRun(request);
      System.out.print("Run details retrieved successfully :" + run.getName() + "\n");
    } catch (ApiException ex) {
      System.out.print("Run details not found." + ex.toString());
    }
  }
}

Modificar suas transferências

É possível modificar transferências existentes editando informações sobre a configuração da transferência, atualizando as credenciais de um usuário anexadas a uma configuração de transferência e desativando ou excluindo uma transferência.

Funções exigidas

Para conseguir as permissões necessárias para modificar as transferências, peça ao administrador para conceder a você o papel do IAM de Administrador do BigQuery (roles/bigquery.admin) no projeto. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Atualizar uma transferência

Depois de criar uma configuração de transferência, você pode editar os seguintes campos:

Conjunto de dados de destino
nome de exibição
qualquer um dos parâmetros especificados para o tipo de transferência específico
Executar configurações de notificação
Conta de serviço

Não é possível editar a origem de uma transferência depois que ela é criada.

Para atualizar uma transferência, siga estas etapas:

Console

No console do Google Cloud, acesse a página "Transferências de dados".

Acesse Transferências de dados
Clique na transferência na lista correspondente.
Clique em EDITAR para atualizar a configuração da transferência.

bq

Digite o comando bq update, insira o nome do recurso da configuração de transferência por meio do flag --transfer_config e especifique os flags --display_name, --params, --refresh_window_days, --schedule ou --target_dataset. Também é possível fornecer uma sinalização --destination_kms_key para consultas programadas ou transferências do Cloud Storage.

bq update \
--display_name='NAME' \
--params='PARAMETERS' \
--refresh_window_days=INTEGER \
--schedule='SCHEDULE'
--target_dataset=DATASET_ID \
--destination_kms_key="DESTINATION_KEY" \
--transfer_config \
--service_account_name=SERVICE_ACCOUNT \
RESOURCE_NAME

Substitua:

NAME: o nome de exibição da configuração da transferência.
PARAMETERS: os parâmetros da configuração de transferência no formato JSON. Por exemplo, --params='{"param1":"param_value1"}'. Os parâmetros a seguir podem ser editados:
- Campaign Manager: bucket e network_id
- Google Ad Manager: bucket e network_code
- Google Ads: customer_id
- Google Merchant Center: merchant_id
- Google Play: bucket e table_suffix
- Consulta programada: destination_table_kms_key, destination_table_name_template, partitioning_field, partitioning_type, query e write_disposition
- Search Ads 360: advertiser_id, agency_id, custom_floodlight_variables, include_removed_entities e table_filter
- Canal do YouTube: table_suffix
- Proprietário do conteúdo do YouTube: content_owner_id e table_suffix
INTEGER: um valor de 0 a 30. Para informações sobre como configurar a janela de atualização, consulte a documentação do seu tipo de transferência.
SCHEDULE: uma programação recorrente, como --schedule="every 3 hours". Para ver uma descrição da sintaxe schedule, consulte Formatar schedule.
DATASET_ID: 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. A CMEK está disponível apenas para consultas programadas ou transferências do Cloud Storage.
SERVICE_ACCOUNT: especifique uma conta de serviço a ser usada com essa transferência.
RESOURCE_NAME: o nome do recurso da transferência, também conhecido como configuração da transferência. Se você não souber o nome do recurso da transferência, encontre-o com: bq ls --transfer_config --transfer_location=location.

Exemplos:

O comando a seguir atualiza o nome de exibição, o conjunto de dados de destino, a janela de atualização e os parâmetros para a transferência projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7 do Google Ads:

bq update \
--display_name='My changed transfer' \
--params='{"customer_id":"123-123-5678"}' \
--refresh_window_days=3 \
--target_dataset=mydataset2 \
--transfer_config \
 projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

O seguinte comando atualiza os parâmetros e a programação da transferência de consulta programada projects/myproject/locations/us/transferConfigs/5678z567-5678-5z67-5yx9-56zy3c866vw9:

bq update \
--params='{"destination_table_name_template":"test", "write_disposition":"APPEND"}' \
--schedule="every 24 hours" \
--transfer_config \
projects/myproject/locations/us/transferConfigs/5678z567-5678-5z67-5yx9-56zy3c866vw9

API

Use o método projects.transferConfigs.patch e forneça o nome do recurso da transferência por meio do parâmetro transferConfig.name. Se você não souber o nome do recurso da transferência, encontre o nome do recurso com: bq ls --transfer_config --transfer_location=location. Também é possível chamar o método a seguir e fornecer o ID do projeto usando o parâmetro parent para listar todas as transferências: projects.locations.transferConfigs.list.

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.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.cloud.bigquery.datatransfer.v1.UpdateTransferConfigRequest;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

// Sample to update transfer config.
public class UpdateTransferConfig {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setName(configId)
            .setDisplayName("UPDATED_DISPLAY_NAME")
            .build();
    FieldMask updateMask = FieldMaskUtil.fromString("display_name");
    updateTransferConfig(transferConfig, updateMask);
  }

  public static void updateTransferConfig(TransferConfig transferConfig, FieldMask updateMask)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      UpdateTransferConfigRequest request =
          UpdateTransferConfigRequest.newBuilder()
              .setTransferConfig(transferConfig)
              .setUpdateMask(updateMask)
              .build();
      TransferConfig updateConfig = dataTransferServiceClient.updateTransferConfig(request);
      System.out.println("Transfer config updated successfully :" + updateConfig.getDisplayName());
    } catch (ApiException ex) {
      System.out.print("Transfer config was not updated." + ex.toString());
    }
  }
}

Python

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

from google.cloud import bigquery_datatransfer
from google.protobuf import field_mask_pb2

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"
new_display_name = "My Transfer Config"

transfer_config = bigquery_datatransfer.TransferConfig(name=transfer_config_name)
transfer_config.display_name = new_display_name

transfer_config = transfer_client.update_transfer_config(
    {
        "transfer_config": transfer_config,
        "update_mask": field_mask_pb2.FieldMask(paths=["display_name"]),
    }
)

print(f"Updated config: '{transfer_config.name}'")
print(f"New display name: '{transfer_config.display_name}'")

Atualizar credenciais

Uma transferência usa as credenciais do usuário que a criou. Se você precisar alterar o usuário anexado a uma configuração de transferência, será possível atualizar as credenciais da transferência. Isso é útil se o usuário que criou a transferência não estiver mais em sua organização.

Para atualizar as credenciais de uma transferência:

Console

No console do Google Cloud, acesse a página "Transferências de dados".

Acesse Transferências de dados
Clique na transferência na lista correspondente.
Clique no menu MAIS e, em seguida, selecione Atualizar credenciais.
Faça login na sua Conta do Google e clique em Permitir para conceder ao serviço de transferência de dados do BigQuery permissão para ver os dados de relatórios e acessar e gerenciar os dados no BigQuery.

bq

Digite o comando bq update, insira o nome do recurso da configuração de transferência por meio do flag --transfer_config e especifique o flag --update_credentials.

bq update \
--update_credentials=boolean \
--transfer_config \
resource_name

Substitua:

boolean é um valor booleano que indica se as credenciais precisam ser atualizadas para a configuração da transferência;
resource_name é o nome do recurso da transferência, também conhecido como configuração da transferência. Se você não souber o nome do recurso da transferência, encontre o nome do recurso com: bq ls --transfer_config --transfer_location=location.

Exemplos:

Insira o comando a seguir para atualizar as credenciais da transferência projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7 do Google Ads.

bq update \
--update_credentials=true \
--transfer_config \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

API

Use o método projects.transferConfigs.patch e forneça os parâmetros authorizationCode e updateMask.

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.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.cloud.bigquery.datatransfer.v1.UpdateTransferConfigRequest;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

// Sample to update credentials in transfer config.
public class UpdateCredentials {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    String serviceAccount = "MY_SERVICE_ACCOUNT";
    TransferConfig transferConfig = TransferConfig.newBuilder().setName(configId).build();
    FieldMask updateMask = FieldMaskUtil.fromString("service_account_name");
    updateCredentials(transferConfig, serviceAccount, updateMask);
  }

  public static void updateCredentials(
      TransferConfig transferConfig, String serviceAccount, FieldMask updateMask)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      UpdateTransferConfigRequest request =
          UpdateTransferConfigRequest.newBuilder()
              .setTransferConfig(transferConfig)
              .setUpdateMask(updateMask)
              .setServiceAccountName(serviceAccount)
              .build();
      dataTransferServiceClient.updateTransferConfig(request);
      System.out.println("Credentials updated successfully");
    } catch (ApiException ex) {
      System.out.print("Credentials was not updated." + ex.toString());
    }
  }
}

Python

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

from google.cloud import bigquery_datatransfer
from google.protobuf import field_mask_pb2

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

service_account_name = "abcdef-test-sa@abcdef-test.iam.gserviceaccount.com"
transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"

transfer_config = bigquery_datatransfer.TransferConfig(name=transfer_config_name)

transfer_config = transfer_client.update_transfer_config(
    {
        "transfer_config": transfer_config,
        "update_mask": field_mask_pb2.FieldMask(paths=["service_account_name"]),
        "service_account_name": service_account_name,
    }
)

print("Updated config: '{}'".format(transfer_config.name))

Desativar uma transferência

Quando você desativa uma transferência, disabled é adicionado ao nome da transferência. Quando a transferência é desativada, nenhuma execução nova é programada e nenhum preenchimento novo é permitido. Todas as transferências em andamento são concluídas.

Desativar uma transferência não remove os dados já transferidos para o BigQuery. Os dados transferidos anteriormente geram custos de armazenamento padrão do BigQuery até você excluir o conjunto de dados ou as tabelas.

Para desativar uma transferência:

Console

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

Ir para o BigQuery
Clique em Transferências.
Na página Transferências, clique na transferência na lista que você quer desativar.
Clique em DESATIVAR. Para reativar a transferência, clique em ATIVAR.

bq

A CLI não aceita a desativação de uma transferência.

API

Use o método projects.locations.transferConfigs.patch e defina disabled como true no recurso projects.locations.transferConfig.

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.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.cloud.bigquery.datatransfer.v1.UpdateTransferConfigRequest;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

// Sample to disable transfer config.
public class DisableTransferConfig {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    TransferConfig transferConfig =
        TransferConfig.newBuilder().setName(configId).setDisabled(true).build();
    FieldMask updateMask = FieldMaskUtil.fromString("disabled");
    disableTransferConfig(transferConfig, updateMask);
  }

  public static void disableTransferConfig(TransferConfig transferConfig, FieldMask updateMask)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      UpdateTransferConfigRequest request =
          UpdateTransferConfigRequest.newBuilder()
              .setTransferConfig(transferConfig)
              .setUpdateMask(updateMask)
              .build();
      TransferConfig updateConfig = dataTransferServiceClient.updateTransferConfig(request);
      System.out.println("Transfer config disabled successfully :" + updateConfig.getDisplayName());
    } catch (ApiException ex) {
      System.out.print("Transfer config was not disabled." + ex.toString());
    }
  }
}

Para reativar a transferência, siga estas etapas:

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

/*
 * Copyright 2020 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.example.bigquerydatatransfer;

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.cloud.bigquery.datatransfer.v1.UpdateTransferConfigRequest;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

// Sample to disable transfer config.
public class DisableTransferConfig {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    TransferConfig transferConfig =
        TransferConfig.newBuilder().setName(configId).setDisabled(true).build();
    FieldMask updateMask = FieldMaskUtil.fromString("disabled");
    disableTransferConfig(transferConfig, updateMask);
  }

  public static void disableTransferConfig(TransferConfig transferConfig, FieldMask updateMask)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      UpdateTransferConfigRequest request =
          UpdateTransferConfigRequest.newBuilder()
              .setTransferConfig(transferConfig)
              .setUpdateMask(updateMask)
              .build();
      TransferConfig updateConfig = dataTransferServiceClient.updateTransferConfig(request);
      System.out.println("Transfer config disabled successfully :" + updateConfig.getDisplayName());
    } catch (ApiException ex) {
      System.out.print("Transfer config was not disabled." + ex.toString());
    }
  }
}

Excluir uma transferência

Quando uma transferência é excluída, nenhuma execução de transferência nova é programada. Qualquer execução de transferência em andamento é interrompida.

A exclusão de uma transferência não remove nenhum dado já transferido para o BigQuery. Os dados transferidos anteriormente geram custos de armazenamento padrão do BigQuery até você excluir o conjunto de dados ou as tabelas.

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

Console

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

Ir para o BigQuery
Clique em Transferências.
Na página Transferências, clique na transferência na lista que você quer excluir.
Clique em EXCLUIR. Como medida de segurança, você precisará digitar a palavra "delete" em uma caixa para confirmar sua intenção.

Cuidado: a operação de exclusão não pode ser desfeita.

bq

Digite o comando bq rm e insira o nome do recurso da configuração da transferência. Use a sinalização -f para excluir uma configuração de transferência sem confirmação.

bq rm \
-f \
--transfer_config \
resource_name

Em que:

resource_name é o nome do recurso da transferência, também conhecido como configuração da transferência. Se você não souber esse nome, execute o comando bq ls --transfer_config --transfer_location=location para listar todas as transferências.

Por exemplo, insira o comando a seguir para excluir a configuração da transferência projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7.

bq rm \
--transfer_config \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

API

Use o método projects.locations.transferConfigs.delete e forneça o recurso que você está excluindo por meio do parâmetro name.

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.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.DeleteTransferConfigRequest;
import java.io.IOException;

// Sample to delete a transfer config
public class DeleteTransferConfig {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // i.e projects/{project_id}/transferConfigs/{config_id}` or
    // `projects/{project_id}/locations/{location_id}/transferConfigs/{config_id}`
    String configId = "MY_CONFIG_ID";
    deleteTransferConfig(configId);
  }

  public static void deleteTransferConfig(String configId) throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      DeleteTransferConfigRequest request =
          DeleteTransferConfigRequest.newBuilder().setName(configId).build();
      dataTransferServiceClient.deleteTransferConfig(request);
      System.out.println("Transfer config deleted successfully");
    } catch (ApiException ex) {
      System.out.println("Transfer config was not deleted." + ex.toString());
    }
  }
}

Python

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

import google.api_core.exceptions
from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"
try:
    transfer_client.delete_transfer_config(name=transfer_config_name)
except google.api_core.exceptions.NotFound:
    print("Transfer config not found.")
else:
    print(f"Deleted transfer config: {transfer_config_name}")

Acionar manualmente uma transferência

É possível acionar manualmente uma transferência, também chamada de execução de preenchimento, para carregar outros arquivos de dados fora das transferências programadas automaticamente. Com fontes de dados compatíveis com parâmetros de ambiente de execução, também é possível acionar manualmente uma transferência especificando uma data ou um período para carregar dados antigos.

É possível iniciar os preenchimentos de dados manualmente a qualquer momento. Além dos limites de origem, o serviço de transferência de dados do BigQuery aceita até 180 dias por solicitação de preenchimento. As solicitações simultâneas de preenchimento não são compatíveis.

Para informações sobre a quantidade de dados disponíveis para preenchimento, consulte o guia de transferência da sua fonte de dados.

Funções exigidas

Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Acionar manualmente uma transferência ou um preenchimento

É possível acionar manualmente uma execução de transferência ou preenchimento com os seguintes métodos:

Selecione a execução de transferência usando o console do Google Cloud e clique em Executar transferência agora ou Programar preenchimento.
Use o comando bq mk –transfer run usando a ferramenta de linha de comando bq.
Chame o método de API projects.locations.transferConfigs.startManualRuns method.

Para instruções detalhadas sobre cada método, selecione a guia correspondente:

Console

No console do Google Cloud, acesse a página "Transferências de dados".

Acesse Transferências de dados
Selecione a transferência na lista.
Clique em Executar transferência agora ou Programar preenchimento. Apenas uma opção está disponível, dependendo do tipo de configuração de transferência.
- 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:
- 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:
Clique em OK.

bq

Para iniciar uma execução de transferência manualmente, insira o comando bq mk com a sinalização --transfer_run:

bq mk \
--transfer_run \
--run_time='RUN_TIME' \
RESOURCE_NAME

Substitua:

RUN_TIME é um carimbo de data/hora que especifica a data de uma transferência anterior. Use carimbos de data/hora que terminam em Z ou contêm um deslocamento de fuso horário válido, por exemplo, 2022-08-19T12:11:35.00Z ou 2022-05-25T00:00:00+00:00.
- Se a transferência não tiver um parâmetro de ambiente de execução ou se você apenas quiser acionar uma transferência agora sem especificar uma transferência anterior, insira o horário atual nesse campo.
RESOURCE_NAME é o nome do recurso listado na configuração da transferência. Por exemplo, projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7.
- Para encontrar o nome do recurso de uma configuração de transferência, consulte Receber informações sobre transferências.
- O nome do recurso usa o formato Relative resource name.

Para iniciar manualmente uma execução de transferência para um intervalo de datas, insira o comando bq mk com a sinalização --transfer_run junto com um período:

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

Substitua:

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. Esses valores especificam o intervalo de tempo que contém as execuções de transferência anteriores que você quer preencher. Por exemplo, 2022-08-19T12:11:35.00Z ou 2022-05-25T00:00:00+00:00.
RESOURCE_NAME é o nome do recurso listado na configuração da transferência. Por exemplo, projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7
- Para encontrar o nome do recurso de uma configuração de transferência, consulte Receber informações sobre transferências.
- O nome do recurso usa o formato Relative resource name.

API

Para iniciar uma execução de transferência manualmente, use o método projects.locations.transferConfigs.startManualRuns e forneça o nome do recurso de configuração da transferência usando o parâmetro pai. Para encontrar o nome do recurso de uma configuração de transferência, consulte Receber informações sobre transferências.

  "requestedRunTime": "RUN_TIME"

Substitua:

RUN_TIME é um carimbo de data/hora que especifica a data de uma transferência anterior. Use carimbos de data/hora que terminam em Z ou contêm um deslocamento de fuso horário válido, por exemplo, 2022-08-19T12:11:35.00Z ou 2022-05-25T00:00:00+00:00.
- Se a transferência não tiver um parâmetro de ambiente de execução ou se você apenas quiser acionar uma transferência agora sem especificar uma transferência anterior, insira o horário atual nesse campo.

Para iniciar manualmente uma execução de transferência para um intervalo de datas, forneça um período:

"requestedTimeRange": {
  "startTime": "START_TIME",
  "endTime": "END_TIME"
}

Substitua:

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. Esses valores especificam o intervalo de tempo que contém as execuções de transferência anteriores que você quer preencher. Por exemplo, 2022-08-19T12:11:35.00Z ou 2022-05-25T00:00:00+00:00.

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.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ScheduleTransferRunsRequest;
import com.google.cloud.bigquery.datatransfer.v1.ScheduleTransferRunsResponse;
import com.google.protobuf.Timestamp;
import java.io.IOException;
import org.threeten.bp.Clock;
import org.threeten.bp.Instant;
import org.threeten.bp.temporal.ChronoUnit;

// Sample to run schedule back fill for transfer config
public class ScheduleBackFill {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String configId = "MY_CONFIG_ID";
    Clock clock = Clock.systemDefaultZone();
    Instant instant = clock.instant();
    Timestamp startTime =
        Timestamp.newBuilder()
            .setSeconds(instant.minus(5, ChronoUnit.DAYS).getEpochSecond())
            .setNanos(instant.minus(5, ChronoUnit.DAYS).getNano())
            .build();
    Timestamp endTime =
        Timestamp.newBuilder()
            .setSeconds(instant.minus(2, ChronoUnit.DAYS).getEpochSecond())
            .setNanos(instant.minus(2, ChronoUnit.DAYS).getNano())
            .build();
    scheduleBackFill(configId, startTime, endTime);
  }

  public static void scheduleBackFill(String configId, Timestamp startTime, Timestamp endTime)
      throws IOException {
    try (DataTransferServiceClient client = DataTransferServiceClient.create()) {
      ScheduleTransferRunsRequest request =
          ScheduleTransferRunsRequest.newBuilder()
              .setParent(configId)
              .setStartTime(startTime)
              .setEndTime(endTime)
              .build();
      ScheduleTransferRunsResponse response = client.scheduleTransferRuns(request);
      System.out.println("Schedule backfill run successfully :" + response.getRunsCount());
    } catch (ApiException ex) {
      System.out.print("Schedule backfill was not run." + ex.toString());
    }
  }
}

Python

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

import datetime

from google.cloud.bigquery_datatransfer_v1 import (
    DataTransferServiceClient,
    StartManualTransferRunsRequest,
)

# Create a client object
client = DataTransferServiceClient()

# Replace with your transfer configuration name
transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"
now = datetime.datetime.now(datetime.timezone.utc)
start_time = now - datetime.timedelta(days=5)
end_time = now - datetime.timedelta(days=2)

# Some data sources, such as scheduled_query only support daily run.
# Truncate start_time and end_time to midnight time (00:00AM UTC).
start_time = datetime.datetime(
    start_time.year, start_time.month, start_time.day, tzinfo=datetime.timezone.utc
)
end_time = datetime.datetime(
    end_time.year, end_time.month, end_time.day, tzinfo=datetime.timezone.utc
)

requested_time_range = StartManualTransferRunsRequest.TimeRange(
    start_time=start_time,
    end_time=end_time,
)

# Initialize request argument(s)
request = StartManualTransferRunsRequest(
    parent=transfer_config_name,
    requested_time_range=requested_time_range,
)

# Make the request
response = client.start_manual_transfer_runs(request=request)

# Handle the response
print("Started manual transfer runs:")
for run in response.runs:
    print(f"backfill: {run.run_time} run: {run.name}")

Geração de registros e monitoramento

O serviço de transferência de dados do BigQuery exporta registros e métricas para o Cloud Monitoring e o Cloud Logging que fornecem observabilidade nas transferências. É possível usar o Monitoring para configurar painéis para monitorar transferências, avaliar o desempenho de execução de transferências e exibir mensagens de erro para resolver falhas de transferência. É possível usar o Logging para ver registros relacionados a uma execução de transferência ou uma configuração de transferência.

Também é possível ver os registros de auditoria disponíveis para o serviço de transferência de dados do BigQuery sobre registros de acesso a dados e atividade de transferência.