处理转移作业

使用 BigQuery Data Transfer Service 创建转移作业后，您可以执行以下操作：

获取有关传输配置的信息
列出传输配置
查看传输的运行历史记录
查看传输运行详情，例如日志消息
更新传输
设置回填
更新凭据
停用传输
删除传输

获取传输相关信息

创建传输后，您可以获取有关传输配置的信息。配置包含您在创建传输时提供的值。

所需权限

要获取有关转移作业的信息，您需要具备 bigquery.transfers.get 权限。以下预定义的 Cloud IAM 角色具有 bigquery.transfers.get 权限：

bigquery.admin
bigquery.user

获得 bigquery.transfers.get 权限的用户可以查看有关项目中所有转移作业的信息。

如需详细了解 BigQuery Data Transfer Service 中的 Cloud IAM 角色，请参阅访问权限控制参考文档。

获取转移作业相关信息

获取转移作业配置相关信息的方法如下：

经典版界面

转到 BigQuery 网页界面。

转到 BigQuery 网页界面
点击 Transfers。
在 Transfers 页面上，点击列表中的相应传输。
传输配置会显示在属性页面中 Run History 的上方。以下示例演示了 Google Ads 转移作业的配置属性。

CLI

输入 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 参数提供转移作业配置。

列出转移作业配置

所需权限

要列出项目中的转移作业配置，您需要具备 bigquery.transfers.get 权限。以下预定义的 Cloud IAM 角色具有 bigquery.transfers.get 权限：

bigquery.admin
bigquery.user

获得 bigquery.transfers.get 权限的用户可以列出项目中的所有转移作业。

如需详细了解 BigQuery Data Transfer Service 中的 Cloud IAM 角色，请参阅访问权限控制参考文档。

列出转移作业

列出项目中的转移作业配置的方法如下：

经典版界面

转到 BigQuery 网页界面。

转到 BigQuery 网页界面
点击 Transfers。转移作业配置会显示在 Transfers 页面上，并且按位置分组。

CLI

要按位置列出一个项目的所有转移作业配置，请输入 bq ls 命令并提供 --transfer_location 和 --transfer_config 标志。您还可以提供 --project_id 标志以指定具体项目。如果未指定 --project_id，则系统会使用默认项目。--format 标志可用于控制输出格式。

要列出特定数据源的转移作业配置，请提供 --filter 标志。

要以分页格式查看特定数量的转移作业配置，请提供 --max_results 标志以指定转移作业数量。该命令使用 --page_token 标志返回您提供的页面标记，以查看后续 n 个配置。

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

其中：

location 是转移作业配置的位置。位置是在您创建转移作业时指定的。
project_id 是您的项目 ID。
integer 是每页要显示的结果数。
data_sources 是以下之一：<<../_shared/_cli-transfer-types.md>>

示例：

输入以下命令以显示您的默认项目位于美国的所有转移作业配置。--format 标志用于控制输出。

bq ls \
--format=prettyjson \
--transfer_config \
--transfer_location=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 的 Ads 和 Campaign Manager 转移作业配置。

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

API

使用 projects.locations.transferConfigs.list 方法并通过 parent 参数提供项目 ID。

查看运行历史记录

在运行已安排好的传输时，系统会为每个传输配置保留运行历史记录，其中包括成功的传输运行和失败的传输运行。超过 90 天的传输运行会从运行历史记录中自动删除。

所需权限

要查看一项转移作业配置的运行历史记录，您需要具备 bigquery.transfers.get 权限。预定义的 Cloud IAM 角色 bigquery.user 具有 bigquery.transfers.get 权限。

如需详细了解 BigQuery Data Transfer Service 中的 Cloud IAM 角色，请参阅访问权限控制参考文档。

查看运行历史记录

查看转移作业配置的运行历史记录的方法如下：

经典版界面

转到 BigQuery 网页界面。

转到 BigQuery 网页界面
点击 Transfers。
在 Transfers 页面上，点击列表中的相应传输。
在属性页面上，运行历史记录显示在转移作业属性下方。
（可选）取消选中 Show only latest run per day 以查看所有转移作业运行。

传输运行的状态以图形方式表示，State 列中给出了详细说明：

图标	状态
	转移作业运行成功。
	转移作业运行失败。
	转移作业运行成功，但出现警告。除非结果表出现异常，否则系统不会认为运行存在问题。

CLI

要列出特定转移作业配置的转移作业运行，请输入 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.list 方法并通过 parent 参数指定项目 ID。

查看转移作业运行详情和日志消息

在传输运行出现在运行历史记录中时，您可以查看运行详情，包括日志消息、警告和错误、运行名称以及开始和结束时间。

所需权限

要查看转移作业运行详情，您需要具备 bigquery.transfers.get 权限。预定义的 Cloud IAM 角色 bigquery.user 具有 bigquery.transfers.get 权限。

如需详细了解 BigQuery Data Transfer Service 中的 Cloud IAM 角色，请参阅访问权限控制参考文档。

查看转移作业运行详情

查看转移作业运行详情的方法如下：

经典版界面

转到 BigQuery 网页界面。

转到 BigQuery 网页界面
点击 Transfers。
在 Transfers 页面上，点击列表中的相应传输。
在属性页面上，运行历史记录显示在传输属性下方。点击一项运行即可查看其详情。
在运行详情中，请注意 Run Name 和任何错误消息。在联系 Google Cloud 支持团队时，您需要用到这些信息。运行详情还包括日志消息和警告。

CLI

要查看转移作业运行详情，请输入 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 参数提供转移作业运行的名称。

更新转移作业

添加传输后，您可以编辑传输。您可以修改在传输创建期间填充的任何字段（源除外）：

目标数据集
显示名
为特定传输类型指定的任何参数
运行通知设置

所需权限

要更新转移作业，您需要具备 bigquery.transfers.update 权限。预定义的 Cloud IAM 角色 bigquery.admin 具有 bigquery.transfers.update 权限。

如需详细了解 BigQuery Data Transfer Service 中的 Cloud IAM 角色，请参阅访问权限控制参考文档。

更新转移作业

更新转移作业的方法如下：

经典版界面

转到 BigQuery 网页界面。

转到 BigQuery 网页界面
点击 Transfers。
在 Transfers 页面上，点击列表中的相应传输。
点击 Edit 以更新传输配置。
完成更改后，点击 Save。

CLI

输入 bq update 命令并使用 --transfer_config 标志提供转移作业配置的资源名称，并提供 --display_name、--target_dataset、--refresh_window_days 或 --params 标志。

bq update \
--display_name='name' \
--target_dataset=dataset \
--params='parameters' \
--refresh_window_days=integer \
--transfer_config \
resource_name

其中：

name 是传输配置的显示名。
dataset 是传输配置的目标数据集。
parameters 包含转移作业配置的参数（采用 JSON 格式）。例如：--params='{"param":"param_value"}'。您可以修改以下参数：
- Google Ads：customer_id
- Campaign Manager：bucket 和 network_id
- Google Ad Manager：bucket 和 network_code
- Google Merchant Center：merchant_id
- Google Play：bucket 和 table_suffix
- Search Ads 360：agency_id、advertiser_id、include_removed_entities、table_filter、custom_floodlight_variables
- YouTube 频道：page_id 和 table_suffix
- YouTube 内容所有者：content_owner_id 和 table_suffix
integer 是一个介于 0 到 30 之间的值。如需了解如何设置刷新时段，请参阅对应于您的转移作业类型的文档。
resource_name 是转移作业的资源名称（也称为转移作业配置）。如果您不知道转移作业的资源名称，请发出 bq ls --transfer_config --transfer_location=location 命令以列出所有转移作业。

示例：

输入以下命令，以更新 Google Ads 转移作业 projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7 的显示名、目标数据集、刷新时段和参数。

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

API

使用 projects.transferConfigs.patch 方法并通过 transferConfig.name 参数提供转移作业的资源名称。如果您不知道转移作业的资源名称，请发出 bq ls --transfer_config --transfer_location=location 命令以列出所有转移作业，或调用 projects.locations.transferConfigs.list 方法并通过 parent 参数提供项目 ID。

设置回填和刷新运行

刷新

请注意，数据回填功能不适用于以下类型的传输。但是，您可以设置刷新运行。

Cloud Storage 转移作业
复制数据集

回填

您可以随时手动启动数据回填。除了源限制之外，BigQuery Data Transfer Service 为每项回填请求提供最长 180 天的支持。该服务不支持多项同时回填请求。

对较大的日期范围进行回填时，您可以将回填请求拆分为多个 180 天的块，等待上一项回填请求完成后再创建另一项回填请求。

如需了解可以回填的数据量，请参阅您的数据源对应的文档：

Campaign Manager
Google Ad Manager
Google Ads
- 为 Google Ads 设置数据回填后，系统会每天获取一次匹配表的快照，并将其存储在与最近运行日期对应的分区中。如果安排了数据回填，则系统不会更新以下表的匹配表快照：
  - Ad
  - AdGroup
  - AgeRange
  - Audience
  - BidGoal
  - Budget
  - Campaign
  - Criteria
  - Customer
  - Gender
  - Keyword
  - LocationBasedCampaignCriterion
  - ParentalStatus
  - Placement
  - Video
Google Merchant Center（Beta 版）
Google Play（Beta 版）
Search Ads 360
- 为 Search Ads 360 设置数据回填后，系统会每天截取一次匹配表的快照，并将其存储在与最近运行日期对应的分区中。如果安排了数据回填，则系统不会更新以下表的匹配表快照：
  - Account
  - Ad
  - Advertiser
  - AdGroup
  - AdGroupTarget
  - BidStrategy
  - Campaign
  - CampaignTarget
  - FeedItem
  - FloodlightActivity
  - Keyword
  - NegativeAdGroupKeyword
  - NegativeAdGroupTarget
  - NegativeCampaignKeyword
  - NegativeCampaignTarget
  - ProductAdvertised
  - ProductGroup
  - ProductLeadAndCrossSellFloodlightStats
  - Video
  - Placement
  - Video
YouTube - 频道报告
YouTube - 内容所有者报告

请注意，数据回填功能不适用于 Cloud Storage（Beta 版）转移作业。但是，您可以设置 Cloud Storage 转移作业的刷新运行。

所需权限

要安排回填，您需要具备 bigquery.transfers.update 权限。预定义的 Cloud IAM 角色 bigquery.admin 具有 bigquery.transfers.update 权限。

如需详细了解 BigQuery Data Transfer Service 中的 Cloud IAM 角色，请参阅访问权限控制参考文档。

安排回填

安排回填的方法如下：

经典版界面

转到 BigQuery 网页界面。BigQuery 网页界面
点击 Transfers。
在 Transfer 页面上，点击相应的传输。
点击 Schedule Backfill。
在 Schedule Run 对话框中执行以下操作：
- 在 Data Start Date 部分中，输入或选择适当的日期（采用 MM/DD/YYYY 格式）。
- 在 Data End Date 部分中，输入或选择适当的日期（采用 MM/DD/YYYY 格式）。
- 点击 Ok。

CLI

输入 bq mk 命令，提供 --transfer_run 标志并指定 --start_time 和 --end_time。

bq mk \
--transfer_run \
--start_time='start_time' \
--end_time='end_time' \
resource_name

其中：

start_time 和 end_time 是以 Z 结尾或包含有效时区偏移量的时间戳。例如：
- 2017-08-19T12:11:35.00Z
- 2017-05-25T00:00:00+00:00
resource_name 是转移作业的资源名称（也称为转移作业配置）。如果您不知道转移作业的资源名称，请发出 bq ls --transfer_config --transfer_location=location 命令以列出所有转移作业。

示例：

输入以下命令，以安排转移作业配置 projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7 的回填。

bq mk \
--transfer_run \
--start_time 2017-05-25T00:00:00Z \
--end_time 2017-05-25T00:00:00Z \
projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

API

使用 projects.locations.transferConfigs.scheduleRuns 方法并通过 parent 参数提供转移作业配置资源。

更新凭据

传输使用创建该传输的用户的凭据。如果您需要更改附加到某项传输配置的用户，则可以更新传输的凭据。如果创建传输的用户不再与贵组织合作，这种做法非常有用。

所需权限

要更新凭据，您需要具备 bigquery.transfers.update 权限。预定义的 Cloud IAM 角色 bigquery.admin 具有 bigquery.transfers.update 权限。

如需详细了解 BigQuery Data Transfer Service 中的 Cloud IAM 角色，请参阅访问权限控制参考文档。

更新转移作业的凭据

更新转移作业凭据的方法如下：

经典版界面

转到 BigQuery 网页界面。BigQuery 网页界面
点击 Transfers。
在 Transfer 页面上，点击相应的传输。
点击 Update Credentials。
出现提示时，点击 OK。
登录您的 Google 帐号，点击 Allow 以授予 BigQuery Transfer Service 权限，允许其查看您的报告数据以及在 BigQuery 中访问和管理数据。您必须允许显示来自 bigquery.cloud.google.com 的弹出式窗口，才能看到权限窗口。

CLI

输入 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 Ads 转移作业 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 参数。

停用转移作业

停用转移作业时，disabled 会添加到转移作业名称。停用转移作业时，系统不会安排新的转移作业运行，也不允许新的回填。任何正在进行的转移作业运行均会完成。

停用转移作业不会移除已转移到 BigQuery 的任何数据。除非删除数据集或删除表，否则您需要为之前转移的数据支付标准 BigQuery 存储费用。

所需权限

要停用转移作业，您需要具备 bigquery.transfers.update 权限。预定义的 Cloud IAM 角色 bigquery.admin 具有 bigquery.transfers.update 权限。

如需详细了解 BigQuery Data Transfer Service 中的 Cloud IAM 角色，请参阅访问权限控制参考文档。

停用转移作业

停用转移作业的方法如下：

经典版界面

转到经典版 BigQuery 网页界面。

转到经典版 BigQuery 网页界面
点击 Transfers。
点击要停用的传输。
在转移作业属性页面上，点击 Disabled。
停用转移作业后，点击 Save。

CLI

CLI 不支持停用转移作业。

API

使用 projects.locations.transferConfigs.patch 方法并在 projects.locations.transferConfig 资源中将 disabled 设置为 true。

删除转移作业

删除传输时，系统不会安排新的传输运行。任何正在进行的转移作业运行均会停止。

删除转移作业不会移除已转移到 BigQuery 的任何数据。除非删除数据集或删除表，否则您需要为之前转移的数据支付标准 BigQuery 存储费用。

所需权限

要删除转移作业，您需要具备 bigquery.transfers.update 权限。预定义的 Cloud IAM 角色 bigquery.admin 具有 bigquery.transfers.update 权限。

如需详细了解 BigQuery Data Transfer Service 中的 Cloud IAM 角色，请参阅访问权限控制参考文档。

删除转移作业

删除转移作业的方法如下：

经典版界面

转到 BigQuery 网页界面。

转到经典版 BigQuery 网页界面
点击 Transfers。
点击要修改的传输。
在传输属性页面中，点击 Delete。
出现提示时，点击 Ok 移除转移作业。

CLI

输入 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 参数提供要删除的资源。