転送を管理する

このドキュメントでは、既存のデータ転送構成を管理する方法について説明します。

既存の転送を手動でトリガーする（バックフィル実行とも呼ばれます）こともできます。

転送を表示する

既存の転送構成は、各転送に関する情報を表示する、既存のすべての転送を一覧表示する、転送の実行履歴やログメッセージを表示するなどの方法で表示します。

必要なロール

転送の詳細を表示するために必要な権限を取得するには、プロジェクトで BigQuery ユーザー（roles/bigquery.user）IAM ロールを付与するように管理者へ依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

また、Google Cloud コンソールでログメッセージを表示するには、Cloud Logging データを表示する権限が必要です。ログ閲覧者ロール（roles/logging.viewer）は、Logging のすべての機能に対する読み取り専用権限を付与します。クラウドログデータに適用される Identity and Access Management（IAM）の権限とロールの詳細については、Cloud Logging のアクセス制御ガイドをご覧ください。

BigQuery Data Transfer Service での IAM ロールについて、詳しくはアクセス制御をご覧ください。

転送の詳細を取得する

転送を作成すると、転送の構成に関する情報を取得できます。この構成には、転送を作成したときに指定した値のほか、リソース名などの重要な情報が含まれます。

転送構成に関する情報を取得するには:

コンソール

[データ転送] ページに移動します。

[データ転送] に移動
詳細を確認する転送を選択します。
転送構成とデータソースの詳細を表示するには、[転送の詳細] ページで [構成] をクリックします。次の例は、Google 広告の転送の構成プロパティを示しています。

bq

bq show コマンドを入力して、転送構成のリソース名を指定します。--format フラグを使用して出力を制御できます。

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

resource_name は、転送のリソース名（転送構成とも呼ばれます）に置き換えます。転送のリソース名がわからない場合は、bq ls --transfer_config --transfer_location=location を使用してリソース名を探します。

たとえば、転送構成 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

projects.locations.transferConfigs.get メソッドを使用して、name パラメータで転送構成を指定します。

Java

このサンプルを試す前に、クライアントライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンスドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアントライブラリの認証を設定するをご覧ください。

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

転送構成を一覧表示する

プロジェクト内の既存のすべての転送構成を一覧表示するには:

コンソール

Google Cloud コンソールで、[データ転送] ページに移動します。

[データ転送] に移動
転送構成がプロジェクトにある場合、転送構成のリストは、[データ転送] リストに表示されます。

bq

プロジェクトのすべての転送構成をロケーション別に一覧表示するには、bq ls コマンドを入力して、--transfer_location フラグと --transfer_config フラグを指定します。--project_id フラグを指定して、特定のプロジェクトを指定することもできます。--project_id を指定しない場合は、デフォルトのプロジェクトが使用されます。--format フラグを使用して出力を制御できます。

--filter フラグを指定すると、特定のデータソースの転送構成を一覧表示できます。

特定の数の転送構成をページ分け形式で表示するには、--max_results フラグを使用して転送の数を指定します。このコマンドは、--page_token フラグを使用して、指定したページトークンを返し、次の n 個の構成を表示します。--max_results を省略すると、1,000 個を超える構成は返されません。--max_results は 1,000 を超える値を受け付けません。プロジェクトに 1,000 を超える構成がある場合は、--max_results と --page_token を使用して反復処理します。

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

次のように置き換えます。

location は転送構成のロケーションです。ロケーションは、転送を作成するときに指定されます。
project_id はプロジェクト ID です。
integer は 1 ページに表示する結果の数です。
data_sources は次の中のいずれか 1 つ以上です。
- amazon_s3 - Amazon S3 データ転送
- azure_blob_storage - Azure Blob Storage データ転送
- dcm_dt - キャンペーンマネージャーデータ転送
- google_cloud_storage - Cloud Storage データ転送
- cross_region_copy - データセットコピー
- dfp_dt - Google アドマネージャーデータ転送
- adwords - Google 広告データ転送
- google_ads - Google 広告データ転送（プレビュー）
- merchant_center - Google Merchant Center データ転送
- play - Google Play データ転送
- scheduled_query - スケジュールされたクエリデータ転送
- doubleclick_search - 検索広告 360 データ転送
- youtube_channel - YouTube チャンネルデータ転送
- youtube_content_owner - YouTube コンテンツ所有者データ転送
- redshift - Amazon Redshift の移行
- on_premises - Teradata の移行

例:

US にあるデフォルトのプロジェクトのすべての転送構成を表示するには、次のコマンドを入力します。--format フラグを使用して出力を制御します。

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

US にある、プロジェクト ID myproject のすべての転送構成を表示するには、次のコマンドを入力します。

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

最新の 3 つの転送構成を一覧表示するには、次のコマンドを入力します。

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

このコマンドは次のページトークンを返します。ページトークンをコピーして bq ls コマンドで指定し、次の 3 件の結果を表示します。

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

プロジェクト ID myproject の広告とキャンペーンマネージャーの転送構成を一覧表示するには、次のコマンドを入力します。

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

API

projects.locations.transferConfigs.list メソッドを使用して、parent パラメータでプロジェクト ID を指定します。

Java

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

このサンプルを試す前に、クライアントライブラリを使用した BigQuery クイックスタートにある Python の設定手順を完了してください。詳細については、BigQuery Python API のリファレンスドキュメントをご覧ください。

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}")

転送の実行履歴を表示する

スケジュールされた転送が実行されると、成功した転送実行と失敗した転送実行を含む実行履歴が転送構成ごとに保持されます。90 日が経過した転送実行は実行履歴から自動的に削除されます。

転送構成の実行履歴を表示するには:

コンソール

Google Cloud コンソールで、[データ転送] ページに移動します。

[データ転送] に移動
データ転送リストで、転送をクリックします。
選択した転送の [実行履歴] ページが表示されます。

bq

特定の転送構成の転送実行を一覧表示するには、bq ls コマンドを入力して、--transfer_run フラグを指定します。--project_id フラグを指定して、特定のプロジェクトを指定することもできます。resource_name にプロジェクト情報が含まれていない場合は、--project_id 値が使用されます。--project_id を指定しない場合は、デフォルトのプロジェクトが使用されます。--format フラグを使用して出力を制御できます。

特定の数の転送実行を表示するには、--max_results フラグを指定します。このコマンドは、--page_token フラグを使用して、指定したページトークンを返し、次の n 個の構成を表示します。

実行状態に基づいて転送実行を一覧表示するには、--filter フラグを指定します。

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

次のように置き換えます。

integer は返す結果の数です。
location は転送構成のロケーションです。ロケーションは、転送を作成するときに指定されます。
project_id はプロジェクト ID です。
state, ... は、次のいずれか、またはカンマ区切りのリストです。
- SUCCEEDED
- FAILED
- PENDING
- RUNNING
- CANCELLED
resource_name は転送のリソース名（転送構成とも呼ばれます）です。転送のリソース名がわからない場合は、bq ls --transfer_config --transfer_location=location を使用してリソース名を探します。

例:

転送構成 projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7 の最新の 3 件の実行を表示するには、次のコマンドを入力します。--format フラグを使用して出力を制御します。

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

このコマンドは次のページトークンを返します。ページトークンをコピーして bq ls コマンドで指定し、次の 3 件の結果を表示します。

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

転送構成 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

projects.locations.transferConfigs.runs.list メソッドを使用して、parent パラメータでプロジェクト ID を指定します。

Java

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

転送実行の詳細とログメッセージを表示する

実行履歴に転送実行が表示されたら、ログメッセージ、警告とエラー、実行名、開始時間と終了時間などの実行の詳細を表示できます。

転送実行の詳細を表示するには:

コンソール

Google Cloud コンソールで、[データ転送] ページに移動します。

[データ転送] に移動
データ転送リストで、転送をクリックします。
選択した転送の [実行履歴] ページが表示されます。
転送の個別の実行をクリックして [実行の詳細] パネルをクリックすると、その転送の実行が開きます。
[実行の詳細] で、エラーメッセージを確認します。この情報は、Cloud カスタマーケアへのお問い合わせの際に必要になります。実行の詳細には、ログメッセージと警告も含まれます。

bq

転送実行の詳細を表示するには、bq show コマンドを入力して、--transfer_run フラグを使用して転送実行の実行名を指定します。--format フラグを使用して出力を制御できます。

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

run_name は、転送実行の実行名に置き換えます。実行名を取得するには、bq ls コマンドを使用します。

例:

転送実行 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

転送実行の転送ログメッセージを表示するには、--transfer_log フラグを指定した bq ls コマンドを入力します。--message_type フラグを使用して、ログメッセージをタイプ別にフィルタリングできます。

特定の数のログメッセージを表示するには、--max_results フラグを指定します。このコマンドは、--page_token フラグを使用して、指定したページトークンを返し、次の n 件のメッセージを表示します。

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

次のように置き換えます。

integer は、返されるログメッセージの数です。
message_type は、表示するログメッセージのタイプです（個別値またはカンマ区切りのリスト）。
- INFO
- WARNING
- ERROR
run_name は、転送実行の実行名です。実行名は bq ls コマンドを使用して取得できます。

例:

転送実行 projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7/runs/1a2b345c-0000-1234-5a67-89de1f12345g の最初の 2 件のログメッセージを表示するには、次のコマンドを入力します。

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

このコマンドは次のページトークンを返します。ページトークンをコピーして bq ls コマンドに指定し、次の 2 件の結果を表示します。

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

転送実行 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

projects.transferConfigs.runs.transferLogs.list メソッドを使用し、parent パラメータで転送実行の実行名を指定します。

Java

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

転送を変更する

既存の転送は、転送構成に関する情報の編集し、転送構成に添付されたユーザーの認証情報を更新して、転送の無効化や削除を行うことで変更できます。

必要なロール

転送を変更するために必要な権限を取得するには、プロジェクトで BigQuery 管理者（roles/bigquery.admin）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

転送の更新

転送構成を作成したら、次のフィールドを編集できます。

宛先データセット
表示名
特定の転送タイプに指定されたすべてのパラメータ
実行通知設定
サービスアカウント

一旦転送が作成されると、転送元を編集することはできません。

転送を更新するには:

コンソール

Google Cloud コンソールで、[データ転送] ページに移動します。

[データ転送] に移動
データ転送リストで、転送をクリックします。
[編集] をクリックして転送構成を更新します。

bq

bq update コマンドを入力して、--transfer_config フラグで転送構成のリソース名を指定し、--display_name、--params、--refresh_window_days、--schedule、または --target_dataset のフラグを指定します。必要に応じて、スケジュールされたクエリや Cloud Storage の転送に --destination_kms_key フラグを指定できます。

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

次のように置き換えます。

NAME: 転送構成の表示名。
PARAMETERS: JSON 形式の転送構成のパラメータ。例: --params='{"param1":"param_value1"}'。次のパラメータは編集できます。
- キャンペーンマネージャー: bucket、network_id
- Google アドマネージャー: bucket、network_code
- Google 広告: customer_id
- Google Merchant Center: merchant_id
- Google Play: bucket、table_suffix
- スケジュールされたクエリ: destination_table_kms_key、destination_table_name_template、partitioning_field、partitioning_type、query、write_disposition
- 検索広告 360: advertiser_id、agency_id、custom_floodlight_variables、include_removed_entities、table_filter
- YouTube チャンネル: table_suffix
- YouTube コンテンツ所有者: content_owner_id、table_suffix
INTEGER - 0～30 の値です。ウィンドウの更新構成については、転送タイプのドキュメントをご覧ください。
SCHEDULE: 定期的なスケジュール（--schedule="every 3 hours" など）。schedule 構文の詳細については、schedule のフォーマットをご覧ください。
DATASET_ID: 転送構成のターゲットデータセット。
DESTINATION_KEY: Cloud KMS 鍵のリソース ID（例: projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name）。CMEK は、スケジュールされたクエリまたは Cloud Storage の転送にのみ使用できます。
SERVICE_ACCOUNT: この転送で使用するサービスアカウントを指定します。
RESOURCE_NAME: 転送のリソース名（転送構成とも呼ばれます）。転送のリソース名がわからない場合は、bq ls --transfer_config --transfer_location=location を使用してリソース名を探します。

例:

次のコマンドは、Google 広告の転送 projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7 の表示名、ターゲットデータセット、更新ウィンドウ、パラメータを更新します。

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

次のコマンドは、スケジュールされたクエリの転送 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

projects.transferConfigs.patch メソッドを使用して、transferConfig.name パラメータで転送構成のリソース名を指定します。転送のリソース名がわからない場合は、bq ls --transfer_config --transfer_location=location を使用してリソース名を探します。また、次のメソッドを呼び出し、parent パラメータを使用してプロジェクト ID を指定して、すべての転送（projects.locations.transferConfigs.list）を一覧表示することもできます。

Java

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

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}'")

認証情報を更新する

転送では、転送を作成したユーザーの認証情報を使用します。転送構成に接続しているユーザーを変更する必要がある場合は、転送の認証情報を更新できます。これは、転送を作成したユーザーが組織からいなくなった場合に役立ちます。

転送の認証情報を更新するには:

コンソール

Google Cloud コンソールで、所有権を移行するユーザーとしてログインします。
[データ転送] ページに移動します。

[データ転送] に移動
データ転送リストで、転送をクリックします。
[展開] メニューをクリックし、[認証情報を更新] を選択します。
[許可] をクリックして、レポートデータの表示権限と、BigQuery 内のデータに対するアクセスと管理の権限を BigQuery Data Transfer Service に付与します。

bq

bq update コマンドを入力して、--transfer_config フラグを使用して転送構成のリソース名を指定し、--update_credentials フラグを指定します。

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

次のように置き換えます。

boolean は、転送構成の認証情報を更新する必要があるかどうかを示すブール値です。
resource_name は転送のリソース名（転送構成とも呼ばれます）です。転送のリソース名がわからない場合は、bq ls --transfer_config --transfer_location=location を使用してリソース名を探します。

例:

Google 広告の転送 projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7 の認証情報を更新するには、次のコマンドを入力します。

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

API

projects.transferConfigs.patch メソッドを使用して、authorizationCode パラメータと updateMask パラメータを指定します。

Java

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

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

転送を無効にする

転送を無効にすると、転送名に disabled が追加されます。転送が無効になると、新しい転送実行はスケジュールされず、新しいバックフィルは許可されません。進行中の転送実行はすべて行われます。

転送を無効にしても、すでに BigQuery に転送されたデータは削除されません。データセットを削除するかテーブルを削除するまでは、これまでに転送されたデータに対して標準の BigQuery ストレージ費用がかかります。

転送を無効にするには:

コンソール

Google Cloud コンソールで [BigQuery] ページに移動します。

[BigQuery] に移動
[転送] をクリックします。
[転送] ページで、リストから無効にする転送をクリックします。
[無効にする] をクリックします。転送を再度有効にするには、[有効にする] をクリックします。

bq

CLI では、転送を無効にすることはできません。

API

projects.locations.transferConfigs.patch メソッドを使用して、projects.locations.transferConfig リソースの disabled を true に設定します。

Java

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

転送を再度有効にするには:

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

転送を削除する

転送が削除されると、新しい転送実行はスケジュールされません。進行中の転送実行はすべて停止されます。

転送を削除しても、すでに BigQuery に転送されたデータは削除されません。データセットを削除するかテーブルを削除するまでは、これまでに転送されたデータに対して標準の BigQuery ストレージ費用がかかります。

転送を削除するには:

コンソール

Google Cloud コンソールで [BigQuery] ページに移動します。

[BigQuery] に移動
[転送] をクリックします。
[転送] ページで、リストから削除する転送をクリックします。
[削除] をクリックします。本当に削除するかの確認のため、「削除」という単語をボックスに入力する必要があります。
注意: 削除操作は元に戻せません。

bq

bq rm コマンドを入力して、転送構成のリソース名を指定します。-f フラグを使用すると、操作の確認を省略して転送構成を削除できます。

bq rm \
-f \
--transfer_config \
resource_name

ここで

resource_name は、転送のリソース名（転送構成とも呼ばれます）です。転送のリソース名が不明の場合は、bq ls --transfer_config --transfer_location=location コマンドを発行してすべての転送を一覧表示します。

たとえば、転送構成 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

projects.locations.transferConfigs.delete メソッドを使用して、name パラメータで削除対象のリソースを指定します。

Java

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

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}")

手動で転送をトリガーする

転送を手動でトリガーする（バックフィル実行とも呼ばれる）と、自動的にスケジュールされた転送の外部で追加のデータファイルを読み込むことができます。ランタイムパラメータをサポートするデータソースでは、過去のデータを読み込む日付または期間を指定して、転送を手動でトリガーすることもできます。

データのバックフィルは、いつでも手動で開始できます。ソースの制限とは別に、BigQuery Data Transfer Service は、バックフィルリクエストごとに最大 180 日間のサポートを提供します。同時バックフィルリクエストはサポートされていません。

バックフィルできるデータ量については、データソースの転送ガイドをご覧ください。

必要なロール

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

転送またはバックフィルを手動でトリガーする

転送やバックフィル実行は、次の方法により手動でトリガーできます。

Google Cloud コンソールを使用して転送実行を選択し、[今すぐ転送を実行] または [バックフィルのスケジュール構成] をクリックします。
bq コマンドラインツールで bq mk –transfer run コマンドを使用する
API メソッド projects.locations.transferConfigs.startManualRuns method を呼び出す

各方法の詳しい手順については、対応するタブを選択してください。

コンソール

Google Cloud コンソールで、[データ転送] ページに移動します。

[データ転送] に移動
リストから転送を選択します。
[今すぐ転送を実行] または [バックフィルのスケジュール構成] をクリックします。転送構成の種類に応じて、1 つのオプションのみを使用できます。
- [今すぐ転送を実行] をクリックした場合は、[1 回限りの転送を実行] または [特定の日付で実行] を選択します（該当する場合）。[特定の日付で実行] を選択した場合は、具体的な日時を選択します。
- [バックフィルをスケジュール] をクリックした場合は、[1 回限りの転送を実行] または [期間を指定して実行] を適宜選択します。[期間を指定して実行] を選択した場合は、開始日時と終了日時を選択します。
[OK] をクリックします。

bq

手動で転送実行を開始するには、--transfer_run フラグを指定して bq mk コマンドを入力します。

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

次のように置き換えます。

RUN_TIME は、過去の転送の日付を指定するタイムスタンプです。Z で終わるタイムスタンプか、有効なタイムゾーンのオフセットを含むタイムスタンプを使用します（例: 2022-08-19T12:11:35.00Z、2022-05-25T00:00:00+00:00）。
- 転送にランタイムパラメータがない場合や、過去の転送を指定せずに今すぐ転送をトリガーする場合は、このフィールドに現在の時刻を入力します。
RESOURCE_NAME は、転送構成に記載されたリソース名です（例: projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7）。
- 転送構成のリソース名を確認するには、転送に関する情報を取得するをご覧ください。
- リソース名は、相対的なリソース名形式を使用します。

特定の期間の転送実行を手動で開始するには、--transfer_run フラグ、期間を指定して bq mk コマンドを入力します。

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

次のように置き換えます。

START_TIME と END_TIME は、Z で終わるタイムスタンプか、有効なタイムゾーンのオフセットを含むタイムスタンプです。これらの値は、バックフィルする以前の転送実行を含む期間を指定します（2022-08-19T12:11:35.00Z、2022-05-25T00:00:00+00:00 など）。
RESOURCE_NAME は、転送構成に一覧表示されるリソース名です。例: projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7
- 転送構成のリソース名を確認するには、転送に関する情報を取得するをご覧ください。
- リソース名は、相対的なリソース名形式を使用します。

API

手動で転送実行を開始するには、projects.locations.transferConfigs.startManualRuns メソッドを使用し、親パラメータを使用して転送構成のリソース名を指定します。転送構成のリソース名を確認するには、転送に関する情報を取得するをご覧ください。

  "requestedRunTime": "RUN_TIME"

次のように置き換えます。

RUN_TIME は、過去の転送の日付を指定するタイムスタンプです。Z で終わるタイムスタンプか、有効なタイムゾーンのオフセットを含むタイムスタンプを使用します（例: 2022-08-19T12:11:35.00Z、2022-05-25T00:00:00+00:00）。
- 転送にランタイムパラメータがない場合や、過去の転送を指定せずに今すぐ転送をトリガーする場合は、このフィールドに現在の時刻を入力します。

特定の期間の転送実行を手動で開始するには、期間を指定します。

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

次のように置き換えます。

START_TIME と END_TIME は、Z で終わるタイムスタンプか、有効なタイムゾーンのオフセットを含むタイムスタンプです。これらの値は、バックフィルする以前の転送実行を含む期間を指定します（2022-08-19T12:11:35.00Z、2022-05-25T00:00:00+00:00 など）。

Java

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

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}")

ロギングとモニタリング

BigQuery Data Transfer Service は、ログと指標を Cloud Monitoring と Cloud Logging にエクスポートして、転送にオブザーバビリティを提供します。Monitoring を使用して、転送のモニタリング、転送実行パフォーマンスの評価、エラーメッセージの確認を行うためのダッシュボードを設定し、転送エラーのトラブルシューティングを行うことができます。Logging を使用して、転送実行または転送構成に関連するログを表示できます。

BigQuery Data Transfer Service で使用できる監査ログを表示して、転送アクティビティとデータアクセスログを確認することもできます。

転送を管理する

転送を表示する

必要なロール

転送の詳細を取得する

コンソール

bq

API

Java

転送構成を一覧表示する

コンソール

bq

API

Java

Python

転送の実行履歴を表示する

コンソール

bq

API

Java

転送実行の詳細とログ メッセージを表示する

コンソール

bq

API

Java

転送を変更する

必要なロール

転送の更新

コンソール

bq

API

Java

Python

認証情報を更新する

コンソール

bq

API

Java

Python

転送を無効にする

コンソール

bq

API

Java

転送を削除する

コンソール

bq

API

Java

Python

手動で転送をトリガーする

必要なロール

転送またはバックフィルを手動でトリガーする

コンソール

bq

API

Java

Python

ロギングとモニタリング

転送実行の詳細とログメッセージを表示する