English
Deutsch
Español – América Latina
Français
Indonesia
Italiano
Português – Brasil
中文 – 简体
中文 – 繁體
日本語
한국어

控制台

聯絡我們免費試用

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

建立物件資料表

本文件說明如何建立物件資料表，以便在 BigQuery 中存取非結構化資料。

如要建立物件資料表，您必須完成下列工作：

建立連線，讀取 Cloud Storage 中的物件資訊。
將「Storage 物件檢視者」(roles/storage.objectViewer) 角色授予與連線相關聯的服務帳戶。
使用 CREATE EXTERNAL TABLE 陳述式建立物件資料表，並將其與連線建立關聯。

事前準備

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the BigQuery and BigQuery Connection API APIs.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the BigQuery and BigQuery Connection API APIs.

Enable the APIs

請確認您的 BigQuery 管理員已建立連線，並設定 Cloud Storage 存取權。

必要的角色

如要使用物件資料表，使用者必須根據其在貴機構中的角色，具備下列 IAM 權限。如要進一步瞭解使用者角色，請參閱「安全性模型」。如要進一步瞭解如何授予權限，請參閱「查看可針對資源授予的角色」。

資料湖泊管理員

如要取得連線至 Cloud Storage 所需的權限，請要求管理員為您授予專案的 BigQuery 連線管理員 (roles/bigquery.connectionAdmin) 角色。

如要取得建立及管理 Cloud Storage 值區所需的權限，請要求管理員為您授予專案的「儲存空間管理員」(roles/storage.admin) 角色。

這個預先定義的角色具備連線至 Cloud Storage 所需的權限，以及建立及管理 Cloud Storage 值區的權限。如要查看確切的必要權限，請展開「必要權限」部分：
所需權限
- bigquery.connections.create
- bigquery.connections.get
- bigquery.connections.list
- bigquery.connections.update
- bigquery.connections.use
- bigquery.connections.delete
- storage.bucket.*
- storage.object.*
資料倉儲管理員

如要取得建立物件資料表所需的權限，請要求管理員在專案中授予您下列角色：
- BigQuery 資料編輯者 (roles/bigquery.dataEditor) 角色。
- BigQuery 連線管理員 (roles/bigquery.connectionAdmin) 角色。
這個預先定義的角色具備建立物件資料表所需的權限。如要查看確切的必要權限，請展開「必要權限」部分：
所需權限
- bigquery.tables.create
- bigquery.tables.update
- bigquery.connections.delegate
資料分析人員

如要取得查詢物件資料表所需的權限，請要求管理員在專案中授予您下列角色：
- BigQuery 資料檢視者 (roles/bigquery.dataViewer) 角色
- BigQuery Connection 使用者 (roles/bigquery.connectionUser) 角色
這個預先定義的角色具備查詢物件資料表所需的權限。如要查看確切的必要權限，請展開「必要權限」部分：
所需權限
- bigquery.jobs.create
- bigquery.tables.get
- bigquery.tables.getData
- bigquery.readsessions.create
您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

建立物件資料表

您必須先建立物件資料表，才能建立物件資料表所需的現有資料集。詳情請參閱「建立資料集」。

如要建立物件資料表，請按照下列步驟操作：

SQL

使用 CREATE EXTERNAL TABLE 陳述式。

前往 Google Cloud 控制台的「BigQuery」頁面。

前往 BigQuery
在查詢編輯器中輸入以下陳述式：
```
CREATE EXTERNAL TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME`
WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID`| DEFAULT}
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['BUCKET_PATH'[,...]],
  max_staleness = STALENESS_INTERVAL,
  metadata_cache_mode = 'CACHE_MODE');
```
請依指示取代下列項目：
- PROJECT_ID：您的專案 ID。
- DATASET_ID：包含物件資料表的資料集 ID。
- TABLE_NAME：物件表格名稱。
- REGION：包含連線的區域或多區域。
- CONNECTION_ID：與此物件資料表搭配使用的雲端資源連線 ID。連線會決定使用哪個服務帳戶讀取 Cloud Storage 中的資料。
  在 Google Cloud 控制台查看連線詳細資料時，連線 ID 是「連線 ID」中顯示的完整連線 ID 最後一個部分的值，例如 projects/myproject/locations/connection_location/connections/myconnection。
  
  如要使用預設連線，請指定 DEFAULT，而非包含 PROJECT_ID.REGION.CONNECTION_ID 的連線字串。
- BUCKET_PATH：Cloud Storage 值區的路徑，其中包含物件表所代表的物件，格式為 ['gs://bucket_name/[folder_name/]*']。
  您可以在每個路徑中使用一個星號 (*) 萬用字元，限制物件表格中包含的物件。舉例來說，如果資料集包含多種類型的非結構化資料，您可以指定 ['gs://bucket_name/*.pdf']，只針對 PDF 物件建立物件資料表。詳情請參閱「Cloud Storage URI 的萬用字元支援」。
  
  您可以提供多個路徑 (例如 ['gs://mybucket1/*', 'gs://mybucket2/folder5/*'])，為 uris 選項指定多個值區。
  
  如要進一步瞭解如何在 BigQuery 中使用 Cloud Storage URI，請參閱「Cloud Storage 資源路徑」。
- STALENESS_INTERVAL：指定是否要讓針對物件資料表的作業使用快取中繼資料，以及快取中繼資料必須多新才能供作業使用。如要進一步瞭解中繼資料快取的考量事項，請參閱「為提升效能而快取中繼資料」。
  如要停用中繼資料快取功能，請指定 0。這是目前的預設做法。
  
  如要啟用中繼資料快取功能，請指定介於 30 分鐘至 7 天之間的間隔文字常值。例如，指定 INTERVAL 4 HOUR 的過時間隔為 4 小時。使用這個值時，如果資料表已在過去 4 小時內重新整理，對資料表執行的作業會使用快取的中繼資料。如果快取的中繼資料較舊，則操作會改為從 Cloud Storage 擷取中繼資料。
- CACHE_MODE：指定中繼資料快取是否自動或手動重新整理。如要進一步瞭解中繼資料快取的考量事項，請參閱「為提升效能而快取中繼資料」。
  將其設為 AUTOMATIC，即可按照系統定義的間隔 (通常為 30 到 60 分鐘) 重新整理中繼資料快取。
  
  如果您想依照指定的時間表重新整理中繼資料快取，請將其設為 MANUAL。在這種情況下，您可以呼叫 BQ.REFRESH_EXTERNAL_METADATA_CACHE 系統程序來重新整理快取。
  
  如果 STALENESS_INTERVAL 設為大於 0 的值，您必須設定 CACHE_MODE。
按一下「Run」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」一文。

範例

以下範例會建立物件資料表，其中的中繼資料快取失效間隔為 1 天：

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://mybucket/*'],
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

以下範例會在三個 Cloud Storage 值區中的物件上建立物件表格：

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://bucket1/*','gs://bucket2/folder1/*','gs://bucket3/*']
);

以下範例只針對 Cloud Storage 值區中的 PDF 物件建立物件資料表：

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://bucket1/*.pdf']
);

bq

使用 bq mk 指令。

bq mk --table \
--external_table_definition=BUCKET_PATH@REGION.CONNECTION_ID \
--object_metadata=SIMPLE \
--max_staleness=STALENESS_INTERVAL \
--metadata_cache_mode=CACHE_MODE \
PROJECT_ID:DATASET_ID.TABLE_NAME

請依指示取代下列項目：

PROJECT_ID：您的專案 ID。
DATASET_ID：包含物件資料表的資料集 ID。
TABLE_NAME：物件表格名稱。
REGION：包含連線的區域或多區域。
CONNECTION_ID：與此外部資料表搭配使用的雲端資源連線 ID。連線會決定使用哪個服務帳戶讀取 Cloud Storage 中的資料。
在 Google Cloud 控制台查看連線詳細資料時，連線 ID 是「連線 ID」中顯示的完整連線 ID 最後一節的值，例如 projects/myproject/locations/connection_location/connections/myconnection。
BUCKET_PATH：Cloud Storage 值區的路徑，其中包含物件表所代表的物件，格式為 gs://bucket_name/[folder_name/]*。
您可以在每個路徑中使用一個星號 (*) 萬用字元，限制物件表格中包含的物件。舉例來說，如果資料集包含多種類型的非結構化資料，您可以指定 gs://bucket_name/*.pdf，只針對 PDF 物件建立物件資料表。詳情請參閱「Cloud Storage URI 的萬用字元支援」。

您可以提供多個路徑 (例如 gs://mybucket1/*,gs://mybucket2/folder5/*)，為 uris 選項指定多個值區。

如要進一步瞭解如何在 BigQuery 中使用 Cloud Storage URI，請參閱「Cloud Storage 資源路徑」。
STALENESS_INTERVAL：指定是否要讓針對物件資料表的作業使用快取中繼資料，以及快取中繼資料必須多新才能供作業使用。如要進一步瞭解中繼資料快取的考量事項，請參閱「為提升效能而快取中繼資料」。
如要停用中繼資料快取功能，請指定 0。這是目前的預設做法。

如要啟用中繼資料快取功能，請使用 INTERVAL 資料類型說明中的 Y-M D H:M:S 格式，指定 30 分鐘至 7 天之間的間隔值。例如，指定 0-0 0 4:0:0 為 4 小時的過時間隔。使用這個值時，如果快取的中繼資料在過去 4 小時內已重新整理，對資料表執行的作業就會使用快取的中繼資料。如果快取的中繼資料較舊，則操作會改為從 Cloud Storage 擷取中繼資料。
CACHE_MODE：指定中繼資料快取是否自動或手動重新整理。如要進一步瞭解中繼資料快取的考量事項，請參閱「為提升效能而快取中繼資料」。
將其設為 AUTOMATIC，即可按照系統定義的間隔 (通常為 30 到 60 分鐘) 重新整理中繼資料快取。

如果您想依照指定的時間表重新整理中繼資料快取，請將其設為 MANUAL。在這種情況下，您可以呼叫 BQ.REFRESH_EXTERNAL_METADATA_CACHE 系統程序來重新整理快取。

如果 STALENESS_INTERVAL 設為大於 0 的值，您必須設定 CACHE_MODE。

範例

以下範例會建立物件資料表，其中的中繼資料快取失效間隔為 1 天：

bq mk --table \
--external_table_definition=gs://mybucket/*@us.my-connection \
--object_metadata=SIMPLE \
--max_staleness=0-0 1 0:0:0 \
--metadata_cache_mode=AUTOMATIC \
my_dataset.object_table

以下範例會在三個 Cloud Storage 值區中的物件上建立物件表格：

bq mk --table \
--external_table_definition=gs://bucket1/*,gs://bucket2/folder1/*,gs://bucket3/*@us.my-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

以下範例只針對 Cloud Storage 值區中的 PDF 物件建立物件資料表：

bq mk --table \
--external_table_definition=gs://bucket1/*.pdf@us.my-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

API

呼叫 tables.insert 方法。在傳入的 Table 資源中，加入 ExternalDataConfiguration 物件，並將 objectMetadata 欄位設為 SIMPLE。

以下範例說明如何使用 curl 呼叫此方法：

ACCESS_TOKEN=$(gcloud auth print-access-token) curl \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST \
-d '{"tableReference": {"projectId": "my_project", "datasetId": "my_dataset", "tableId": "object_table_name"}, "externalDataConfiguration": {"objectMetadata": "SIMPLE", "sourceUris": ["gs://mybucket/*"]}}' \
https://www.googleapis.com/bigquery/v2/projects/my_project/datasets/my_dataset/tables

Terraform

本例會建立物件資料表，並啟用中繼資料快取功能，以便手動重新整理。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

物件資料表的必要欄位為 google_bigquery_table.external_data_configuration.object_metadata、google_bigquery_table.external_data_configuration.metadata_cache_mode 和 google_bigquery_table.max_staleness。如要進一步瞭解各項資源，請參閱 Terraform BigQuery 說明文件。


# This queries the provider for project information.
data "google_project" "default" {}

# This creates a connection in the US region named "my-connection-id".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection-id"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.default.project_id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This defines a Google BigQuery dataset.
resource "google_bigquery_dataset" "default" {
  dataset_id = "my_dataset_id"
}

# This creates a bucket in the US region named "my-bucket" with a pseudorandom suffix.
resource "random_id" "bucket_name_suffix" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.bucket_name_suffix.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

# This defines a BigQuery object table with manual metadata caching.
resource "google_bigquery_table" "default" {
  deletion_protection = false
  table_id            = "my-table-id"
  dataset_id          = google_bigquery_dataset.default.dataset_id
  external_data_configuration {
    connection_id = google_bigquery_connection.default.name
    autodetect    = false
    # `object_metadata is` required for object tables. For more information, see
    # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/bigquery_table#object_metadata
    object_metadata = "SIMPLE"
    # This defines the source for the prior object table.
    source_uris = [
      "gs://${google_storage_bucket.default.name}/*",
    ]

    metadata_cache_mode = "MANUAL"
  }

  # This ensures that the connection can access the bucket
  # before Terraform creates a table.
  depends_on = [
    google_project_iam_member.default
  ]
}

如要在 Google Cloud 專案中套用 Terraform 設定，請完成下列各節中的步驟。

準備 Cloud Shell

啟動 Cloud Shell。
設定要套用 Terraform 設定的預設 Google Cloud 專案。

您只需為每個專案執行這個指令一次，而且可以在任何目錄中執行。
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
如果您在 Terraform 設定檔中設定明確的值，系統就會覆寫環境變數。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱必須包含 .tf 副檔名，例如 main.tf。在本教學課程中，檔案稱為 main.tf。
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
如果您正在參考教學課程，可以複製各個章節或步驟中的程式碼範例。

將範例程式碼複製到新建立的 main.tf 中。

您可以視需要從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分，建議您採用這種做法。
查看並修改要套用至環境的範例參數。
儲存變更。
初始化 Terraform。這項操作只需對每個目錄執行一次。
```
terraform init
```
如要使用最新版的 Google 供應器，您可以選擇加入 -upgrade 選項：
```
terraform init -upgrade
```

套用變更

檢查設定，確認 Terraform 要建立或更新的資源符合您的預期：
```
terraform plan
```
視需要修正設定。
執行下列指令，並在提示中輸入 yes，即可套用 Terraform 設定：
```
terraform apply
```
等待 Terraform 顯示「Apply complete!」(套用完成) 訊息。
開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

查詢物件資料表

您可以像查詢其他 BigQuery 資料表一樣查詢物件資料表，例如：

SELECT *
FROM mydataset.myobjecttable;

查詢物件資料表會傳回基礎物件的中繼資料。詳情請參閱「物件資料表結構定義」。

後續步驟

瞭解如何針對圖片物件資料表執行推論。
瞭解如何使用遠端函式分析物件資料表。

除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。

上次更新時間：2025-06-19 (世界標準時間)。