# 连接 Google BigQuery

使用 Google Cloud 服务账号连接 BigQuery，并选择需要同步的表。

AskTable 连 BigQuery 不用主机和端口，凭证是一份 Google Cloud 服务账号的 JSON 密钥。把密钥交给 AskTable 之后，BigQuery 的 dataset 会出现在选表页的库列表里。

## 开始前

| 项目 | 要求                                     |
| -- | -------------------------------------- |
| 权限 | 项目负责人或项目管理员                            |
| 前置 | 一份服务账号 JSON 密钥，且该账号对要同步的 dataset 有读取权限 |
| 入口 | 左侧主导航 → 「更多」→ 「数据源」→ 右上角「添加数据源」        |

## 操作步骤

**在 Google Cloud 准备服务账号**

这一步在 Google Cloud 控制台完成，不在 AskTable 里（以 Google 官方文档为准）：

1. 在「IAM 与管理 → 服务账号」里新建一个服务账号，名称任意（例如 `asktable-readonly`）。
2. 给服务账号授予两个角色：在要开放的 **dataset** 上授予 `roles/bigquery.dataViewer`（读取数据和元数据），在**运行查询的项目**上授予 `roles/bigquery.jobUser`（提交查询任务）。Job User 不能授予 dataset。若允许读取整个项目的数据，也可以在项目级授予 Data Viewer。授权范围见 [Google BigQuery 角色说明](https://docs.cloud.google.com/bigquery/docs/access-control#bigquery.jobUser)。
3. 生成并下载 **JSON** 格式的密钥，AskTable 只认这一种。

如果组织策略禁用了服务账号密钥创建（`iam.disableServiceAccountKeyCreation`），第 3 步会失败，需要 GCP 管理员放行或改用你们已有的凭证下发方式。

**选择 Google BigQuery**

在「选择类型」步骤的「大数据」分组里点「Google BigQuery」卡片，进入「配置连接」。

**填写名称和密钥**

表单只有两项：

- 数据源名称：可以留空，留空时会自动生成。
- Service Account JSON 字段：文本框里预置了一份 JSON 模板，含 `type`、`project_id`、`private_key`、`client_email` 四个键，把它整体替换成真实密钥。

也可以点右下角「上传 JSON 文件」，选本地的 `.json` 文件，内容会自动填进文本框。

**立即添加**

点「立即添加」会先测试一次连接，通过后进入「添加数据表」步骤。失败时弹出连接失败对话框，正文是 BigQuery 返回的原始错误。

**选表**

BigQuery 的 dataset 对应选表页里库（schema）这一层。勾选要同步的表，点「确认选择 (N)」；也可以「跳过」，之后在数据源详情页补选。

## 关键约束

| 项目                   | 值或默认                                             | 在哪里改                                 |
| -------------------- | ------------------------------------------------ | ------------------------------------ |
| Service Account JSON | 新建时必填，为空时提交被拒绝                                   | 表单本身                                 |
| 密钥必须包含的键             | project\_id、client\_email、private\_key，缺一个就提交被拒绝 | Google Cloud 生成的密钥文件                 |
| 编辑时密钥                | 留空表示不修改，填了才覆盖                                    | 数据源 → 「设置」→ 「连接配置」→「编辑」              |
| 项目 ID                | 表单里没有这一项，不用填                                     | —                                    |
| 主机 / 端口              | 不需要填写                                            | —                                    |
| 单数据源可选表数             | 默认 100 张                                         | 头像菜单 → 「设置」→ 「数据源」→ 单数据源最大表数（云端部署生效） |

单数据源可选表数是默认值，可在管理后台调整。

## 出问题怎么判断

| 现象                                                   | 判定条件                                    | 处理                                                            |
| ---------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------- |
| 提交被拒，提示密钥不能为空                                        | 文本框为空，且没有上传文件                           | 粘贴密钥全文，或点「上传 JSON 文件」                                         |
| 提交被拒，提示密钥不是合法 JSON                                   | 粘贴内容被截断，或前后带了说明文字                       | 重新复制整个密钥文件的内容，只保留 JSON                                        |
| 提交被拒，提示密钥缺少 project\_id、client\_email 或 private\_key | 用的是 OAuth 客户端密钥或 API Key，不是服务账号密钥       | 回 Google Cloud 生成服务账号密钥                                       |
| 连接测试提示认证失败                                           | BigQuery 返回密钥或身份相关错误                    | 确认服务账号和密钥仍然有效，必要时换一份有效密钥                                      |
| 连接测试提示无法提交查询任务                                       | BigQuery 返回缺少 `bigquery.jobs.create` 权限 | 在运行查询的项目上授予服务账号 BigQuery Job User；仅有 dataset 的 Data Viewer 不够 |
| 连接测试提示无法读取表                                          | BigQuery 返回表或数据集访问权限错误                  | 在目标 dataset 上授予服务账号 BigQuery Data Viewer                      |
| 选表页看不到某个 dataset                                     | 该 dataset 不在库列表里                        | 在 Google Cloud 给服务账号授予这个 dataset 的读取权限                        |
| 昨天能连、今天报认证失败                                         | 密钥被禁用或已过期                               | 生成新密钥，在「连接配置」→「编辑」里替换                                         |

## 下一步

- 字段名看不懂、要写业务含义：[表与字段备注](https://docs.asktable.com/data/semantics)
- 接完要做日常维护：[管理数据源、文件与训练集](https://docs.asktable.com/data/manage)
- 想再连一个库或一份文件：[连接数据源](https://docs.asktable.com/data/connect)
- 直接开始提问：[对话](https://docs.asktable.com/conversation)