本頁面由 Cloud Translation API 翻譯而成。

BigQuery

使用 BigQuery 連接器，針對 Google BigQuery 資料執行插入、刪除、更新和讀取作業。您也可以針對 BigQuery 資料執行自訂 SQL 查詢。您可以使用 BigQuery 連接器，整合多個 Google Cloud 服務或其他第三方服務 (例如 Cloud Storage 或 Amazon S3) 的資料。

事前準備

在 Google Cloud 專案中執行下列工作：

確認已設定網路連線。如要瞭解網路模式，請參閱「網路連線」。
將 roles/connectors.admin IAM 角色授予設定連接器的使用者。
將 roles/bigquery.dataEditor 身分與存取權管理角色授予要用於連接器的服務帳戶。
啟用下列服務：
- secretmanager.googleapis.com (Secret Manager API)
- connectors.googleapis.com (連接器 API)
如要瞭解如何啟用服務，請參閱「啟用服務」。如果先前未為專案啟用這些服務或權限，在設定連接器時，系統會提示您啟用這些服務或權限。

建立 BigQuery 連線

連線是特定資料來源的連線，也就是說，如果您有多個資料來源，則必須為每個資料來源建立個別的連線。如要建立連線，請按照下列步驟操作：

在 Cloud 控制台中，前往「Integration Connectors」 >「Connections」頁面，然後選取或建立 Google Cloud 專案。
前往「連線」頁面
按一下「+ 建立新連線」，開啟「建立連線」頁面。
在「Location」部分，從「Region」清單中選取位置，然後點選「NEXT」。
如需所有支援地區的清單，請參閱「位置」一節。
在「連線詳細資料」部分執行下列操作：
1. 在「連接器」清單中選取「BigQuery」。
2. 從「Connector version」清單中選取連接器版本。
3. 在「Connection Name」欄位中，輸入連線執行個體的名稱。連線名稱可以包含小寫英文字母、數字或連字號。名稱開頭須為英文字母，結尾須為英文字母或數字，且名稱不得超過 49 個字元。
4. 您可以選擇啟用 Cloud Logging，然後選取記錄層級。根據預設，記錄層級會設為 Error。
5. 服務帳戶：選取具備必要角色的服務帳戶。
6. 專案 ID：資料所在的 Google Cloud 專案 ID。
7. 資料集 ID：BigQuery 資料集的 ID。
8. 如要支援 BigQuery 陣列資料類型，請選取「支援原生資料類型」。系統支援以下陣列類型：Varchar、Int64、Float64、Long、Double、Bool 和 Timestamp。不支援巢狀陣列。
9. 點按「下一步」。
在「Authentication」部分中，輸入驗證詳細資料。
1. 選取要使用 OAuth 2.0 授權碼驗證，還是不驗證就繼續。
  如要瞭解如何設定驗證方法，請參閱「設定驗證」。
2. 點按「下一步」。
查看連線和驗證詳細資料，然後按一下「建立」。

設定驗證機制

根據要使用的驗證方法輸入詳細資料。

無驗證：如果不需要驗證，請選取這個選項。
OAuth 2.0 - 授權碼：選取這個選項，即可使用以網路為基礎的使用者登入流程進行驗證。請指定下列詳細資料：

用戶端 ID： 連線至後端 Google 服務所需的用戶端 ID。
範圍： 以逗號分隔的所需範圍清單。如要查看所需 Google 服務支援的所有 OAuth 2.0 範圍，請參閱「Google API 適用的 OAuth 2.0 範圍」頁面中的相關部分。
用戶端密鑰： 選取 Secret Manager 密鑰。您必須先建立 Secret Manager 密鑰，才能設定這項授權。
密鑰版本： 用戶端密鑰的 Secret Manager 密鑰版本。

對於 Authorization code 驗證類型，您必須在建立連線後授權連線。

授權連線

如果您使用 OAuth 2.0 授權碼驗證連線，請在建立連線後完成下列工作。

在「Connections」頁面中，找出新建立的連線。
請注意，新連接器的狀態會是「需要授權」。
按一下「需要授權」。
這會顯示「Edit authorization」窗格。
將「Redirect URI」值複製到外部應用程式。
驗證授權詳細資料。
按一下「Authorize」。
如果授權成功，連線頁面中的連線狀態會設為「Active」。

重新授權授權碼

如果您使用 Authorization code 驗證類型，且在 BigQuery 中進行任何設定變更，就必須重新授權 BigQuery 連線。如要重新授權連線，請按照下列步驟操作：

在「Connections」(連線) 頁面中，按一下所需連線。
系統會開啟連線詳細資料頁面。
按一下「編輯」即可編輯連結詳細資料。
在「驗證」部分確認「OAuth 2.0 - 授權碼」詳細資料。
視需要進行必要的變更。
按一下 [儲存]。系統會將您導向連線詳細資料頁面。
在「驗證」部分中，按一下「編輯授權」。畫面上會顯示「Authorize」窗格。
按一下「Authorize」。
如果授權成功，「連線」頁面中的連線狀態就會設為「啟用」。

在整合中使用 BigQuery 連線

建立連線後，Apigee 整合和應用程式整合都會提供這項連線。您可以透過連接器工作，在整合中使用連線。

如要瞭解如何在 Apigee Integration 中建立及使用連接器工作，請參閱「連接器工作」。
如要瞭解如何在 Application Integration 中建立及使用連接器工作，請參閱「連接器工作」。

動作

本節說明 BigQuery 連接器提供的動作。

執行整合後，所有實體作業和動作的結果會以 JSON 回應的形式提供在 Connectors 工作項的 connectorOutputPayload 回應參數中。

CancelJob 動作

這項操作可讓您取消執行中的 BigQuery 工作。

下表說明 CancelJob 動作的輸入參數。

參數名稱	資料類型	說明
JobId	字串	您要取消的工作 ID。這是必填欄位。
地區	字串	工作目前執行的區域。如果工作位於美國或歐盟地區，則不需要這項資訊。

GetJob 動作

這個動作可讓您擷取現有工作的設定資訊和執行狀態。

下表說明 GetJob 動作的輸入參數。

參數名稱	資料類型	說明
JobId	字串	要擷取設定的工作 ID。這是必填欄位。
地區	字串	工作目前執行的區域。如果工作位於美國或歐盟地區，則不需要這項資訊。

InsertJob 動作

這項動作可讓您插入 BigQuery 工作，之後再選取該工作來擷取查詢結果。

下表說明 InsertJob 動作的輸入參數。

參數名稱	資料類型	說明
查詢	字串	要提交至 BigQuery 的查詢。這是必填欄位。
IsDML	字串	如果查詢是 DML 陳述式，則應設為 `true`；如果不是，則應設為 `false`。預設值為 `false`。
DestinationTable	字串	查詢的目的資料表，格式為 `DestProjectId:DestDatasetId.DestTable`。
WriteDisposition	字串	指定如何將資料寫入目的地資料表，例如截斷現有結果、附加現有結果，或僅在資料表為空白時寫入資料。以下是支援的值： WRITE_TRUNCATE WRITE_APPEND WRITE_EMPTY 預設值為 WRITE_TRUNCATE。
DryRun	字串	指定工作執行作業是否為模擬測試。
MaximumBytesBilled	字串	指定工作可處理的最大位元組數。如果工作嘗試處理的位元組數超過指定值，BigQuery 會取消該工作。
地區	字串	指定工作應執行的區域。

InsertLoadJob 動作

這項動作可讓您插入 BigQuery 載入工作，將 Google Cloud Storage 中的資料新增至現有資料表。

下表說明 InsertLoadJob 動作的輸入參數。

參數名稱	資料類型	說明
SourceURIs	字串	以空格分隔的 Google Cloud Storage URI 清單。
SourceFormat	字串	檔案的來源格式。支援的值如下： AVRO NEWLINE_DELIMITED_JSON DATASTORE_BACKUP PARQUET ORC CSV
DestinationTable	字串	查詢的目的資料表，格式為 `DestProjectId.DestDatasetId.DestTable`。
DestinationTableProperties	字串	指定表格友善名稱、說明和標籤清單的 JSON 物件。
DestinationTableSchema	字串	指定用於建立資料表的欄位的 JSON 清單。
DestinationEncryptionConfiguration	字串	指定資料表的 KMS 加密設定的 JSON 物件。
SchemaUpdateOptions	字串	JSON 清單，指定更新目標資料表結構定義時要套用的選項。
TimePartitioning	字串	指定時間區隔類型和欄位的 JSON 物件。
RangePartitioning	字串	指定區間分割欄位和值區的 JSON 物件。
分群	字串	指定用於叢集的欄位的 JSON 物件。
自動偵測	字串	指定是否應自動判斷 JSON 和 CSV 檔案的選項和結構定義。
CreateDisposition	字串	指定如果目的地資料表不存在，是否需要建立。支援的值如下： CREATE_IF_NEEDED CREATE_NEVER 預設值為 CREATE_IF_NEEDED。
WriteDisposition	字串	指定如何將資料寫入目的地資料表，例如截斷現有結果、附加現有結果，或僅在資料表為空白時寫入。以下是支援的值： WRITE_TRUNCATE WRITE_APPEND WRITE_EMPTY 預設值為 WRITE_APPEND。
地區	字串	指定工作應執行的區域。Google Cloud Storage 資源和 BigQuery 資料集必須位於相同的地區。
DryRun	字串	指定工作執行作業是否為模擬測試。預設值為 `false`。
MaximumBadRecords	字串	指定整個工作取消前，可允許的無效記錄數量。根據預設，所有記錄都必須有效。預設值為 `0`。
IgnoreUnknownValues	字串	指定是否必須在輸入檔案中忽略不明欄位，或將其視為錯誤。根據預設，系統會將這些值視為錯誤。預設值為 `false`。
AvroUseLogicalTypes	字串	指定是否必須使用 AVRO 邏輯類型，將 AVRO 資料轉換為 BigQuery 類型。預設值為 `true`。
CSVSkipLeadingRows	字串	指定在 CSV 檔案開頭要略過的列數。這通常用於略過標題列。
CSVEncoding	字串	CSV 檔案的編碼類型。支援的值如下： ISO-8859-1 UTF-8 預設值為 UTF-8。
CSVNullMarker	字串	如果提供此字串，系統會將其用於 CSV 檔案中的空值。根據預設，CSV 檔案無法使用 NULL。
CSVFieldDelimiter	字串	用於分隔 CSV 檔案中資料欄的字元。預設值為半形逗號 (`,`)。
CSVQuote	字串	CSV 檔案中用於引號欄位的字元。可設為空白，以停用引號。預設值為英文雙引號 (`"`)。
CSVAllowQuotedNewlines	字串	指定 CSV 檔案是否可以在引號欄位中包含換行符號。預設值為 `false`。
CSVAllowJaggedRows	字串	指定 CSV 檔案是否可包含缺少的欄位。預設值為 `false`。
DSBackupProjectionFields	字串	從 Cloud Datastore 備份載入的欄位 JSON 清單。
ParquetOptions	字串	指定 Parquet 專屬匯入選項的 JSON 物件。
DecimalTargetTypes	字串	提供套用至數值類型的偏好順序 JSON 清單。
HivePartitioningOptions	字串	指定來源端區隔選項的 JSON 物件。

執行自訂 SQL 查詢

如要建立自訂查詢，請按照下列步驟操作：

按照詳細操作說明新增連接器工作。
設定連接器工作時，請在要執行的動作類型中選取「動作」。
在「Action」清單中，選取「Execute custom query」，然後按一下「Done」。
展開「Task input」部分，然後執行下列操作：
1. 在「Timeout after」欄位中，輸入要等待多久時間才執行查詢。
  預設值：180 秒。
2. 在「資料列數量上限」欄位中，輸入資料庫要傳回的資料列數量上限。
  預設值：25。
3. 如要更新自訂查詢，請按一下「編輯自訂指令碼」。系統會開啟「Script editor」對話方塊。
4. 在「Script editor」對話方塊中輸入 SQL 查詢，然後按一下「Save」。
  您可以在 SQL 陳述式中使用問號 (?) 代表單一參數，該參數必須在查詢參數清單中指定。舉例來說，下列 SQL 查詢會選取 Employees 資料表中與 LastName 資料欄指定值相符的所有資料列：
```
SELECT * FROM Employees where LastName=?
```
  注意：系統支援資料操縱語言 (DML) 和資料定義語言 (DDL) 陳述式。
5. 如果您在 SQL 查詢中使用了問號，請按一下每個問號旁的「+ 新增參數名稱」，新增參數。執行整合作業時，這些參數會依序取代 SQL 查詢中的問號 (?)。舉例來說，如果您新增了三個問號 (?)，就必須依序新增三個參數。
  
  如要新增查詢參數，請按照下列步驟操作：
  1. 在「類型」清單中，選取參數的資料類型。
  2. 在「Value」欄位中輸入參數的值。
  3. 如要新增多個參數，請按一下「+ 新增查詢參數」。

使用 Terraform 建立連線

您可以使用 Terraform 資源建立新的連線。

如要瞭解如何套用或移除 Terraform 設定，請參閱「基本 Terraform 指令」。

如要查看建立連線的範例 Terraform 範本，請參閱範例範本。

使用 Terraform 建立這項連線時，請務必在 Terraform 設定檔中設定下列變數：

參數名稱	資料類型	必填	說明
project_id	STRING	是	包含 BigQuery 資料集的專案 ID，例如 myproject。
dataset_id	STRING	否	BigQuery 資料集的資料集 ID (不含專案名稱)，例如 mydataset。
proxy_enabled	BOOLEAN	否	選取這個核取方塊，即可為連線設定 Proxy 伺服器。
proxy_auth_scheme	ENUM	否	用於向 ProxyServer Proxy 驗證的驗證類型。支援的值如下：BASIC、DIGEST、NONE
proxy_user	STRING	否	用於向 ProxyServer Proxy 驗證的使用者名稱。
proxy_password	SECRET	否	用於驗證 ProxyServer Proxy 的密碼。
proxy_ssltype	ENUM	否	連線至 ProxyServer Proxy 時要使用的 SSL 類型。支援的值為：AUTO、ALWAYS、NEVER、TUNNEL

系統限制

BigQuery 連接器可處理每個節點每秒最多 8 筆交易，並限制超過此限制的任何交易。根據預設，Integration Connectors 會為連線分配 2 個節點 (可提高可用性)。

如要瞭解 Integration Connectors 適用的限制，請參閱「限制」一節。

支援的資料類型

以下為此連接器支援的資料類型：

ARRAY
BIGINT
BINARY
BIT
BOOLEAN
CHAR
DATE
DECIMAL
DOUBLE
FLOAT
INTEGER
LONGN VARCHAR
LONG VARCHAR
NCHAR
NUMERIC
NVARCHAR
REAL
SMALL INT
時間
TIMESTAMP
TINY INT
VARBINARY
VARCHAR

已知問題

BigQuery 連接器不支援 BigQuery 資料表中的主鍵。也就是說，您無法使用 entityId 執行 Get、Update 和 Delete 實體作業。或者，您也可以使用篩選器子句，根據 ID 篩選記錄。

向 Google Cloud 社群尋求協助

如有任何問題，歡迎在 Google Cloud 社群 (Cloud 論壇) 中發問並討論這個連接器。

後續步驟

瞭解如何暫停及恢復連線。
瞭解如何監控連接器使用情形。
瞭解如何查看連接器記錄。