本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# BigQuery 連線
<a name="aws-glue-programming-etl-connect-bigquery-home"></a>

您可以使用 AWS Glue for Spark 在 Glue 4.0 AWS 和更新版本中讀取和寫入 Google BigQuery 中的資料表。您可以使用 Google SQL 查詢，從 BigQuery 讀取。您可以使用 AWS Secrets Manager 透過 Glue 連線儲存在 AWS 中的登入資料來連線至 BigQuery。

如需有關 Google BigQuery 的詳細資訊，請參閱 [Google Cloud BigQuery 網站](https://cloud.google.com/bigquery)。

## 設定 BigQuery 連線
<a name="aws-glue-programming-etl-connect-bigquery-configure"></a>

若要從 Glue AWS 連線至 Google BigQuery，您需要在 AWS Secrets Manager 秘密中建立和存放 Google Cloud Platform 登入資料，然後將該秘密與 Google BigQuery AWS Glue 連線建立關聯。

**設定連至 BigQuery 的連線：**

1. 在 Google Cloud Platform 中建立並識別相關資源：
   + 建立或識別 GCP 專案，其中應包含您要連線之 BigQuery 資料表。
   + 啟用 BigQuery API。如需詳細資訊，請參閱 [Use the BigQuery Storage Read API to read table data](https://cloud.google.com/bigquery/docs/reference/storage/#enabling_the_api)。

1. 在 Google Cloud Platform 中建立和匯出服務帳戶憑證：

   您可以使用 BigQuery 憑證精靈來加速此步驟：[Create credentials](https://console.cloud.google.com/apis/credentials/wizard?api=bigquery.googleapis.com)。

   若要在 GCP 中建立服務帳戶，請依照 [Create service accounts](https://cloud.google.com/iam/docs/service-accounts-create) 中提供的教學課程進行操作。
   + 在選取**專案**時，請選取包含您 BigQuery 資料表的專案。
   + 在為您的服務帳戶選取 GCP IAM 角色時，請新增或建立角色，其會授予供執行 BigQuery 任務的適當許可，以讀取、寫入或建立 BigQuery 資料表。

   若要為您的服務帳戶建立憑證，請依照 [Create a service account key](https://cloud.google.com/iam/docs/keys-create-delete#creating) 中提供的教學課程進行操作。
   + 在選取金鑰類型時，請選取 **JSON**。

   您現在應已下載 JSON 檔案，該檔案中包含您服務帳戶的憑證。其看起來與下列類似：

   ```
   {
     "type": "service_account",
     "project_id": "*****",
     "private_key_id": "*****",
     "private_key": "*****",
     "client_email": "*****",
     "client_id": "*****",
     "auth_uri": "https://accounts.google.com/o/oauth2/auth",
     "token_uri": "https://oauth2.googleapis.com/token",
     "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
     "client_x509_cert_url": "*****",
     "universe_domain": "googleapis.com"
   }
   ```

1. 將您的憑證 JSON 檔案上傳至適當安全的 Amazon S3 位置。保留前往該檔案的路徑，{{s3secretpath}}，以供後續步驟使用。

1. 在 中 AWS Secrets Manager，使用您的 Google Cloud Platform 登入資料建立秘密。若要在 Secrets Manager 中建立秘密，請遵循 AWS Secrets Manager 文件中[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中提供的教學課程。建立機密之後，請保留機密名稱 {{secretName}}，以便進行下一個步驟。

   建立索引鍵/值對時，請指定索引鍵和值，如下所示：
   + 對於 `token_uri`、`client_x509_cert_url`、`private_key_id`、`project_id`、`universe_domain`、`auth_provider_x509_cert_url`、`auth_uri`、`client_email``private_key`、`type`、、 `client_id`金鑰，請在下載的 JSON 檔案中指定對應的值。
   + 針對`spark.hadoop.google.cloud.auth.service.account.json.keyfile`金鑰，指定 {{s3secretpath}}。

1. 在 AWS Glue Data Catalog 中，依照中的步驟建立連線[新增 AWS Glue 連線](console-connections.md)。建立連線之後，請保留連線名稱 {{connectionName}}，以便進行下一個步驟。
   + 選取**連線類型**時，請選取 Google BigQuery。
   + 選取 **AWS 機密**時，請提供 {{secretName}}。

1. 授予與您的 Glue 任務相關聯的 IAM AWS 角色讀取 {{secretName}} 的許可。

1. 在您的 AWS Glue 任務組態中，提供 {{connectionName}} 作為**其他網路連線**。

## 從 BigQuery 資料表讀取
<a name="aws-glue-programming-etl-connect-bigquery-read"></a>

**先決條件：**
+ 您要從中讀取的 BigQuery 資料表。您將會需要 BigQuery 資料表和資料集名稱，形式為 `[dataset].[table]`。我們稱此為 {{tableName}}。
+ BigQuery 資料表的計費專案。您將會需要專案的名稱，{{parentProject}}。若無計費父系專案，請使用包含資料表的專案。
+ BigQuery 身分驗證資訊。完成步驟 *使用 Glue AWS 管理您的連線憑證*，以設定您的身分驗證資訊。您將會需要 AWS Glue 連線的名稱，{{connectionName}}。

例如：

```
bigquery_read = glueContext.create_dynamic_frame.from_options(
    connection_type="bigquery",
    connection_options={
        "connectionName": "{{connectionName}}",
        "parentProject": "{{parentProject}}",
        "sourceType": "table",
        "table": "{{tableName}}",
    }
```

您也可提供查詢，以篩選傳回至 DynamicFrame 的結果。您將需要設定 `query`、`sourceType`、`viewsEnabled` 和 `materializationDataset`。

例如：

**其他先決條件：**

您必須建立或識別 BigQuery 資料集 {{materializationDataset}}，BigQuery 才能為您的查詢寫入具體化視觀表。

您將需授予適當的 GCP IAM 許可給您的服務帳戶，以在 {{materializationDataset}} 中建立資料表。

```
glueContext.create_dynamic_frame.from_options(
            connection_type="bigquery",
            connection_options={
                "connectionName": "{{connectionName}}",
                "materializationDataset": {{materializationDataset}},
                "parentProject": "{{parentProject}}",
                "viewsEnabled": "true",
                "sourceType": "query",
                "query": "select * from bqtest.test"
            }
        )
```

## 寫入 BigQuery 資料表
<a name="aws-glue-programming-etl-connect-bigquery-write"></a>

此範例會直接寫入 BigQuery 服務。此外，BigQuery 也支援「間接」寫入方法。如需有關設定間接寫入的詳細資訊，請參閱[透過 Google BigQuery 使用間接寫入](#aws-glue-programming-etl-connect-bigquery-indirect-write)。

**先決條件：**
+ 您要寫入的 BigQuery 資料表。您將會需要 BigQuery 資料表和資料集名稱，形式為 `[dataset].[table]`。您也可以提供自動建立的新資料表名稱。我們稱此為 {{tableName}}。
+ BigQuery 資料表的計費專案。您將會需要專案的名稱，{{parentProject}}。若無計費父系專案，請使用包含資料表的專案。
+ BigQuery 身分驗證資訊。完成步驟 *使用 Glue AWS 管理您的連線憑證*，以設定您的身分驗證資訊。您將會需要 AWS Glue 連線的名稱，{{connectionName}}。

例如：

```
bigquery_write = glueContext.write_dynamic_frame.from_options(
    frame={{frameToWrite}},
    connection_type="bigquery",
    connection_options={
        "connectionName": "{{connectionName}}",
        "parentProject": "{{parentProject}}",
        "writeMethod": "direct",
        "table": "{{tableName}}",
    }
)
```

## BigQuery 連線選項參考
<a name="aws-glue-programming-etl-connect-bigquery-reference"></a>
+ `project` – 預設：Google Cloud 服務帳戶預設值。用於讀取/寫入。與您資料表相關聯的 Google Cloud 專案名稱。
+ `table`：(必要) 用於讀取/寫入。BigQuery 資料表的名稱，格式為 `[[project:]dataset.]`。
+ `dataset` – 未透過 `table` 選項定義時為必要。用於讀取/寫入。包含您 BigQuery 資料表的資料集名稱。
+ `parentProject` – 預設：Google Cloud 服務帳戶預設值。用於讀取/寫入。與用於計費之 `project` 相關聯的 Google Cloud 專案名稱。
+ `sourceType` – 用於讀取。讀取時需要。有效值：`table`、 會`query`通知 AWS Glue 您要依資料表或查詢讀取。
+ `materializationDataset` – 用於讀取。有效值：字串。用來儲存檢視之實體化的 BigQuery 資料集名稱。
+ `viewsEnabled` – 用於讀取。預設：false。有效值：true、false。設定 BigQuery 是否要使用檢視。
+ `query` – 用於讀取。`viewsEnabled` 為 true 時使用。GoogleSQL DQL 查詢。
+ `temporaryGcsBucket` – 用於寫入。當 `writeMethod` 設定為預設 (`indirect`) 時，此為必要項。在寫入 BigQuery 時，用來儲存您資料之中繼格式的 Google Cloud Storage 儲存貯體名稱。
+ `writeMethod`：預設：`indirect`。有效值：`direct`、`indirect`。用於寫入。指定用來寫入資料的方法。
  + 若設定為 `direct`，您的連接器將使用 BigQuery Storage Write API 來寫入。
  + 若設定為 `indirect`，您的連接器會寫入 Google Cloud Storage，然後使用載入操作將其傳輸至 BigQuery。您的 Google Cloud 服務帳戶需要適當的 GCS 許可。

## 透過 Google BigQuery 使用間接寫入
<a name="aws-glue-programming-etl-connect-bigquery-indirect-write"></a>

此範例會使用間接寫入，即將資料寫入 Google Cloud Storage，然後將資料複製至 Google BigQuery。

**先決條件：**

您將需要一個臨時的 Google Cloud Storage 儲存貯體，{{temporaryBucket}}。

Glue 的 GCP AWS 服務帳戶的 GCP IAM 角色將需要適當的 GCS 許可才能存取 {{temporaryBucket}}。

**其他組態：**

**使用 BigQuery 設定間接寫入：**

1. 評估 [設定 BigQuery 連線](#aws-glue-programming-etl-connect-bigquery-configure) 並找出或重新下載您的 GCP 憑證 JSON 檔案。識別 {{secretName}}，這是任務中使用的 Google BigQuery AWS Glue 連線的 AWS Secrets Manager 秘密。

1. 將您的憑證 JSON 檔案上傳至適當安全的 Amazon S3 位置。保留前往該檔案的路徑，{{s3secretpath}}，以供後續步驟使用。

1. 編輯 {{secretName}}，新增 `spark.hadoop.google.cloud.auth.service.account.json.keyfile` 金鑰。將值設定為 {{s3secretpath}}。

1. 授予 AWS Glue 任務 Amazon S3 IAM 存取 {{s3secretpath}} 的許可。

您現在可將暫時 GCS 儲存貯體位置提供給寫入方法。由於過去 `indirect` 為預設，您無需提供 `writeMethod`。

```
bigquery_write = glueContext.write_dynamic_frame.from_options(
    frame={{frameToWrite}},
    connection_type="bigquery",
    connection_options={
        "connectionName": "{{connectionName}}",
        "parentProject": "{{parentProject}}",
        "temporaryGcsBucket": "{{temporaryBucket}}",
        "table": "{{tableName}}",
    }
)
```